Tool Facility Land Cover Views - USEPA/ATtILA2 GitHub Wiki

Facility Land Cover Views

Summary

Counts the number of facilities in each reporting unit polygon that have less than or equal to a threshold percentage of selected land cover classes within a given distance and creates an output table. The percentage threshold value and buffer distance are 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: 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.

  • If a feature in the Reporting unit feature zone data does not contain any features from the Facility feature, those zones will not be represented in the Output table.

  • The tool buffers a copy of the points in the Facility feature and uses Tabulate Area to calculate the percentage of the buffer area that is a selected land cover class. Tabulate Area performs a vector to raster conversion of the buffer area to use as zones for its operation. Results may vary depending on the settings of the Raster Analysis Cell Size and Snap Raster Environment settings

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

  • WARNING: - If the buffer zone for a facility does not overlap any cell centers in the Land cover grid (e.g., the View radius is smaller than the Processing cell size or a facility exists beyond the extent of the Land cover grid), that facility will not be included in any metric calculations. As a result, values recorded for any reporting unit where facilities were dropped will not be accurately represented in the Output table. ATtILA will alert the user when the calculated number of facilities above and below the View threshold do not add up to the total number of facilities located within a reporting unit. If intermediate products are saved (see Additional options below), the table, flcv_ViewLCP_RUID[view radius]_#, can be used to identify the specific facilities with missing land cover information.

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

  • Facility feature must be a vector point dataset. Multipoint features are not accepted. The View radius specifies the distance around the point features for which buffer zones are created.

  • 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 flcvField] or [class Id]_Low[view threshold] - The number of facilities in the reporting unit with percentages of the selected land cover class below the View threshold value in facility's buffer area.

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

        • (e.g. LowForestViews for <class Id="for" Name="Forest Land Cover" filter="" flcvField="LowForestViews">)
      • [class Id]_Low[view threshold] - is used if a flcvField attribute is not provided.

        • (e.g. for_Low10 for <class Id="for" Name="Forest Land Cover" filter=""> and a 10 meter view threshold 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.

  • FAC_Count will be included in the Output table as an ancillary field. It reports the total number of facilities in the reporting unit.

  • An additional ancillary field is provided in the Output table to report the number of facilities in the reporting unit with percentages of the selected land cover class at or above the View threshold. The field name follows a similar naming scheme regarding the flcvField class attribute in the Land cover classification file as described above. The ancillary field name in this Output table is as follows:

    • [class flcvField]_High[view threshold] or [class Id]_High[view threshold] - The number of facilities in the reporting unit with percentages of the selected land cover class at or above the View threshold.

    • NOTE: The calculated number of facilities above and below the View threshold should add up to the total number of facilities located within a reporting unit.

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

        • flcv_Facility[view radius]_# (vector) - Copy of the Facility feature with all but the OBJECTID and Shape fields removed.

        • flcv_FacilityRUID[view radius]_# (vector) - Copy of the flcv_Facility[view radius]_# feature with the overlying Reporting unit feature's ID attached via Identity. A facility point that occurs in overlapping Reporting Unit feature areas will produce a separate output feature for each of the Reporting unit features it occurs in.

        • flcv_ViewBuffer[view radius]_# (vector) - flcv_FacilityRUID[view radius]_# feature buffered to the View radius. The attribute table will contain fields for the Reporting unit feature ID, the buffer distance (View radius), and a field named, 'ORIG_FID'. The ORIG_FID is used as a unique identifier for future operations to tag each facility/reporting unit combination.

        • flcv_TabArea# (table) - Tabulate Area output table using flcv_ViewBuffer[view radius]_#'s ORIG_FID field as the zone identifier and the Land cover grid as the raster to be summarized.

        • flcv_ViewLCP[view radius]_# (table) - Table containing the percentage of each facility's view buffer area composed of selected land cover classes. Additional fields in the attribute table include: FLCV_TOTA, FLCV_EFFA, FLCV_EXCA, and two separate fields for each selected land cover class named, [class Id]_Below and [class Id]_Above.

          • FLCV_TOTA is the sum of the Land cover grid cell areas within the View radius.

          • FLCV_EFFA is the sum of the Land cover grid cell areas within the View radius that are not marked as "Excluded' in the Land cover classification scheme XML file.

          • FLCV_EXCA is the sum of the Land cover grid cell areas within the View radius that are marked as "Excluded' in the Land cover classification scheme XML file.

          • [class Id]_Below is a binary field where land cover class percentage below View threshold = 1, and land cover class percentage at or above View threshold = 0.

          • [class Id]_Above is a binary field where land cover class percentage below View threshold = 0, and land cover class percentage at or above View threshold = 1.

        • flcv_ViewLCP_RUID[view radius]_# (table) - The flcv_ViewLCP[view radius]_# table with the Reporting unit feature ID field attached. The ID was obtained by a join with the flcv_FacilityRUID[view radius]_# table and the common 'ORIG_FID' field.

        • flcv_ViewStats[view radius]_# (table) - Summary Statistics output table where each [class Id]_Below field and [class Id]_Above field in the flcv_ViewLCP_RUID[view radius]_# table is summed by Reporting unit feature ID.

        • 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

FLCV (Reporting_unit_feature, Reporting_unit_ID_field, Land_cover_grid, Land_cover_classification_scheme, Land_cover_classification_file, Report_metrics_for_these_classes, Facility_feature, View_radius, View_threshold, 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 to be summarized within each Reporting unit feature.

The grid 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
Facility_feature The vector point dataset that provides the basis for the buffer zones.

Land cover proportions are calculated for the area within the buffer zones.
Feature Layer
View_radius The distance around the Facility point features which comprises the buffer zones.

The value must be an integer.

If the distance linear units are not specified or are entered as Unknown, the linear unit of the input features' spatial reference is used.
Linear Unit
View_threshold Threshold number used to determine if the percentage of a selected land cover class within the View radius is identified as low.

Low percentage values include the View threshold.
Double
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 (Optional) One tool option is available to provide additional information:

  • Retain Intermediate Layers Generated During Metric Calculation - Saves the intermediate data layers that are normally deleted after processing is complete.
Multiple Value

Code Samples

Facility Land Cover Views example 1 (Python window)

This example returns a table with number of daycares in the reporting unit and the number of daycares in the reporting unit with less than 10 percent coverage of natural land cover within 250 meters of the facility. No Additional options were 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 = "'NI  -  [NI_Low]  All Natural Land Use'"
Facility_feature = r"D:\pyexamples\data.gdb\Daycares"
View_radius = "250 Meters"
View_threshold = "10"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_FLCV"
Processing_cell_size = "30"
Snap_raster = r"D:\pyexamples\data.gdb\NLCD_2016"
Select_options = ""

metric.runFacilityLandCoverViews(Reporting_unit_feature,
                                 Reporting_unit_ID_field,
                                 Land_cover_grid,
                                 Land_cover_classification_scheme,
                                 Land_cover_classification_file,
                                 Report_metrics_for_these_classes,
                                 Facility_feature,
                                 View_radius,
                                 View_threshold,
                                 Output_table,
                                 Processing_cell_size,
                                 Snap_raster,
                                 Select_options)

Facility Land Cover Views 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 a copy of the Facility feature. Intermediate: filename
Time: yyyy-mm-dd hh:mm:ss Deleting unnecessary fields from filename
Time: yyyy-mm-dd hh:mm:ss Assigning reporting unit ID to filename. Intermediate: filename
Time: yyyy-mm-dd hh:mm:ss Buffering filename to view radius. Intermediate: filename
Time: yyyy-mm-dd hh:mm:ss Constructing facility buffer land cover proportions table. Intermediate: filename
Time: yyyy-mm-dd hh:mm:ss Constructing the ATtILA metric output table: filename
Time: yyyy-mm-dd hh:mm:ss Generating a zonal tabulate area table for view buffer areas
Time: yyyy-mm-dd hh:mm:ss Completed zonal tabulate area table. Intermediate: filename
Time: yyyy-mm-dd hh:mm:ss Processing the tabulate area table and computing metric values
Time: yyyy-mm-dd hh:mm:ss Finding facilities with views below threshold limit for selected class(es)...
Time: yyyy-mm-dd hh:mm:ss Summarizing facilities with low views by Reporting Unit...
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 Top of the page     |     arrow_left People in the Landscape     |     arrow_right Intersection Density


⚠️ **GitHub.com Fallback** ⚠️