ObjectNat 1.2.2__tar.gz → 1.3.1__tar.gz

objectnat-1.3.1/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: ObjectNat
+Version: 1.3.1
+Summary: ObjectNat is an open-source library created for geospatial analysis created by IDU team
+License: BSD-3-Clause
+License-File: LICENSE.txt
+Author: DDonnyy
+Author-email: 63115678+DDonnyy@users.noreply.github.com
+Requires-Python: >=3.11,<3.13
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: geopandas (>=1.0.1,<2.0.0)
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
+Requires-Dist: networkx (>=3.4.2,<4.0.0)
+Requires-Dist: numpy (>=2.1.3,<3.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: scikit-learn (>=1.4.0,<2.0.0)
+Requires-Dist: tqdm (>=4.66.2,<5.0.0)
+Description-Content-Type: text/x-rst
+
+ObjectNat
+=========
+
+Object-oriented Network Analysis Tools
+--------------------------------------
+
+.. |badge-black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: Code style: black
+
+.. |badge-pypi| image:: https://img.shields.io/pypi/v/objectnat.svg
+   :target: https://pypi.org/project/objectnat/
+   :alt: PyPI version
+
+.. |badge-ci| image:: https://github.com/IDUclub/ObjectNat/actions/workflows/ci_pipeline.yml/badge.svg
+   :target: https://github.com/IDUclub/ObjectNat/actions/workflows/ci_pipeline.yml
+   :alt: CI
+
+.. |badge-codecov| image:: https://codecov.io/gh/DDonnyy/ObjectNat/graph/badge.svg?token=K6JFSJ02GU
+   :target: https://codecov.io/gh/DDonnyy/ObjectNat
+   :alt: Coverage
+
+.. |badge-license| image:: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
+   :target: https://opensource.org/licenses/BSD-3-Clause
+   :alt: License
+
+.. |badge-docs| image:: https://img.shields.io/badge/docs-latest-4aa0d5?logo=readthedocs
+   :target: https://iduclub.github.io/ObjectNat/
+   :alt: Docs
+
+|badge-black| |badge-pypi| |badge-ci| |badge-codecov| |badge-license| |badge-docs|
+
+`РИДМИ (Russian) <https://github.com/IDUclub/ObjectNat/blob/master/README_RU.rst>`__
+
+.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/master/docs/_static/ONlogo.svg
+   :align: center
+   :width: 400
+   :alt: ObjectNat logo
+
+
+**ObjectNat** is an open-source library developed by the **IDU** team
+for spatial and network analysis in urban studies.
+The library provides tools for analyzing **accessibility**, **visibility**,
+**noise propagation**, and **service provision**.
+----
+
+Key Features
+------------
+
+Each feature includes a **Jupyter Notebook example** and **full documentation**.
+
+1. **Isochrones and Transport Accessibility**  
+
+   Isochrones represent areas reachable from an origin point within a specified time along a transport network.
+   This feature allows the analysis of transport accessibility using pedestrian, road,
+   public transport, or multimodal graphs.
+
+   The library supports several methods for building isochrones:
+
+   - **Basic isochrones**: display a single zone reachable within a specified time.
+   - **Step isochrones**: divide the accessibility area into time intervals (e.g., 3, 5, 10 minutes).
+
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/isochrones.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/isochrones.html>`__
+
+2. **Graph Coverage Zones from Points**
+
+   A function for generating **coverage areas** from a set of origin points using a transport network.
+   It computes the area reachable from each point by **travel time** or **distance**,
+   then builds polygons using **Voronoi diagrams** and clips them by a given boundary if specified.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/coverage.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/coverage.html>`__
+
+3. **Service Provision Analysis**  
+
+   A function to evaluate how well residential buildings and their populations are provided
+   with services (e.g., schools, clinics) that have limited **capacity**
+   and a defined **accessibility threshold** (in minutes or meters).
+   The function models the **balance between supply and demand**,
+   assessing how well services meet the needs of nearby buildings within an acceptable time.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/provision.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/provision.html>`__
+
+4. **Visibility Analysis**  
+
+   A function for evaluating visibility from a given point or set of points to nearby buildings within a given radius.
+   It is used to assess visual accessibility in urban environments.
+   A module is also implemented for computing **visibility coverage zones**
+   using a dense observer grid (recommended ~1000 points with a 10–20 m spacing).
+   Points can be generated along the transport network and distributed across its edges.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/visibility.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/visibility.html>`__
+
+5. **Noise Simulation & Noise Frame**
+
+   Simulation of noise propagation from sources, taking into account **obstacles**, **vegetation**,
+   and **environmental factors**.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/noise.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/noise.html>`__
+   🧠 `Detailed theory <https://github.com/DDonnyy/ObjectNat/wiki/Noise-simulation>`__
+
+6. **Point Clusterization**  
+
+   A function for constructing **cluster polygons** based on a set of points using:
+
+   - Minimum **distance** between points.
+   - Minimum **number of points** in a cluster.
+
+   The function can also compute the **ratio of service types** in each cluster
+   for spatial analysis of service composition.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/clustering.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/clustering.html>`__
+
+----
+
+City Graphs via *IduEdu*
+------------------------
+
+For optimal performance, **ObjectNat** is recommended to be used with graphs
+created by the `IduEdu <https://github.com/IDUclub/IduEdu>`_ library.
+
+**IduEdu** is an open-source Python library designed for building and processing
+complex urban networks based on OpenStreetMap data.
+
+
+**IduEdu** can be installed via ``pip``::
+
+    pip install IduEdu
+
+Example usage::
+
+    from iduedu import get_4326_boundary, get_intermodal_graph
+
+    poly = get_4326_boundary(osm_id=1114252)
+    G_intermodal = get_intermodal_graph(territory=poly, clip_by_territory=True)
+
+----
+
+Installation
+------------
+
+**ObjectNat** can be installed via ``pip``::
+
+    pip install ObjectNat
+
+----
+
+Configuration
+-------------
+
+You can adjust logging and progress bar output using the config module::
+
+    from objectnat import config
+
+    config.change_logger_lvl("INFO")   # mute debug logs
+    config.set_enable_tqdm(False)      # disable tqdm progress bars
+
+----
+
+Contacts
+--------
+
+- `NCCR <https://actcognitive.org/>`_ — National Center for Cognitive Research  
+- `IDU <https://idu.itmo.ru/>`_ — Institute of Design and Urban Studies  
+- `Natalya Chichkova <https://t.me/nancy_nat>`_ — Project Manager  
+- `Danila Oleynikov (Donny) <https://t.me/ddonny_dd>`_ — Lead Software Engineer
+
+----
+
+Publications
+------------
+
+Coming soon.
+

objectnat-1.3.1/README.rst

@@ -0,0 +1,179 @@
+ObjectNat
+=========
+
+Object-oriented Network Analysis Tools
+--------------------------------------
+
+.. |badge-black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: Code style: black
+
+.. |badge-pypi| image:: https://img.shields.io/pypi/v/objectnat.svg
+   :target: https://pypi.org/project/objectnat/
+   :alt: PyPI version
+
+.. |badge-ci| image:: https://github.com/IDUclub/ObjectNat/actions/workflows/ci_pipeline.yml/badge.svg
+   :target: https://github.com/IDUclub/ObjectNat/actions/workflows/ci_pipeline.yml
+   :alt: CI
+
+.. |badge-codecov| image:: https://codecov.io/gh/DDonnyy/ObjectNat/graph/badge.svg?token=K6JFSJ02GU
+   :target: https://codecov.io/gh/DDonnyy/ObjectNat
+   :alt: Coverage
+
+.. |badge-license| image:: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
+   :target: https://opensource.org/licenses/BSD-3-Clause
+   :alt: License
+
+.. |badge-docs| image:: https://img.shields.io/badge/docs-latest-4aa0d5?logo=readthedocs
+   :target: https://iduclub.github.io/ObjectNat/
+   :alt: Docs
+
+|badge-black| |badge-pypi| |badge-ci| |badge-codecov| |badge-license| |badge-docs|
+
+`РИДМИ (Russian) <https://github.com/IDUclub/ObjectNat/blob/master/README_RU.rst>`__
+
+.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/master/docs/_static/ONlogo.svg
+   :align: center
+   :width: 400
+   :alt: ObjectNat logo
+
+
+**ObjectNat** is an open-source library developed by the **IDU** team
+for spatial and network analysis in urban studies.
+The library provides tools for analyzing **accessibility**, **visibility**,
+**noise propagation**, and **service provision**.
+----
+
+Key Features
+------------
+
+Each feature includes a **Jupyter Notebook example** and **full documentation**.
+
+1. **Isochrones and Transport Accessibility**  
+
+   Isochrones represent areas reachable from an origin point within a specified time along a transport network.
+   This feature allows the analysis of transport accessibility using pedestrian, road,
+   public transport, or multimodal graphs.
+
+   The library supports several methods for building isochrones:
+
+   - **Basic isochrones**: display a single zone reachable within a specified time.
+   - **Step isochrones**: divide the accessibility area into time intervals (e.g., 3, 5, 10 minutes).
+
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/isochrones.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/isochrones.html>`__
+
+2. **Graph Coverage Zones from Points**
+
+   A function for generating **coverage areas** from a set of origin points using a transport network.
+   It computes the area reachable from each point by **travel time** or **distance**,
+   then builds polygons using **Voronoi diagrams** and clips them by a given boundary if specified.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/coverage.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/coverage.html>`__
+
+3. **Service Provision Analysis**  
+
+   A function to evaluate how well residential buildings and their populations are provided
+   with services (e.g., schools, clinics) that have limited **capacity**
+   and a defined **accessibility threshold** (in minutes or meters).
+   The function models the **balance between supply and demand**,
+   assessing how well services meet the needs of nearby buildings within an acceptable time.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/provision.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/provision.html>`__
+
+4. **Visibility Analysis**  
+
+   A function for evaluating visibility from a given point or set of points to nearby buildings within a given radius.
+   It is used to assess visual accessibility in urban environments.
+   A module is also implemented for computing **visibility coverage zones**
+   using a dense observer grid (recommended ~1000 points with a 10–20 m spacing).
+   Points can be generated along the transport network and distributed across its edges.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/visibility.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/visibility.html>`__
+
+5. **Noise Simulation & Noise Frame**
+
+   Simulation of noise propagation from sources, taking into account **obstacles**, **vegetation**,
+   and **environmental factors**.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/noise.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/noise.html>`__
+   🧠 `Detailed theory <https://github.com/DDonnyy/ObjectNat/wiki/Noise-simulation>`__
+
+6. **Point Clusterization**  
+
+   A function for constructing **cluster polygons** based on a set of points using:
+
+   - Minimum **distance** between points.
+   - Minimum **number of points** in a cluster.
+
+   The function can also compute the **ratio of service types** in each cluster
+   for spatial analysis of service composition.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/clustering.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/clustering.html>`__
+
+----
+
+City Graphs via *IduEdu*
+------------------------
+
+For optimal performance, **ObjectNat** is recommended to be used with graphs
+created by the `IduEdu <https://github.com/IDUclub/IduEdu>`_ library.
+
+**IduEdu** is an open-source Python library designed for building and processing
+complex urban networks based on OpenStreetMap data.
+
+
+**IduEdu** can be installed via ``pip``::
+
+    pip install IduEdu
+
+Example usage::
+
+    from iduedu import get_4326_boundary, get_intermodal_graph
+
+    poly = get_4326_boundary(osm_id=1114252)
+    G_intermodal = get_intermodal_graph(territory=poly, clip_by_territory=True)
+
+----
+
+Installation
+------------
+
+**ObjectNat** can be installed via ``pip``::
+
+    pip install ObjectNat
+
+----
+
+Configuration
+-------------
+
+You can adjust logging and progress bar output using the config module::
+
+    from objectnat import config
+
+    config.change_logger_lvl("INFO")   # mute debug logs
+    config.set_enable_tqdm(False)      # disable tqdm progress bars
+
+----
+
+Contacts
+--------
+
+- `NCCR <https://actcognitive.org/>`_ — National Center for Cognitive Research  
+- `IDU <https://idu.itmo.ru/>`_ — Institute of Design and Urban Studies  
+- `Natalya Chichkova <https://t.me/nancy_nat>`_ — Project Manager  
+- `Danila Oleynikov (Donny) <https://t.me/ddonny_dd>`_ — Lead Software Engineer
+
+----
+
+Publications
+------------
+
+Coming soon.

{objectnat-1.2.2 → objectnat-1.3.1}/pyproject.toml

@@ -1,41 +1,49 @@
 [tool.poetry]
 name = "ObjectNat"
-version = "1.2.2"
+version = "1.3.1"
 description = "ObjectNat is an open-source library created for geospatial analysis created by IDU team"
 license = "BSD-3-Clause"
 authors = ["DDonnyy <63115678+DDonnyy@users.noreply.github.com>"]
-readme = "README.md"
+readme = "README.rst"
 
 packages = [{ include = "objectnat", from = "src" }]
 
 [tool.poetry.dependencies]
-python = ">=3.10,<3.13"
+python = ">=3.11,<3.13"
 numpy = "^2.1.3"
 pandas = "^2.2.0"
 geopandas = "^1.0.1"
 tqdm = "^4.66.2"
-pandarallel = "^1.6.5"
 networkx = "^3.4.2"
 scikit-learn = "^1.4.0"
 loguru = "^0.7.3"
 
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.5"
+pytest-cov = "^6.0.0"
+folium = "^0.19.5"
+matplotlib = "^3.10.1"
+mapclassify = "^2.8.1"
+iduedu = "^1.0.0"
+
 [tool.poetry.group.dev.dependencies]
-iduedu = "^0.5.0"
 pyarrow = "^19.0.1"
 black = "^24.2.0"
 pylint = "^3.0.3"
 isort = "^5.13.2"
 jupyter = "^1.0.0"
-pytest = "^8.3.5"
-pytest-cov = "^6.0.0"
 pre-commit = "^4.2.0"
-folium = "^0.19.5"
-matplotlib = "^3.10.1"
-mapclassify = "^2.8.1"
-mkdocs = "^1.6.1"
-mkdocstrings = {extras = ["python"], version = "^0.29.1"}
-mkdocs-material = "^9.6.14"
-mike = "^2.1.3"
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^8.0.0"
+furo = "^2025.9.25"
+myst-nb = "^1.1.0"
+sphinx-autodoc-typehints = "^3.2.0"
+sphinx-copybutton = "^0.5.2"
+sphinx-design = "^0.6.0"
+myst-parser = "^4.0.1"
+linkify-it-py = "^2.0.3"
 
 [build-system]
 requires = ["poetry-core"]
@@ -43,7 +51,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.black]
 line-length = 120
