Class Location

Summary

Class Location performs a full Class Location analysis workflow from start to finish. Class Location is implemented as a ModelBuilder model tool, using the tools from the Prepare and Process toolsets in the Gas HCA Tool Python toolbox. It creates a project geodatabase to store copies of your input data, performs data loading and conditioning, executes intermediate calculations, and calculates final Class Locations units per the requirements of 49 CFR §192.5. 

Usage

Class Location implements G2-IS’ best practices for Class Location analysis. However, because it is implemented as a ModelBuilder model tool, you are free to make a copy of the tool and modify it to suit your own needs.

The following tools are used in Class Location. They are listed in their order of execution within the Class Location tool; the heading for each section below is a hyperlink to the detailed help for the tool. Please note that while the tools Class Location uses are listed in the order in which they are executed, the Class Location tool parameters are shown in association with the tools that expose them, not necessarily in the order in which Class Location lists them:

1) Initialize Database

Initialize Database tool creates a project file geodatabase for the Class Location analysis. It stores copies of your input data (to preserve all data used in the analysis), as well as intermediate results and final Class Location unit outputs. The first and last parameters exposed by the Class Location tool are from Initialize Database.

  • Project Name – Your Class Location project geodatabase is internally identified by a Global Unique Identifier (GUID) value. Your designated project name serves as an informal, human-readable name for your analysis project.
  • Output Project Geodatabase Initialize Database tool creates a new file geodatabase to store the project data.

2) Copy Centerlines

Copy Centerlines copies your centerline features from your pipeline database into the CENTERLINE feature class in the project geodatabase. Although it’s not a requirement to preserve input data, doing so enables you to retain an archival copy of the input data used in the analysis.

  • Input Centerline Features – Your input centerline features should consist of the continuous, non-branching runs of pipeupon which you desire to perform calculations.

Your input centerline features must contain the following attributes (your field names need not match, but fields containing this information must be present):

      • Centerline Identifier Field – A field that uniquely identifies each input centerline feature. Your centerline ID field is preserved in the ORIGINAL_ROUTE_ID field in the CENTERLINE feature class in the project geodatabase.
      • Centerline Begin Measure Field – A field that defines the begin measure values of your centerline features.
      • Centerline End Measure Field – A field that defines the end measure values of your centerline features.

3) Prepare Centerline Buffers

Prepare Centerline Buffers creates centerline buffer features for use in subsequent selection of Buildings Intended for Human Occupancy (BIHOs) and Qualifying Areas/Buildings for the analysis. The tool also creates ‘dissolved’ versions of the buffer features for use in display. The undissolved and dissolved versions of the output centerline buffer features are stored in the following feature classes in the project geodatabase: CENTERLINE_STRUCTURE_BUFFER, CENTERLINE_STRUCTURE_BUFFER_DISSOLVED, CENTERLINE_QUALIFIED_AREA_BUFFER and CENTERLINE_QUALIFIED_AREA_BUFFER_DISSOLVED.

  • Structure Buffer Distance – The default value of 660 feet represents the mandated Class Location unit width, per 49 CFR §192.5(a)(1). However, you may increase the value, if desired, to account for uncertainty in the location of your pipeline centerline, or your structure features.
  • Qualifying Area/Building Buffer Distance – This parameter is analogous to the above Structure Buffer Distanceparameter but applies instead to Class Location Qualifying Areas and Buildings. The default value of 300 feet conforms to that specified by regulation, per 49 CFR §192.5(b)(3)(ii). You may increase the value, if desired, to account for uncertainty in the location of your pipeline centerline, or your Qualifying Area/Building features.

4) Prepare Structures

