Metadata-Version: 2.4
Name: linref
Version: 1.0.0
Summary: Linearly referenced data management, manipulation, and operations
Author-email: Tariq Shihadah <tariq.shihadah@gmail.com>
License-Expression: MIT
Project-URL: documentation, https://linref.readthedocs.io/
Project-URL: repository, https://github.com/tariqshihadah/linref
Keywords: python,geospatial,linear,data,event,dissolve,overlay,range,numeric,interval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.rst
Requires-Dist: numpy>=2.1
Requires-Dist: scipy>=1.13
Requires-Dist: shapely>=2.0
Requires-Dist: pandas>=2.0
Requires-Dist: geopandas>=1.0
Dynamic: license-file

Overview
========
The ``linref`` library builds on tabular and geospatial libraries ``pandas`` and ``geopandas`` to provide powerful features for linearly referenced data management, manipulation, and analysis. Using a modern pandas accessor pattern (``.lr``), linref seamlessly extends DataFrames with linear referencing capabilities while maintaining full compatibility with existing pandas/geopandas workflows.

At its core, linref uses:

* **LRS (Linear Referencing System)** objects to define the schema of your linearly referenced data
* **EventsData** as the underlying computational engine for efficient linear operations
* **DataFrame accessor pattern** (``.lr``) for intuitive, pandas-like syntax
* Optimized implementations powered by ``numpy``, ``shapely``, and ``scipy``

Some of the main features of this library include:

* **Event data engineering** - Merge consecutive events with ``df.lr.dissolve()``, create uniform segments with ``df.lr.resegment()``, and project point and linear data onto linearly referenced data
* **Data conflation operations** - Create relationships between datasets with ``df.lr.relate()`` and aggregate data by attributes, counts, and more using count and length-weighted methods
* **Geometry operations** - Generate geometries from mile markers, extract mile markers from geometries, and perform spatial linear referencing operations
* **Integration** - Combine multiple event datasets into unified linearly referenced frameworks
* **Prepare and run in-depth analyses** - Built-in support for advanced analyses such as high-injury networks, intersection influence areas, and more through simple, well-documented methods

Getting Started
===============

Installation
------------
Install linref using pip::

    pip install linref

Basic Concepts
--------------
**Linear Referencing System (LRS)**

An LRS defines the schema of your linearly referenced data by specifying which columns represent:

* **Key columns** ``key_col`` - One or more unique route identifier or grouping columns (e.g., 'Route', 'County')
* **Chain column** ``chain_col`` - An optional column for chain indices that identify contiguous geometry groups within each route, extending standard key columns to avoid non-contiguous groups
* **Measure columns** - For point events use ``loc_col`` (e.g., 'Milepost'), for linear events ``beg_col`` and ``end_col`` (e.g., 'Begin_Milepost', 'End_Milepost')
* **Geometry columns** - For spatial data ``geom_col`` and for spatial data that is m-enabled ``geom_m_col`` (generally m-enabled geometries are prepared and managed by ``linref``)
* **Closure type** ``closed`` - How range endpoints are handled: 'left', 'right', 'both', 'neither', or 'left_mod'/'right_mod'

Documentation
=============

* **Examples**: See the `examples <examples/index.html>`_ section for step-by-step Jupyter notebook tutorials
* **API Reference**: See the `API reference <api/index.html>`_ for detailed class and method documentation
* **GitHub**: https://github.com/tariqshihadah/linref
* **Release Notes**: See the `changelog <changelog.html>`_ for detailed version history