-target-version = ['py310']
+target-version = ['py311']
 
 [tool.pylint.format]
 max-line-length = 120

{objectnat-1.2.2 → objectnat-1.3.1}/src/objectnat/_config.py

@@ -1,47 +1,43 @@
-import sys
-from typing import Literal
-
-from loguru import logger
-
-
-class Config:
-    """
-    A configuration class to manage global settings for the application, such as Overpass API URL,
-    timeouts, and logging options.
-
-    Attributes
-    ----------
-    enable_tqdm_bar : bool
-        Enables or disables progress bars (via tqdm). Defaults to True.
-    logger : Logger
-        Logging instance to handle application logging.
-
-    Methods
-    -------
-    change_logger_lvl(lvl: Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"])
-        Changes the logging level to the specified value.
-    set_enable_tqdm(enable: bool)
-        Enables or disables progress bars in the application.
-    """
-
-    def __init__(
-        self,
-        enable_tqdm_bar=True,
-    ):
-        self.enable_tqdm_bar = enable_tqdm_bar
-        self.logger = logger
-        self.pandarallel_use_file_system = False
-
-    def change_logger_lvl(self, lvl: Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]):
-        self.logger.remove()
-        self.logger.add(sys.stderr, level=lvl)
-
-    def set_enable_tqdm(self, enable: bool):
-        self.enable_tqdm_bar = enable
-
-    def set_pandarallel_use_file_system(self, enable: bool):
-        self.pandarallel_use_file_system = enable
-
-
-config = Config()
-config.change_logger_lvl("INFO")
+import sys
+from typing import Literal
+
+from loguru import logger
+
+
+class Config:
+    """
+    A configuration class to manage global settings for the application, such as Overpass API URL,
+    timeouts, and logging options.
+
+    Attributes
+    ----------
+    enable_tqdm_bar : bool
+        Enables or disables progress bars (via tqdm). Defaults to True.
+    logger : Logger
+        Logging instance to handle application logging.
+
+    Methods
+    -------
+    change_logger_lvl(lvl: Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"])
+        Changes the logging level to the specified value.
+    set_enable_tqdm(enable: bool)
+        Enables or disables progress bars in the application.
+    """
+
+    def __init__(
+        self,
+        enable_tqdm_bar=True,
+    ):
+        self.enable_tqdm_bar = enable_tqdm_bar
+        self.logger = logger
+
+    def change_logger_lvl(self, lvl: Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]):
+        self.logger.remove()
+        self.logger.add(sys.stderr, level=lvl)
+
+    def set_enable_tqdm(self, enable: bool):
+        self.enable_tqdm_bar = enable
+
+
+config = Config()
+config.change_logger_lvl("INFO")

