Use the embeddings

The USA Geodemographic Embeddings can support multiple geospatial AI workflows using the Embeddings Based Analysis toolset available in ArcGIS Pro. This document demonstrates three common ways to apply the embeddings:

• Embeddings as Predictors—Using embeddings directly as explanatory variables when original predictors are unavailable.
• Embeddings for Model Enhancement—Combining embeddings with existing explanatory variables to improve downstream model performance.
• Embeddings for Similarity Search—Using embeddings to identify geographically or semantically similar locations and features.

The examples in this guide walk through each workflow and highlight the ArcGIS Pro tools that simplify implementation.

To use the embeddings, make sure you have added the USA Geodemographic Embeddings feature layer to the Map from ArcGIS Living Atlas of the World.

Note:

Refer to the Recommendations on the use of USA Geodemographic Embeddings section in the Concepts of USA Geodemographic Embeddings document for best practices on embeddings usage.

Embeddings as Predictors

USA Geodemographic Embeddings can be used directly as explanatory variables with your geospatial datasets in ArcGIS Pro. In this example, the embeddings are used as predictors to estimate the crude prevalence rates of depression in counties where the target (which is the crude prevalence rate of depression in this case) values are unavailable.

The example dataset has crude prevalence rates of depression for counties in the United States (cdc_places_depression layer) except a few counties marked with red outlines (predict_depressionlayer). It is also worth noting that the dataset does not have any preexisting independent variables that could be used to estimate the depression crude prevalence rates.

Note:

The Adults with Frequent Mental Health Distress (CDC Places) dataset can be opened in ArcGIS Pro to try this workflow.

To estimate the crude prevalence rates of depression for counties marked in red with USA Geodemographic Embeddings, use the following steps:

Merge embeddings

USA Geodemographic Embeddings are provided at the Uber H3 resolution 7 hex-bin level, while the example dataset requires the embeddings at county level. To aggregate the embeddings at county level, complete the following steps:

1. Browse to Tools on the Analysis tab.

   

2. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Merge Embeddings tool under the Embeddings Based Analysis toolset.

   

3. Set the following parameters on the Parameters tab:
   1. Select the cdc_places_depression layer as the Target Features.
   2. Select the usa_geodemographic_embeddings layer as the Embedding Features.
   3. Set the Output Embeddings Feature Class that will contain the merged embeddings. In this case, the output must be placed inside a Geodatabase for the Merge Embeddings tool to work.

   

   Tip:

   To learn more about merging embeddings and why a Geodatabase output is required, refer to the How Merge Embeddings works documentation. Additionally, embeddings in ArcGIS Pro are stored in Blob fields, reference for which you can find in the Embeddings in BLOB fields documentation.

4. Click Run.

   As soon as the processing completes, the output feature class is added to the map. You can right-click on the layer and open the Attribute Table to see a new field called Embedding added to the layer. This is a Blob field where the merged embeddings are stored serially for each of the counties.

   

   

Use the Extract Embedding To Fields tool

To apply the merged embeddings for estimation of depression crude prevalence rates, you'll use the Train Using AutoML tool that expects the embedding dimensions as individual columns instead of a Blob field. Follow the steps below:

1. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Extract Embedding To Fields tool under the Embeddings Based Analysis toolset.

   

2. Set the following parameters on the Parameters tab:
   1. Select the cdc_places_depression_merge_embed layer as the Input Features.
   2. Set the Output Features that will contain the extracted embedding fields. In this case, the output must be placed inside a Geodatabase for the Extract Embedding To Fields tool to work.
   3. Select the Blob type Embedding field as the Embedding Field.
   4. Specify the string which will define how the column names start with in the extracted embedding field columns as the Output Field Prefix.

   

   Tip:

   To learn more about extracting embedding fields, refer to the How Extract Embedding to Fields works documentation.

3. Click Run.

   As soon as the processing completes, the output feature class is added to the map. You can right-click on the layer and open the attribute table to see the individual extracted emb_ fields added to the dataset.

   

4. Repeat the same for the predict_depression_merge_embed layer to add the extracted embedding dimensions.

Use the Train Using AutoML tool to find prevalence rates

To train the machine learning model for estimating the depression crude prevalence rates, follow these steps:

1. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Train Using AutoML tool under the Feature and Tabular Analysis toolset.

   

2. Set the following parameters on the Parameters tab:
   1. Select the cdc_places_depression_extract_embed layer as the Input Training Features.
   2. Set the Output Model in a folder of your choice.
   3. Select the DEPRESSION_CrudePrev field as the Variable to Predict.
   4. Select all the extracted embedding field columns beginning with emb_ from the drop-down menu as the Explanatory Training Variables.
   5. Leave everything else as default.

   

3. Click Run.

Use the Predict Using AutoML tool

Follow the steps below to estimate the depression crude prevalence rates for the red-marked counties in the predict_depression_extract_embed layer:

1. Right-click the predict_depression_extract_embed layer and open Attribute Table. Then, right-click the field named Embedding and click Delete. This will drop the Blob type Embedding field that is not required during the prediction stage.

   

2. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Predict Using AutoML tool under the Feature and Tabular Analysis toolset.

   

3. Set the following parameters on the Parameters tab:
   1. Select the model dlpk that you saved in the Train Using AutoML step as the Model Definition.
   2. Set Prediction Type to Predict feature.
   3. Select the predict_depression_extract_embed layer as the Input Prediction Features.
   4. Set the Output Prediction Features to a feature class where the estimated depression crude prevalence rates will be saved.
   5. The Match Explanatory Variables will populate by default using the embedding fields used for training.
   6. Leave everything else as default.

   

4. Click Run.

   As soon as prediction completes, the output layer is automatically added to the map, and the estimated depression crude prevalence rates can be visualized.

   

   Note:

   The missing crude prevalence rates of depression for these counties can also be predicted using the Predict Missing Values Using AI Model tool.

Embeddings for model enhancement

In this example, the USA Geodemographic Embeddings are used alongside the original predictor variables in a dataset to enhance downstream model performance and improve prediction accuracy.

The California Housing Prices dataset, is used for this example. It is a point dataset that represents the block level aggregated housing prices in California. Various explanatory variables that influence housing prices in a block like total number of rooms in the block (total_room), total number of bedrooms in the block (total_bedr), and so on are originally present in the dataset.

However, these original predictors are only able to predict the median housing prices with a certain degree of accuracy. To boost the accuracy further, you'll add additional explanatory variables in the form of USA Geodemographic Embeddings.

Add more variables with a spatial join

To add more explanatory variables, complete the following steps:

1. Browse to Tools on the Analysis tab.

   

2. Click the Toolboxes tab in the Geoprocessing pane, select Analysis Tools, and open the Spatial Join tool under the Overlay toolset.

   

3. Set the following parameters on the Parameters tab:
   1. Select the Raw Housing Prices layer on which the embeddings are to be joined as the Target Features.
   2. Select the usa_geodemographic_embeddings layer as the Join Features.
   3. Set the Output Feature Class to a feature class inside a Geodatabase where the points with embeddings will be saved.
   4. Leave everything else as default.

   

4. Click Run.

   After processing, the output layer is added to the map. This layer has the original explanatory variables along with the joined embeddings. You can visualize the Attribute Table of the layer to see the joined emb_ columns.

   

Use the Prepare Data for Prediction tool

The next step is to prepare the training and testing datasets from this embedding-enriched California Housing Prices dataset. Follow the steps below:

1. Click the Toolboxes tab in the Geoprocessing pane, select Spatial Statistics Tools, and open the Prepare Data for Prediction tool under the Modeling Spatial Relationships toolset.

   

2. Set the following parameters on the Parameters tab:
   1. Select the Embedding_Housing_Prices layer produced in the Spatial Join step as the Input Features.
   2. Set the Output Features to a feature class inside a Geodatabase where the training points with embeddings will be saved.
   3. Set the Splitting Type to Random Split.
   4. Set the Output Test Subset Features to a feature class inside a Geodatabase where the testing points with embeddings will be saved.
   5. Select the median house price variable median_hou as the Variable to Predict.
   6. Select all the original explanatory variables and the emb_ columns as the Explanatory Variables. Categorical fields such as ocean_prox are automatically checked.
   7. Set the Percent of Data as Test Subset to 20 for an 80:20 train:test split.
   8. Leave everything else as default.

   