Prepare Structures copies your point and/or polygon BIHO features from your pipeline database into your project geodatabase for use in the analysis. The output features are stored in the following feature classes in the project geodatabase: STRUCTURE_POINT and STRUCTURE_POLYGON.

  • Input Structure Features – This parameter allows you to select multiple input layers or feature classes, and to mix point and polygon shape types in the input feature layers or feature classes. However, all input layers/feature classes must have a common schema. Your input BIHO features must contain the following attributes (your field names need not match, but fields containing this information must be present):
      • Structure Identifier Field – A field that uniquely identifies each input BIHO feature. Your structure ID field is preserved in the ORIGINAL_STR_OR_AREA_ID field in the STRUCTURE_POINT and STRUCTURE_POLYGONfeature classes in the project geodatabase.
      • Number of Dwelling Units Field – This parameter indicates the number of dwelling units present in the BIHO feature. For a single-family residence, the number is 1. For an apartment structure, the number is the number of apartment units in the feature.
      • Number of Stories Field – This field contains the number of stories in the BIHO feature. This field is used in the determination of Class 4 ranges in Class Location analysis. This field is not used in HCA-MCA analysis.
      • Discovery Date Field for Structures – This optional field stores the date on which the BIHO feature was actually discovered in the field.
      • Database Date Field for Structures – This optional field stores the date on which the BIHO feature was entered into your pipeline database.

5) Prepare Qualifying Areas

Prepare Qualifying Areas tool copies your point or polygon features for Qualifying Areas/Buildings from your pipeline database into your project geodatabase. The output features are stored in the following feature classes in the project geodatabase: QUALIFYING_AREA_POINT and QUALIFYING_AREA_POLYGON.

  • Input Qualifying Area/Building Features This parameter allows you to select multiple input layers or feature classes, and to mix point and polygon shape types in the input feature layers or feature classes. However, all input layers/feature classes must have a common schema. Your input qualifying area/building features must contain the following attributes (your field names need not match, but fields containing this information must be present):
      • Qualifying Area/Building Identifier Field – A field that uniquely identifies each input qualifying area/building feature. Your qualifying area/building ID field is preserved in the ORIGINAL_STR_OR_AREA_ID field in the QUALIFYING_AREA_POINT and QUALIFYING_AREA_POLYGON feature classes in the project geodatabase.
      • Qualifying Area/Building Type Field– A field that defines the type of qualifying outside area or building. This field is intended primarily for use in map display; all features in the QUALIFYING_AREA_POINT and QUALIFYING_AREA_POLYGON feature classes are used in analysis.
      • Discovery Date Field for Qualifying Areas/Buildings – This optional field stores the date on which the qualifying outside area or building feature was actually discovered in the field.
      • Database Date for Field Qualifying Areas/Buildings – This optional field stores the date on which the qualifying outside area or building feature was entered into your pipeline database.

6) Prepare Structure and Site Buffers and Segments

Prepare Structure and Site Buffers and Segments buffers for your BIHO features and qualifying area/building features. The tool creates 660-foot buffers for BIHO features and 300-foot buffers for qualifying areas/buildings features (plus any additional spatial tolerance specified). The tool also generates polyline segment features representing the intersections of the BIHO and qualifying areas/buildings buffer polygons with the pipeline centerline features stored in your project geodatabase. This tool creates the following feature classes in your project geodatabase: STRUCTURE_BUFFER, QUALIFYING_AREA_BUFFER, and DOT_STRUCTURESEGMENT.

Class Location exposes none of this tool’s parameters.

7) Calculate Influence Ranges

Calculate Influence Ranges calculates the ‘influence ranges’ of BIHO and qualifying area/structure features on the centerline in preparation for ‘sliding mile’ calculations. The output influence range features are stored in the DOT_BIHO_INFLUENCE_RANGE feature class in your project geodatabase.

Class Location exposes none of this tool’s parameters.

8) Prepare Cluster Buffers

