Calculates the number of patches (NUM), largest patch size (LRG), average patch size (AVG), the number of patches per square kilometer (DENS), and proportion of largest patch area to total patch area (PLGP) within each reporting unit for selected land cover classes and creates an output table. Minimum patch size and maximum patch separation are provided by the user.

Optionally, Mean Distance to Closest Patch (MDCP) within each reporting unit for selected land cover classes may also be calculated.

• 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: This tool is resource-intensive in terms of both processing time and disk space. Processing time varies depending on the extent and resolution of the input Land cover grid, the number of reporting units, and the number of classes selected for processing. To minimize processing time, consider creating a new Reporting unit feature layer that does not include unwanted reporting units. Also select only the land cover classes in the Report metrics for these classes parameter that are important for analysis. This tool creates multiple interim rasters and other data layers during processing which may consume considerable disk space in the Scratch Workspace. If the Scratch Workspace resides on a disk with limited disk space, the tool may fail during processing. To prevent this, consider changing the Scratch Workspace in Environments > Workspace > Scratch Workspace to a location with sufficient available disk space, or free up disk space on the disk in which the current Scratch Workspace resides to accommodate the interim datasets.

• 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 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 Values Window in the Land Cover Classification Editor for more information on excluded values.

• Minimum patch size sets the lower threshold of connected grid cells necessary to be considered a distinct patch. An eight-cell neighborhood is used to determine connectivity.

• The Maximum separation is the maximum distance in raster cells for disjunct patches to be considered continuous. The default is zero, requiring all cells in a patch to be continuous.

  • NOTE: Due to the nature of the algorithm, the number entered is half the amount used in processing. For example, entering a 1 will result in patches 2 cells apart to be considered continuous.

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

  • [class Id]_PLGP - proportion of largest patch area to total patch area for the selected class within the reporting unit (e.g. "for_PLGP" is the name of the field for the proportion of largest forest patch area to all forest area within the reporting unit for the NLCD "Forest" class).

  • [class Id]_NUM - The number of distinct patches for the selected class within the reporting unit (e.g. "nat_NUM" is the name of the field for the patch number metric for the NLCD "All natural land use" class).

  • [class Id]_LRG - The size in squared map units of the largest class patch within the reporting unit (e.g. "agr_LRG" is the name of the field for the largest patch metric for the NLCD "All agriculture" class).

  • [class Id]_AVG - The average size in squared map units of all of the selected class patches within the reporting unit (e.g. "shb_AVG" is the name of the field for the average patch metric for the NLCD "Shrubland" class).

  • [class Id]_DENS - The density of the selected class patches within the reporting unit given as the number of patches per square kilometer (e.g. "wtl_DENS" is the name of the field for the patch density metric for the NLCD "All wetland" class).

  • 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]_PLGP field name is presented in the Report metrics for these classes.

  • When the MDCP option is selected:

    • [class Id]_MDCP - measures the shortest edge-to-edge distance between distinct patches and calculates the mean value in the reporting unit.

    • NOTE: The [class Id]_MDCP field will populated with a value of -9999 when no patches of [class Id] are located in the reporting unit.

