Metadata-Version: 2.4
Name: transport_frames
Version: 2.0.6
Summary: Python library for transport indicator analysis based on travel-time matrices.
Author-email: Alexander Morozov <alexandermorozzov@gmail.com>, Polina Krupenina <krupenina.p@mail.ru>
License: BSD 3-Clause License
        
        Copyright (c) 2024, iduprojects
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Repository, https://github.com/alexandermorozzov/tf
Project-URL: Bug Tracker, https://github.com/alexandermorozzov/tf/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: geopandas<2.0,>=1.1
Requires-Dist: osmnx>=2.0
Requires-Dist: networkx>=3.2
Requires-Dist: contextily==1.6.2
Requires-Dist: folium==0.14.0
Requires-Dist: momepy==0.9.1
Requires-Dist: mapclassify==2.6.1
Requires-Dist: numpy<3.0,>=2.2
Requires-Dist: pyogrio==0.10.0
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow==19.0.0
Requires-Dist: pandera==0.22.1
Requires-Dist: iduedu==1.2.1
Provides-Extra: dev
Requires-Dist: black[jupyter]==22.3; extra == "dev"
Requires-Dist: mapclassify==2.6.1; extra == "dev"
Requires-Dist: folium==0.14.0; extra == "dev"
Requires-Dist: matplotlib-inline==0.1.6; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: ipywidgets; extra == "dev"
Requires-Dist: isort==5.10.1; extra == "dev"
Requires-Dist: pylint==2.17.5; extra == "dev"
Requires-Dist: pre-commit>=3.1; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<8.0.0,>=7.0.0; extra == "test"
Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == "test"
Provides-Extra: docs
Requires-Dist: docutils<0.20,>=0.18.1; extra == "docs"
Requires-Dist: sphinx==6.2.1; extra == "docs"
Requires-Dist: sphinx-book-theme==1.0.1; extra == "docs"
Requires-Dist: nbsphinx==0.9.3; extra == "docs"
Requires-Dist: nbsphinx-link==1.3.0; extra == "docs"
Requires-Dist: numpydoc==1.5.0; extra == "docs"
Requires-Dist: autodocsumm==0.2.12; extra == "docs"
Requires-Dist: myst_parser<4.0.0,>=3.0.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme<2.0.0,>=1.2.0; extra == "docs"
Requires-Dist: pandoc<3.0.0,>=2.0.0; extra == "docs"
Requires-Dist: readme_renderer<44.0; extra == "docs"
Dynamic: license-file

Transport Frames
================

.. logo-start

.. .. figure:: https://sun9-46.userapi.com/impf/aUFBStH0x_6jN9UhgwrKN1WN4hZ9Y2HMMrXT2w/NuzVobaGlZ0.jpg?size=1590x400&quality=95&crop=0,0,1878,472&sign=9d33baa41a86de35d951d4bbd8011994&type=cover_group
..    :alt: The Institute of Design and Urban Studies

.. logo-end

|Documentation Status| |PythonVersion| |Black| 

.. description-start

**Transport Frames** is a Python library designed for spatial transport analysis, offering tools to:

- Generate **transport frames** based on drive graphs.
- Identify **priority roads** by evaluating the expected popularity of routes between exit pairs.
- Update drive graphs with new road connections, ensuring proper integration.
- Grade **territory polygons** by analyzing distances to federal and regional roads.
- Compute a **weighted connectivity score** for a region based on accessibility to transport services and road network quality.
- Interpret accessibility scores into textual descriptions.
- Aggregate **administrative-level statistics** by computing transport indicators at different spatial scales (regions, districts, etc.).
- Analyze **territory-specific indicators** by using buffer-based calculations around the center of a given territory.

.. description-end

Features
--------

.. features-start


**Frame and Road Network Analysis**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Constructs **frames** from drive graphs to analyze road connectivity.
- Investigates **priority roads** based on estimated route popularity.
- Updates transport graphs by adding new edges and ensuring seamless network connectivity.

**Territory Grading and Connectivity**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Grades territories based on **proximity to federal and regional roads**.
- Computes **connectivity values** from road networks and accessibility to key transport services (bus stops, railways, airports, ports).
- Assigns **territory-wide scores** to summarize transport accessibility.

**Indicator Computation**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The library calculates various transport indicators at different **administrative levels** (region, district, etc.), including:

- **Distance to regional centers** 
- **Distance to federal roads** 
- **Connectivity score**  (measuring how well a region is connected to the transport network)
- **Lengths of roads and railway paths** 
- **Road density**  (road length per area)
- **Service accessibility**  (bus routes, railway coverage, and general service accessibility)
- **Number of services**  (number of services inside or near a given territory)
- **Number of bus routes**  (number of bus routes intersecting the territory)
- **Distance to nature objects**  (water objects, nature reserves, etc.)