Prepare Cluster Buffers generates dissolved ‘cluster’ buffer polygons for BIHO and qualifying areas/buildings features based on groups of BIHOs and qualifying areas/buildings, respectively, whose individual buffer polygons overlap. The tool also generates dissolved ‘cluster’ buffer polygons for 4-story and higher BIHOs. The cluster buffers are intersected with the centerline to produce structure and qualifying areas/buildings cluster segments. These operations are performed in preparation for calculating Class 4 and ‘clustered’ Class 2 and Class 3 location ranges (per 49 CFR §192.5(c)), and Class 3 ranges due to the presence of qualifying areas/buildings (per 49 CFR §192.5(b)(3)(ii)). The output features are stored in the following feature classes in the project geodatabase: DOT_STRUCTURE_CLUSTERBUFFER and DOT_CLASS4_CLUSTERBUFFER. The tool also generates the following output tables:  DOT_STRUCTURE_CLUSTERSEGMENT, DOT_SITE_CLUSTERSEGMENT, and DOT_CLASS4_CLUSTERSEGMENT.

  • Number of Structures to be Considered a Cluster – This parameter allows you to define the number of BIHO dwelling units that constitute a cluster.
  • Percentage (%) for a Cluster to be Considered Class 4 – This parameter allows you to define the threshold percentage of 4-story or higher BIHO features (i.e., building footprints, not dwelling units) in a cluster that require a Class 4 location unit.
  • Boundary Adjustment MethodArc Method (also called radial arc method) – This parameter calculates clustered Class Location unit ranges using cluster buffers; the clustered Class Location unit ends where the BIHO cluster buffer intersects the pipeline centerline.
  • Perpendicular/Parallel Method – This parameter calculates clustered Class Location units by locating the bounding BIHO/qualifying areas/buildings influence range features for the cluster, and then extending along the pipeline centerline from the endpoints of the bounding influence range features using the values of Extension Length From Last Structure in Cluster (Feet) or Extension Length From Last Qualifying Area in Cluster (Feet), as appropriate.
  • Extension Length From Last Structure in Cluster (Feet) – This parameter specifies the distance to extend along the centerline from the last BIHO in a cluster of BIHOs to define the extent of a clustered Class 2 or Class 3 Location range, or a Class 4 Location range, when using the Perpendicular/Parallel clustered Class Location range Boundary Adjustment The default value is 660 feet.
  • Extension Length From Last Qualifying Area in Cluster (Feet) – This parameter specifies the distance to extend along the centerline from the last qualifying area or building in a cluster of qualifying areas/buildings to define the extent of a Class 3 Location unit due the presence of one or more qualifying areas/buildings, when using the Perpendicular/Parallel clustered Class Location range Boundary Adjustment The default value is 300 feet.

9) Generate Sliding Ranges

Generate Sliding Ranges calculates ‘sliding mile’ ranges for BIHO features, and also ‘raw’ Class Location unit records based solely on ‘sliding mile’ BIHO counts. The tool outputs the DOT_STRUCTUREONEMILESEGMENT feature class and the DOT_ONEMILECLASSSEGMENT table into your project geodatabase.

  • Sliding Mile Distance (in feet) –This parameter allows you to specify the length of your sliding ranges, as measured (in feet) along the centerline from the ends of your input influence range records. The default value is 5,280 feet (1 mile). This value should not be modified for this Class Location workflow.

10) Class Location Calculation

Class Location Calculation performs the final step in the Class Location analysis workflow, calculating your final DOT Class Location units, as well as dynamically segmented Class Location unit segments that retain much useful attributes from the analysis process. The output features are stored in the following feature classes in the project geodatabase: DOT_CLASS_RANGE_UNCLUSTERED, DOT_CLASS_RANGE_CLUSTERED, DOT_CLASS_SEGMENT_UNCLUSTERED, and DOT_CLASS_SEGMENT_CLUSTERED.

  • Sliver Segment Dissolve Tolerance for Class 4 (and 3 and 2) – These parameters allow you to specify the maximum ‘sliver’ length to be allowed when two higher Class Location units surround a short length lesser Class Location unit (a ‘sliver’). When the length of the lesser Class Location unit is less that the tolerance length, the ‘sliver’ Class Location unit is assigned the higher class of the surrounding Class Location units, in effect ‘dissolving’ the sliver. Note that the actual Class Location unit value is preserved in the data.

Syntax

DOTClass (Project_Name, Input_Centerline_Features, Centerline_ Identifier_Field, Centerline_Begin_Measure_Field, Centerline_End_Measure_Field, Input_Structure_Features, Structure_Identifier_Field, Number_of_Dwelling_Units_Field, Number_of_Stories_Field, Structure_Buffer_Distance, {Discovery_Date_Field_for_Structures}, {Database_Date_Field_for_Structures}, Input_Qualifying_Area_Building_Features, Qualifying_Area_Building_Type_Field, Qualifying_Area_Building_Buffer_Distance, {Discovery_Date_Field_for_Qualifying_Areas_Buildings}, {Database_Date_Field_for_Qualifying_Areas_Buildings}, Number_of_Structures_to_be_Considered_a_Cluster, Percentage____for_cluster_to_be_Considered_Class_4, Boundary_Adjustment_Method, {Extension_Length_from_Last_Structure_in_Cluster__Feet_}, {Extension_Length_from_Last_Qualifying_Area_Building_in_Cluster__Feet_}, Sliding_Mile_Distance__In_Feet_, {Sliver_Segment_Dissolve_Tolerance_for_Class_4}, {Sliver_Segment_Dissolve_Tolerance_for_Class_3}, {Sliver_Segment_Dissolve_Tolerance_for_Class_2}, Output_Project_Geodatabase)

Parameter Explanation Data Type
Project_Name

Dialog Reference

Specify the name of your project.

There is no Python reference for this parameter.

String
Input_Centerline_Features

Dialog Reference

Specify your input centerline features.

There is no Python reference for this parameter.

Table View
Centerline_Identifier_Field

Dialog Reference

Select the field that uniquely identifies your input centerline features.

There is no Python reference for this parameter.

Field
Centerline_Begin_Measure_Field

Dialog Reference

Specify the field that contains the begin measure values for your input centerline features.

There is no Python reference for this parameter.

Field
Centerline_End_Measure_Field

Dialog Reference

Specify the field that contains the end measure values for your input centerline features.

There is no Python reference for this parameter.

Field
Input_Structure_Features

Dialog Reference

Specify your input BIHO features. You may select multiple point and polygon feature layers or feature classes.

There is no Python reference for this parameter.

Multiple Value
Structure_Identifier_Field

Dialog Reference

Specify the field that uniquely identifies each BIHO feature.

There is no Python reference for this parameter.

String
Number_of_Dwelling_Units_Field

Dialog Reference

Specify the field that defines the number of dwelling units in each BIHO feature.

There is no Python reference for this parameter.

String
Number_of_Stories_Field

Dialog Reference

Specify the field that defines the number of stories in each BIHO feature.

There is no Python reference for this parameter.

String
Structure_Buffer_Distance

Dialog Reference

Specify the desired BIHO buffer selection distance value and linear units of measure. The default value is 660 feet.

There is no Python reference for this parameter.

Linear unit

Discovery_Date_Field_for_Structures

(Optional)

Dialog Reference

Specify the field that records the “discovery date” of your BIHO features.

There is no Python reference for this parameter.

String

Database_Date_Field_for_Structures

(Optional)

Dialog Reference

Specify the field that records the date at which your BIHO features were added to your pipeline database.

There is no Python reference for this parameter.

String
Input_Qualifying_Area_Building_Features

Dialog Reference

Specify your input qualifying area/building features. You may select multiple point and polygon feature layers or feature classes.

There is no Python reference for this parameter.

Multiple Value
Qualifying_Area_Building_Identifier_Field

Dialog Reference

Specify the field that uniquely identifies your qualifying area/building features.

There is no Python reference for this parameter.

String
Qualifying_Area_Building_Type_Field

Dialog Reference

Specify the field that defines the qualifying area/building type.

There is no Python reference for this parameter.

String
Qualifying_Area_Buliding_Buffer_Distance

