Tool Stream Density Metrics - USEPA/ATtILA2 Wiki

Stream Density Metrics

Summary

Calculates density metrics based on input vector line dataset(s) for each reporting unit polygon and creates an output table. Default metrics include area of the reporting unit (km²), total length (km) and line density (km/km²) within the reporting unit.

In addition to the default metrics, length and density metrics can be calculated by stream order. Stream order is designated based on values in a specified field in the Stream feature layer.

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.

  • This tool is designed to use a vector line dataset that represent streams, but any vector line dataset may be used. Caution should be exercised when interpreting results, particularly when using line datasets that do not represent streams.

  • The Reporting unit feature must be a polygon feature class or shapefile.

  • The optional Stream order field may be used to create density metrics for different classes of Stream feature lines. The Stream order field may be any field that differentiates classes of Stream feature lines and does not necessarily need to represent stream order.

  • Values in the Stream order field have restrictions. They may may not contain spaces or special characters such as hyphens, parentheses, brackets, and symbols such as #, $, %, and &. Essentially, the values in this field are acceptable if they consist only of alphanumeric characters or an underscore. The values in these fields are used to create class-specific metric fields for the two metrics (aliases: STRMKM and STRMDENS) in the Output table. If any of the values in the Stream order field violate these character restrictions, consider using a different class field or creating a new one that corresponds to the restrictions.

  • If a Stream order field is specified, the tool creates the new field names by appending the Stream order field characters to the metric field names. Since field name length is dependent on the output table type (i.e., dBase, or geodatabase) care should be used so that the length of the final output field name does not exceed the maximum allowable field name limit for the desired output table. When the limit is exceeded, the Stream order field characters may replace the characters at the end of these field names.

    • Example 1: The selected Stream order field uses an integer to designate the stream order, and contains only second- and third-order streams (field values "2" or "3"). When the tool is run, four output fields are created in the Output table which are named as follows (Stream order field characters in bold for emphasis):

      • 2: STRMKM2 (7 characters), STRMDENS2 (9 characters)

      • 3: STRMKM3 (7 characters), STRMDENS3 (9 characters)

    • Example 2: The selected Stream order field uses alphanumeric characters to designate stream feature types (field values "C6" or "F558"). When the tool is run, four output fields are created in the Output table which are named as follows (Stream order field characters in bold for emphasis):

      • C6: STRMKMC6 (10 characters), STRMDENSC6 (10 characters)

      • F558: STRMKMF558 (10 characters), STRMDEF558 (10 characters)

    • NOTE: If the Stream order field characters replace too many of the characters in the metric field names, duplicate field names will be created.

  • NOTE: Do not use 'ORDER' as the Stream order field name as it is considered a reserved keyword in several database management systems, and its use may cause the Stream Density Metrics tool to fail.

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

    • For default tool settings (e.g. no optional settings selected):

      • AREAKM2 - The area of the reporting unit in km².

      • STRMKM - The total length of Stream feature lines in km within the reporting unit.

      • STRMDENS - The density of Stream feature lines in km/km² within the reporting unit.

    • When the option to report metrics by Stream order field is selected, separate fields are generated for each metric/order combination. The metric/order field naming convention is described above.

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

        • sdm_[Reporting unit feature]# (vector) - A polygon feature class containing reporting units with a new area field in km².

        • sdm_StrByRU# (vector) - A line feature class with Stream features intersected with reporting units.

        • 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

SDM (Reporting_unit_feature, Reporting_unit_ID_field, Stream_feature, Output_table, {Stream_order_field}, {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
Stream_feature The vector line dataset representing streams. Feature Layer
Output_table The output reporting unit metrics table to be created.

It is recommended that the Output table be saved either within a file geodatabase.
Table
Stream_order_field (Optional) The field in the Stream feature layer that contains the stream order for each feature.

It may be an integer or a string data type.

The values in this field must not contain spaces or special characters.

As order code values are appended to output field names, care should be taken not to exceed the limit for field name size set by output table type.
Field
Select_options (Optional) One tool option is available to provide additional information:

  • 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

Stream Density Metrics example 1 (Python window)

This example returns a table with the following fields: the area of the reporting unit in square kilometers, the length of streams by stream order within the reporting unit in kilometers, and the density of streams by stream order within the reporting unit in km/km².

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"
Stream_feature = r"D:\pyexamples\data.gdb\Stream_Lines"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_SDM"
Stream_order_field = "StreamOrde"
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation'"


arcpy.ATtILA.SDM(Reporting_unit_feature,
                 Reporting_unit_ID_Field,
                 Stream_feature,
                 Output_table,
                 Stream_order_field,
                 Select_options)

Stream Density Metrics 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 temporary copy of Watersheds
Time: yyyy-mm-dd hh:mm:ss Calculating reporting unit area
Time: yyyy-mm-dd hh:mm:ss Calculating feature density
Time: yyyy-mm-dd hh:mm:ss Compiling calculated values into output table
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** ⚠️