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 not uncommon 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. 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. 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. 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. 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. 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 a 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 and 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 that defines the ID type in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter and in the same parameter, populate theField 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 across multiple cell sectors, both the Cell Sector ID Fieldsand 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 used:
- IDTYPE—The field identifying whether a call record is primary sector or 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.
If the tool determines 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 primary sector or 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 Sectorsparameters.
The following fields will also be added to the Output Estimated Call Points parameter:
- 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.
Syntax
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})| Parameter | 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 has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table 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 has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table 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 |
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)Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes