ObjectNat 0.2.6__py3-none-any.whl → 1.0.0__py3-none-any.whl

objectnat/methods/isochrones/isochrones.py

@@ -0,0 +1,325 @@
+from typing import Literal
+
+import geopandas as gpd
+import networkx as nx
+import numpy as np
+from shapely.ops import polygonize
+
+from objectnat import config
+from objectnat.methods.isochrones.isochrone_utils import (
+    _calculate_distance_matrix,
+    _create_isochrones_gdf,
+    _prepare_graph_and_nodes,
+    _process_pt_data,
+    _validate_inputs,
+)
+from objectnat.methods.utils.geom_utils import polygons_to_multilinestring, remove_inner_geom
+from objectnat.methods.utils.graph_utils import graph_to_gdf
+
+logger = config.logger
+
+
+def get_accessibility_isochrone_stepped(
+    isochrone_type: Literal["radius", "ways", "separate"],
+    point: gpd.GeoDataFrame,
+    weight_value: float,
+    weight_type: Literal["time_min", "length_meter"],
+    nx_graph: nx.Graph,
+    step: float = None,
+    **kwargs,
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame | None, gpd.GeoDataFrame | None]:
+    """
+    Calculate stepped accessibility isochrones for a single point with specified intervals.
+
+    Parameters
+    ----------
+    isochrone_type : Literal["radius", "ways", "separate"]
+        Visualization method for stepped isochrones:
+        - "radius": Voronoi-based in circular buffers
+        - "ways": Voronoi-based in road network polygons
+        - "separate": Circular buffers for each step
+    point : gpd.GeoDataFrame
+        Single source point for isochrone calculation (uses first geometry if multiple provided).
+    weight_value : float
+        Maximum travel time (minutes) or distance (meters) threshold.
+    weight_type : Literal["time_min", "length_meter"]
+        Type of weight calculation:
+        - "time_min": Time-based in minutes
+        - "length_meter": Distance-based in meters
+    nx_graph : nx.Graph
+        NetworkX graph representing the transportation network.
+    step : float, optional
+        Interval between isochrone steps. Defaults to:
+        - 100 meters for distance-based
+        - 1 minute for time-based
+    **kwargs
+        Additional buffer parameters:
+        - buffer_factor: Size multiplier for buffers (default: 0.7)
+        - road_buffer_size: Buffer size for road edges in meters (default: 5)
+
+    Returns
+    -------
+    tuple[gpd.GeoDataFrame, gpd.GeoDataFrame | None, gpd.GeoDataFrame | None]
+        Tuple containing:
+        - stepped_isochrones: GeoDataFrame with stepped polygons and distance/time attributes
+        - pt_stops: Public transport stops within isochrones (if available)
+        - pt_routes: Public transport routes within isochrones (if available)
+
+    Examples
+    --------
+    >>> from iduedu import get_intermodal_graph # pip install iduedu to get OSM city network graph
+    >>> graph = get_intermodal_graph(polygon=my_territory_polygon)
+    >>> point = gpd.GeoDataFrame(geometry=[Point(30.33, 59.95)], crs=4326)
+    >>> # Stepped radius isochrones with 5-minute intervals
+    >>> radius_stepped, stops, _ = get_accessibility_isochrone_stepped(
+    ...     "radius", point, 30, "time_min", graph, step=5
+    ... )
+    >>> # Stepped road isochrones with 200m intervals
+    >>> ways_stepped, _, routes = get_accessibility_isochrone_stepped(
+    ...     "ways", point, 1000, "length_meter", graph, step=200
+    ... )
+    >>> # Voronoi-based stepped isochrones
+    >>> separate_stepped, stops, _ = get_accessibility_isochrone_stepped(
+    ...     "separate", point, 15, "time_min", graph
+    ... )
+    """
+    buffer_params = {
+        "buffer_factor": 0.7,
+        "road_buffer_size": 5,
+    }
+
+    buffer_params.update(kwargs)
+    original_crs = point.crs
+    point = point.copy()
+    if len(point) > 1:
+        logger.warning(
+            f"This method processes only single point. The GeoDataFrame contains {len(point)} points - "
+            "only the first geometry will be used for isochrone calculation. "
+        )
+        point = point.iloc[[0]]
+
+    local_crs, graph_type = _validate_inputs(point, weight_value, weight_type, nx_graph)
+
+    if step is None:
+        if weight_type == "length_meter":
+            step = 100
+        else:
+            step = 1
+    nx_graph, points, dist_nearest, speed = _prepare_graph_and_nodes(
+        point, nx_graph, graph_type, weight_type, weight_value
+    )
+
+    dist_matrix, subgraph = _calculate_distance_matrix(
+        nx_graph, points["nearest_node"].values, weight_type, weight_value, dist_nearest
+    )
+
+    logger.info("Building isochrones geometry...")
+    nodes, edges = graph_to_gdf(subgraph)
+    nodes.loc[dist_matrix.columns, "dist"] = dist_matrix.iloc[0]
+    steps = np.arange(0, weight_value + step, step)
+    if steps[-1] > weight_value:
+        steps[-1] = weight_value  # Ensure last step doesn't exceed weight_value
+
+    if isochrone_type == "separate":
+        for i in range(len(steps) - 1):
+            min_dist = steps[i]
+            max_dist = steps[i + 1]
+            nodes_in_step = nodes["dist"].between(min_dist, max_dist, inclusive="left")
+            nodes_in_step = nodes_in_step[nodes_in_step].index
+            if not nodes_in_step.empty:
+                buffer_size = (max_dist - nodes.loc[nodes_in_step, "dist"]) * 0.7
+                if weight_type == "time_min":
+                    buffer_size = buffer_size * speed
+                nodes.loc[nodes_in_step, "buffer_size"] = buffer_size
+        nodes.geometry = nodes.geometry.buffer(nodes["buffer_size"])
+        nodes["dist"] = np.round(nodes["dist"], 0)
+        nodes = nodes.dissolve(by="dist", as_index=False)
+        polygons = gpd.GeoDataFrame(
+            geometry=list(polygonize(nodes.geometry.apply(polygons_to_multilinestring).union_all())),
+            crs=local_crs,
+        )
+        polygons_points = polygons.copy()
+        polygons_points.geometry = polygons.representative_point()
+
+        stepped_iso = polygons_points.sjoin(nodes, predicate="within").reset_index()
+        stepped_iso = stepped_iso.groupby("index").agg({"dist": "mean"})
+        stepped_iso["geometry"] = polygons
+        stepped_iso = gpd.GeoDataFrame(stepped_iso, geometry="geometry", crs=local_crs).reset_index(drop=True)
+    else:
+        if isochrone_type == "radius":
+            isochrone_geoms = _build_radius_isochrones(
+                dist_matrix, weight_value, weight_type, speed, nodes, buffer_params["buffer_factor"]
+            )
+        else:  # isochrone_type == 'ways':
+            if graph_type in ["intermodal", "walk"]:
+                isochrone_edges = edges[edges["type"] == "walk"]
+            else:
+                isochrone_edges = edges.copy()
+            all_isochrones_edges = isochrone_edges.buffer(buffer_params["road_buffer_size"], resolution=1).union_all()
+            all_isochrones_edges = gpd.GeoDataFrame(geometry=[all_isochrones_edges], crs=local_crs)
+            isochrone_geoms = _build_ways_isochrones(
+                dist_matrix=dist_matrix,
+                weight_value=weight_value,
+                weight_type=weight_type,
+                speed=speed,
+                nodes=nodes,
+                all_isochrones_edges=all_isochrones_edges,
+                buffer_factor=buffer_params["buffer_factor"],
+            )
+        nodes = nodes.clip(isochrone_geoms[0], keep_geom_type=True)
+        nodes["dist"] = np.minimum(np.ceil(nodes["dist"] / step) * step, weight_value)
+        voronois = gpd.GeoDataFrame(geometry=nodes.voronoi_polygons(), crs=local_crs)
+        stepped_iso = (
+            voronois.sjoin(nodes[["dist", "geometry"]]).dissolve(by="dist", as_index=False).drop(columns="index_right")
+        )
+        stepped_iso = stepped_iso.clip(isochrone_geoms[0], keep_geom_type=True)
+
+    pt_nodes, pt_edges = _process_pt_data(nodes, edges, graph_type)
+    if pt_nodes is not None:
+        pt_nodes.to_crs(original_crs, inplace=True)
+    if pt_edges is not None:
+        pt_edges.to_crs(original_crs, inplace=True)
+    return stepped_iso.to_crs(original_crs), pt_nodes, pt_edges
+
+
+def get_accessibility_isochrones(
+    isochrone_type: Literal["radius", "ways"],
+    points: gpd.GeoDataFrame,
+    weight_value: float,
+    weight_type: Literal["time_min", "length_meter"],
+    nx_graph: nx.Graph,
+    **kwargs,
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame | None, gpd.GeoDataFrame | None]:
+    """
+    Calculate accessibility isochrones from input points based on the provided city graph.
+
+    Supports two types of isochrones:
+    - 'radius': Circular buffer-based isochrones
+    - 'ways': Road network-based isochrones
+
+    Parameters
+    ----------
+    isochrone_type : Literal["radius", "ways"]
+        Type of isochrone to calculate:
+        - "radius": Creates circular buffers around reachable nodes
+        - "ways": Creates polygons based on reachable road network
+    points : gpd.GeoDataFrame
+        GeoDataFrame containing source points for isochrone calculation.
+    weight_value : float
+        Maximum travel time (minutes) or distance (meters) threshold.
+    weight_type : Literal["time_min", "length_meter"]
+        Type of weight calculation:
+        - "time_min": Time-based accessibility in minutes
+        - "length_meter": Distance-based accessibility in meters
+    nx_graph : nx.Graph
+        NetworkX graph representing the transportation network.
+        Must contain CRS and speed attributes for time calculations.
+    **kwargs
+        Additional buffer parameters:
+        - buffer_factor: Size multiplier for buffers (default: 0.7)
+        - road_buffer_size: Buffer size for road edges in meters (default: 5)
+
+    Returns
+    -------
+    tuple[gpd.GeoDataFrame, gpd.GeoDataFrame | None, gpd.GeoDataFrame | None]
+        Tuple containing:
+        - isochrones: GeoDataFrame with calculated isochrone polygons
+        - pt_stops: Public transport stops within isochrones (if available)
+        - pt_routes: Public transport routes within isochrones (if available)
+
+    Examples
+    --------
+    >>> from iduedu import get_intermodal_graph # pip install iduedu to get OSM city network graph
+    >>> graph = get_intermodal_graph(polygon=my_territory_polygon)
+    >>> points = gpd.GeoDataFrame(geometry=[Point(30.33, 59.95)], crs=4326)
+    >>> # Radius isochrones
+    >>> radius_iso, stops, routes = get_accessibility_isochrones(
+    ...     "radius", points, 15, "time_min", graph, buffer_factor=0.8
+    ... )
+    >>> # Road network isochrones
+    >>> ways_iso, stops, routes = get_accessibility_isochrones(
+    ...     "ways", points, 1000, "length_meter", graph, road_buffer_size=7
+    ... )
+    """
+
+    buffer_params = {
+        "buffer_factor": 0.7,
+        "road_buffer_size": 5,
+    }
+    original_crs = points.crs
+    buffer_params.update(kwargs)
+
+    points = points.copy()
+    local_crs, graph_type = _validate_inputs(points, weight_value, weight_type, nx_graph)
+
+    nx_graph, points, dist_nearest, speed = _prepare_graph_and_nodes(
+        points, nx_graph, graph_type, weight_type, weight_value
+    )
+
+    weight_cutoff = (
+        weight_value + (100 if weight_type == "length_meter" else 1) if isochrone_type == "ways" else weight_value
+    )
+
+    dist_matrix, subgraph = _calculate_distance_matrix(
+        nx_graph, points["nearest_node"].values, weight_type, weight_cutoff, dist_nearest
+    )
+
+    logger.info("Building isochrones geometry...")
+    nodes, edges = graph_to_gdf(subgraph)
+    if isochrone_type == "radius":
+        isochrone_geoms = _build_radius_isochrones(
+            dist_matrix, weight_value, weight_type, speed, nodes, buffer_params["buffer_factor"]
+        )
+    else:  # isochrone_type == 'ways':
+        if graph_type in ["intermodal", "walk"]:
+            isochrone_edges = edges[edges["type"] == "walk"]
+        else:
+            isochrone_edges = edges.copy()
+        all_isochrones_edges = isochrone_edges.buffer(buffer_params["road_buffer_size"], resolution=1).union_all()
+        all_isochrones_edges = gpd.GeoDataFrame(geometry=[all_isochrones_edges], crs=local_crs)
+        isochrone_geoms = _build_ways_isochrones(
+            dist_matrix=dist_matrix,
+            weight_value=weight_value,
+            weight_type=weight_type,
+            speed=speed,
+            nodes=nodes,
+            all_isochrones_edges=all_isochrones_edges,
+            buffer_factor=buffer_params["buffer_factor"],
+        )
+    isochrones = _create_isochrones_gdf(points, isochrone_geoms, dist_matrix, local_crs, weight_type, weight_value)
+    pt_nodes, pt_edges = _process_pt_data(nodes, edges, graph_type)
+    if pt_nodes is not None:
+        pt_nodes.to_crs(original_crs, inplace=True)
+    if pt_edges is not None:
+        pt_edges.to_crs(original_crs, inplace=True)
+    return isochrones.to_crs(original_crs), pt_nodes, pt_edges
+
+
+def _build_radius_isochrones(dist_matrix, weight_value, weight_type, speed, nodes, buffer_factor):
+    results = []
+    for source in dist_matrix.index:
+        buffers = (weight_value - dist_matrix.loc[source]) * buffer_factor
+        if weight_type == "time_min":
+            buffers = buffers * speed
+        buffers = nodes.merge(buffers, left_index=True, right_index=True)
+        buffers.geometry = buffers.geometry.buffer(buffers[source], resolution=8)
+        results.append(buffers.union_all())
+    return results
+
+
+def _build_ways_isochrones(dist_matrix, weight_value, weight_type, speed, nodes, all_isochrones_edges, buffer_factor):
+    results = []
+    for source in dist_matrix.index:
+        reachable_nodes = dist_matrix.loc[source]
+        reachable_nodes = reachable_nodes[reachable_nodes <= weight_value]
+        reachable_nodes = (weight_value - reachable_nodes) * buffer_factor
+        if weight_type == "time_min":
+            reachable_nodes = reachable_nodes * speed
+        reachable_nodes = nodes.merge(reachable_nodes, left_index=True, right_index=True)
+        clip_zone = reachable_nodes.buffer(reachable_nodes[source], resolution=4).union_all()
+
+        isochrone_edges = all_isochrones_edges.clip(clip_zone, keep_geom_type=True).explode(ignore_index=True)
+        geom_to_keep = isochrone_edges.sjoin(reachable_nodes, how="inner").index.unique()
+        isochrone = remove_inner_geom(isochrone_edges.loc[geom_to_keep].union_all())
+        results.append(isochrone)
+    return results

