ssb-sgis 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

sgis/networkanalysis/networkanalysis.py

@@ -4,22 +4,27 @@ The class has five analysis methods: od_cost_matrix, get_route, get_k_routes,
 get_route_frequencies and service_area.
 """
 
-
-from copy import copy, deepcopy
+from copy import copy
+from copy import deepcopy
 from datetime import datetime
 from time import perf_counter
+from typing import Any
 
 import igraph
 import numpy as np
 import pandas as pd
 from geopandas import GeoDataFrame
 from igraph import Graph
-from pandas import DataFrame, MultiIndex
+from pandas import DataFrame
+from pandas import MultiIndex
 
 from ..geopandas_tools.general import _push_geom_col
-from ._get_route import _get_k_routes, _get_route, _get_route_frequencies
+from ._get_route import _get_k_routes
+from ._get_route import _get_route
+from ._get_route import _get_route_frequencies
 from ._od_cost_matrix import _od_cost_matrix
-from ._points import Destinations, Origins
+from ._points import Destinations
+from ._points import Origins
 from ._service_area import _service_area
 from .cutting_lines import split_lines_by_nearest_point
 from .network import Network
@@ -46,24 +51,12 @@ class NetworkAnalysis:
     line segments that were visited with an added column for how many times the
     segments were used.
 
-    Args:
-        network: A GeoDataFrame of line geometries.
-        rules: The rules for the analysis, either as an instance of
-            NetworkAnalysisRules or a dictionary with the parameters
-            as keys.
-        log: If True (default), a DataFrame with information about each
-            analysis run will be stored in the 'log' attribute.
-        detailed_log: If True, the log DataFrame will include columns for
-            all arguments passed to the analysis method, plus standard deviation and
-            percentiles (25th, 50th, 75th) of the weight column in the results.
-            Defaults to False.
-
     Attributes:
         network: A Network instance that holds the lines and nodes (points).
         rules: NetworkAnalysisRules instance.
         log: A DataFrame with information about each analysis run.
 
-    Examples
+    Examples:
     --------
     Read example data.
 
@@ -79,13 +72,15 @@ class NetworkAnalysis:
     ...     direction_col="oneway",
     ...     direction_vals_bft=("B", "FT", "TF"),
     ...     minute_cols=("drivetime_fw", "drivetime_bw"),
+    ...     dropnegative=True,
+    ...     dropna=True,
     ... )
 
-    >>> rules = sg.NetworkAnalysisRules(weight="minutes")
+    >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
     >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
     >>> nwa
     NetworkAnalysis(
-        network=DirectedNetwork(6364 km, percent_bidirectional=87),
+        network=Network(6364 km, percent_bidirectional=87),
         rules=NetworkAnalysisRules(weight=minutes, directed=True, search_tolerance=250, search_factor=0, split_lines=False, ...),
         log=True, detailed_log=True,
     )
@@ -100,7 +95,22 @@ class NetworkAnalysis:
         rules: NetworkAnalysisRules | dict,
         log: bool = True,
         detailed_log: bool = False,
-    ):
+    ) -> None:
+        """Initialise NetworkAnalysis instance.
+
+        Args:
+            network: A GeoDataFrame of line geometries.
+            rules: The rules for the analysis, either as an instance of
+                NetworkAnalysisRules or a dictionary with the parameters
+                as keys.
+            log: If True (default), a DataFrame with information about each
+                analysis run will be stored in the 'log' attribute.
+            detailed_log: If True, the log DataFrame will include columns for
+                all arguments passed to the analysis method, plus standard deviation and
+                percentiles (25th, 50th, 75th) of the weight column in the results.
+                Defaults to False.
+
+        """
         if not isinstance(rules, NetworkAnalysisRules):
             rules = NetworkAnalysisRules(**rules)
 
@@ -125,8 +135,8 @@ class NetworkAnalysis:
         self._graph_updated_count = 0
         self._k_nearest_points = 50
 
-    def _check_if_holes_are_nan(self):
-        HOLES_ARE_NAN = (
+    def _check_if_holes_are_nan(self) -> None:
+        holes_are_nan: str = (
             "Network holes have been filled by straigt lines, but the rows have "
             f"NaN values in the {self.rules.weight!r} column. Either remove NaNs "
             "or fill these values with a numeric value (e.g. 0)."
@@ -140,7 +150,7 @@ class NetworkAnalysis:
                 .all()
             )
         ):
-            raise ValueError(HOLES_ARE_NAN)
+            raise ValueError(holes_are_nan)
 
     def od_cost_matrix(
         self,
@@ -180,13 +190,13 @@ class NetworkAnalysis:
             GeoDataFrames. If lines is True, also returns a geometry column with
             straight lines between origin and destination.
 
-        Examples
+        Examples:
         --------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
         >>> roads = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
-        >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
+        >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
         >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
         >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
 
@@ -423,8 +433,8 @@ class NetworkAnalysis:
         destinations: GeoDataFrame,
         weight_df: DataFrame | None = None,
         default_weight: int | float | None = None,
-        strict: bool = False,
         rowwise: bool = False,
+        strict: bool = False,
         frequency_col: str = "frequency",
     ) -> GeoDataFrame:
         """Finds the number of times each line segment was visited in all trips.