Dialog Reference

Specify the desired qualifying area/building buffer selection distance value and linear units of measure. The default value is 300 feet.

There is no Python reference for this parameter.

Linear unit
Discovery_Date_Field_for_Qualifying_Areas_Buildings (Optional)

Dialog Reference

Specify the field that records the ‘discovery date’ of your qualifying area/building features.

There is no Python reference for this parameter.

String
Database_Date_Field_for_Qualifying_Areas_Buildings (Optional)

Dialog Reference

Specify the field that records the date at which your qualifying area/building features were added to your pipeline database.

There is no Python reference for this parameter.

String
Number_of_Structures_to_be_Considered_a_Cluster

Dialog Reference

Specify the number of dwelling units that constitute a cluster. The default value is 1.

There is no Python reference for this parameter.

Long
Percentage_for_Cluster_to_be_Considered_Class_4

Dialog Reference

Specify the threshold percentage of 4-story or higher buildings relative to the total number of buildings in a cluster of 4-story or higher buildings that results in a Class 4 Location unit. The default value is 50%.

There is no Python reference for this parameter.

Double
Boundary_Adjustment_Method

Dialog Reference

Specify the method used to determine the spatial extent of clustered Class Location ranges.

There is no Python reference for this parameter.

String
Extension_Length_from_Last_Structure_in_Cluster_Feet_ (Optional)

Dialog Reference

Specify the distance to extend along the centerline from the last BIHO in a cluster of BIHOs to define the extent of a clustered Class 2 or Class 3 Location range, or a Class 4 Location range, when using the Perpendicular/Parallelclustered Class Location range Boundary Adjustment method. The default value is 660 feet.

There is no Python reference for this parameter.

Double

Extension_Length_from_Last_Qualifying

_Area_Building_in_Cluster__Feet_

(Optional)

Dialog Reference

Specify the distance to extend along the centerline from the last qualifying area or building in a cluster of qualifying areas/buildings to define the extent of a Class 3 Location unit due the presence of one or more qualifying areas/buildings, when using the Perpendicular/Parallelclustered Class Location range Boundary Adjustment method. The default value is 300 feet.

There is no Python reference for this parameter.

Double
Sliding_Mile_Distance__in_Feet

Dialog Reference

Specify your desired sliding mile length. 5,280 feet is the default. You should not modify this value.

There is no Python reference for this parameter.

Long
Sliver_Segment_Dissolve_Tolerance_for_Class_4 (Optional)

Dialog Reference

Specify the maximum sliver length value below which lower Class Location units that are surrounded by Class 4 location units will be dissolved into the surrounding Class 4 location units.

There is no Python reference for this parameter.

Double
Sliver_Segment_Dissolve_Tolerance_for_Class_3 (Optional)

Dialog Reference

Specify the maximum sliver length value below which lower Class Location units that are surrounded by Class 3 location units will be dissolved into the surrounding Class 3 location units.

There is no Python reference for this parameter.

Double
Sliver_Segment_Dissolve_Tolerance_for_Class_2 (Optional)

Dialog Reference

Specify the maximum sliver length value below which Class 1 location units that are surrounded by Class 2 location units will be dissolved into the surrounding Class 2 location units.

There is no Python reference for this parameter.

Double
Output_Project_Geodatabase

Dialog Reference

Specify the destination of the output project geodatabase.

There is no Python reference for this parameter.

Workspace

Code sample

The following script demonstrates how to use the Class Location master tool with file geodatabase data.

