v3_Tool Population Within Zone Metrics

Population within Zone Metrics

Available with Spatial Analyst license.

Summary

Calculates percentage of total population living within or near a zone for each reporting unit polygon and creates an output table.

Counts for the total population in the reporting unit and within the zone are also reported.

Usage

NOTE: For the most accurate results and shortest processing times, it is highly recommended that all input layers be in the same spatial reference.
NOTE: Enabling the Parallel Processing Factor environment can improve computation time for several ATtILA tools, but we have detected, on rare occasions, doing so can lead to spurious results. As a precaution, ATtILA will disable the Parallel Processing Factor environment for this tool. We hope to return this choice to the user once the impact on operational speed and accuracy of swapping geoprocessing tools with their pairwise counterparts has been assessed.
This tool processes all polygons in the Reporting unit feature regardless of selections set. The ability to limit calculations to only selected reporting unit polygons is not supported in this release.
This tool processes all zone features in the Zone raster or vector feature regardless of selections set. The ability to limit calculations to only selected features is not supported in this release.
The Reporting unit feature is a zone dataset.
- A zone is defined as all areas in the input that have the same value. The areas do not have to be contiguous. The term "value" in this definition refers to the unique values in the Reporting unit ID field. Therefore, all polygons with the same reporting unit ID are treated as a single zone.
- When more than one polygon has the same reporting unit ID, the populations for each polygon are combined and metrics are reported as a single record in the Output table.
Final output is written to the location specified in the Output table parameter. The Output table may be saved as a File Geodatabase Table, or a dBASE Table.
- NOTE: For most consistent results, it is highly recommended that tool output be saved to a file geodatabase.
- When saving as a File Geodatabase Table, no extension is necessary for the Output table name. The output location must be a file geodatabase.
- When saving as a dBASE Table, include the .dbf extension in the Output table name. dBASE tables may not be saved in a file geodatabase.
When the optional Group by zone selection is checked, the tool allows the user to select a Zone ID field.
- The Zone raster or vector feature will allow you to choose either an integer raster, or a vector polygon, polyline, or point feature layer.
  - When choosing a raster, this tool assumes the grid cell value to be the population count for the grid cell.
  - When choosing a polygon feature, this tool assumes that population is distributed evenly throughout each feature polygon. The tool apportions population by area weighting. For example, if 50% of a population polygon is within a reporting unit, the tool will assign 50% of the value in the polygon's Population field to that reporting unit. Caution should be exercised when population polygons do not have even population distributions as this could result in an overweighting or underweighting of population when the tool performs the apportionment. Generally, greater accuracy will be achieved if the population polygons are smaller than the smallest Reporting unit feature polygons.
  - NOTE: The Population field dropdown is only available when the Population raster or polygon feature is a polygon feature.
  - NOTE: The Population field will default to 'Value' when the Population raster or polygon feature is an integer grid.
  - NOTE: The Population field will be empty when the Population raster or polygon feature is a non-integer grid.
