Part 2 - Where to enrich? (what are study areas?)

Enriching Study Areas¶

GeoEnrichment uses the concept of a study area to define the location of the point or area that you want to enrich with additional information or create reports about. The accepted forms of study areas are:

1. Street address locations
   • a. Single line input
   • b. Multiple field input
2. Point, line and polygon geometries
3. Buffered study areas
4. Named statistical areas

Before we look at the exmaples of study areas, let's understand the concept of Data collections and analysis variables. We will look at Data collections in detail in a later section.

Data collections and analysis variables¶

GeoEnrichment uses the concept of a data collection to define the data attributes (analysis variables) returned by the enrichment service. A data collection is a preassembled list of attributes that will be used to enrich the input features. Collection attributes can describe various types of information, such as demographic characteristics and geographic context of the locations or areas submitted as input features. We will introduce the concept of data collections here and look at the details in the next guide.

The Country class can be used to discover the data collections, sub-geographies and available reports for a country. When working with a particular country, you will find it convenient to get a reference to it using the Country.get() method.

The data_collections property of a Country object lists a combination of available data collections and analysis variables for each data collection as a Pandas dataframe.

Once we know the data collection we would like to use, we can look at all the unique analysisVariable available in that data collection.

Each data collection can have multiple analysis variables as seen in the table above. Every such analysis variable has a unique ID, found in the analysisVariable column. When calling the enrich() method, these analysis variables can be passed in the data_collections and analysis_variables parameters.

You can filter the data_collections and query the collections analysis_variables using Pandas expressions.

The snippet below shows how you can query the Age data collection and get all the unique analysisVariables under that collection.

Now, let's look at some examples of enriching each of the study areas.

Enriching street address¶

Street address locations can be passed as strings of input street addresses, points of interest or place names. A street address can be passed as a single line or as a multiple field input. If a point (e.g. a street address) is used as a study area, the service will create a 1 mile ring buffer around the point to collect and append enrichment data.

The example below uses a street address as a study area for enrichment using Age data collection.

Single line address¶

Visualize results on a map¶

The returned spatial dataframe can be visualized on a map as shown below:

A buffer of 1 mile is created by default, as seen on this map, for any address.

Multiple addresses as single line input

Multiple field input¶

Enriching with various analysis variables for age such as FEM45, FEM50, FEM65 etc.

Enriching point, line and polygon geometries¶

Point geometries can be passed as x and y coordinates to study_areas parameter. When points are specified as study areas, the service will analyze map areas surrounding or associated with the input point locations. Unless otherwise specified, the service will analyze a one mile ring around a point. This is also true for a line. Locations can also be given as polygon geometries.

Single Point described as map coordinates¶

Multiple points with attributes described as map coordinates¶

Line feature described as geometry¶

Visualize results on a map¶

The returned spatial dataframe can be visualized on a map as shown below:

We can clearly see the line and a 1 mile buffer around the line in this map

Map area described as polygons¶

Enriching Buffered study areas¶

BufferStudyArea instances are used to change the ring buffer size or create drive-time service areas around points specified using one of the above methods. BufferStudyArea allows you to buffer point and street address study areas. They can be created using the following parameters:

    * area: the point geometry or street address (string) study area to be buffered
    * radii: list of distances by which to buffer the study area, eg. [1, 2, 3]
    * units: distance unit, eg. Miles, Kilometers, Minutes (when using drive times/travel_mode)
    * overlap: boolean, uses overlapping rings/network service areas when True, or non-overlapping disks when False
    * travel_mode: None or string, one of the supported travel modes when using network service areas

BufferStudyArea also allows you to define drive time service areas around points as well as other advanced service areas such as walking and trucking.

Buffering location using driving distance¶

The example below creates disks of radii 1, 3 and 5 Miles respectively from a street address and enriches these using the 'Age' data collection.

Visualize results on a map¶

The returned spatial dataframe can be visualized on a map as shown below:

Buffering location using drive times¶

The example below creates 5 and 10 minute drive times from a street address and enriches these using the 'Age' data collection.

Visualize results on a map¶

The returned spatial dataframe can be visualized on a map as shown below:

Enriching a named statistical area¶

In all previous examples of different study area types, locations were defined as either points or polygons. Study area locations can also be passed as one or many named statistical areas. This form of study area lets you define an area as a standard geographic statistical feature, such as a census or postal area, for example, to obtain enrichment information for a U.S. state, county, or ZIP Code or a Canadian province or postal code. We will explore Named statistical areas in detail in the next section.

Enriching a zip code¶

Enriching zip code 92373 in California using the 'Age' data collection:

Visualize results on a map¶

The returned spatial dataframe can be visualized on a map as shown below:

Enriching all counties in a state¶

Visualize results on a map¶

Using comparison levels¶

Using comparison_levels the information for the study areas can also be compared with standard geography areas in other levels. For example, if the study area is a zip code, you can compare enriched information for this zip code with information for the county or the state.

Example 1

Let's look at an example of enriching a zip code (study area) and then comparing its enrichment information with information for the county to which the zip code belongs using comparison_levels.

The first row in the table above shows data for the requested zip and the second row has the data it was compared against - US.counties. We can see how using County as the comparison_level, we are able to compare the enriched study area (zip code) with information for the county it was compared to.

Example 2

Let's look at another example. In this example below, the 92373 zip code in Redlands intersects with both Riverside and San Bernardino counties in California. Hence, when using comparsion_levels both these counties are returned along with the results for the named zip code. We can also add State to the list of comparsion_levels to output results for counties and well as states.

To understand how the data is different between the zip code, the two counties and the state, let's plot the male to female ratio for ages 80-85.

From the above plot, we can see minor difference in the male/female ratio between two counties, the state and Redlands (Zip=92373).

Enriching Arbitrary Geometries¶

Enrichment not only works on clearly defined geometries such as county or state boundaries but it can also power arbitrary goemetires (random polygon on a map or an area covering parts of different counties etc.) just as well. Let's look at an example of how an arbitrary geometry can be enrich()ed.

In this example, we will:

1. Draw a map of Los Angeles, CA
2. Ask the user to draw a polygon on the map
3. Enrich the polygon drawn by the user
4. Visualize enriched geometry on a map

Create a Map¶

Enable User Input¶

Here, we will define a callback function that enables user input. If no input is provided, a default polygon geometry will be enriched.

Now, run the cell below and then draw a polygon on la_map, finish drawing by double clicking the mouse pointer. If no map is drawn within 30 seconds, a default polygon geometry will be used for enrichment.

Enrich Drawn Geometry¶

Visualize Enriched Geometry¶

We can clearly see the enriched geometry on this map. Clicking on the geometry will display enriched features.

Conclusion¶

In this part of the arcgis.geoenrichment module guide series, you were introduced to the concept of study areas and how Geoenrichment uses a study area to define the location of the point, polyline or area that you want to enrich. You have also seen in detail how different types of study areas can be enriched and visualized on a map.

In the subsequent pages, you will learn about:

1. Exploring Named Statistical Areas (explains where to enrich continued)
2. Data Collections and GeoEnrichment coverage (explains what datasets/variables to enrich with)
3. Generating Reports
4. Standard Geography Queries