Tool Population Land Cover Views - USEPA/ATtILA2 Wiki

Population Land Cover Views

Summary

Estimates the percentage of the population in each reporting unit that have potential views of selected land cover classes within a given distance from their location and creates an output table. A land cover class is visible if it is found within the neighborhood defined by the View radius and in a group of cells larger than or equal to the Minimum visible patch size. The Minimum visible patch size and View radius are provided by the user. The neighborhood is circular in shape.

Additional fields for total population count within the reporting unit, the total population count in the reporting unit with potential views, the total population count in the reporting unit without potential views, and the percentage of the total population in the reporting unit without potential views are also output.

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 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 the extent of the Reporting unit feature is smaller than that of the Land cover grid, the user may wish to check the Reduce land cover grid to smallest recommended size option. This creates a temporary land cover raster with the processing extent equal to that of the Reporting unit feature 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 the Values Window in the Land Cover Classification Editor for more information on excluded values.

  • The Population raster assumes the grid cell value to be the population count for the grid cell.

  • The View radius defines the circular neighborhood to determine visiblity of a land cover class. It is a straight-line distance only and is not a viewshed analysis parameter.

    • NOTE: Only a single cell of the land cover class needs to be in the View radius of the focal cell for the focal cell to be categorized as 'Potential View Area'.
  • Field names in the Output table are as follows:

    • RU_POP - The population for the reporting unit.

    • [class Id]_PV_C - The population count within the reporting unit with potential views of the selected class (e.g. "for_PV_C" is the name of the field for the population count within the reporting unit with potential views of forest land cover).

    • [class Id]_PV_P - The proportion of the population within the reporting unit with potential views of the selected class (e.g. "for_PV_P" is the name of the field for the proportion of the population with potential views of forest land cover within the reporting unit).

    • [class Id]_MV_C - The population count within the reporting unit with zero or minimal views of the selected class (e.g. "for_PV_C" is the name of the field for the population count within the reporting unit with zero or minimal views of forest land cover).

    • [class Id]_MV_P - The proportion of the population within the reporting unit with zero or minimal views of the selected class (e.g. "for_MV_P" is the name of the field for the proportion of the population with zero or miminal views of forest land cover within the 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.

    • NOTE: Only the [class Id]_PV_C field name is presented in the Report metrics for these classes.

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

        • plcv_[class Id]_ViewPatch_# (raster) - Rasters created from the Land cover grid for each class selected in the Report metrics for these classes parameter of the tool with reclassed values corresponding to the following scheme: 1 = [class Id], 0 = Other. Patches of [class Id] below the Minimum visible patch size have been eliminated (i.e., set to 0).

        • plcv_[class Id]_ViewArea_# (raster) - Rasters created by performing a focal statistics sum on the plcv_[class Id]_ViewPatch_# raster using a circular neighborhood of View radius. The resulting rasters where then reclassified into a single-value raster where 1 = Potential View Area of [class Id]. All other areas were set to NoData.

          • NOTE: Only a single cell of [class Id] needs to be in the View radius of the focal cell for the focal cell to be categorized as 'Potential View Area'.
        • plcv_[class Id]_ViewAreaPoly_# (vector) - A polygon feature class produced by performing a raster to polygon conversion of plcv_[class Id]_ViewArea_#.

        • plcv_[class Id]_ViewPopulation_# (raster) - A copy of Population raster extracted for the plcv_[class Id]_ViewAreaPoly_# area.

        • plcv_[class Id]_ViewPopulationByRU_# (table) - A table of the population count in potential view areas within each reporting unit. The table is produced by performing 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 plcv_[class Id]_ViewPopulation_# as the in_value_raster, and 'Sum' as the statistics_type.

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

Syntax

PLCV (Reporting_unit_feature, Reporting_unit_ID_field, Land_cover_grid, Land_cover_classification_scheme, Land_cover_classification_file, Report_metrics_for_these_classes, View_radius, Minimum_visible_patch_size, Population_raster, Output_table, {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
Land_cover_grid The raster dataset representing land cover classes to be summarized within each Reporting unit feature.

The grid input must be an integer raster layer.
Raster Layer
Land_cover_classification_scheme The land cover classification schemes included in ATtILA and a User Defined option.

The default schemes correspond to common input land cover datasets. Two schemes are supplied for each dataset included in ATtILA:

  • {DATASET NAME} ALL - includes all land cover types in the grid with no exclusions.
  • {DATASET NAME} LAND - excludes non-terrestrial land cover types.
String
Land_cover_classification_file The full pathname to the user-defined .xml file for custom or non-standard land cover classification schemes.

Pathname is automatically filled when a default scheme is selected.
File
Report_metrics_for_these_classes A list of the land cover classes and metric combinations for processing.

Check the box to calculate metrics for each land cover class and/or combination class desired within the reporting units.
Multiple Value
View_radius The radius of the view neighborhood, measured in number of grid cells. The neighborhood is circular in shape.

The input must be an integer value.
Long
Minimum_visible_patch_size The minimum patch size, measured in number of grid cells, necessary to be considered a visible patch.

Connectivity is defined within the immediate eight-cell neighborhood. Cells of the same class to the right, left, above, below, or diagonal to each other are considered as part of the same patch.

The input must be an integer value.
Long
Population_raster The raster dataset that contains population data.

The grid input can be either an integer or floating-point raster layer.
Raster Layer
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) One tool option is available to provide additional information:

  • Retain Intermediate Layers Generated During Metric Calculation - Saves the intermediate data layers that are normally deleted after processing is complete.
Multiple Value

Code Samples

Population Land Cover Views example 1 (Python window)

This example returns a table with the percentage of the population in each reporting unit that have potential views of forest land cover within 50 meters from their location. The forest class is visible if it is in a group of cells larger than or equal to one cell. Additional fields for total population count within the reporting unit, the total population count in the reporting unit with potential views, the total population count in the reporting unit without potential views, and the percentage of the total population in the reporting unit without potential views are also output.

NOTE: ATtILA tools that utilize the Report metrics for these classes parameter will clear all class selections when the tool is opened. This results in setting any variable set for that parameter to None when calling the tool from a script. Because of this, the standard scripting syntax (e.g. arcpy.ATtILA.LCP(variable 1, variable 2, variable 3, etc.) will fail. To overcome this idiosyncrasy, use the scripting example provided below. When using this technique, all variables are passed in as strings.

import arcpy
from arcpy.sa import *
arcpy.ImportToolbox(r"D:\Destination Folder\ATtILA v2.tbx")
from ATtILA2 import metric

Reporting_unit_feature = r"D:\pyexamples\data.gdb\Blockgroups"
Reporting_unit_ID_field = "bgrp"
Land_cover_grid = r"D:\pyexamples\data.gdb\MULC_2017"
Land_cover_classification_scheme = "MULC Blended Levels ALL"
Land_cover_classification_file = r"D:\Destination Folder\ToolboxSource\LandCoverClassifications\MULC Blended Levels ALL.xml"
Report_metrics_for_these_classes = "'for  -  [for_PV_C]  Trees/Forest, and Woody Wetlands'"
View_radius = "50"
Minimum_visible_patch_size = "1"
Population_raster = r"D:\pyexamples\data.gdb\DASY_Population"
Output_table = r"D:\pyexamples\results.gdb\Blockgroup_PLCV"
Processing_cell_size = "1"
Snap_raster = r"D:\pyexamples\data.gdb\MULC_2017"
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation'"

metric.runPopulationLandCoverViews(Reporting_unit_feature,
                                   Reporting_unit_ID_field,
                                   Land_cover_grid,
                                   Land_cover_classification_scheme,
                                   Land_cover_classification_file,
                                   Report_metrics_for_these_classes,
                                   View_radius,
                                   Minimum_visible_patch_size,
                                   Population_raster,
                                   Output_table,
                                   Processing_cell_size,
                                   Snap_raster,
                                   Select_options)

Population Land Cover Views 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 Calculating population within each reporting unit
Time: yyyy-mm-dd hh:mm:ss Reclassifying selected land cover class, FOR, to 1. All other values = 0...
Time: yyyy-mm-dd hh:mm:ss Save intermediate grid complete: plcv_FOR_ViewPatch_0
Time: yyyy-mm-dd hh:mm:ss Performing focal SUM on patches of FOR using 50 cell radius neighborhood...
Time: yyyy-mm-dd hh:mm:ss Reclassifying focal SUM results into a single-value raster where 1 = potential view area...
Time: yyyy-mm-dd hh:mm:ss Save intermediate grid complete: plcv_FOR_ViewArea_0
Time: yyyy-mm-dd hh:mm:ss Converting view raster to a polygon feature
Setting geoprocessing environmental parameters for snap raster and cell size to match population raster
Time: yyyy-mm-dd hh:mm:ss Extracting population pixels within the potential view area...
Time: yyyy-mm-dd hh:mm:ss Save intermediate grid complete: plcv_FOR_ViewPopulation_0
Time: yyyy-mm-dd hh:mm:ss Calculating population within minimal-view areas for each reporting unit
Restoring snap raster geoprocessing environmental parameter to original setting
Restoring cell size geoprocessing environmental parameter to original setting
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** ⚠️