Field names in the Output table are as follows:
- RU_POP - The population for the reporting unit.
- ZN_POP_C - The population in a zone within the reporting unit.
- ZN_POP_P - The percentage of the reporting unit population in a zone.
In Additional Options, the user may elect to 'Retain Intermediate Layers Generated During Metric Processing', and/or 'Record Process Steps Taken During Metric Calculation'.
- Retain Intermediate Layers Generated During Metric Calculation
  - Choosing INTERMEDIATES retains several of the key intermediate products (e.g., rasters, feature classes, tables) used to generate the final tool output. By examining the intermediate products, the user can gain a better understanding how the metric is calculated. The following intermediate products are listed in the general order they are generated:
    - pwzm_[Population raster or polygon feature]_Work_# (vector) - A copy of the Population raster or polygon feature with the Population field retained and a tmpClass field added to assist in the population calculations via a Tabulate Intersection operation. This feature class is only produced when a polygon population feature is selected.
    - pwzm_[Zone raster or vector feature]_Buffer_# (vector) - Zone raster or vector feature buffered to the Buffer distance. The attribute table will contain fields from Zone raster or vector feature, the buffer distance (BUFF_DIST), and a field named, 'ORIG_FID'. This feature class is only produced when the Zone raster or vector feature is a vector feature and a Buffer distance greater than zero is specified.
    - pwzm_populationCnt_# (table) - A table with the population count within each reporting unit.
      - If the Population raster or polygon feature is a polygon feature, the table is generated by performing a Tabulate Intersection operation using the Reporting unit feature as the Input Zone Feature, the Reporting unit ID field as the Zone Field, and the pwzm_[Population raster or polygon feature]_Work_# as the Input Class Features.
      - If the Population raster or polygon feature is a raster, the table is generated by performing a Zonal Statistics as Table operation using the Reporting unit feature as the Input raster or feature zone data, the Reporting unit ID field as the Zone field, and the Population raster or polygon feature as the Input value raster. The statistics type is "Sum" and the Ignore NoData in calculations is checked.
      - The population count for the reporting unit is calculated first before the zone population count and will have the lower of the two incremental filename values (i.e., #) of the produced intermediate pwzm_populationCnt_# files.
    - pwzm_[Zone raster or vector feature]_Poly_# (vector) - A polygon feature class produced by setting 0-value areas in the input zone raster to NULL and then performing a raster to polygon conversion. A tmpClass field is added to assist in the population calculations. This feature class is only produced when the Zone raster or vector feature is a raster and the Population raster or polygon feature is a polygon feature or if the Group by zone option has been selected and the Population raster or polygon feature is a raster.
    - pwzm_[Zone raster or vector feature]_Dissolve_# (vector) - A polygon feature class produced by dissolving Zone raster or vector feature. This feature class is only produced if the Zone raster or vector feature is a vector feature or in the special circumstance when the Zone raster or vector feature is a raster, the Population raster or polygon feature is a raster, and the Group by zone option has been selected.
      - If the Group by zone option has been selected, the Zone raster or vector feature layer is dissolved on the Zone ID field unless the Zone raster or vector feature is a raster. In that case, the dissolve is performed on the gridcode field in the intermediate pwzm_[Zone raster or vector feature]_Poly_# layer.
      - If the Group by zone option has not been selected, all features in the Zone raster or vector feature layer are dissolved into a single multipart featue.
      - If Zone raster or vector feature was buffered, the intermediate pwzm_[Zone raster or vector feature]_Buffer_# layer is used as the input for the dissolve operation.
    - pwzm_[Zone raster or vector feature]_Identity_# (vector) - A feature class of the zone areas by reporting unit. The identity operation will be performed using the Reporting unit feature and the intermediate pwzm_[Zone raster or vector feature]_Dissolve_# layer.
    - pwzm_[Zone raster or vector feature]_Poly_#_Identity_# (vector) - A feature class of the zone areas by reporting unit. This feature class is produced when the Zone raster or vector feature is a raster and the Population raster or polygon feature is a vector. The identity operation will be performed using the Reporting unit feature and the intermediate pwzm_[Zone raster or vector feature]_Poly_# layer.
    - pwzm_[Zone raster or vector feature]_IdentityDissolve_# (vector) - A polygon feature class produced by dissolving the intermediate pwzm_[Zone raster or vector feature]_Identity_# layer by the Zone ID field and Reporting unit ID field. This feature is only produced if the Group by zone option is selected.
    - pwzm_[Zone raster or vector feature]_Poly_#_IdentityDissolve_# (vector) - A polygon feature class produced by dissolving the intermediate pwzm_[Zone raster or vector feature]_Poly_#_Identity_# layer by the Zone ID field and Reporting unit ID field. This feature is only produced if the Group by zone option is selected.
    - pwzm_populationZN_# (raster) - A population raster where grid cells within zone areas contain population values from the Population raster or polygon feature raster. Areas outside of designated zone areas are set to NoData. This intermediate product is only produced when the Population raster or polygon feature and Zone raster or vector feature are both rasters. The cell size and cell boundaries match the Population raster or polygon feature raster.
    - pwzm_populationCnt_#+1 (table) - A table with the population count within the zonal areas in each reporting unit.
      1. Raster Population and Raster Zone: this table is produced using a Zonal Statistics as Table operation with the Reporting unit feature as the in_zone_data, the Reporting unit ID field as the zone_field, the intermediate pwzm_populationZN_# as the in_value_raster, and 'Sum' as the statistics_type.
      2. Raster Population and Buffered or Non-Buffered Vector Zone: this table is produced using a Zonal Statistics as Table operation using pwzm_[Zone raster or vector feature]_Identity_# as the in_zone_data, the Reporting unit ID field as the zone_field, the Population raster or polygon feature as the in_value_raster, and 'Sum' as the statistics_type.
      3. Polygon Population and Raster Zone: this table is produced using a Tabulate Intersection operation using pwzm_[Zone raster or vector feature]_Poly_#_Identity_# as the in_zone_features, Reporting unit ID field as the zone_field, pwzm_[Population raster or polygon feature]_Work_# as the in_class_features, tmpClass as the class-fields, and Population field as the sum_fields.
      4. Polygon Population and Buffered or Non-Buffered Vector Zone: this table is produced using a Tabulate Intersection operation using pwzm_[Zone raster or vector feature]_Identity_# as the in_zone_features, Reporting unit ID field as the zone_field, pwzm_[Population raster or polygon feature]_Work_# as the in_class_features, tmpClass as the class-fields, and Population field as the sum_fields.
    - NOTE: To ensure unique filenames, intermediate filenames are typically generated using the CreateScratchName ArcPy function. This function provides a unique name for the intermediate product by appending a number to a filename prefix. The number starts at 0 and is incremented until a unique filename for the output workspace is found. The generated number is represented in this manual by the hashtag (#) symbol.
    - NOTE: The appended number may not be the same for all intermediate products saved during a tool run. Running a tool with different input options can result in different intermediate products being produced. If a tool is run more than once using the same output workspace, different number suffixes may be generated depending on the files already present in the output workspace.
  - Intermediate products are saved to one of the following locations:
    - When the Output table is saved as a File Geodatabase Table, intermediate products are placed in the same file geodatabase.
    - When the Output table is saved as a dBASE Table, a file geodatabase named "attilaScratchWorkspace" is automatically generated in the same output location specified for the Output table. Intermediate products are placed in the attilaScratchWorkspace file geodatabase.
    - NOTE: ATtILA will report the location of the saved intermediate products in the Tool Details' Messages section.
- Record Process Steps Taken During Metric Calculation
  - Choosing LOGFILE will generate a text file containing information on system setup, tool inputs, parameter selections, script operations, and any encountered error or warning messages.
  - Log files will be named, [Output table]_[date_time].txt, with the date represented as YYYYMMDD and time as hh_mm_ss.
  - Where the log file is saved is dependent on the Current Workspace environment setting:
    - When the Current Workspace is a geodatabase, the log file will be located in the folder that contains that workspace.
    - When the Current Workspace is a folder, the log file will be located in that folder.
    - NOTE: In ArcGIS Pro, the default value for the Current Workspace environments is the project default geodatabase.
    - NOTE: ATtILA will report the name and location of the log file in the Tool Details' Messages section.

Syntax

PAAA (Park_feature, {Dissolve_parks}, Cost_surface_raster, Population_raster_or_polygon_feature, {Population_field}, Maximum_travel_distance, Expand_area_served, Output_raster, {Processing_cell_size}, {Snap_raster}, {Select_options})

Parameter	Explanation	Data Type
Reporting_unit_feature	The vector polygon dataset that defines the reporting units.	Feature Layer
Reporting_unit_ID_field	The field in the Reporting unit feature layer that contains the unique ID for each reporting unit. It may be an integer or a string data type.	Field
Population_raster_or_polygon_feature	The raster or vector polygon dataset that contains population data.	Feature Layer or Raster Layer
Population_field (Optional)	The field in the Population raster or polygon feature layer that contains population data. The behavior of this parameter is dependent on the input for the Population or polygon feature: The field selection dropdown is available when the input is a polygon feature. The field selection will default to 'Value' when the input is an integer grid. The field selection will be empty when the input is a non-integer grid.	Field
Zone_raster_or_vector_feature	The integer raster or vector dataset that defines the zone. Integer Raster - raster where non-zero values define zone areas. Values of 0 represent areas outside of the zone. Vector Dataset - all polygon features are considered within the zone regardless of attributes.	Feature Layer or Raster Layer
Buffer_distance	An additional distance around the zone vector features that population counts are returned for. A valid entry for this parameter is dependent on the input for the Zone raster or vector feature: Buffers around raster zones are not permitted. Enter a value of zero. Buffers around polygon zones are not necessary. Enter a value of zero if no additional buffering is required. A buffer around point or line features is required. Enter an integer value greater than zero. If the distance linear units are not specified or are entered as Unknown, the linear unit of the input features' spatial reference is used.	Linear Unit
Group_by_zone (Optional)	Specifies whether population counts are returned for each unique intersection of reporting unit and one or more zone features. false – All input zone features are merged into a single feature. This can be considered as the population near or within any zone feature, but does not consider if there is population within multiple zones. This is the default. true – Population counts are returned for each unique intersection of reporting unit and one or more zone features. This can be considered as the population near or within each zone features. Because some areas can be in more than one overlapping zone, the population counts for each zone can sum to more than the population for the reporting unit.	Boolean
Zone_ID_field	The field in the Zone raster or vector feature layer that contains the unique ID for each zone.	Field
Output_table	The output reporting unit metrics table to be created. It is recommended that the Output table be saved within a file geodatabase.	Table
Select_options (Optional)	Tool options available to provide additional information: Retain Intermediate Layers Generated During Metric Calculation - Saves key intermediate products (e.g., rasters, feature classes, tables) used to generate the final tool output. Record Process Steps Taken During Metric Calculation - Saves a log file containing information on tool inputs, selections, and operations.	Multiple Value

Code Samples

Population Within Zone Metrics example 1 (Python window)

This example returns a table with the population count in a reporting unit that is within 2000 meters of a daycare facility, the total population count within the reporting unit, and the percentage of the reporting unit's population that is in the 2000 meter buffer area. The options to retain the intermediate calculation products, and to record the process steps into a log file have also been selected.

import arcpy
from arcpy.sa import *
arcpy.ImportToolbox(r"D:\Destination Folder\ATtILA v{#}.tbx")

Reporting_unit_feature = "D:\\pyexamples\\data.gdb\\Blockgroups"
Reporting_unit_ID_field = "GEOID10"
Population_raster_or_polygon_feature = "D:\\pyexamples\\data.gdb\\Census2010"
Population_field = "TOTALPOP"
Zone_raster_or_polygon_feature = "D:\\pyexamples\\data.gdb\\Daycares"
Buffer_distance = "2000 Meters"
Group_by_zone = ""
Zone_ID_field = ""
Output_table = "D:\\pyexamples\\results.gdb\\Blockgroups_PWZM"
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation';'LOGFILE  -  Record Process Steps Taken During Metric Calculation'" 

arcpy.ATtILA.PWZM(
                  Reporting_unit_feature,
                  Reporting_unit_ID_field,
                  Population_raster_or_polygon_feature,
                  Population_field,
                  Zone_raster_or_polygon_feature,
                  Buffer_distance,
                  Group_by_zone,
                  Zone_ID_field,
                  Output_table,
                  Select_options
                  )

Population Within Zone Metrics example 2 (Tool Details Messages)

This is a sample capture of the geoprocessing messages generated during a typical tool run. It is provided here to assist in the understanding of the tool's processing steps.


Start Time: Day, Month DD, YYYY hh:mm:ss AM/PM
Created log file: workspace path\\filename
Started: YYYY-MM-DD hh:mm:ss Setting up environment variables
Intermediates are stored in this directory: workspace path
[YYYY-MM-DD hh:mm:ss] Adding 2000 Meters buffer to Daycares. Intermediate: pwzm_Daycares_Buffer_0
[YYYY-MM-DD hh:mm:ss] Calculating population within each reporting unit. Intermediate: pwzm_populationCnt_0
[YYYY-MM-DD hh:mm:ss] Making a working copy of Census2010. Intermediate: pwzm_Census2010_Work_0
[YYYY-MM-DD hh:mm:ss] Making a working copy of Daycares. Intermediate: pwzm_Daycares_Work_0
[YYYY-MM-DD hh:mm:ss] Dissolving pwzm_Daycares_Work_1. Intermediate: pwzm_Daycares_Dissolve_0
[YYYY-MM-DD hh:mm:ss] Assigning reporting unit IDs to Daycares. Intermediate: pwzm_Daycares_Identity_0
[YYYY-MM-DD hh:mm:ss] Calculating population within zone areas for each reporting unit. Intermediate: pwzm_populationCnt_0
[YYYY-MM-DD hh:mm:ss] Calculating the percent of the population that is within a zone for each reporting unit
Start Time: Day, Month DD, YYYY hh:mm:ss AM/PM
Succeeded at Day, Month DD, YYYY hh:mm:ss AM/PM (Elapsed Time: ##.## units)
[YYYY-MM-DD hh:mm:ss] Calculation complete
Summarizing the ATtILA metric output table to log file
Summary complete
Log file closed