3. Click Run.

   After the tool runs, the train and test layers are added to the Map.

Use the Train Using AutoML tool for house prices

To train the machine learning model for predicting the median house prices, follow these steps:

1. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Train Using AutoML tool under the Feature and Tabular Analysis toolset.

   

2. Set the following parameters on the Parameters tab:
   1. Input Training Features—Select the Embedding_Housing_Prices_Train layer.
   2. Output Model—Set the output trained model in a folder of your choice.
   3. Variable to Predict—Select the median_hou field.
   4. Explanatory Training Variables—Select all the original explanatory variables and the embedding field columns beginning with emb_ from the drop-down menu.
   5. Leave everything else as default.

   

3. Click Run.

Use the Predict Using AutoML tool for the testing set

Follow the steps below to predict the median housing prices for the testing set in the Embedding_Housing_Prices_Test layer:

1. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Predict Using AutoML tool under the Feature and Tabular Analysis toolset.

   

2. Set the following parameters on the Parameters tab:
   1. Select the model dlpk that you saved in the Train Using AutoML step as the Model Definition.
   2. Set the Prediction Type to Predict Feature.
   3. Select the Embedding_Housing_Prices_Test layer as the Input Prediction Features.
   4. Set the Output Prediction Features to a feature class where the predicted median house prices will be saved.
   5. The Match Explanatory Variables will populate by default using the original variables and embedding fields used for training.
   6. Leave everything else as default.

   

3. Click Run.

   As soon as prediction completes, the output layer is automatically added to the map, and the predicted median housing prices can be visualized.

   

4. Repeat the Train Using AutoML and Predict Using AutoML steps using only the original predictor variables to see the difference in results.

   The following plot shows the difference in model performance (R² scores) between Raw Predictions using only the original predictors and Embedding Predictions using both the original predictors and the embeddings.

   

   Tip:

   To learn about making charts in ArcGIS Pro, refer to the Make a chart documentation.

Embeddings for similarity search

Another way to use the USA Geodemographic Embeddings is for retrieval tasks or finding similar features using a query embedding hex-bin.

In this example, you'll try to retrieve university hex-bins across the United States that are similar to a query university embedding hex-bin using embedding-aware ArcGIS Pro tools.

Ensure you have added the USA Geodemographic Embeddings feature layer to the map.

Select a query hex-bin

To select a query hex-bin, complete the following steps:

1. Browse to Select on the Map tab.

   

2. Zoom to the Arizona State University campus and click to select a hex-bin from the usa_geodemographic_embeddings layer.

   You'll see the selected hex-bin highlighted in blue.

   

3. Right-click the usa_geodemographic_embeddings layer and select Make Layer From Selected Features under Selection.

   

   You'll see a layer called usa_geodemographic_embeddings selection appear in the Contents pane.

   

4. Browse to Clear on the Map tab to clear the selection.

   

Use the Find Similar Features Using Embeddings tool

To find similar features, complete the following steps:

1. Click the Toolboxes tab in the Geoprocessing pane, select GeoAI Tools, and open the Find Similar Features Using Embeddings tool under the Embeddings Based Analysis toolset.

   

2. Set the following parameters on the Parameters tab:
   1. Select the usa_geodemographic_embeddings layer as the Embedding Features.
   2. Select the usa_geodemographic_embeddings selection layer as the Embedding Features.
   3. Set the Output Embeddings Feature Class to a feature class inside a Geodatabase where the similar university results will be stored.
   4. Set a similarity score Threshold (cosine similarity score) of 0.85 to return similar university embedding vectors whose cosine similarity score with the query university embedding vector is greater than or equal to the threshold value.

   

3. Click Run.

   After the completion of the tool run, the similar_universities output layer will be added to the map.

4. Right-click the similar_universities output layer and open Attribute Table. Scroll to the right and find the column SIMILARITY.

   This column represents the cosine similarity scores between the query embedding vector and the matched similar embedding vector above the Threshold.

   

   Inspect the hex-bins with high SIMILARITY scores by zooming in to their locations. They will be the similar university hex-bins. Some example outputs are shown below.

   

   Tip:

   You could also try the Find Similar pane to find similar features based on embeddings on the fly without using geoprocessing tools. Refer to the Find Similar pane documentation for the implementation steps.