@@ -446,6 +456,11 @@ class NetworkAnalysis:
                 index, destination index and weight. In that order) or only a weight
                 column and a MultiIndex where level 0 is origin index and level 1 is
                 destination index.
+            default_weight: If set, OD pairs not represented in 'weight_df'
+                will be given a default weight value.
+            rowwise: if False (default), it will calculate the cost from each
+                origins to each destination. If true, it will calculate the cost from
+                origin 1 to destination 1, origin 2 to destination 2 and so on.
             strict: If True, all OD pairs must be in weigth_df if specified. Defaults
                 to False.
             frequency_col: Name of column with the number of times each road was
@@ -463,14 +478,14 @@ class NetworkAnalysis:
             ValueError: If weight_df is not a DataFrame with one or three columns
                 that contain weights and all indices of 'origins' and 'destinations'.
 
-        Examples
+        Examples:
         --------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
         >>> import pandas as pd
         >>> roads = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
-        >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
+        >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
         >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
         >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
 
@@ -599,10 +614,13 @@ class NetworkAnalysis:
             # map to temporary ids
             ori_idx_mapper = {v: k for k, v in self.origins.idx_dict.items()}
             des_idx_mapper = {v: k for k, v in self.destinations.idx_dict.items()}
-            multiindex_mapper = lambda x: (
-                ori_idx_mapper.get(x[0]),
-                des_idx_mapper.get(x[1]),
-            )
+
+            def multiindex_mapper(x: tuple[int, int]) -> tuple[int, int]:
+                return (
+                    ori_idx_mapper.get(x[0]),
+                    des_idx_mapper.get(x[1]),
+                )
+
             weight_df.index = weight_df.index.map(multiindex_mapper)
         else:
             od_pairs = self._create_od_pairs(
@@ -673,13 +691,13 @@ class NetworkAnalysis:
             Also returns a weight column and the columns 'origin' and 'destination',
             containing the indices of the origins and destinations GeoDataFrames.
 
-        Examples
+        Examples:
         --------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
         >>> roads = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
-        >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
+        >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
         >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
         >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
 
@@ -801,13 +819,13 @@ class NetworkAnalysis:
         Raises:
             ValueError: if drop_middle_percent is not between 0 and 100.
 
-        Examples
+        Examples:
         --------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
         >>> roads = sg.read_parquet_url('https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet')
-        >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
+        >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
         >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
         >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
 
@@ -943,17 +961,17 @@ class NetworkAnalysis:
             a dissolved line geometry. If dissolve is False, it will return each line
             that is part of the service area.
 
-        See also:
+        See Also:
             precice_service_area: Equivelent method where lines are also cut to get
             precice results.
 
-        Examples
+        Examples:
         --------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
         >>> roads = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
-        >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
+        >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
         >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
         >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
 
@@ -972,7 +990,6 @@ class NetworkAnalysis:
 
         Service areas of 5, 10 and 15 minutes from three origin points.
 
-        >>> nwa = NetworkAnalysis(network=nw, rules=rules)
         >>> service_areas = nwa.service_area(
         ...         points.iloc[:2],
         ...         breaks=[5, 10, 15],
@@ -1072,16 +1089,16 @@ class NetworkAnalysis:
             geometry. If dissolve is False, it will return all the columns of the
             network.gdf as well.
 
-        See also:
+        See Also:
             service_area: Faster method where lines are not cut to get precice results.
 
-        Examples
+        Examples:
         --------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
         >>> roads = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
-        >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
+        >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
         >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
         >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
 
@@ -1099,7 +1116,6 @@ class NetworkAnalysis:
 
         Service areas of 5, 10 and 15 minutes from three origin points.
 
-        >>> nwa = NetworkAnalysis(network=nw, rules=rules)
         >>> sa = nwa.precice_service_area(
         ...         points.iloc[:2],
         ...         breaks=[5, 10, 15],
@@ -1189,7 +1205,7 @@ class NetworkAnalysis:
             "the trip frequency for this origin-destination pair."
         )
 
-        if not isinstance(weight_df, (DataFrame, pd.Series)):
+        if not isinstance(weight_df, (DataFrame | pd.Series)):
             raise ValueError(error_message)
 
         if isinstance(weight_df, pd.Series):
@@ -1221,7 +1237,7 @@ class NetworkAnalysis:
     def _make_sure_index_match(
         weight_df: DataFrame,
         od_pairs: MultiIndex,
-    ):
+    ) -> None:
         """Make sure this index matches the index of origins and destinations."""
         if not od_pairs.isin(weight_df.index).all():
             if not od_pairs.isin(weight_df.index).any():
@@ -1321,7 +1337,7 @@ class NetworkAnalysis:
             for key, value in kwargs.items():
                 if isinstance(value, np.ndarray):
                     value = list(value)
-                if isinstance(value, (list, tuple)):
+                if isinstance(value, (list | tuple)):
                     value = [str(x) for x in value]
                     value = ", ".join(value)
                 df[key] = value
@@ -1329,7 +1345,10 @@ class NetworkAnalysis:
         self.log = pd.concat([self.log, df], ignore_index=True)
 
     def _prepare_network_analysis(
-        self, origins, destinations=None, rowwise: bool = False
+        self,
+        origins: GeoDataFrame,
+        destinations: GeoDataFrame | None = None,
+        rowwise: bool = False,
     ) -> None:
         """Prepares the weight column, node ids, origins, destinations and graph.
 
@@ -1337,7 +1356,6 @@ class NetworkAnalysis:
         has changed. this method is run inside od_cost_matrix, get_route and
         service_area.
         """
-
         if rowwise and len(origins) != len(destinations):
             raise ValueError(
                 "'origins' and 'destinations' must have the same length when "
@@ -1585,14 +1603,14 @@ class NetworkAnalysis:
             ]
 
     @staticmethod
-    def _sort_breaks(breaks) -> list[float | int]:
+    def _sort_breaks(breaks: str | list | tuple | int | float) -> list[float | int]:
         if isinstance(breaks, str):
             breaks = float(breaks)
 
         if hasattr(breaks, "__iter__"):
             return list(sorted(list(breaks)))
 
-        if isinstance(breaks, (int, float)):
+        if isinstance(breaks, (int | float)):
             return [breaks]
 
         raise ValueError(
@@ -1628,11 +1646,11 @@ class NetworkAnalysis:
             "\n)"
         )
 
-    def __getitem__(self, item):
+    def __getitem__(self, item: str) -> Any:
         """To be able to write self['origins'] as well as self.origins."""
         return getattr(self, item)
 
-    def copy(self, deep=True):
+    def copy(self, deep: bool = True) -> "NetworkAnalysis":
         """Returns a (deep) copy of the class instance.
 
         Args:

sgis/networkanalysis/networkanalysisrules.py

@@ -3,7 +3,9 @@
 The class is to be used as the 'rules' parameter in the NetworkAnalysis
 class.
 """
-from copy import copy, deepcopy
+
+from copy import copy
+from copy import deepcopy
 from dataclasses import dataclass
 
 from geopandas import GeoDataFrame
@@ -20,7 +22,7 @@ class NetworkAnalysisRules:
     Args:
         weight: Either a column in the GeoDataFrame of the Network or
             'meters'/'metres'. A 'minutes' column can be created with the
-            'make_directed_network' method of the DirectedNetwork class.
+            'make_directed_network' or 'make_directed_network_norway' functions.
         directed: Whether the lines will be considered traversable in both directions.
         search_tolerance: distance to search for nodes in the network. Origins and
             destinations further away from the network than the search_tolerance will
@@ -47,7 +49,7 @@ class NetworkAnalysisRules:
             them. Defaults to None, meaning 0 weight is added for these edges. If set
             to 1, the weight will be equal to the straigt line distance.
 
-    Examples
+    Examples:
     --------
     Read testdata.
 
@@ -59,12 +61,12 @@ class NetworkAnalysisRules:
     values.
 
     >>> rules = sg.NetworkAnalysisRules(weight="minutes", directed=True)
-    >>> directed_roads = sg.remove_isolated(roads).pipe(sg.make_directed_network_norway)
-    >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=False)
+    >>> directed_roads = sg.get_connected_components(roads).loc[lambda x: x["connected"] == 1].pipe(sg.make_directed_network_norway, dropnegative=True)
+    >>> nwa = sg.NetworkAnalysis(network=directed_roads, rules=rules, detailed_log=True)
     >>> nwa
     NetworkAnalysis(
-        network=DirectedNetwork(6364 km, percent_bidirectional=87),
-        rules=NetworkAnalysisRules(weight=minutes, search_tolerance=250, search_factor=0, split_lines=False, ...),
+        network=Network(6364 km, percent_bidirectional=87),
+        rules=NetworkAnalysisRules(weight=minutes, directed=True, search_tolerance=250, search_factor=0, split_lines=True, ...),
         log=True, detailed_log=True,
     )
 
