Tool Core and Edge Metrics - USEPA/ATtILA2 Wiki

Core and Edge Metrics

Summary

Calculates the edge-to-area ratio within each reporting unit for selected land cover classes and creates an output table. Edge width is provided by the user.

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: 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 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 rasters.

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

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

  • Edge width must be an integer value measuring the number of grid cells. For example, if the Land cover grid is at 30-meter cell resolution, an Edge width of five (5) would result in a width of (30 X 5) = 150 meters.

  • 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 caemField] or [class Id]_E2A[edge width] - The edge-to-area ratio for the land cover class within the reporting unit.

      • [class caemField] is used if a caemField attribute is provided in the class's element in the selected Land cover classification file.

        • (e.g. FOREST_EdgeRatio for <class Id="for" Name="Forest Land Cover" filter="" caemField="FOREST_EdgeRatio">)
      • [class Id]_E2A[edge width] - is used if a caemField attribute is not provided.

        • (e.g. for_E2A5 for <class Id="for" Name="Forest Land Cover" filter=""> and a five-cell edge width is used)
    • 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.

  • To describe the amounts of core and edge within each reporting unit for each selected land cover class, two ancillary fields are provided in the Output table. These field names follow the same naming scheme regarding the caemField class attribute in the Land cover classification file as described above. The ancillary field names in this Output table are as follows:

    • [class caemField]_COR[edge width] or [class Id]_COR[edge width] - The percent of the reporting unit comprised of core cells for the land cover class.

    • [class caemField]_COR[edge width] or [class Id]_COR[edge width] - The percent of the reporting unit comprised of edge cells for the land cover class.

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

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

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

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

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

        • caem_Raster[class name][edge width]_# (raster) - Rasters created for each class selected in the Report metrics for these classes parameter of the tool with reclassed values corresponding to the following scheme: 1 = Excluded, 2 = Other, 3 = Edge, 4 = Core.

        • caem_TabArea[class name][edge width]_# (table) - A table of areas corresponding to the values in the caem_Raster[class name][edge width]_# 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.

      • 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

CAEM (Reporting_unit_feature, Reporting_unit_ID_field, Land_cover_grid, Land_cover_classification_scheme, Land_cover_classification_file, Report_metrics_for_these_classes, Edge_width, Output_table, {Processing_cell_size}, {Snap_raster}, Select_options, {Reduce_land_cover_grid_to_smallest_recommended_size})

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 upon which core and edge area metrics will be derived within each Reporting unit feature.

The class 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
Edge_width The width of the edge, measured in number of grid cells.

The input must be an integer value.
Long
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
Processing_cell_size (Optional) The Processing cell size for the zonal operation.

The default Processing cell size is the cell size of the input raster land cover data. Optionally, the user may select a different cell size.
Analysis cell size
Snap_raster (Optional) The raster that the cell alignment of the Land cover grid and rasterized Reporting unit feature layer will be matched to during processing.

The default Snap raster is the Land cover grid.
Raster Layer
Select_options Three tool options are available to provide additional information:

  • Add Quality Assurance Fields - Adds area fields to the Output table to facilitate quality assurance checking.
  • Add Area Fields for All Land Cover Classes - Adds fields to the Output table that includes the areas of each land cover class and combination class selected.
  • Retain Intermediate Layers Generated During Metric Calculation - Saves the intermediate table and/or raster that is normally deleted after processing is complete.
Multiple Value
Reduce_land_cover_grid_to_smallest_recommended_size (Optional) Specifies whether the Land cover grid extent will be clipped to that of the Reporting unit feature layer during processing.

  • false - The Land cover grid will not be clipped. This is the default.
  • true - The Land cover grid will be clipped. This option may save processing time if the Land cover grid extent is larger than the extent of the Reporting unit feature layer.
Boolean

Code Samples

Core and Edge Metrics example 1 (Python window)

This example returns a table with the following fields: the proportion of the reporting unit zone comprised of forest edge, the proportion of the reporting unit zone comprised of forest core, and the ratio of forest edge to total forest area in the reporting unit zone. Edge width was defined as three grid cells. Calculations are then repeated for the All Natural Land Cover class and written to the output table. The options to retain the intermediate calculation products and to generate the quality assurance fields have also been 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_E2A]  Forest';'NI  -  [NI_E2A]  All Natural Land Use'"
Edge_width = "3"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_CAEM"
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 = "true"

metric.runCoreAndEdgeMetrics(Reporting_unit_feature,
                             Reporting_unit_ID_field,
                             Land_cover_grid,
                             Land_cover_classification_scheme,
                             Land_cover_classification_file,
                             Report_metrics_for_these_classes,
                             Edge_width,
                             Output_table,
                             Processing_cell_size,
                             Snap_raster,
                             Select_options, 
                             Reduce_land_cover_grid_to_smallest_recommended_size)

Land Cover Proportions 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
Intermediates are stored in this directory: workspace path
Time: yyyy-mm-dd hh:mm:ss Reducing input Land cover grid to smallest recommended size...
Time: yyyy-mm-dd hh:mm:ss Reduction complete
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 Generating core and edge grid for Class: FOR
Time: yyyy-mm-dd hh:mm:ss Step 1 of 4: Reclassing land cover grid to Class = 3, Other = 2, and Excluded = 1...
Time: yyyy-mm-dd hh:mm:ss Step 2 of 4: Setting Class areas to Null...
Time: yyyy-mm-dd hh:mm:ss Step 3 of 4: Finding distance from Other...
Time: yyyy-mm-dd hh:mm:ss Step 4 of 4: Delimiting Class areas to Edge = 3 and Core = 4...
Time: yyyy-mm-dd hh:mm:ss Core and edge grid complete for Class: FOR
Time: yyyy-mm-dd hh:mm:ss Generating a zonal tabulate area table
Time: yyyy-mm-dd hh:mm:ss Core/Edge Ratio calculations are complete for class: FOR
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 Generating core and edge grid for Class: NI
Time: yyyy-mm-dd hh:mm:ss Step 1 of 4: Reclassing land cover grid to Class = 3, Other = 2, and Excluded = 1...
Time: yyyy-mm-dd hh:mm:ss Step 2 of 4: Setting Class areas to Null...
Time: yyyy-mm-dd hh:mm:ss Step 3 of 4: Finding distance from Other...
Time: yyyy-mm-dd hh:mm:ss Step 4 of 4: Delimiting Class areas to Edge = 3 and Core = 4...
Time: yyyy-mm-dd hh:mm:ss Core and edge grid complete for Class: NI
Time: yyyy-mm-dd hh:mm:ss Generating a zonal tabulate area table
Time: yyyy-mm-dd hh:mm:ss Core/Edge Ratio calculations are complete for class: NI
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** ⚠️