| Label | Explanation | Data Type |
Input Phone Records Table
| The input table containing call records or phone data event records provided by the wireless network provider. | Table View |
Input Cell Site Points | The feature class containing cell site points generated by the Cell Site Records to Feature Class tool. | Feature Layer |
Input Cell Site Sectors
| The feature class containing cell site sectors generated by the Cell Site Records to Feature Class tool. | Feature Layer |
Output Phone Record Site Points
| The point feature class containing phone record site points. One point will be generated per phone record linked to cell site points. | Feature Class |
Output Phone Record Sectors
| The polygon feature class containing phone record sectors. One sector polygon will be generated per phone record linked to cell site sectors. | Feature Class |
Cell Sector ID Fields
| Specifies the unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas.
ID Type options are as follows:
| Value Table |
Subscriber ID Field
| The field in the input table that contains the phone number or identifier of the subscriber. | Field |
Destination Phone Number Field
(Optional) | The field in the input table that contains the phone number or identifier of the callee. | Field |
Additional Cell Sector ID Fields (Optional) |
Specifies the additional unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas.
ID Type options are as follows:
| Value Table |
Start Date and Time Field (Optional) | The field in the input table that contains the start date and time field of the phone call or data event. | Field |
Duration Field (Optional) | The field in the input table that contains the duration of the phone call in seconds. | Field |
End Date and Time Field (Optional) | The field in the input table that contains the end date and time of the phone call or data event. | Field |
Convert UTC Dates to Local Time Zone
(Optional) | Specifies whether the start and end date and time of the input records will be converted to the time zone of the local system or will remain in coordinated universal time (UTC).
| Boolean |
Estimated Phone Location X Field (Optional) | The field in the input table that contains the x-coordinate of the estimated phone location as provided by the wireless network provider. | Field |
Estimated Phone Location Y Field (Optional) | The field in the input table that contains the y-coordinate of the estimated phone location as provided by the wireless network provider. | Field |
Estimated Phone Location Coordinate System (Optional) | The estimated phone location coordinate system of the x,y-coordinates. The default coordinate system is WGS84. | Coordinate System |
Output Estimated Call Points (Optional) | The point feature class containing the estimated call locations as provided by the wireless network provider. | Feature Class |
Start Timing Advance Distance Field
(Optional) | The field in the input table that contains the timing advance distance at the start of the call. | Field |
End Timing Advance Distance Field
(Optional) | The field in the input table that contains the timing advance distance at the end of the call. | Field |
Timing Advance Distance Unit
(Optional) | Specifies the linear unit of measurement that will be used for the Start Timing Advance Distance Field and End Timing Advance Distance Field parameter values.
| String |
Timing Advance Band Total Width (Optional) | The full width of the timing advance band. The default is 78.07 meters. | Linear Unit |
Output Timing Advance Bands
(Optional) | The polygon feature class that will contain the timing advance bands as provided by the wireless network provider. | Feature Class |
Summary
Imports cell phone records from wireless network providers and associates those records with a cell site and sector feature classes as generated by the Cell Site Records To Feature Class tool based on identifier fields.
Usage
The Input Cell Site Points parameter values must be generated using the Cell Site Records To Feature Class tool.
The Output Phone Record Site Points and Output Phone Record Sectors parameters will only contain the phone records that were successfully linked to the input cell site and sectors based on matching ID fields. The Output Phone Record Site Points and Output Phone Record Sectors parameter values do not represent the actual location of the cell phone.
Wireless network providers provide cell phone records or call detail records (CDR) in a variety of formats and styles. It is common to receive data in a nontabular format or schema. The Input Phone Records Table parameter value must be a table with column names at the top.
The table provided by the wireless network provider may contain CDR and cell site information in one row. When the table is structured this way, it must be separated into two tables. Use the table containing the call information (identifiers, phone numbers, dates, time, call duration, and coordinates) as the input to this tool.
A feature is created in the output feature classes for each record (call or data event) of the Input Phone Records Table parameter.
The following fields will be added to the output feature classes:
- SUBSCRIBER—The subscriber phone number of the Input Phone Records Table parameter value. All nonnumeric characters are removed from the output.
- UNIQUEID—The unique identifier of the cell sector antennas.
The following fields will be added to the output when the specified parameter is used:
- DESTPHONE—The callee phone number of the Input Phone Records Table parameter value. This is added to the output when the Destination Phone Number Field parameter is used. All nonnumeric characters are removed from the output.
- STARTTIME—The start date and time field of the Input Phone Records Table parameter value. This is added to the output when the Start Date and Time Field parameter is used.
- DURATION—The duration of the phone call, in seconds, of the Input Phone Records Table parameter value. Duration values formatted as HH:MM:SS will be converted to total seconds. This is added to the output when the Duration Field parameter is used or when both the Start Date and Time Field and End Date and Time Field parameters are used.
- ENDTIME—The end date and time field of the Input Phone Records Table parameter value. This is added to the output when the End Date and Time Field parameter is used or when both the Start Date and Time Field and Duration parameters are used
The table provided by the wireless network provider may include a cell site information table with one unique ID field to define all unique records or a combination of identifier fields to define unique records in the table. For example, a table may contain site identifier and sector identifier fields to uniquely define some records, but other records in the table are uniquely defined with Location Area Code identifier and cell identifier fields.
- When one unique ID field is provided for the input table, set the ID Type option to Unique ID in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter. In the same parameter, populate the Field option with the field that represents that unique ID.
- When many ID fields are provided for the table to indicate uniqueness, all ID fields must be added to the output. For each ID field choose the ID Type value that defines the ID type in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter. In the same parameter, populate the Field option with the related field that contains the ID information. The tool will combine these ID fields and populate a single unique ID field in the output feature classes called UNIQUEID.
The following fields will be added to the output if they're specified in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter:
- SITEID—The unique identifier of a cell site
- SECTORID—The unique identifier of a cell sector
- SWITCHID—The unique identifier of a wireless network switch
- LACID—The unique identifier of a Location Area Code
- CASCADEID—The unique identifier of the sector within wireless network cascade
- CELLID—The unique identifier of the sector within a Location Area Code
When the input phone record table contains call records that span multiple cell sectors, both the Cell Sector ID Fields and Additional Cell Sector ID Fields parameters must be populated. The Cell Sector ID Fields parameter must contain the identifiers associated with the beginning sector, and the Additional Cell Sector ID Fields parameter must contain the end sector or any sector other than the beginning sector in the call record.
When the input phone record table contains data event records or only one sector is referenced in the call record, only the Cell Sector ID Fields parameter must be populated.
The following field and values are generated when the Additional Cell Sector ID Fields parameter is populated:
- IDTYPE—The field identifying whether a call record is a primary sector or an additional sector of a call record.
- PRIMARY—The value assigned when a cell phone record is linked to a sector at the beginning of a call.
- ADDITIONAL—The value assigned when a cell phone record is linked to a sector at the end of a call or any sector during the duration of the call when the sector is different than the sector at the beginning of the call.
- LOCTIME—The field containing a unique date and time value of a call record based on whether the IDTYPE field is PRIMARY or ADDITIONAL. The value of the STARTTIME field is assigned to the LOCTIME field when the IDTYPE field value is PRIMARY. The value of the ENDTIME field is assigned to the LOCTIME field when the IDTYPE field value is ADDITIONAL. The LOCTIME field allows the features to be visualized by a unique date time value and estimated location of calls.
If a cell phone record is linked to the same sector at the beginning and end of a call, no separate feature is created for the cell sector representing the end of a call.
- IDTYPE—The field identifying whether a call record is a primary sector or an additional sector of a call record.
The output estimated call points will contain all the associated fields of the Output Phone Records Site Points and Output Phone Records Site Sectors parameter values.
The following fields will be added to the Output Estimated Call Points parameter value:
- PHONEX—The estimated x-coordinate of the call location as provided by the wireless network provider
- PHONEY—The estimated y-coordinate of the call location as provided by the wireless network provider
If the SUBSCRIBER field record is null, it will be ignored and will not be imported into the output feature classes.
If the STARTTIME and DURATION fields have values and the ENDTIME field does not, the tool will generate an ENDTIME value in the output feature classes.
If the STARTTIME and ENDTIME fields have values and the DURATION field does not, the tool will generate a DURATION value in the output feature classes.
The Timing Advance Band Output Options parameters (Start Timing Advance Distance Field, End Timing Advance Distance Field, Timing Advance Distance Unit, Timing Advance Band Total Width, and Output Timing Advance Bands) are optional and not necessary for associating call detail records to cell tower and sector locations.
Some cell phone records include timing advance data that can be used to identify the distance of a phone from a cell tower at the time of a call. If timing advance data exists in the records, this tool can create a polygon feature class containing a band representing the distance of the phone from the cell site along the beamwidth arc of the sector in which a call occurred.
The output timing advance bands will contain all the associated fields of the Output Phone Records Site Points and Output Phone Records Site Sectors parameter values.
The following fields will be added to the Output Timing Advance Bands parameter:
- TASTART—The timing advance distance at the start of the call as provided by the wireless network provider. This field is added to the output when the Start Timing Advance Distance Field parameter is specified.
- TAEND—The timing advance distance at the end of the call as provided by the wireless network provider. This field is added to the output when the End Timing Advance Distance Field parameter is specified.
- TATYPE—The field identifying whether the timing advance band is located at the start or end timing distance from the cell site. This field is added to the output when the Start Timing Advance Distance Field and End Timing Advance Distance Field parameters are specified.
- START—The value assigned when the band is located at the start timing distance
- END—The value assigned when the band is located at the end timing distance
Parameters
arcpy.ca.CellPhoneRecordsToFeatureClass(in_table, in_site_features, in_sector_features, out_site_feature_class, out_sector_feature_class, id_fields, subscriber_field, {destination_field}, {additional_id_fields}, {start_time_field}, {duration_field}, {end_time_field}, {convert_utc}, {location_x_field}, {location_y_field}, {location_coordinate_system}, {out_call_points}, {start_timing_distance_field}, {end_timing_distance_field}, {timing_advance_unit}, {timing_band_width}, {out_timing_advance_bands})| Name | Explanation | Data Type |
in_table | The input table containing call records or phone data event records provided by the wireless network provider. | Table View |
in_site_features | The feature class containing cell site points generated by the Cell Site Records to Feature Class tool. | Feature Layer |
in_sector_features | The feature class containing cell site sectors generated by the Cell Site Records to Feature Class tool. | Feature Layer |
out_site_feature_class | The point feature class containing phone record site points. One point will be generated per phone record linked to cell site points. | Feature Class |
out_sector_feature_class | The polygon feature class containing phone record sectors. One sector polygon will be generated per phone record linked to cell site sectors. | Feature Class |
id_fields [id_fields,...] | Specifies the unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas.
ID Type options are as follows:
| Value Table |
subscriber_field | The field in the input table that contains the phone number or identifier of the subscriber. | Field |
destination_field (Optional) | The field in the input table that contains the phone number or identifier of the callee. | Field |
additional_id_fields [additional_id_fields,...] (Optional) |
Specifies the additional unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas.
ID Type options are as follows:
| Value Table |
start_time_field (Optional) | The field in the input table that contains the start date and time field of the phone call or data event. | Field |
duration_field (Optional) | The field in the input table that contains the duration of the phone call in seconds. | Field |
end_time_field (Optional) | The field in the input table that contains the end date and time of the phone call or data event. | Field |
convert_utc (Optional) | Specifies whether the start and end date and time of the input records will be converted to the time zone of the local system or will remain in coordinated universal time (UTC).
| Boolean |
location_x_field (Optional) | The field in the input table that contains the x-coordinate of the estimated phone location as provided by the wireless network provider. | Field |
location_y_field (Optional) | The field in the input table that contains the y-coordinate of the estimated phone location as provided by the wireless network provider. | Field |
location_coordinate_system (Optional) | The estimated phone location coordinate system of the x,y-coordinates. The default coordinate system is WGS84. | Coordinate System |
out_call_points (Optional) | The point feature class containing the estimated call locations as provided by the wireless network provider. | Feature Class |
start_timing_distance_field (Optional) | The field in the input table that contains the timing advance distance at the start of the call. | Field |
end_timing_distance_field (Optional) | The field in the input table that contains the timing advance distance at the end of the call. | Field |
timing_advance_unit (Optional) | Specifies the linear unit of measurement that will be used for the start_timing_distance_field and End Timing Advance Distance Field parameter values.
| String |
timing_band_width (Optional) | The full width of the timing advance band. The default is 78.07 meters. | Linear Unit |
out_timing_advance_bands (Optional) | The polygon feature class that will contain the timing advance bands as provided by the wireless network provider. | Feature Class |
Code sample
The following Python window script demonstrates how to use the CellPhoneRecordsToFeatureClass function in immediate mode:
import arcpy
arcpy.env.workspace = r"C:/data/city_pd.gdb"
arcpy.ca.CellPhoneRecordsToFeatureClass("CDR_Phone_1",
"Phone_1_Sites",
"Phone_1_Sectors",
"CDR_Phone_1_Sites_out",
"CDR_Phone_1_Sectors_out",
"SWITCH_ID BEGSWITCH;SITE_ID BEGSITE;SECTOR_ID BEGSECTOR",
"SUBSCRIBERID")The stand-alone script below is an example of how to use the CellPhoneRecordsToFeatureClass function in a script:
# Name: CellPhoneRecordsToFeatureClass.py
# Description: Imports cell phone records then associates those records with a
# cell site and sector feature classes based on identifier fields.
# Import system modules
import arcpy
# Set environment settings
arcpy.env.workspace = r"C:\data\city_pd.gdb"
# Set local variables
in_table = "CDR_Phone_1"
in_sites = "Phone_1_Sites"
in_sectors = "Phone_1_Sectors"
out_cdr_sites = "CDR_Phone_1_Sites_out"
out_cdr_sectors = "CDR_Phone_1_Sectors_out"
# Set up Beginning of Phone IDs
# [ID Type, Field]
begin_switch_id = ["SWITCH_ID","BEGSWITCH"]
begin_site_id = ["SITE_ID","BEGSITE"]
begin_sector_id = ["SECTOR_ID","BEGSECTOR"]
begin_id_fields = [begin_switch_id, begin_site_id, begin_sector_id]
subscriber_field = "SUBSCRIBERID"
destination_field = "DESTNUM"
# Set up End of Phone Call IDs
# [ID Type, Field]
end_switch_id = ["SWITCH_ID","ENDSWITCH"]
end_site_id = ["SITE_ID","ENDSITE"]
end_sector_id = ["SECTOR_ID","ENDSECTOR"]
end_id_fields = [end_switch_id, end_site_id, end_sector_id]
# Input Table Contains information about the duration of the call
start_date_field = "DATETIME"
duration_field = "DURATION"
arcpy.ca.CellPhoneRecordsToFeatureClass(in_table,
in_sites,
in_sectors,
out_cdr_sites,
out_cdr_sectors,
begin_id_fields,
subscriber_field,
destination_field,
end_id_fields,
start_date_field,
duration_field)