# Import GasHCA Library
import hcapy
# improt Gas HCA Tools
arcpy.ImportToolbox(“C:\Python27\ArcGIS10.6\Lib\site-packages\hcapy\esri\Toolboxes\GasHCA Master Tools (Desktop)
.tbx”)
Project_Name = “ClassLocation”
Input_Centerline_Features = r”C:\projects\GasHCA_Enhancements\Test.gdb\StationSeries”
Centerline_Identifier_Field = “EVENTID”
Centerline_Begin_Measure_Field = “BEGIN_MEASURE”
Centerline_End_Measure_Field = “END_MEASURE”
Input_Structure_Features =  r”C:\projects\GasHCA_Enhancements\Test.gdb\Structure_BIHO”
Structure_Identifier_Field = “EVENTID”
Number_of_Dwelling_Units_Field = “Num_Units”
Number_of_Stories_Field = “Num_Stories
Structure_Buffer_Distance = 660
Discovery_Date_Field_for_Structures = None
Database_Date_Field_for_Structures = None
Input_Qualifying_Area_Building_Features= r”C:\projects\GasHCA_Enhancements\Test.gdb\Identified_Site”
Qualifying_Area_Building_Identifier_Field = “StructorSiteID”
Qualifying_Area_Building_Type_Field = “Identified_Site_Type”
Qualifying_Area_Buffer_Distance = 300
Discovery_Date_Field_for_Qualifying_Areas_Buildings = None
Database_Date_Field_for_Qualifying_Areas_Buildings = None
Number_of_Structures_to_be_Considered_a_Cluster = 1
Percentage____for_Cluster_to_be_Considered_Class_4 = 50
Boundary_Adjustment_Method = “Arc Method”
Extension_Length_from_Last_Structure_in_Cluster__Feet_ = 660
Extension_Length_from_Last_Qualifying_Area_Buildings_in_Cluster__Feet_ = 300
Sliding_Mile_Distance__in_Feet_ = 5280
Sliver_Segment_Dissolve_Tolerance_for_Class_4 = 0
Sliver_Segment_Dissolve_Tolerance_for_Class_3 = 0
Sliver_Segment_Dissolve_Tolerance_for_Class_2 = 0
Output_Project_Geodatabase = r”C:\projects\GasHCA_Enhancements\A_DOTCLass_Test3.gdb”
# Execute tool
ClassLocation(Project_Name, Input_Centerline_Features, Centerline_Identifier_Field, Centerline_Begin_Measure_Field, Centerline_End_Measure_Field, Input_Structure_Features, Structure_Identifier_Field, Number_of_Dwelling_Units_Field, Number_of_Stories_Field, Structure_Buffer_Distance, Discovery_Date_Field_for_Structures, Database_Date_Field_for_Structures, Input_Qualifying_Area_Building_Features, Qualifying_Area_Building_Identifier_Field, Qualifying_Area_Building_Type_Field, Qualifying_Area_Buffer_Distance, Discovery_Date_Field_for_Qualifying_Areas_Buildings, Database_Date_Field_for_Qualifying_Areas_Buildings, Number_of_Structures_to_be_Considered_a_Cluster, Percentage____for_Cluster_to_be_Considered_Class_4, Boundary_Adjustment_Method, Extension_Length_from_Last_Structure_in_Cluster__Feet_, Extension_Length_from_Last_Qualifying_Area_Buildings_in_Cluster__Feet_, Sliding_Mile_Distance__in_Feet_, Sliver_Segment_Dissolve_Tolerance_for_Class_4, Sliver_Segment_Dissolve_Tolerance_for_Class_3, Sliver_Segment_Dissolve_Tolerance_for_Class_2, Output_Project_Geodatabase)

Environments

Current Workspace, Scratch Workspace, Default Output Z Value, M Resolution, M Tolerance, Output M Domain, Output XY Domain, Output Z Domain, Output Coordinate System, Extent, Geographic Transformations, Output has M values, Output has Z values, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance

Licensing information

This tool requires a valid Gas HCA Tool user license or subscription. Please see the Request License and Register License tool help topics for details on obtaining and registering a Gas HCA Tool software license.

Related topics

Tags

Class Location, building intended for human occupancy, BIHO, qualifying area/building, sliding mile, cluster, sliver, unit.

Credits

Copyright © 2016-2020 by G2 Integrated Solutions, LLC. All Rights Reserved.

Use limitations

There are no access and use limitations for this item.