objectnat-1.3.1/src/objectnat/_version.py

@@ -0,0 +1 @@
+VERSION = "1.3.1"

{objectnat-1.2.2 → objectnat-1.3.1}/src/objectnat/methods/coverage_zones/graph_coverage.py

@@ -27,20 +27,27 @@ def get_graph_coverage(
         4. Combining reachability information with Voronoi cells
         5. Clipping results to specified zone boundary
 
-    Parameters:
+    Args:
         gdf_to (gpd.GeoDataFrame):
             Source points to which coverage is calculated.
+
         nx_graph (nx.Graph):
             NetworkX graph representing the transportation network.
-        weight_type (Literal["time_min", "length_meter"]):
-            Edge attribute to use as weight for path calculations.
+
+        weight_type:
+            Type of edge weight to use for path calculation:
+
+            - ``"time_min"``: Edge travel time in minutes
+            - ``"length_meter"``: Edge length in meters
+
         weight_value_cutoff (float):
             Maximum weight value for path calculations (e.g., max travel time/distance).
+
         zone (gpd.GeoDataFrame):
             Boundary polygon to clip the resulting coverage zones. If None, concave hull of reachable nodes will be used.
 
     Returns:
-        (gpd.GeoDataFrame):
+        gpd.GeoDataFrame:
             GeoDataFrame with coverage zones polygons, each associated with its source point, returns in the same CRS
             as original gdf_from.
 

{objectnat-1.2.2 → objectnat-1.3.1}/src/objectnat/methods/coverage_zones/radius_voronoi_coverage.py

@@ -6,16 +6,18 @@ def get_radius_coverage(gdf_from: gpd.GeoDataFrame, radius: float, resolution: i
     """
     Calculate radius-based coverage zones using Voronoi polygons.
 
-    Parameters:
+    Args:
         gdf_from (gpd.GeoDataFrame):
             Source points for which coverage zones are calculated.
+
         radius (float):
             Maximum coverage radius in meters.
+
         resolution (int):
             Number of segments used to approximate quarter-circle in buffer (default=32).
 
     Returns:
-        (gpd.GeoDataFrame):
+        gpd.GeoDataFrame:
             GeoDataFrame with smoothed coverage zone polygons in the same CRS as original gdf_from.
 
     Notes:

{objectnat-1.2.2 → objectnat-1.3.1}/src/objectnat/methods/coverage_zones/stepped_coverage.py

@@ -31,30 +31,40 @@ def get_stepped_graph_coverage(
         4. Aggregates zones into stepped coverage layers
         5. Optionally clips results to a boundary zone
 
-    Parameters:
+    Args:
         gdf_to (gpd.GeoDataFrame):
             Source points from which stepped coverage is calculated.
+
         nx_graph (nx.Graph):
             NetworkX graph representing the transportation network.
-        weight_type (Literal["time_min", "length_meter"]):
+
+        weight_type:
             Type of edge weight to use for path calculation:
-            - "time_min": Edge travel time in minutes
-            - "length_meter": Edge length in meters
-        step_type (Literal["voronoi", "separate"]):
+
+            - ``"time_min"``: Edge travel time in minutes
+            - ``"length_meter"``: Edge length in meters
+
+        step_type:
             Method for generating stepped zones:
-            - "voronoi": Stepped zones based on Voronoi polygons around graph nodes
-            - "separate": Independent buffer zones per step
+
+            - ``"voronoi"``: Stepped zones based on Voronoi polygons around graph nodes
+            - ``"separate"``: Independent buffer zones per step
+
         weight_value_cutoff (float, optional):
             Maximum weight value (e.g., max travel time or distance) to limit the coverage extent.
+
         zone (gpd.GeoDataFrame, optional):
             Optional boundary polygon to clip resulting stepped zones. If None, concave hull of reachable area is used.
+
         step (float, optional):
             Step interval for coverage zone construction. Defaults to:
-                - 100 meters for distance-based weight
-                - 1 minute for time-based weight
+
+            - 100 meters for distance-based weight
+            - 1 minute for time-based weight
 
     Returns:
-        (gpd.GeoDataFrame): GeoDataFrame with polygons representing stepped coverage zones for each input point,
+        gpd.GeoDataFrame:
+            GeoDataFrame with polygons representing stepped coverage zones for each input point,
             annotated by step range.
 
     Notes: