Tool Population Density Metrics - USEPA/ATtILA2 Wiki

Population Density Metrics

Summary

Calculates population count and density (people per km²) for each reporting unit polygon and creates an output table.

In addition to the default metrics, the tool optionally calculates population change over time.

Usage

  • 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.

  • The Reporting unit feature must be a polygon feature class or shapefile.

  • This tool assumes that population is distributed evenly throughout each Census feature polygon. The tool apportions population by area weighting. For example, if 50% of a Census feature 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 Census feature 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 Census feature polygons are smaller than the smallest Reporting unit feature polygons.

  • When the optional POPCHG (population change) is checked, the tool allows the user to select a Census T2 feature and a corresponding Population T2 field.

    • For best results, the Census T2 feature should contain polygons at a similar scale to that of the Census feature (e.g. if Census feature represents census block groups, then Census T2 feature should also represent census block groups rather than census tracts or some other census geography).

    • Census T2 feature may be the same feature layer as used for Census feature.

  • 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.

  • Field names in the Output table follow this naming scheme:

    • For default tool settings (e.g. no optional settings selected):

      • AREAKM2 - The area of the reporting unit in km².

      • POPCNT - The estimated total population within the reporting unit derived by area weighting the population values within each Census feature polygon that intersects with the reporting unit and summing the area-weighted values.

      • POPDENS - The estimated population density in persons per km² within the reporting unit derived by dividing POPCNT by AREAKM2.

    • When the POPCHG option is selected:

      • POPCNT_T1 - The estimated total population within the reporting unit derived by area weighting the population values within each Census feature polygon (Time 1) that intersects with the reporting unit and summing the area-weighted values.

      • POPDENS_T1 - The estimated population density in persons per km² within the reporting unit derived by dividing POPCNT_T1 by AREAKM2.

      • POPCNT_T2 - The estimated total population within the reporting unit derived by area weighting the population values within each Census T2 feature polygon (Time 2) that intersects with the reporting unit and summing the area-weighted values.

      • POPDENS_T2 - The estimated population density in persons per km² within the reporting unit derived by dividing POPCNT_T2 by AREAKM2.

      • POPCHG - The estimate percent change in population from Time 1 to Time 2.

  • In Additional Options, the user may elect to 'Retain Intermediate Layers Generated During Metric Processing'.

    • 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:

        • pdm_[Reporting unit feature]_# (vector) - A polygon feature class containing reporting units with a new area field in km² (AREAKM2).

        • pdm_[Census feature]_# (vector) - A polygon feature class of all census polygons with fields containing population, polygon area, and population density within the census polygons.

        • pdm_intersectOutput_# (vector) - A polygon feature class with Census features intersected with reporting units.

        • pdm_summaryTable_# (table) - A table of the number of intersected Census feature polygons and the sums of the area-weighted population counts within each reporting unit.

        • 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.

        • NOTE: If the optional POPCHG is selected, some intermediate products will have a "T1" or "T2" designation added to their filenames to indicate whether the products were generated for the population density calculations at Time 1 or Time 2.

      • 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.

Syntax

PDM (Reporting_unit_feature, Reporting_unit_ID_field, Census_feature, Population_field, Output_table, {POPCHG}, Census_T2_feature, Population_T2_field, {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
Census_feature The vector polygon dataset that contains population data. Feature Layer
Population_field The field in the Census feature layer that contains population data. 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
POPCHG (Optional) Specifies whether population change over time (POPCHG) metrics will be included in the output table.

  • false - No POPCHG metrics will not be included. This is the default.
  • true - POPCHG metrics will be included.
Boolean
Census_T2_feature The optional vector polygon dataset (Census time 2) that contains population data for the comparison date.

It may be the same feature layer as Census feature.
Feature Layer
Population_T2_field The field in the Census feature layer that contains population data for the comparison date. Field
Select_options (Optional) One tool option is available to provide additional information:

  • Retain Intermediate Layers Generated During Metric Calculation - Saves the intermediate table and/or raster that is normally deleted after processing is complete.
Multiple Value

Code Samples

Population Density Metrics example 1 (Python window)

This example returns a table with the population density of the reporting unit zone in capita per square kilometer along with the reporting unit's total population count and square kilometer area calculation. The option to retain the intermediate calculation products is also selected.

import arcpy
arcpy.ImportToolbox(r"D:\Destination Folder\ATtILA v2.tbx")

Reporting_unit_feature = r"D:\pyexamples\data.gdb\Watersheds"
Reporting_unit_ID_field = "HUC_12"
Census_feature = r"D:\pyexamples\data.gdb\Census2010"
Population_field = "TOTALPOP"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_PDM"
POPCHG = "false"
Census_T2_feature = ""
Population_T2_field = ""
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation'"

arcpy.ATtILA.PDM(Reporting_unit_feature,
                 Reporting_unit_ID_field,
                 Census_feature,
                 Population_field,
                 Output_table,
                 POPCHG,
                 Census_T2_feature,
                 Population_T2_field,
                 Select_options)

Population Density 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
Started: yyyy-mm-dd hh:mm:ss Setting up environment variables
Intermediates are stored in this directory: workspace path
Time: yyyy-mm-dd hh:mm:ss Creating temporary copy of Watersheds
Time: yyyy-mm-dd hh:mm:ss Creating output table
Time: yyyy-mm-dd hh:mm:ss Calculating population density
Time: yyyy-mm-dd hh:mm:ss Calculating population density for second feature class
Time: yyyy-mm-dd hh:mm:ss Calculating population change
Time: yyyy-mm-dd hh:mm:ss Calculation complete
Succeeded at Day, Month dd, yyyy hh:mm:ss AM/PM (Elapsed Time: ##.## units)

Tags

There are no tags for this item.

Credits

There are no credits for this item.

Use Limitations

There are no access and use limitations for this item.

arrow_up Page

⚠️ **GitHub.com Fallback** ⚠️