objectnat/methods/noise/__init__.py

@@ -0,0 +1,3 @@
+from .noise_sim import simulate_noise
+from .noise_reduce import dist_to_target_db, green_noise_reduce_db
+from .noise_exceptions import InvalidStepError

objectnat/methods/noise/noise_exceptions.py

@@ -0,0 +1,14 @@
+class InvalidStepError(ValueError):
+    def __init__(self, source_noise_db, target_noise_db, db_sim_step, div_, *args):
+        if args:
+            self.message = args[0]
+        else:
+            self.message = (
+                f"The difference between `source_noise_db`({source_noise_db}) and `target_noise_db`({target_noise_db})"
+                f" is not divisible by the step size ({db_sim_step}, remainder = {div_})"
+            )
+
+    def __str__(self):
+        if self.message:
+            return self.message
+        return "The difference between `source_noise_db` and `target_noise_db` is not divisible by the step size"

objectnat/methods/noise/noise_init_data.py

@@ -0,0 +1,10 @@
+import pandas as pd
+
+data = {
+    30: {63: 0, 125: 0.0002, 250: 0.0009, 500: 0.003, 1000: 0.0075, 2000: 0.014, 4000: 0.025, 8000: 0.064},
+    20: {63: 0, 125: 0.0003, 250: 0.0011, 500: 0.0028, 1000: 0.0052, 2000: 0.0096, 4000: 0.025, 8000: 0.083},
+    10: {63: 0, 125: 0.0004, 250: 0.001, 500: 0.002, 1000: 0.0039, 2000: 0.01, 4000: 0.035, 8000: 0.125},
+    0: {63: 0, 125: 0.0004, 250: 0.0008, 500: 0.0017, 1000: 0.0049, 2000: 0.017, 4000: 0.058, 8000: 0.156},
+}
+
+air_resist_ratio = pd.DataFrame(data)

