v3_Tool Population within Zone Metrics

Population within Zone Metrics

Available with Spatial Analyst license.

Summary

Insert Text

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.
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.
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 areas for each polygon are combined and metrics are reported as a single record in the Output table.
As the Reporting unit feature is a vector dataset, ArcGIS will perform a vector to raster conversion during processing.
- To better control the vector to raster conversion, the tool defaults the Snap raster and the Processing cell size to that of the Land cover grid. These may be changed from within the tool.
- If a large size disparity exists between the extents of the Reporting unit feature and the Land cover grid, the user may wish to set the Extent in Environment Settings > Processing Extent to the smaller of the two to avoid unnecessary processing.
If the Reporting unit feature has overlapping features, the zonal analysis will be performed for each individual feature.
If a feature in the Reporting unit feature zone data does not overlap any cell centers in the secondary class rasters (e.g.,Land cover grid), those zones will not get converted to the internal zone raster. As a result, those zones will not be represented in the Output table.
The Land cover classification scheme must correspond to the Land cover grid.
- Schemes for common land cover datasets are included with ATtILA. Supplied schemes may be designated as either "ALL" or "LAND" (e.g. NLCD 2001 ALL vs. NLCD 2001 LAND). Schemes designated as "ALL" include all land cover classes in reporting unit area calculations, while those designated as "LAND" include only terrestrial land cover classes, with non-terrestrial land cover classes such as water and snow/ice excluded. More information about each of the classification schemes supplied with ATtILA may be found in Supplied Land Cover Classification Schemas.
- In addition to the common land cover schemes, the tool permits a user-defined land cover classification scheme to be used by specifying a Land cover classification file. Refer to Land Cover Classification for more information on how ATtILA may be customized for user-specific needs.
- NOTE: When a classification scheme with excluded land cover classes is selected, the areas of the excluded classes are disregarded in metric calculations. For example, when selecting a "LAND" classification scheme, the tool will process individual land cover classes and calculate metrics based on the total terrestrial area they occupy within the reporting unit, rather than the percent of the total area within the reporting unit. See Values Element in ATtILA's LCC XML Document and Values Window in the Land Cover Classification Editor for more information on excluded values.
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 PER CAPITA (square meters of land cover type per individual) selection is checked, the tool allows the user to select a Population raster or polygon feature and a corresponding Population field.
- The Population raster or polygon feature will allow you to choose either a raster, or a polygon feature.
  - 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 follow this naming scheme:
- [class lcpField] or p[class Id] - The percent of the non-excluded reporting unit occupied by the land cover class.
  - [class lcpField] is used if an lcpField attribute is provided in the class's element in the selected Land cover classification file.
    - (e.g., NINDEX for <class Id="NI" Name="All Natural Land Use" filter="" lcpField="NINDEX">)
  - p[class Id] - is used if an lcpField attribute is not provided.
    - (e.g., pNI for <class Id="NI" Name="All Natural Land Use" filter="">)
- When the PER CAPITA option is selected:
  - [class lcpField]_PC or p[class Id]_PC - The area (m²) per person of the land cover class by reporting unit.
- NOTE: Output field names can be altered by editing the Land cover classification file with the Land Cover Classification Editor (Refer to Classes Element in ATtILA's LCC XML Document for general information, or the individual Land cover classification file for details).
- NOTE: The output field name for each class is shown as the second item next to the class's check box in Report metrics for these classes.
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:
    - lcp_TabArea# (table) - A table of areas corresponding to the values in the Land cover grid within each reporting unit. The name of the intermediate table has the prefix "lcpTabArea" followed by a number (e.g. lcpTabArea0, lcpTabArea1, lcpTabArea2, etc.). The number suffix is added when the table is saved in order to give each successive table a unique name when the tool is executed more than once and results saved to the same output location.
    - lcp_[Population polygon feature]# (vector) - A copy of the Population raster or polygon feature with all but its the Population field removed. A tmpClass field is added to the attribute table and populated with a value of 1 to facilitate reporting unit population calculations. This feature class is only produced when the optional PER CAPITA selection is checked and the Population raster or polygon feature is a polygon feature.
    - lcp_populationCnt# (table) - A table with the population count within each reporting unit. It is produced only when the optional PER CAPITA selection is checked.
      - 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 lcp_[Population polygon feature]# 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.
    - 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
Park_feature	The vector polygon dataset that defines the reporting units.	Feature Layer
Dissolve_parks (Optional)	Specifies whether park units that overlap or share a boundary are dissolved into a single unit (i.e., there are no barriers to movement between units). false - Park boundaries will not be dissolved. Barriers to movement exist. This is the default. true - Park boundaries will be dissolved.	Boolean
Cost_surface_raster	The raster dataset representing ... The input must be an integer raster layer.
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
Maximum_travel_distance	The maximum	Long
Expand_area_served		Long
Output_raster	The output accessibility and availability raster. It is always a floating point raster.	Raster Dataset
Processing_cell_size (Optional)	The Processing cell size for the Output raster. The default Processing cell size is the cell size of the input Cost surface raster. Optionally, the user may select a different cell size.	Analysis cell size
Snap_raster (Optional)	The raster that the cell alignment of the Output raster will be aligned to. The default Snap raster is the Cost surface raster.	Raster Layer
Select_options	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

Pedestrian Access and Availability example 1 (Python window)

This example returns a table with the proportion of the reporting unit zone comprised of agriculture and all natural land cover classes. The options to calculate the square meters of each land cover class per captia, to retain the intermediate calculation products, and to generate the quality assurance fields have also been selected.

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

Park_feature = r"D:\pyexamples\data.gdb\Parks",
Dissolve_parks = False,
Cost_surface_raster = r"D:\pyexamples\data.gdb\\SurfaceCostRaster",
Population_raster_or_polygon_feature = r"D:\pyexamples\data.gdb\CensusBlocks",
Population_field = "Pop",
Maximum_travel_distance = 800,
Expand_area_served = 3,
Output_raster = r"D:\pyexamples\results.gdb\AccessAndAvailability",
Processing_cell_size = 10,
Snap_raster = r"D:\pyexamples\data.gdb\\SurfaceCostRaster",
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation','LOGFILE  -  Record Process Steps Taken During Metric Calculation'"


arcpy.ATtILA.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)

