Calculates the area percentage of selected land cover classes within a given neighborhood. The neighborhood is square in shape. Its size is provided by the user.

An optional secondary raster can be created which reclassifies those values into percentage zones.

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

• When the optional Burn in areas of excluded values selection is checked, the tool allows the user to select a Burn in value and a Minimum patch size for burn in to identify areas of excluded values in the output raster. Grid values are marked as excluded in the Land cover classification scheme.

  • NOTE: If no excluded values are indicated in the Land cover classification scheme, the burn in operation will not be performed and ATtILA will alert the user with a warning message in the tool's View Details box and the Geoprocessing > History window.

  • Burn in value is restricted to a value not possible in the output raster. It can be any integer value outside the range of 0 - 100.

• When the optional Create zone raster selection is checked, the tool allows the user to select Zone proportion bins. This will produce a second output raster which is a reclassification of the output neighborhood proportions grid categorized into the Zone proportion bins. For example, if a Zone proportion bins of 20 is selected, the neighborhood proximity raster would be reclassed into bins of 0 - 20, 21 - 40, 41 - 60, 61 - 80, and 81 - 100. The respective attribute values for the optional zone raster would be 20, 40, 60, 80, and 100 and any Burn in value if provided. Possible zone bins to select are 5, 10, 20, 25, and 50.

• When the optional Overwrite existing outputs selection is checked, ATtILA will set the geoprocessing option to 'Allow geoprocessing tools to overwrite existing datasets' to TRUE and output rasters will be named using preset ATtILA defaults (i.e., output rasters will terminate with '_Prox' and '_ProxZone'). ATtILA will not use the CreateScratchName ArcPy function to generate unique output filename by appending a number to the end of the filename. The geoprocessing option to 'Allow geoprocessing tools to overwrite existing datasets' will be reset to its original setting upon tool completion.

• In Output workspace, select the geodatabase where the standard and optional tool outputs are to be stored.

  • Standard outputs:

    • [class Id]_[neighborhood width]_Prox# (raster) - Rasters created for each class selected in the Report metrics for these classes parameter of the tool with values representing the proportion of the Neighborhood width x Neighborhood width rectangle around each grid cell that is [class ID]. The values can range from 0 percent to 100 percent plus the Burn in value if the Burn in areas of excluded values option was selected.

    • [class Id]_[neighborhood width]_Zone# (raster) - A copy of the [class Id]_[neighborhood width]_Prox# raster reclassified into the specified Zone proportion bins. If the Burn in areas of excluded values option was selected, the Burn in value is also included. This raster is only saved if the Create zone raster option is selected.

    • NOTE: To ensure unique filenames, output filenames are typically generated using the CreateScratchName ArcPy function. This function provides a unique name for the tool 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.

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

      • np_[minimum patch size]_BurnIn# (raster) - A reclassified version of the Land cover grid where patches of excluded areas (e.g., water bodies) equal to or greater than the Minimum patch size for burn in are coded with the Burn in value. All other areas are coded as 0. This raster is only saved if the Burn in areas of excluded values option is selected.

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

          1. Reclass the Land cover grid so that cells representing excluded values = 1, and all other land cover cells = 0.

          2. Perform a RegionGroup operation to calculate the size of excluded area patches with the reclassed raster as the in_raster, eight as the number_neighbors, WITHIN as the zone_connectivity, and add_link set to TRUE.

          3. Use a Con statement on the RegionGroup output to set any patches with a count greater than or equal to the Minimum patch size for burn in and a LINK value equal to one to the Burn in value and everywhere else set to zero.

      • [class Id]_[neighborhood width]_Cnt# (raster) - Rasters created for each class selected in the Report metrics for these classes parameter of the tool with values representing the count of [class ID] cells within a Neighborhood width x Neighborhood width rectangle around each grid cell. The values can range from 0 to the square of the Neighborhood width.

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

          1. Reclass the Land cover grid so that cells representing the selected class = 1, and all other land cover cells = 0.

          2. Perform a focal statistics sum on the reclassified raster using a rectangular neighborhood of Neighborhood width x Neighborhood width.

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

      • NOTE: The ending number for the output filenames is assigned only when the geoprocessing option 'Allow geoprocessing tools to overwrite existing datasets' setting is not selected and the tool option, Overwrite existing outputs, is also unselected.

    • Intermediate products are saved in the Output workspace.

      • NOTE: ATtILA will report the location of the saved intermediate products in the Tool Details' Messages section.