• In Additional Options, the user may elect to 'Add Quality Assurance Fields', and/or 'Retain Intermediate Layers Generated During Metric Processing'.

  • Add Quality Assurance Fields

    • Choosing QAFIELDS adds a number of fields to the Output table to facilitate quality assurance checking.

      • PM_OVER - The percent overlap between the Reporting unit feature layer and the Land cover grid for each reporting unit.

      • PM_TOTA - The total raster zonal area for each reporting unit (zone) after the Reporting unit feature layer has been rasterized.

      • PM_EFFA - The effective raster area of each reporting unit (zone) after excluded classes have been removed.

      • PM_EXCA - The raster area of the excluded classes within each reporting unit (zone) based on exclusions in the Land cover classification scheme.

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

      • pm_[class Id]_PatchRast# (raster) - Rasters created for each class selected in the Report metrics for these classes parameter of the tool with values corresponding to the following scheme: -9999 = Excluded, 0 = Other, and 1 thru n = a numbered patch.

        • The processes involved in creating this raster are as follows:

          1. Reclass the input land cover grid so that cells representing the selected class = 3, cells with values marked as excluded = -9999, and all other land cover cells = 0.
          2. If a Maximum separation value is NOT provided: Assign unique values to each distinct clump of class cells by use of the regiongroup command using the eight neighbor rule to determine connectivity.
          3. If a Maximum separation value is provided: Create a single value class raster by setting to NULL cells in the reclassed raster with values less than 3. Use a euclidean distance operation on the class patch/NULL raster to buffer the classes out by the supplied maximum separation distance. Assign unique values to each distinct clump of class cells by use of the regiongroup command using the eight neighbor rule to determine connectivity. Trim the buffered regiongroup patches to the original boundaries of the patch clumps by use of the con statement and the reclass grid (if it's a patch in the reclass grid (i.e., its value = 3) assign it the regiongroup number, else leave the other values (-9999, 0) alone.
          4. If a Minimum patch size value is provided: Eliminate all patches below the Minimum patch size (i.e., any regiongroup patch with COUNT field entry less than the Minimum patch size, set its VALUE field entry to 0).
          5. Add the excluded class areas back to the raster if any are indicated.

      • pm_[class Id]_PatchPoly# (vector) - A polygon feature class of all patches of [class Id] derived from the pm_[class Id]_PatchRast# using the Raster to Polygon conversion operation. The Simplify polygons option was unchecked to force the polygon edges to conform to the cell boundaries of the input raster. The gridcode field contains the unique identifier for each distinct patch.

      • pm_[class Id]_PatchPoly_Diss# (vector) - A polygon feature class of all patches of [class Id] after performing a Dissolve on the pm_[class Id]_PatchPoly# feature class using gridcode as the dissolve field. Gridcode is the unique identifier for each distinct patch.

        • NOTE: Due to the complex pattern of some patches, the dissolve function may not create a single multipart polygon for each distinct patch. A quick check to see if duplicate values are found in the gridcode field by using either the Frequency tool or by the field Summarize... option.

      • pm_[class Id]_PatchCentroids# (vector) - A point feature class depicting the cell centroids of cells delimiting patches in the pm_[class Id]_PatchRast# raster with the unique patch identifier found in the grid_code field.

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

PM (Reporting_unit_feature, Reporting_unit_ID_field, Land_cover_grid, Land_cover_classification_scheme, Land_cover_classification_file, Report_metrics_for_these_classes, Minimum_Patch_Size, Maximum_Separation, Output_table, {MDCP}, {Processing_cell_size}, {Snap_raster}, Select_options, {Reduce_land_cover_grid_to_smallest_recommended_size})

Patch Metrics Views example 1 (Python window)

This example creates a table with the number of patches (NUM), largest patch size (LRG), average patch size (AVG), the number of patches per square kilometer (DENS), and proportion of largest patch area to total patch area (PLGP) within each reporting unit for the forest land cover class as defined in the 'NLCD LAND' land cover classification file. Patches needed to be clumps of four or more connected cells, but adjacent patches would be considered connected if they were within the maximum patch separation distance. The option to include the quality assurance fields and to retain the intermediate calculation files was selected.

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\Watersheds"
Reporting_unit_ID_field = "HUC_12"
Land_cover_grid = r"D:\pyexamples\data.gdb\NLCD_2016"
Land_cover_classification_scheme = "NLCD LAND"
Land_cover_classification_file = r"D:\Destination Folder\ToolboxSource\LandCoverClassifications\NLCD LAND.xml"
Report_metrics_for_these_classes = "'for  -  [for_PLGP]  Forest'"
Minimum_Patch_Size = "4"
Maximum_Separation = "2"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_PM"
MDCP = "true"
Processing_cell_size = "30"
Snap_raster = r"D:\pyexamples\data.gdb\NLCD_2016"
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation';'QAFIELDS  -  Add Quality Assurance Fields'"
Reduce_land_cover_grid_to_smallest_recommended_size = "false"

metric.runPatchMetrics(Reporting_unit_feature,
                       Reporting_unit_ID_field,
                       Land_cover_grid,
                       Land_cover_classification_scheme,
                       Land_cover_classification_file,
                       Report_metrics_for_these_classes,
                       Minimum_Patch_Size,
                       Maximum_Separation,
                       Output_table,
                       MDCP,
                       Processing_cell_size,
                       Snap_raster,
                       Select_options,
                       Reduce_land_cover_grid_to_smallest_recommended_size)

Patch 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 output table
Started: yyyy-mm-dd hh:mm:ss Setting up environment variables
Intermediates are stored in this directory: D:\pyexamples\results.gdb
Time: yyyy-mm-dd hh:mm:ss Creating Patch Grid for Class:for
Time: yyyy-mm-dd hh:mm:ss Reclassing land cover to Class:for = 3, Other = 0, and Excluded = -9999...
Time: yyyy-mm-dd hh:mm:ss Connecting clusters of Class:for within maximum separation distance...
Time: yyyy-mm-dd hh:mm:ss Assigning unique numbers to each unconnected cluster of Class:for...
Time: yyyy-mm-dd hh:mm:ss Eliminating clusters below minimum patch size...
Time: yyyy-mm-dd hh:mm:ss Patch Grid Completed for Class:for
Time: yyyy-mm-dd hh:mm:ss Calculating Patch Numbers by Reporting Unit for Class:for
1 out of 4 loops, 25.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
2 out of 4 loops, 50.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
3 out of 4 loops, 75.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
4 out of 4 loops, 100.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
Time: yyyy-mm-dd hh:mm:ss Patch analysis has been run for Class:for
Time: yyyy-mm-dd hh:mm:ss Calculating MDCP for Class:for
Time: yyyy-mm-dd hh:mm:ss Converting raster patches to polygons...
Time: yyyy-mm-dd hh:mm:ss Dissolving patch polygons by value field...
Time: yyyy-mm-dd hh:mm:ss Converting raster patch cells to centroid points...
Time: yyyy-mm-dd hh:mm:ss Analyzing MDCP by reporting unit...
1 out of 4 loops, 25.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
2 out of 4 loops, 50.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
3 out of 4 loops, 75.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
4 out of 4 loops, 100.0% complete, hh:mm:ss elapsed, est. hh:mm:ss remaining, average time per loop: hh:mm:ss
Time: yyyy-mm-dd hh:mm:ss MDCP analysis has been run for Class:for
Succeeded at Day, Month dd, yyyy hh:mm:ss AM/PM (Elapsed Time: ##.## units)

There are no tags for this item.

There are no credits for this item.

There are no access and use limitations for this item.

Top of the page     |     Neighborhood Proportions     |     People in the Landscape