Pedestrian Access and Availability 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] Using SurfaceCostRaster's extent for geoprocessing steps.
[YYYY-MM-DD hh:mm:ss] Using SurfaceCostRaster's spatial reference for geoprocessing steps: Albers_Conical_Equal_Area
[YYYY-MM-DD hh:mm:ss] Creating temporary copy of Parks. Intermediate: paaa_Parks_0
[YYYY-MM-DD hh:mm:ss] Collecting id values from OBJECTID for each park
[YYYY-MM-DD hh:mm:ss] Calculating park area in square meters
[YYYY-MM-DD hh:mm:ss] Calculating access and availability for 9 areas
The following steps are performed for each park:
            1) Select park by its id value and create a feature layer
            2) Create a buffer around the park extending 5% beyond the maximum travel distance
            3) Create Cost Distance raster to the Maximum travel distance with the buffer area as the processing extent
            4) Designate the accessible area by setting all cell values to 1 for any cell in the Cost Distance raster with a value >= 0
            4) Expand the accessible area if indicated by the Expand area served parameter
            5) Determine Population within accessible area
                a) if Population parameter is a raster:
                    1) Set the geoprocessing snap raster and processing cell size environments to match the population raster 
                    2) Zonal Statistics As Table with the SUM option is used to calculate the surrounding population
                b) if Population parameter is a polygon feature:
                    1) the accessible area raster is converted to a polygon
                    2) Tabulate Intersection is used with this polygon and the Population polygon feature to get 
                       an area-weighted estimate of the surrounding population
            6) Determine Availability (Cost distance value to park area divided by surrounding population)
Starting calculations per park...
1 out of 9 loops, 11.11% complete, 0:00:19 elapsed, est. 0:02:32 remaining, average time per loop: 0:00:19
2 out of 9 loops, 22.22% complete, 0:00:23 elapsed, est. 0:01:20 remaining, average time per loop: 0:00:11
3 out of 9 loops, 33.33% complete, 0:00:50 elapsed, est. 0:01:40 remaining, average time per loop: 0:00:16
4 out of 9 loops, 44.44% complete, 0:01:18 elapsed, est. 0:01:37 remaining, average time per loop: 0:00:19
5 out of 9 loops, 55.56% complete, 0:01:46 elapsed, est. 0:01:24 remaining, average time per loop: 0:00:21
6 out of 9 loops, 66.67% complete, 0:02:15 elapsed, est. 0:01:07 remaining, average time per loop: 0:00:22
7 out of 9 loops, 77.78% complete, 0:02:42 elapsed, est. 0:00:46 remaining, average time per loop: 0:00:23
8 out of 9 loops, 88.89% complete, 0:03:10 elapsed, est. 0:00:23 remaining, average time per loop: 0:00:23
9 out of 9 loops, 100.0% complete, 0:03:38 elapsed, est. 0:00:00 remaining, average time per loop: 0:00:24
Finished last park
Number of areas which did not rasterize: 1
  Ids for these areas can be found in the log file if the LOGFILE Additional option was selected.
[YYYY-MM-DD hh:mm:ss] Merging 8 calculated park/population rasters. Output: AccessAndAvailability.
Succeeded at Day, Month DD, YYYY hh:mm:ss AM/PM (Elapsed Time: ##.## units)