Tool Land Cover Coefficient Calculator

Land Cover Coefficient Calculator

Summary

Calculates metrics based on coefficient values (multipliers) associated with specific land cover classes within each reporting unit polygon and creates an output table.

Within the reporting unit polygons, the area of each land cover class present is multiplied by its supplied coefficient. The products for each land cover class are summed to produce a value for each coefficient type.

In this version of ATtILA, this tool produces three metrics: percent impervious area, nitrogen loading (kg/ha/yr), and phosphorus loading (kg/ha/yr).

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.
NOTE: To ensure desired results, the Land cover grid must be in a projected coordinate system with linear units of measure.
Three coefficients for which metrics are calculated are included in this tool: IMPERVIOUS, NITROGEN, and PHOSPHORUS. Coefficient values are stored in the Land cover classification file. For more information on how coefficients are coded into the Land cover classification file, please refer to the Coefficients Element and Values Element sections of ATtILA's LCC XML Document. To view specific coefficient values associated with supplied land cover schemes, refer to the particular scheme in Supplied Land Cover Classification Schemas. To view and optionally edit coefficient values in a Land cover classification file, use either the Create or Modify Land Cover Classification tool or a text editor.
- IMPERVIOUS coefficient - Represents an estimate of the percent impervious area for each land cover class. For example, many land cover classification schemes contain multiple "developed" land cover classes based on the intensity of development. Generally, high-intensity developed areas (e.g. city centers) contain a greater proportion of impervious surfaces per unit area than low-intensity developed areas (e.g. rural residential). Hence, a high-intensity developed land cover class should be assigned a higher coefficient value (perhaps 0.9 for 90% impervious) than that of a medium- or low-intensity developed land cover class (the coefficient values of which perhaps range from 0.7 to 0.25 for 70% to 25% impervious). Generally, percent impervious area in land cover classes other than developed is very low or zero.
- NITROGEN coefficient - Represents an estimate of the amount of nitrogen output (stream loading) in kilograms per hectare per year for each land cover class. Nitrogen loading is generally found to be highest in land cover classes that are primarily human-use oriented (agricultural and developed land); hence ATtILA assigns a higher nitrogen loading coefficient value to these classes as compared to natural land cover classes. Considering only the various natural land cover classes, nitrogen loading is generally found to be highest in classes with high vegetative biomass per unit area (forest) and ATtILA assigns a higher nitrogen loading coefficient value than those of other natural land cover classes with lower biomass per unit area.
- PHOSPHORUS coefficient - Represents an estimate of the amount of phosphorus output (stream loading) in kilograms per hectare per year for each land cover class. Phosphorus loading follows a similar pattern as nitrogen loading--it is found to be highest in human-use oriented land cover classes to which ATtILA assigns higher phosphorus loading coefficient values versus natural land cover classes. Again, as with nitrogen loading, within the various natural land cover classes ATtILA assigns the highest phosphorus loading coefficient values to classes with high vegetative biomass per unit area (forest), with coefficient values decreasing with diminishing biomass per unit area.
Reporting unit metrics are based on the coefficient values as coded into the Land cover classification file for each land cover class. These metrics are calculated in the following manner:
- IMPERVIOUS - The percent impervious metric uses a percent area method to calculate values. For each land cover class, the area within each reporting unit is multiplied by the impervious coefficient associated with that class, resulting in a product for each class. Products for all land cover classes are summed to produce the percent impervious area metric for each reporting unit.
  - NOTE: The percent area method expects coefficient values to be expressed as decimal values between 1 and 0 (e.g., 0.9 for 90%).
  - NOTE: The output calculated value is supplied as a percentage.
- NITROGEN - The nitrogen loading metric uses a per-unit-area method to calculate values. For each land cover class, the area within each reporting unit is converted to hectares then multiplied by the nitrogen coefficient associated with that class, resulting in a product for each class. Products for all land cover classes are summed, then divided by the total number of hectares within the reporting unit to provide an average nitrogen loading value across each reporting unit in kilograms per hectare per year.
- PHOSPHORUS - The phosphorus loading metric uses a per-unit-area method to calculate values. For each land cover class, the area within each reporting unit is converted to hectares then multiplied by the phosphorus coefficient associated with that class, resulting in a product for each class. Products for all land cover classes are summed, then divided by the total number of hectares within the reporting unit to provide an average phosphorus loading value across each reporting unit in kilograms per hectare per year.
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.
Field names in the Output table are as follows:
- PCTIA - The percent impervious area metric for the reporting unit.
- N_Load - The average annual nitrogen load per hectare for the reporting unit (kg/ha/yr).
- P_Load - The average annual phosphorus load per hectare for the reporting unit (kg/ha/yr).
- NOTE: Field names are obtained from the fieldName attribute in each coefficient element in the specified Land cover classification file (See the Coefficients Element in ATtILA's LCC XML Document). Output field names can be changed by editing the Land cover classification file with the Land Cover Classification Editor.
- NOTE: The output field name for each coefficient is shown as the second item next to the coefficient's check box in Report metrics for these coefficients.
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.
    - LCCC_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:
    - lccc_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.

Syntax

LCCC (Reporting_unit_feature, Reporting_unit_ID_field, Land_cover_grid, Land_cover_classification_scheme, Land_cover_classification_file, Report_metrics_for_these_coefficients, 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 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
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	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 Coefficient Calculator example 1 (Python window)

This example returns a table with an estimate of the amount of nitrogen output (stream loading) in kilograms per hectare per year and an estimate of the percent impervious area for each reporting unit zone. 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 ALL" 
Land_cover_classification_file = r"D:\Destination Folder\ToolboxSource\LandCoverClassifications\NLCD LAND.xml"
Report_metrics_for_these_coefficients = "'IMPERVIOUS  -  [PCTIA]  Percent Cover Total Impervious Area';'NITROGEN  -  [N_Load]  Estimated Nitrogen Loading Based on Land Cover'"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_LCCC"
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'"

metric.runLandCoverCoefficientCalculator(Reporting_unit_feature,
                                         Reporting_unit_ID_field,
                                         Land_cover_grid,
                                         Land_cover_classification_scheme,
                                         Land_cover_classification_file,
                                         Report_metrics_for_these_coefficients,
                                         Output_table,
                                         Processing_cell_size,
                                         Snap_raster,
                                         Select_options)

Land Cover Coefficient Calculator 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: D:\pyexamples\results.gdb
Time: yyyy-mm-dd hh:mm:ss Generating a zonal tabulate area table
Succeeded at Day, Month dd, yyyy hh:mm:ss AM/PM (Elapsed Time: ##.## units)