.. features-end

Installation
------------

.. installation-start

**Transport_frames** can be installed with ``pip``:

::

   pip install transport-frames

.. installation-end

How to use
----------

.. use-start

For the detailed tutorial on usage case see our `examples <#examples>`__.

The following **Jupyter Notebooks** illustrate core library functions:

1. **Graph Frame Creation** → `1_graph_frame_creation.ipynb <examples/1_graph_frame_creation.ipynb>`_
   - Created graph from territory polygon.
   - Generates transport frames from drive graphs.
   - Identifies priority roads using network analysis.

2. **Indicator Computation** → `2_indicators.ipynb <examples/2_indicators.ipynb>`_
   - Computes transport indicators (road density, connectivity, admin center distances, etc.).
   - Aggregates statistics at area and territory levels.

3. **Territory grading** → `3_criteria.ipynb <examples/3_criteria.ipynb>`_
   - Assigns territory scores based on federal and regional roads accessibility.
   - Analyzes proximity to key infrastructure (bus stops, ports, airports).
   - Analyzes connectivity metrics of the territory.
   - Converts numeric scores into textual interpretations.

4. **Road Graph Updates** → `4_road_adder.ipynb <examples/4_road_adder.ipynb>`_
   - Updates transport graphs with new roads and edges.
   - Analyzes connectivity improvement after graph modifications.


5. **Transport Provision** → `5_transport_provision.ipynb <examples/5_transport_provision.ipynb>`_
   - Calculates a transport provision index for each territory polygon.
   - Combines road and railway density, airport accessibility, and settlement area share into one metric.

.. use-end

Data
----

Before running the examples, one can use the data from ``examples/data`` directory. You can use your own
data, but it must follow the structure described in the
`API documentation <https://aimclub.github.io/blocksnet/>`__.

Documentation
-------------

Detailed information and description of Transport Frames is available in
`documentation <https://alexandermorozzov.github.io/tf/>`__.

Project Structure
-----------------

The latest version of the library is available in the ``main`` branch.

The repository includes the following directories and modules:

-  `transport_frames <https://github.com/blackcoster/transport_frames/tree/main/transport_frames>`__
   - directory with the library code:

   -  graph - graph creation module
   -  frame - creation of the frame and priority roads module
   -  criteria - module for grading territory based on frame and criteria calculation
   -  indicators - module for area and territory indicators calculation
   -  road_adder - module for updating graph with new road edges
   -  utils - module containing utulity functions and consts

-  `tests <https://github.com/blackcoster/transport_frames/tree/main/tests>`__
   ``pytest`` testing
-  `examples <https://github.com/blackcoster/transport_frames/tree/main/examples>`__
   examples of how methods work
-  `docs <https://github.com/blackcoster/transport_frames/tree/main/docs>`__ -
   documentation sources


.. 7. Update
..    `tests <https://github.com/blackcoster/transport_frames/tree/main/tests>`__
..    according to your changes and run the following command:

..    ::

..          $ make test

..    Make sure that all tests pass.

.. 8. Update the
..    `documentation <https://github.com/blackcoster/transport_frames/tree/main/docs>`__
..    and **README** according to your changes.

.. 9.  When you're done editing and local testing, run:

..    ::

..          $ git add modified_files
..          $ git commit

..    to record your changes in Git, then push them to GitHub with:

..    ::

..             $ git push -u origin my-contribution

..    Finally, go to the web page of your fork of the transport_frames repo, and click
..    'Pull Request' (PR) to send your changes to the maintainers for review.

.. developing-end


License
-------

The project has `BSD-3-Clause license <./LICENSE>`__

Contacts
--------

.. contacts-start

You can contact us:


-  `IDU <https://idu.itmo.ru/en/contacts/contacts.htm>`__ - Institute of
   Design and Urban Studies
-  `Alexander Morozov <https://t.me/insert_later>`__ - project manager, software engineer
-  `Polina Krupenina <https://t.me/ratyear>`__ - software engineer


.. contacts-end


.. |Documentation Status| image:: https://github.com/alexandermorozzov/tf/actions/workflows/documentation.yml/badge.svg?branch=main
   :target: https://alexandermorozzov.github.io/tf/
.. |PythonVersion| image:: https://img.shields.io/badge/python-3.11-blue
   :target: https://pypi.org/project/blocksnet/
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
.. |Readme_ru| image:: https://img.shields.io/badge/lang-ru-yellow.svg
   :target: README-RU.rst