@@ -171,7 +173,7 @@ class NetworkAnalysisRules:
     nodedist_multiplier: int | float | None = None
     nodedist_kmh: int | float | None = None
 
-    def _update_rules(self):
+    def _update_rules(self) -> None:
         """Stores the rules as separate attributes.
 
         Used for checking whether the rules have changed and the graph have to be
@@ -185,7 +187,7 @@ class NetworkAnalysisRules:
         self._nodedist_multiplier = self.nodedist_multiplier
         self._nodedist_kmh = self.nodedist_kmh
 
-    def _rules_have_changed(self):
+    def _rules_have_changed(self) -> bool:
         """Checks if any of the rules have changed since the graph was last created.
 
         If no rules have changed, time can be saved by not remaking the graph
@@ -235,8 +237,8 @@ class NetworkAnalysisRules:
             self._check_for_negative_values(gdf, self.weight)
             return gdf
 
-        # at this point, the weight is wrong. Now to determine the error
-        # message
+        # at this point, the weight is wrong.
+        # Now to determine the error message
 
         if "meter" in self.weight or "metre" in self.weight:
             raise ValueError(
@@ -257,7 +259,7 @@ class NetworkAnalysisRules:
         raise KeyError(incorrect_weight_column)
 
     @staticmethod
-    def _check_for_nans(df, col):
+    def _check_for_nans(df: GeoDataFrame, col: str) -> None:
         """Remove NaNs and give warning if there are any."""
         if all(df[col].isna()):
             raise ValueError(f"All values in the {col!r} column are NaN.")
@@ -270,7 +272,7 @@ class NetworkAnalysisRules:
             )
 
     @staticmethod
-    def _check_for_negative_values(df, col):
+    def _check_for_negative_values(df: GeoDataFrame, col: str) -> None:
         """Remove negative values and give warning if there are any."""
         negative = sum(df[col] < 0)
         if negative:
@@ -280,7 +282,7 @@ class NetworkAnalysisRules:
             )
 
     @staticmethod
-    def _try_to_float(df, col):
+    def _try_to_float(df: GeoDataFrame, col: str) -> GeoDataFrame:
         """Try to convert weight column to float, raise ValueError if it fails."""
         try:
             df[col] = df[col].astype(float)
@@ -291,8 +293,10 @@ class NetworkAnalysisRules:
             ) from e
         return df
 
-    def copy(self):
+    def copy(self) -> "NetworkAnalysisRules":
+        """Return a shallow copy the instance."""
         return copy(self)
 
-    def deepcopy(self):
+    def deepcopy(self) -> "NetworkAnalysisRules":
+        """Return a deep copy the instance."""
         return deepcopy(self)

sgis/networkanalysis/nodes.py

@@ -6,7 +6,8 @@ to use explicitly.
 
 import geopandas as gpd
 import pandas as pd
-from geopandas import GeoDataFrame, GeoSeries
+from geopandas import GeoDataFrame
+from geopandas import GeoSeries
 from shapely.geometry import Point
 
 from ..geopandas_tools.general import _push_geom_col
@@ -34,7 +35,6 @@ def make_node_ids(
     Note:
         The lines must be singlepart linestrings.
     """
-
     gdf = gdf.explode(index_parts=False).explode(index_parts=False)
 
     if wkt:
@@ -192,7 +192,6 @@ def _prepare_make_edge_cols_simple(
     lines: GeoDataFrame,
 ) -> tuple[GeoDataFrame, GeoDataFrame]:
     """Faster version of _prepare_make_edge_cols."""
-
     endpoints = lines[lines._geometry_column_name].boundary.explode(ignore_index=True)
 
     if len(lines) and len(endpoints) / len(lines) != 2:

sgis/networkanalysis/traveling_salesman.py

@@ -1,6 +1,7 @@
 import networkx as nx
 import pandas as pd
-from geopandas import GeoDataFrame, GeoSeries
+from geopandas import GeoDataFrame
+from geopandas import GeoSeries
 from networkx.utils import pairwise
 from shapely.geometry import Point
 
@@ -30,8 +31,10 @@ def traveling_salesman_problem(
     Returns:
         List of Points making up the traveling salesman's path.
 
-    Examples
+    Examples:
     --------
+    >>> import sgis as sg
+    >>> from shapely.geometry import LineString
     >>> points = sg.to_gdf(
     ...     [
     ...         (0, 0),