objectnat/methods/noise/noise_reduce.py

@@ -0,0 +1,155 @@
+import numpy as np
+from scipy.optimize import fsolve
+
+from objectnat import config
+
+from .noise_init_data import air_resist_ratio
+
+logger = config.logger
+
+
+def get_air_resist_ratio(temp, freq, check_temp_freq=False):
+    if check_temp_freq:
+        if temp > max(air_resist_ratio.columns) or temp < min(air_resist_ratio.columns):
+            logger.warning(
+                f"The specified temperature of {temp}°C is outside the tabulated data range. "
+                f"The air resistance coefficient for these values may be inaccurate. "
+                f"Recommended temperature range: {min(air_resist_ratio.columns)}°C "
+                f"to {max(air_resist_ratio.columns)}°C."
+            )
+
+        if freq > max(air_resist_ratio.index) or freq < min(air_resist_ratio.index):
+            logger.warning(
+                f"The specified geometric mean frequency of {freq} Hz is outside the tabulated data range."
+                f" The air resistance coefficient for these values may be inaccurate."
+                f" Recommended frequency range: {min(air_resist_ratio.index)} Hz to {max(air_resist_ratio.index)} Hz."
+            )
+
+    def get_nearest_values(array, value):
+        sorted_array = sorted(array)
+        if value in sorted_array:
+            return [value]
+        if value > max(sorted_array):
+            return [sorted_array[-1]]
+        if value < min(sorted_array):
+            return [sorted_array[0]]
+
+        for i, val in enumerate(sorted_array):
+            if value < val:
+                return sorted_array[max(i - 1, 0)], sorted_array[i]
+        return sorted_array[-2], sorted_array[-1]
+
+    nearest_temp = get_nearest_values(air_resist_ratio.columns, temp)
+    nearest_freq = get_nearest_values(air_resist_ratio.index, freq)
+
+    if len(nearest_temp) == 1 and len(nearest_freq) == 1:
+        return air_resist_ratio.loc[nearest_freq[0], nearest_temp[0]]
+
+    if len(nearest_temp) == 2 and len(nearest_freq) == 2:
+        freq1, freq2 = nearest_freq
+        temp1, temp2 = nearest_temp
+
+        coef_temp1_freq1 = air_resist_ratio.loc[freq1, temp1]
+        coef_temp1_freq2 = air_resist_ratio.loc[freq2, temp1]
+        coef_temp2_freq1 = air_resist_ratio.loc[freq1, temp2]
+        coef_temp2_freq2 = air_resist_ratio.loc[freq2, temp2]
+
+        weight_temp1 = (temp2 - temp) / (temp2 - temp1)
+        weight_temp2 = (temp - temp1) / (temp2 - temp1)
+        weight_freq1 = (freq2 - freq) / (freq2 - freq1)
+        weight_freq2 = (freq - freq1) / (freq2 - freq1)
+
+        coef_freq1 = coef_temp1_freq1 * weight_temp1 + coef_temp2_freq1 * weight_temp2
+        coef_freq2 = coef_temp1_freq2 * weight_temp1 + coef_temp2_freq2 * weight_temp2
+
+        final_coef = coef_freq1 * weight_freq1 + coef_freq2 * weight_freq2
+
+        return final_coef
+
+    if len(nearest_temp) == 2 and len(nearest_freq) == 1:
+        temp1, temp2 = nearest_temp
+        freq1 = nearest_freq[0]
+
+        coef_temp1 = air_resist_ratio.loc[freq1, temp1]
+        coef_temp2 = air_resist_ratio.loc[freq1, temp2]
+
+        weight_temp1 = (temp2 - temp) / (temp2 - temp1)
+        weight_temp2 = (temp - temp1) / (temp2 - temp1)
+
+        return coef_temp1 * weight_temp1 + coef_temp2 * weight_temp2
+
+    if len(nearest_temp) == 1 and len(nearest_freq) == 2:
+        temp1 = nearest_temp[0]
+        freq1, freq2 = nearest_freq
+
+        coef_freq1 = air_resist_ratio.loc[freq1, temp1]
+        coef_freq2 = air_resist_ratio.loc[freq2, temp1]
+
+        weight_freq1 = (freq2 - freq) / (freq2 - freq1)
+        weight_freq2 = (freq - freq1) / (freq2 - freq1)
+
+        return coef_freq1 * weight_freq1 + coef_freq2 * weight_freq2
+
+
+def dist_to_target_db(
+    init_noise_db, target_noise_db, geometric_mean_freq_hz, air_temperature, return_desc=False, check_temp_freq=False
+) -> float | str:
+    """
+    Calculates the distance required for a sound wave to decay from an initial noise level to a target noise level,
+    based on the geometric mean frequency of the sound and the air temperature. Optionally, can return a description
+    of the sound propagation behavior.
+
+    Args:
+        init_noise_db (float): The initial noise level of the source in decibels (dB). This is the starting sound
+            intensity.
+        target_noise_db (float): The target noise level in decibels (dB), representing the level to which the sound
+            decays over distance.
+        geometric_mean_freq_hz (float): The geometric mean frequency of the sound (in Hz). This frequency influences
+            the attenuation of sound over distance. Higher frequencies decay faster than lower ones.
+        air_temperature (float): The temperature of the air in degrees Celsius. This influences the air's resistance
+            to sound propagation.
+        return_desc (bool, optional): If set to `True`, the function will return a description of the sound decay
+            process instead of the calculated distance.
+        check_temp_freq (bool, optional): If `True`, the function will check whether the temperature and frequency
+            are within valid ranges.
+
+    Returns:
+        float or str: If `return_desc` is `False`, the function returns the distance (in meters) over which the sound
+        decays from `init_noise_db` to `target_noise_db`. If `return_desc` is `True`, a descriptive string is returned
+        explaining the calculation and the conditions.
+    """
+
+    def equation(r):
+        return l - l_ist + 20 * np.log10(r) + k * r
+
+    l_ist = init_noise_db
+    l = target_noise_db
+    k = get_air_resist_ratio(air_temperature, geometric_mean_freq_hz, check_temp_freq)
+    initial_guess = 1
+    r_solution = fsolve(equation, initial_guess)
+    if return_desc:
+        string = (
+            f"Noise level of {init_noise_db} dB "
+            f"with a geometric mean frequency of {geometric_mean_freq_hz} Hz "
+            f"at an air temperature of {air_temperature}°C decays to {target_noise_db} dB "
+            f"over a distance of {r_solution[0]} meters. Air resistance coefficient: {k}."
+        )
+        return string
+    return r_solution[0]
+
+
+def green_noise_reduce_db(geometric_mean_freq_hz, r_tree) -> float:
+    """
+    Calculates the amount of noise reduction (in dB) provided by vegetation of a given thickness at a specified
+    geometric mean frequency. The function models the reduction based on the interaction of the sound with trees or
+    vegetation.
+
+    Args:
+        geometric_mean_freq_hz (float): The geometric mean frequency of the sound (in Hz).
+        r_tree (float): The thickness or density of the vegetation (in meters).
+
+    Returns:
+        float: The noise reduction (in dB) achieved by the vegetation. This value indicates how much quieter the sound
+        will be after passing through or interacting with the vegetation of the specified thickness.
+    """
+    return round(0.08 * r_tree * ((geometric_mean_freq_hz ** (1 / 3)) / 8), 1)