Tool Road Density Metrics - USEPA/ATtILA2 GitHub Wiki

Road Density Metrics

Summary

Calculates metrics based on input vector line dataset(s) for each reporting unit polygon and creates an output table.

Default metrics include total length (km) and line density (km/km²) by reporting unit. Also included in the default metrics is percent impervious surface within each reporting unit, the calculation of which assumes that the input vector line dataset represents roads.

In addition to the default metrics, the tool allows for several optional metrics to be calculated:

  • Length and density metrics by Road feature class within each reporting unit. Classes are designated based on values in a specified field in the Road feature layer.

  • Metrics that involve spatial relationships between the Road feature and a second linear feature (Stream feature). The user may select to calculate the following:

    • Metrics that measure the frequency of intersections between the Road feature lines and the Stream feature lines in each reporting unit. Measurements by Road feature class are also available.

    • Metrics that measure the length of the Road feature lines within a specified buffer distance from Stream feature lines within each reporting unit. Measurements by Road feature class are also available.

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.

  • This tool is designed to use vector line datasets that represent roads and 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 roads and/or streams.

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

  • The optional Road class field may be used to create metrics for different classes of Road feature lines. The Road class field may be any field that differentiates category of Road feature lines and does not necessarily need to represent road class.

  • Values in the optional Road class field have restrictions. They 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 three metrics (RDKM, RDDENS, and RDTIA) in the Output table. If any of the values in the Road class field violate these character restrictions, consider using a different class field or creating a new one that corresponds to the restrictions.

  • If a Road class field is specified, the tool creates the new field names by appending the Road class 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 Road class field characters may replace the characters at the end of these field names.

    • Example: Two road classes exist in the Road feature and a dBASE output table type is specified (maximum field length = 10 characters). The Road class field designates these as "A31" and "B45100". When the tool is run with default settings (e.g. no options are selected), six output fields are created in the Output table, which are named as follows (Road class field characters in bold for emphasis):

      • A31: RDKMA31 (7 characters), RDDENSA31 (9 characters), RDTIAA31 (8 characters)

      • B45100: RDKMB45100 (10 characters), RDDEB45100 (10 characters), RDTIB45100 (10 characters)

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

  • When the optional STXRD (stream-road crossing) and/or RNS (roads near streams) are checked, the tool allows the user to select a Stream feature. When RNS is checked, the user is also allowed to enter a Buffer distance from the Stream feature lines.

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

      • RDKM - The total length of Road feature lines in km within the reporting unit.

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

      • RDTIA - An estimate of percent impervious area within the reporting unit. This metric uses road density as the independent variable in a linear regression model to estimate percent impervious surface (see May, et al., 1997). Due to the nature of the regression equation used, values below 1.8 km/km² are assigned a value of 0 for the percent impervious metric, while values above 11 km/km² are considered invalid and are reported as −1.

    • When the STXRD option is selected:

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

      • XCNT - The count of intersections (crossings) between the Road feature lines and the Stream feature lines within the reporting unit.

      • STXRD - The density of stream-road crossings per stream km within the reporting unit.

    • When the RNS option is selected:

      • RNS[buffer distance] - The proportion of the total length of Road feature lines within the Buffer distance to the total length of Stream feature lines by reporting unit.
    • When the option to report metrics by Road class field is selected, separate fields are generated for each metric/class combination. The metric/class 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:

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

        • rdm_[Road feature]# (vector) - A line feature class containing road features. This intermediate vector is only generated if the geometry coordinates for the input Road feature include M or Z values. These values are stripped off in the intermediate file.

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

        • rdm_[Stream feature]# (vector) - A line feature class containing stream features. This intermediate vector is only generated if the geometry coordinates for the input Stream feature include M or Z values. These values are stripped off in the intermediate file. This feature class is only produced when the optional STXRD selection is checked.

        • rdm_StrByRU# (vector) - A line feature class with Stream features intersected with reporting units. This feature class is only produced when the optional STXRD or RNS selection is checked.

        • rdm_PtsOfXing# (vector) - A point feature class depicting locations where Road feature lines intersect Stream feature lines. This feature class is only produced when the optional STXRD selection is checked.

        • rdm_RdsXStrMP# (vector) - A multipoint feature class in which all stream-road crossing points from the rdm_PtsOfXing# feature class are assembled by reporting unit. This feature class is only produced when the optional STXRD selection is checked.

        • rdm_RdsXStrTbl# (table) - A table of stream lengths and stream-road crossing density within each reporting unit. This table is only produced when the optional STXRD selection is checked.

        • rdm_StrBuffers# (vector) - A polygon feature class containing Stream features from the rdm_StrByRU# intermediate feature class buffered by the selected buffer distance. This feature class is only produced when the optional RNS selection is checked.

        • rdm_RdsNrStrms# (vector) - A line feature class containing Road features contained within the rdm_StrBuffers# intermediate feature class. This feature class is only produced when the optional RNS selection is checked.

        • 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

