HOW TO

Migrate arcpy.ba.spatialoverlay() scripts to arcpy.ba.enrichlayer() scripts

Last Published: May 26, 2022

Summary

In the migration from ArcGIS Desktop Business Analyst to ArcGIS Pro Business Analyst, the Spatial Overlay tool has been migrated to the Enrich Layer tool. While these tools provide equivalent functionality, there are differences in syntax when utilized as part of an ArcPy script. These differences include:

  • arcpy.ba.spatialoverlay() takes an older format of variable names for the SelectedSummarizations parameter, for example, "TOTPOP_CY";  "VACANT_FY"; "GENALPHAFY"; "POPFAMHH10"; “X11001_A“; “MP09148a_I”.
    • The variable can have various suffixes appended to the end of the variable name to indicate different summarization types:
    • CY represents current year variable, FY represents five-year estimates, P represents a percentage variable, I represents an index variable, and A represents an average.
  • arcpy.ba.enrichlayer() uses a variable naming convention that is standardized across the ArcGIS Business Analyst platform, for example,  "populationtotals.totpop_cy"; "keyusfacts.vacant_cy_p"; "generations.genalphafy"; "householdtype.popfamhh10"; “education.x11001_x_a”; “electronicsinternet.mp09148a_b_i”.
    • The string prior to the period separator indicates the variable category and the string that follows the period separator indicates the variable name. 
    • cy represents current year variable, fy represents five-year estimates, represents a percentage variable, i represents an index variable, represents averages, 00 or 10 or 20 indicate an attribute from the decennial census.
  • The names of the input variables are passed directly to the field names in the geoprocessing output, causing the arcpy.ba.spatialoverlay() and arcpy.ba.enrichlayer() tools to write different field names.

When migrating an ArcPy 2.x script to be compatible with ArcGIS Pro and ArcPy 3.x, the Spatial Overlay process must be migrated to the equivalent Enrich Layer process. This migration process requires migrating SelectedSummarizations to match the naming conventions required for the variables parameters to be equivalent with the Business Analyst Platform. Additionally, if the fields created by this process are used in an application, an additional step is needed to revert field names to the arcpy.ba.spatialoverlay() format.

Procedure

Converting Spatial Overlay Selected Summarizations to Enrich Layer Variables

  1. Download and unzip the VariablesConverter_full.zip, which contains a script resource that can be used to aid in migrating a script tool from arcpy.ba.spatialoverlay() to arcpy.ba.enrichlayer().
  2. Using an IDE of choice, for example, the command prompt, IDLE, or the Python window in ArcGIS Pro, run the VariablesConverter_full.py script.
    • This script first prompts for an input Business Analyst Data Source environment, for example, "USA_ESRI_2021", or "CAN_ESRI_2020".
    • Note: this solution requires a locally installed Business Analyst dataset.
    • This information can be gathered from ArcGIS Pro by clicking the Analysis tab > Business Analysis > Business Analyst Data Source, as shown in the following image.
image.png
  1. Provide a list of Business Analyst variables using the naming convention used by the SelectedSummarization parameter, separated by semi-colons. The variable names can be formatted using either naming convention provided below, matching the simplified field names or the aliases accessed in the Spatial Overlay guided workflow.
TSEGNAME;TOTPOP_CY;HHPOP_CY;POPDENS_CY;TOTHH_CY;MEDHINC_CY;AVGHINC_CY;PCI_CY;MEDDI_CY;MP01058h_I;MP01059h_B;MP01059h_I;MP06001a_I;

OR

TSEGNAME.2021 Dominant Tapestry Segment Name (Esri)(USA Esri 2021);TSPOP14_CY.2014 Total Population (Esri 2021)(USA Esri 2021);HHPOP_CY.2021 Household Population (Esri)(USA Esri 2021);POPDENS_CY.2021 Population Density (Pop per Square Mile) (Esri)(USA Esri 2021);TOTHH_CY.2021 Total Households (Esri)(USA Esri 2021);MEDHINC_CY.2021 Median Household Income (Esri)(USA Esri 2021);PCI_CY.2021 Per Capita Income (Esri)(USA Esri 2021);MEDDI_CY.2021 Median Disposable Income (Esri)(USA Esri 2021);MP01058h_I.2021 HH Owns Any Motorcycle: Index(USA Esri 2021);MP01059h_B.2021 HH Bought Any New Motorcycle(USA Esri 2021);MP01059h_I.2021 HH Bought Any New Motorcycle: Index(USA Esri 2021);MP06001a_I.2021 Participated in Any Public Activity Last 12 Mo: Index(USA Esri 2021)
  1. Press Enter to run the script.
image.png
  1. This script returns two outputs:
  • A list of Converted variables to use as inputs for the Enrich Layer process
image.png
  • A list of Converted variables for use as a Field Map with a Feature Class to Feature Class process
