{ "cells": [ { "cell_type": "markdown", "id": "149d6b8c", "metadata": {}, "source": [ "# Setup and LRS Configuration\n", "\n", "This notebook covers installing linref, loading data, and configuring a Linear Referencing System (LRS)." ] }, { "cell_type": "markdown", "id": "8a788c06", "metadata": {}, "source": [ "## Installation\n", "\n", "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.\n", "\n", "```bash\n", "pip install linref\n", "```" ] }, { "cell_type": "markdown", "id": "43419a29", "metadata": {}, "source": [ "## Core Functionality\n", "\n", "First, import `linref` with the shortened `lr` for ease of access and consistency with the dataframe accessor." ] }, { "cell_type": "code", "execution_count": 1, "id": "bce32a17", "metadata": { "execution": { "iopub.execute_input": "2026-05-29T16:42:11.007985Z", "iopub.status.busy": "2026-05-29T16:42:11.007762Z", "iopub.status.idle": "2026-05-29T16:42:11.580929Z", "shell.execute_reply": "2026-05-29T16:42:11.580319Z" } }, "outputs": [], "source": [ "import linref as lr" ] }, { "cell_type": "markdown", "id": "dcad01e0", "metadata": {}, "source": [ "### Load Sample Datasets" ] }, { "cell_type": "code", "execution_count": 2, "id": "2a404117", "metadata": { "execution": { "iopub.execute_input": "2026-05-29T16:42:11.582734Z", "iopub.status.busy": "2026-05-29T16:42:11.582538Z", "iopub.status.idle": "2026-05-29T16:42:11.611752Z", "shell.execute_reply": "2026-05-29T16:42:11.611245Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " route beg end traffic_volume speed_limit geometry\n", "0 US-101 0.0 2.5 15000 45 LINESTRING (0 0, 2.5 0.5)\n", "1 US-101 2.5 5.0 22000 55 LINESTRING (2.5 0.5, 5 1.2)\n", "2 US-101 5.0 7.8 18500 55 LINESTRING (5 1.2, 7.8 2)\n" ] } ], "source": [ "# Load sample roadway, crash, and pavement datasets\n", "# By default, LRS is not configured - you must set it up\n", "roadways = lr.datasets.load('roadways')\n", "crashes = lr.datasets.load('crashes')\n", "pavement = lr.datasets.load('pavement')\n", "\n", "# Or load with LRS pre-configured using set_lrs=True\n", "# roadways = lr.datasets.load('roadways', set_lrs=True)\n", "\n", "print(roadways.head(3))" ] }, { "cell_type": "markdown", "id": "102506bc", "metadata": {}, "source": [ "### Setting Up an Existing LRS\n", "\n", "**Method 1: Set LRS per DataFrame**" ] }, { "cell_type": "code", "execution_count": 3, "id": "ce80766b", "metadata": { "execution": { "iopub.execute_input": "2026-05-29T16:42:11.613447Z", "iopub.status.busy": "2026-05-29T16:42:11.613086Z", "iopub.status.idle": "2026-05-29T16:42:11.616464Z", "shell.execute_reply": "2026-05-29T16:42:11.616036Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "LRS_Accessor with linear referencing system (LRS):\n", "[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')\n" ] } ], "source": [ "roadways = roadways.lr.set_lrs(\n", " key_col=['route'],\n", " chain_col='chain', # Chain column for contiguous geometry grouping (added later via add_chaining)\n", " loc_col='loc', # Should be defined even if not present in all datasets\n", " beg_col='beg',\n", " end_col='end',\n", " geom_col='geometry',\n", " geom_m_col='geometry_m', # Not currently present but will be generated later\n", " closed='left_mod' # 'left_mod' is a the recommended convention for most linear datasets\n", ")\n", "print(roadways.lr)" ] }, { "cell_type": "markdown", "id": "98ed191d", "metadata": {}, "source": [ "**Method 2: Set Default LRS**" ] }, { "cell_type": "code", "execution_count": 4, "id": "b4cedac6", "metadata": { "execution": { "iopub.execute_input": "2026-05-29T16:42:11.618089Z", "iopub.status.busy": "2026-05-29T16:42:11.617768Z", "iopub.status.idle": "2026-05-29T16:42:11.624305Z", "shell.execute_reply": "2026-05-29T16:42:11.623582Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "LRS_Accessor with linear referencing system (LRS):\n", "[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')\n", "LRS_Accessor with linear referencing system (LRS):\n", "[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')\n" ] } ], "source": [ "# Define default LRS once\n", "default_lrs = lr.LRS(\n", " key_col=['route'],\n", " chain_col='chain', # Chain column for contiguous geometry grouping (added later via add_chaining)\n", " loc_col='loc', # Should be defined even if not present in all datasets\n", " beg_col='beg',\n", " end_col='end',\n", " geom_col='geometry',\n", " geom_m_col='geometry_m', # Not currently present but will be generated later\n", " closed='left_mod' # 'left_mod' is a the recommended convention for most linear datasets\n", ")\n", "\n", "# Set as default for all DataFrames\n", "lr.set_default_lrs(default_lrs)\n", "\n", "# Now all DataFrames will use this LRS unless overridden\n", "crashes = lr.datasets.load('crashes')\n", "pavement = lr.datasets.load('pavement')\n", "print(crashes.lr)\n", "print(pavement.lr)" ] } ], "metadata": { "kernelspec": { "display_name": "venv (3.12.3)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.3" } }, "nbformat": 4, "nbformat_minor": 5 }