RDM (Reporting_unit_feature, Reporting_unit_ID_field, Road_feature, Output_table, Road_class_field, STXRD, RNS, Stream_feature, Buffer_distance, 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
Road_feature The vector line dataset representing roads or other linear features to be measured. Feature 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.
Table
Road_class_field (Optional) The field in the Road feature layer that distinguishes classes of linear features in order to calculate separate metrics for each class.

It may be an integer or a string data type.

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

As class 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
STXRD (Optional) Specifies whether stream-road crossing (STXRD) metrics will be included in the output table.

  • false - No STXRD metrics will not be included. This is the default.
  • true - STXRD metrics will be included. These include the total number of stream-road crossings (field name: FREQUENCY) and the density of stream-road crossings per stream kilometer (field name: STXRD) in the reporting unit.
Boolean
RNS (Optional) Specifies whether the roads near streams (RNS) metric will be included in the output table.

  • false - RNS metric will not be included. This is the default.
  • true - RNS metric will be included. This metric is a measurement of the total length of roads within the buffer distance divided by the total length of stream in the reporting unit.
Boolean
Stream_feature The vector line dataset representing streams that is used to calculate the STXRD and/or RNS metrics.

This dataset is required when the STXRD and/or RNS options are checked.
Feature Layer
Buffer_distance The distance around the Stream features in which buffer zones are created.

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.

This parameter is required when the RNS option is checked.
Linear unit
Select_options 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

Road 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 roads within the reporting unit in kilometers, the density of roads within the reporting unit in km/km², the length of streams within the reporting unit in kilometers, the density of streams within the reporting unit in km/km², the count of road and stream crossings, the average number of road and stream crossings per kilometer of stream, and the amount of roads in kilometers within 50 meters of a stream.

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"
Road_feature = r"D:\pyexamples\data.gdb\Roads"
Output_table = r"D:\pyexamples\results.gdb\Watersheds_RDM"
Road_class_field = ""
STXRD = "true"
RNS = "true"
Stream_feature = r"D:\pyexamples\data.gdb\Stream_Lines"
Buffer_distance = "50 Meters"
Select_options = "'INTERMEDIATES  -  Retain Intermediate Layers Generated During Metric Calculation'"

arcpy.ATtILA.RDM(Reporting_unit_feature,
                 Reporting_unit_ID_field,
                 Road_feature,
                 Output_table,
                 Road_class_field,
                 STXRD,
                 RNS,
                 Stream_feature,
                 Buffer_distance,
                 Select_options)

Road 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 reporting unit layer
Time: yyyy-mm-dd hh:mm:ss Calculating reporting unit area
Time: yyyy-mm-dd hh:mm:ss Calculating road density
Time: yyyy-mm-dd hh:mm:ss Compiling calculated values into output table
Time: yyyy-mm-dd hh:mm:ss Calculating Stream and Road Crossings (STXRD)
Time: yyyy-mm-dd hh:mm:ss Compiling calculated values into output table
Time: yyyy-mm-dd hh:mm:ss Calculating Roads Near Streams (RNS)
Buffering stream features...
Intersecting road features with stream buffers...
Assigning reporting unit feature ID values to road segments...
Dissolving intersection result and calculating values...
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

May, C.W., Horner, R.R., Karr, J.R., Mar B.W., Welch, E.B. 1997. Effects of urbanization on small streams in the Puget Sound Lowland Ecoregion. Watershed Protection Techniques. 2:4. pp. 483−493.

Use Limitations

There are no access and use limitations for this item.


arrow_up Top of the page     |     arrow_left Population Land Cover Views     |     arrow_right Riparian Characteristics


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