image.png

Configuring the Enrich Layer process

  • Take the first output from this script, and copy+paste the string as the variable parameter for an arcpy.ba.EnrichLayer() process.
Note:
Because of enterprise geodatabase field name restrictions, the output of the Enrich Layer process should be created in a file geodatabase, used to stage the input for the next step.

Converting output Field Names to match Spatial Overlay naming convention

  1. To convert the output field names, for compatibility with a downstream process, add an arcpy.conversion.FeatureClassToFeatureClass() process to the working script: 
  2. Specify the enrichlayer() output as the input layer.
  3. Delete any Business Analyst-related field mapping that has populated, then copy+paste the second output from the VariableConverter_full script into the field mapping parameter.
    • Do not delete any field mapping that you wish to preserve in the output, such as ID fields or non-Business Analyst attributes.
    • The output from the Feature Class to Feature Class process can be written to an enterprise geodatabase since the output field names will meet field name restrictions for enterprise geodatabase.

Example of the configured Enrich Layer and Feature Class to Feature Class processes

import arcpy

input_fc = r"C:\Users\<userid>\Documents\ArcGIS\Default.gdb\input_polygons"
enrich_fc = r"C:\Users\<userid>\Documents\ArcGIS\Default.gdb\EnrichLayeroutput"
output_gdb = r"C:\Users\<userid>\Documents\ArcGIS\Default.gdb"
converted_fc = "Enrichtransform"
enrich_variables = "AtRisk.tsegname;Age_by_Sex_by_Race_Profile_rep.totpop_cy;populationtotals.hhpop_cy;populationtotals.popdens_cy;Age_by_Sex_by_Race_Profile_rep.tothh_cy;entertainment.x9066_i;entertainment.x9077_i;entertainment.x9077_x;entertainment.x9079_i"

arcpy.ba.EnrichLayer(input_fc, enrich_fc, enrich_variables) 

arcpy.conversion.FeatureClassToFeatureClass(enrich_fc, output_gdb, converted_fc, '', 'ID "ID" true true false 3 Text 0 0,First,#,EnrichLayer1,ID,0,3;TSEGNAME "2021 Dom Tapestry Segment Name" true true false 8 Double 0 0,First,#,test,AtRisk_tsegname,-1,-1;TOTPOP_CY "2021 Total Population" true true false 8 Double 0 0,First,#,test,Age_by_Sex_by_Race_Profile_rep_totpop_cy,-1,-1;HHPOP_CY "2021 Household Population" true true false 8 Double 0 0,First,#,test,populationtotals_hhpop_cy,-1,-1;POPDENS_CY "2021 Population Density" true true false 8 Double 0 0,First,#,test,populationtotals_popdens_cy,-1,-1;TOTHH_CY "2021 Total Households" true true false 8 Double 0 0,First,#,test,Age_by_Sex_by_Race_Profile_rep_tothh_cy,-1,-1;MEDHINC_CY "2021 Median Household Income" true true false 8 Double 0 0,First,#,test,Health_medhinc_cy,-1,-1;AVGHINC_CY "2021 Average Household Income" true true false 8 Double 0 0,First,#,test,AtRisk_avghinc_cy,-1,-1;PCI_CY "2021 Per Capita Income" true true false 8 Double 0 0,First,#,test,householdincome_pci_cy,-1,-1;MEDDI_CY "2021 Median Disposable Income" true true false 8 Double 0 0,First,#,test,disposableincome_meddi_cy,-1,-1;MP01058h_I "2021 Index: HH Owns Any Motorcycle" true true false 8 Double 0 0,First,#,test,AutomobilesAutomotiveProducts_mp01058h_i,-1,-1;MP01059h_B "2021 HH Bought Any New Motorcycle" true true false 8 Double 0 0,First,#,test,AutomobilesAutomotiveProducts_mp01059h_b,-1,-1;MP01059h_I "2021 Index: HH Bought Any New Motorcycle" true true false 8 Double 0 0,First,#,test,AutomobilesAutomotiveProducts_mp01059h_i,-1,-1;MP06001a_I "2021 Index: Participated in Any Public Activity/12 Mo" true true false 8 Double 0 0,First,#,test,CivicActivitiesPoliticalAffiliation_mp06001a_i,-1,-1;MP06002a_I "2021 Index: Attended Public Mtg On Town/School Affairs/12 Mo" true true false 8 Double 0 0,First,#,test,CivicActivitiesPoliticalAffiliation_mp06002a_i,-1,-1')

Article ID: 000027720

Software:
  • ArcGIS Business Analyst Desktop

Receive notifications and find solutions for new or common issues

Get summarized answers and video solutions from our new AI chatbot.

Download the Esri Support App

Related Information

Discover more on this topic

Get help from ArcGIS experts

Contact technical support

Download the Esri Support App

Go to download options