Tool Land Cover Diversity - USEPA/ATtILA2 Wiki

Land Cover Diversity


Calculates land cover diversity within each reporting unit and creates an output table. Metrics include Shannon-Weiner index, standardized Shannon-Weiner index, Simpson's index, and simple diversity.

Diversity metrics quantify landscape composition. These metrics are influenced by two components - richness, the number of different patch types present, and evenness, the distribution of area among the patch types. The four diversity metrics calculated in this tool are:

  • Shannon-Weiner index (H) - a measure of the diversity of land cover types throughout the reporting unit. The index value increases with the number of land cover types in the reporting unit.


  • Standardized Shannon-Weiner index (H') - standardizes the Shannon-Weiner index to account for the variety of distinct land cover classes present in the reporting unit.


  • Simpson's index (C) - a measure of the evenness of the distribution of land cover classes throughout the reporting unit. Simpson's index is most sensitive to the presence of common land cover types. Simpson's index values range from 0 to 1, with 1 representing perfect evenness of all land cover types.


  • Simple diversity (S) - a count of the number of distinct land cover classes present in the reporting unit.


  • For all of the above,

    • m = the number of different land cover types in the reporting unit

    • Pi = the proportion of the reporting unit comprised of land cover type i


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

  • 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 are as follows:

    • H - The Shannon-Weiner index metric for the reporting unit.

    • H_Prime - The Standardized Shannon-Weiner index metric for the reporting unit.

    • C - The Simpson's index metric for the reporting unit.

    • S - The simple diversity metric for 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.

        • LCD_OVER - The percent overlap between the Reporting unit feature layer and the Land cover grid for each reporting unit.
    • 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:

        • lcd_TabArea# (table) - A table of areas corresponding to the values in the Land cover raster 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.


LCD (Reporting_unit_feature, Reporting_unit_ID_field, Land_cover_grid, 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.
Land_cover_grid The raster dataset representing land cover classes upon which diversity metrics will be derived within each Reporting unit feature.

The class input must be an integer 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.
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 Two tool options are available to provide additional information:

  • Add Quality Assurance Fields - Adds area fields to the Output table to facilitate quality assurance checking.
  • 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

Land Cover Diversity example 1 (Python window)

This example returns a table with the Shannon-Weiner index, standardized Shannon-Weiner index, Simpson's index, and simple diversity index of land cover categories within each reporting unit.

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"
Land_cover_grid = r"D:\pyexamples\data.gdb\NLCD_2016"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_LCD"
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)'"


Land Cover Diversity 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 Constructing the ATtILA metric output table
Time: yyyy-mm-dd hh:mm:ss Generating a zonal tabulate area table
Time: yyyy-mm-dd hh:mm:ss Processing the tabulate area table and computing metric values
Succeeded at Tuesday, August 30, 2022 2:26:37 PM (Elapsed Time: 12.37 seconds)


There are no tags for this item.


Shannon, C. E. (1948). A mathematical theory of communication. The Bell System Technical Journal, 27, 379-423. Simpson, E. H. (1949). Measurement of diversity. Nature, 163, 4148, 688-688.

Use Limitations

There are no access and use limitations for this item.

arrow_up Page

⚠️ ** Fallback** ⚠️