NP (Land_cover_grid, Land_cover_classification_scheme, Land_cover_classification_file, Generate_output_for_these_classes, Neighborhood_width, {Burn_in_areas_of_excluded_values}, Burn_in_value, Minimum_patch_size_for_burn_in, {Create_zone_raster}, Zone_proportion_bins, {Overwrite_existing_outputs}, Output_workspace, {Select_options})

Neighborhood Proportions example 1 (Python window)

This example returns a raster with the area percentage of the 'All Natural Land Use' land cover class within a nine cell x nine cell neighborhood around each grid cell. Patches of excluded values designated in the 'NLCD LAND' land cover classification file which were larger than or equal to ten cells in size were given a value of -99999 in the output raster. The options to retain the intermediate calculation products, and to record the process steps in a log file were also 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.

NOTE: By running this script with local data in ArcGIS Pro's Python Window, all geoprocessing operations performed by this tool can be viewed in the History Pane.

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

toolPath = "D:\\Destination Folder\\ToolboxSource\\ATtILA2\\scripts\\NeighborhoodProportions_ArcGIS.py"
Land_cover_grid = "D:\\pyexamples\\data.gdb\\NLCD_2016"
Land_cover_classification_scheme = "NLCD LAND"
Land_cover_classification_file = "D:\\Destination Folder\\ToolboxSource\\LandCoverClassifications\\NLCD LAND.xml"
Report_metrics_for_these_classes = "NI  -  [NI_Prox]  All Natural Land Use"
Neighborhood_width = "9"
Burn_in_areas_of_excluded_values = "true"
Burn_in_value = "-99999"
Minimum_visible_patch_size = "10"
Create_zone_raster = "false"
Zone_proportion_bins = ""
Overwrite_existing_outputs = "false"
Output_workspace = "D:\\pyexamples\\results.gdb"
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation';'LOGFILE  -  Record Process Steps Taken During Metric Calculation'" 

metric.runNeighborhoodProportions(
                                  toolPath,
                                  Land_cover_grid,
                                  Land_cover_classification_scheme,
                                  Land_cover_classification_file,
                                  Report_metrics_for_these_classes,
                                  Neighborhood_width,
                                  Burn_in_areas_of_excluded_values,
                                  Burn_in_value,
                                  Minimum_visible_patch_size,
                                  Create_zone_raster,
                                  Zone_proportion_bins,
                                  Overwrite_existing_outputs,
                                  Output_workspace,
                                  Select_options
                                  )

Neighborhood 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
Created log file: workspace path\Output table_YYYYMMDD_hh-mm-ss.txt
Started: YYYY-MM-DD hh:mm:ss Setting up environment variables
Intermediates are stored in this directory: D:\pyexamples\results.gdb
[YYYY-MM-DD hh:mm:ss] Processing BURN IN areas
[YYYY-MM-DD hh:mm:ss] Reclassing excluded values in land cover to 1. All other values = 0
[YYYY-MM-DD hh:mm:ss] Calculating size of excluded area patches
[YYYY-MM-DD hh:mm:ss] Assigning -99999 to excluded area patches >= 10 cells in size
[YYYY-MM-DD hh:mm:ss] Saving intermediate grid: np_10_BurnIn_0
[YYYY-MM-DD hh:mm:ss] Save intermediate grid complete: np_10_BurnIn_0
[YYYY-MM-DD hh:mm:ss] Processing neighborhood proportions grid for NI
[YYYY-MM-DD hh:mm:ss] Reclassifying selected NI land cover class to 1. All other values = 0
[YYYY-MM-DD hh:mm:ss] Performing focal SUM on reclassified raster using 9 x 9 cell neighborhood
[YYYY-MM-DD hh:mm:ss] Calculating the proportion of land cover class within 9 x 9 cell neighborhood
[YYYY-MM-DD hh:mm:ss] Burning excluded areas into proportions grid
[YYYY-MM-DD hh:mm:ss] Saving proportions grid: NI_9_Prox_0
[YYYY-MM-DD hh:mm:ss] Save proportions grid complete: NI_9_Prox_0
[YYYY-MM-DD hh:mm:ss] Saving intermediate grid: NI_9_Cnt_0
[YYYY-MM-DD hh:mm:ss] Save intermediate grid complete: NI_9_Cnt_0
Adding NI_9_Prox_0 to Map view
Log file closed
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     |     Land Cover Proportions     |     Patch Metrics