Setup and LRS Configuration

This notebook covers installing linref, loading data, and configuring a Linear Referencing System (LRS).

Installation

Linref can easily be installed using pip. The package is dependent on a few major libraries (geopandas, numpy, scipy) which may require additional effort on some machines. Please review documentation for those packages as needed if any issues arise.

pip install linref

Core Functionality

First, import linref with the shortened lr for ease of access and consistency with the dataframe accessor.

import linref as lr

Load Sample Datasets

# Load sample roadway, crash, and pavement datasets
# By default, LRS is not configured - you must set it up
roadways = lr.datasets.load('roadways')
crashes  = lr.datasets.load('crashes')
pavement = lr.datasets.load('pavement')

# Or load with LRS pre-configured using set_lrs=True
# roadways = lr.datasets.load('roadways', set_lrs=True)

print(roadways.head(3))

    route  beg  end  traffic_volume  speed_limit                     geometry
0  US-101  0.0  2.5           15000           45    LINESTRING (0 0, 2.5 0.5)
1  US-101  2.5  5.0           22000           55  LINESTRING (2.5 0.5, 5 1.2)
2  US-101  5.0  7.8           18500           55    LINESTRING (5 1.2, 7.8 2)

Setting Up an Existing LRS

Method 1: Set LRS per DataFrame

roadways = roadways.lr.set_lrs(
    key_col=['route'],
    chain_col='chain', # Chain column for contiguous geometry grouping (added later via add_chaining)
    loc_col='loc', # Should be defined even if not present in all datasets
    beg_col='beg',
    end_col='end',
    geom_col='geometry',
    geom_m_col='geometry_m', # Not currently present but will be generated later
    closed='left_mod' # 'left_mod' is a the recommended convention for most linear datasets
)
print(roadways.lr)

LRS_Accessor with linear referencing system (LRS):
[GR lc LN SP sm] LRS(key_col=['route'], chain_col='chain', loc_col='loc', beg_col='beg', end_col='end', geom_col='geometry', geom_m_col='geometry_m', closed='left_mod')

Method 2: Set Default LRS

# Define default LRS once
default_lrs = lr.LRS(
    key_col=['route'],
    chain_col='chain', # Chain column for contiguous geometry grouping (added later via add_chaining)
    loc_col='loc', # Should be defined even if not present in all datasets
    beg_col='beg',
    end_col='end',
    geom_col='geometry',
    geom_m_col='geometry_m', # Not currently present but will be generated later
    closed='left_mod' # 'left_mod' is a the recommended convention for most linear datasets
)

# Set as default for all DataFrames
lr.set_default_lrs(default_lrs)

# Now all DataFrames will use this LRS unless overridden
crashes = lr.datasets.load('crashes')
pavement = lr.datasets.load('pavement')
print(crashes.lr)
print(pavement.lr)

LRS_Accessor with linear referencing system (LRS):
[GR LC ln SP sm] LRS(key_col=['route'], chain_col='chain', loc_col='loc', beg_col='beg', end_col='end', geom_col='geometry', geom_m_col='geometry_m', closed='left_mod')
LRS_Accessor with linear referencing system (LRS):
[GR lc LN sp sm] LRS(key_col=['route'], chain_col='chain', loc_col='loc', beg_col='beg', end_col='end', geom_col='geometry', geom_m_col='geometry_m', closed='left_mod')