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

sgis/maps/thematicmap.py

@@ -10,8 +10,10 @@ import numpy as np
 import pandas as pd
 from geopandas import GeoDataFrame
 
+from .legend import LEGEND_KWARGS
 from .legend import ContinousLegend
 from .legend import Legend
+from .legend import prettify_bins
 from .map import Map
 
 # the geopandas._explore raises a deprication warning. Ignoring for now.
@@ -20,60 +22,132 @@ warnings.filterwarnings(
 )
 pd.options.mode.chained_assignment = None
 
+MAP_KWARGS = {
+    "bins",
+    "title",
+    "title_fontsize",
+    "size",
+    "cmap",
+    "cmap_start",
+    "cmap_stop",
+    "scheme",
+    "k",
+    "column",
+    "title_color",
+    "facecolor",
+    "labelcolor",
+    "nan_color",
+    "title_kwargs",
+    "bg_gdf_color",
+    "title_position",
+}
+
 
 class ThematicMap(Map):
-    """Class for creating static maps with geopandas and matplotlib.
-
-    The class takes one or more GeoDataFrames and a column name. The class attributes
-    can then be set to customise the map before plotting.
-
-    Attributes:
-        size (int): Width and height of the plot in inches.
-        k (int): Number of color groups.
-        legend (Legend): The legend object of the map. The legend holds its own set of
-            attributes. See the Legend class for details.
-        title (str): Title of the plot.
-        title_color (str): Color of the title font.
-        title_fontsize (int): Color of the title font.
-        bins (list[int | float]): For numeric columns. List of numbers that define the
-            maximum value for the color groups.
-        cmap (str): Colormap of the plot. See:
+    """Class for making static maps.
+
+    Args:
+        *gdfs: One or more GeoDataFrames.
+        column: The name of the column to plot.
+        title: Title of the plot.
+        title_position: Title position. Either "center" (default), "left" or "right".
+        size: Width and height of the plot in inches. Fontsize of title and legend is
+            adjusted accordingly. Defaults to 25.
+        dark: If False (default), the background will be white and the text black. If
+            True, the background will be black and the text white. When True, the
+            default cmap is "viridis", and when False, the default is red to purple
+            (RdPu).
+        cmap: Colormap of the plot. See:
             https://matplotlib.org/stable/tutorials/colors/colormaps.html
-        cmap_start (int): Start position for the color palette.
-        cmap_stop (int): End position for the color palette.
-        facecolor (str): Background color.
+        scheme: How to devide numeric values into categories. Defaults to
+            "naturalbreaks".
+        k: Number of color groups.
+        bins: For numeric columns. List of numbers that define the
+            maximum value for the color groups.
+        nan_label: Label for missing data.
+        legend_kwargs: dictionary with attributes for the legend. E.g.:
+            title: Legend title. Defaults to the column name.
+            rounding: If positive number, it will round floats to n decimals.
+                If negative, eg. -2, the number 3429 is rounded to 3400.
+                By default, the rounding depends on the column's maximum value
+                and standard deviation.
+            position: The legend's x and y position in the plot. By default, it's
+                decided dynamically by finding the space with most distance to
+                the geometries. To be specified as a tuple of
+                x and y position between 0 and 1. E.g. position=(0.8, 0.2) for a position
+                in the bottom right corner, (0.2, 0.8) for the upper left corner.
+            pretty_labels: Whether to capitalize words in text categories.
+            label_suffix: For numeric columns. The text to put after each number
+                in the legend labels. Defaults to None.
+            label_sep: For numeric columns. Text to put in between the two numbers
+                in each color group in the legend. Defaults to '-'.
+            thousand_sep: For numeric columns. Separator between each thousand for
+                large numbers. Defaults to None, meaning no separator.
+            decimal_mark: For numeric columns. Text to use as decimal point.
+                Defaults to None, meaning '.' (dot) unless 'thousand_sep' is
+                '.'. In this case, ',' (comma) will be used as decimal mark.
+        **kwargs: Additional attributes for the map. E.g.:
+            title_color (str): Color of the title font.
+            title_fontsize (int): Color of the title font.
+            cmap_start (int): Start position for the color palette.
+            cmap_stop (int): End position for the color palette.
+            facecolor (str): Background color.
+            labelcolor (str): Color for the labels.
+            nan_color: Color for missing data.
 
     Examples:
     --------
     >>> import sgis as sg
-    >>> points = sg.random_points(100).pipe(sg.buff, np.random.rand(100))
-    >>> points2 = sg.random_points(100).pipe(sg.buff, np.random.rand(100))
+    >>> points = sg.random_points(100, loc=1000).pipe(sg.buff, np.random.rand(100) * 100)
+    >>> points2 = sg.random_points(100, loc=1000).pipe(sg.buff, np.random.rand(100) * 100)
+
 
     Simple plot with legend and title.
 
-    >>> m = sg.ThematicMap(points, points2, "area")
-    >>> m.title = "Area of random circles"
+    >>> m = sg.ThematicMap(points, points2, column="area", title="Area of random circles")
     >>> m.plot()
 
-    Plot with custom legend units (label_suffix) and separator (label_sep).
-
-    >>> m = sg.ThematicMap(points, points2, "area")
-    >>> m.title = "Area of random circles"
-    >>> m.legend.label_suffix = "m2"
-    >>> m.legend.label_sep = "to"
+    Plot with custom legend units (label_suffix) and thousand separator.
+    And with rounding set to -2, meaning e.g. 3429 is rounded to 3400.
+    If rounding was set to positive 2, 3429 would be rounded to 3429.00.
+
+    >>> m = sg.ThematicMap(
+    ...     points,
+    ...     points2,
+    ...     column="area",
+    ...     title = "Area of random circles",
+    ...     legend_kwargs=dict(
+    ...         rounding=-2,
+    ...         thousand_sep=" ",
+    ...         label_sep="to",
+    ...     ),
+    ... )
     >>> m.plot()
 
-    With custom bins and legend labels.
-
-    >>> m = sg.ThematicMap(points, points2, "area")
-    >>> m.title = "Area of random circles"
-    >>> m.bins = [1, 2, 3]
-    >>> m.legend.labels = [
-    ...     f"{int(round(min(points.length),0))} to 1",
-    ...     "1 to 2",
-    ...     "2 to 3",
-    ...     f"3 to {int(round(max(points.length),0))}",
-    ... ]
+    With custom bins for the categories, and other customizations.
+
+    >>> m = sg.ThematicMap(
+    ...     points,
+    ...     points2,
+    ...     column="area",
+    ...     cmap="Greens",
+    ...     cmap_start=50,
+    ...     cmap_stop=255,
+    ...     nan_label="Missing",
+    ...     title = "Area of random circles",
+    ...     bins = [5000, 10000, 15000, 20000],
+    ...     title_kwargs=dict(
+    ...         loc="left",
+    ...         y=0.93,
+    ...         x=0.025,
+    ...     ),
+    ...     legend_kwargs=dict(
+    ...         thousand_sep=" ",
+    ...         label_sep="to",
+    ...         decimal_mark=".",
+    ...         label_suffix="m2",
+    ...     ),
+    ... )
     >>> m.plot()
     """
 
@@ -81,37 +155,100 @@ class ThematicMap(Map):
         self,
         *gdfs: GeoDataFrame,
         column: str | None = None,
+        title: str | None = None,
+        title_position: tuple[float, float] | None = None,
         size: int = 25,
-        black: bool = False,
+        dark: bool = False,
+        cmap: str | None = None,
+        scheme: str = "naturalbreaks",
+        k: int = 5,
+        bins: tuple[float] | None = None,
+        nan_label: str = "Missing",
+        legend_kwargs: dict | None = None,
+        title_kwargs: dict | None = None,
+        **kwargs,
     ) -> None:
-        """Initialiser.
-
-        Args:
-            *gdfs: One or more GeoDataFrames.
-            column: The name of the column to plot.
-            size: Width and height of the plot in inches. Fontsize of title and legend is
-                adjusted accordingly. Defaults to 25.
-            black: If False (default), the background will be white and the text black. If
-                True, the background will be black and the text white. When True, the
-                default cmap is "viridis", and when False, the default is red to purple
-                (RdPu).
-
-        """
-        super().__init__(*gdfs, column=column)
+        """Initialiser."""
+        super().__init__(
+            *gdfs,
+            column=column,
+            scheme=scheme,
+            k=k,
+            bins=bins,
+            nan_label=nan_label,
+        )
 
+        self.title = title
         self._size = size
-        self._black = black
+        self._dark = dark
+        self.title_kwargs = title_kwargs or {}
+        if title_position and "position" in self.title_kwargs:
+            raise TypeError(
+                "Specify either 'title_position' or title_kwargs position, not both."
+            )
+        if title_position or "position" in self.title_kwargs:
+            position = self.title_kwargs.pop("position", title_position)
+            error_mess = (
+                "legend_kwargs position should be a two length tuple/list with two numbers between "
+                "0 and 1 (x, y position)"
+            )
+            if not hasattr(position, "__len__"):
+                raise TypeError(error_mess)
+            if len(position) != 2:
+                raise ValueError(error_mess)
+            x, y = position
+            if "loc" not in self.title_kwargs:
+                if x < 0.4:
+                    self.title_kwargs["loc"] = "left"
+                elif x > 0.6:
+                    self.title_kwargs["loc"] = "right"
+                else:
+                    self.title_kwargs["loc"] = "center"
+
+            self.title_kwargs["x"], self.title_kwargs["y"] = x, y
         self.background_gdfs = []
 
-        self._title_fontsize = self._size * 2
+        legend_kwargs = legend_kwargs or {}
 
-        self.black = black
+        self._title_fontsize = self._size * 1.9
 
-        if not self._is_categorical:
+        black = kwargs.pop("black", None)
+        self._dark = self._dark or black
+
+        if not self.cmap and not self._is_categorical:
             self._choose_cmap()
 
+        self._dark_or_light()
         self._create_legend()
 
+        if cmap:
+            self._cmap = cmap
+
+        for key, value in kwargs.items():
+            if key not in MAP_KWARGS:
+                raise TypeError(
+                    f"{self.__class__.__name__} got an unexpected keyword argument {key}"
+                )
+            try:
+                setattr(self, key, value)
+            except Exception:
+                setattr(self, f"_{key}", value)
+
+        for key, value in legend_kwargs.items():
+            if key not in LEGEND_KWARGS:
+                raise TypeError(
+                    f"{self.__class__.__name__} legend_kwargs got an unexpected key {key}"
+                )
+            try:
+                setattr(self.legend, key, value)
+            except Exception:
+                setattr(self.legend, f"_{key}", value)
+
+    @property
+    def valid_keywords(self) -> set[str]:
+        """List all valid keywords for the class initialiser."""
+        return MAP_KWARGS
+
     def change_cmap(self, cmap: str, start: int = 0, stop: int = 256) -> "ThematicMap":
         """Change the color palette of the plot.
 
@@ -177,7 +314,7 @@ class ThematicMap(Map):
         else:
             kwargs = self._prepare_continous_plot(kwargs)
             if self.legend:
-                if not self.legend._rounding_has_been_set:
+                if not self.legend.rounding:
                     self.legend._rounding = self.legend._get_rounding(
                         array=self._gdf.loc[~self._nan_idx, self._column]
                     )
@@ -194,15 +331,15 @@ class ThematicMap(Map):
                 self._gdf, k=self._k + bool(len(self._nan_idx))
             )
 
-        if __test:
-            return
-
         self._prepare_plot(**kwargs)
 
         if self.legend:
             self.ax = self.legend._actually_add_legend(ax=self.ax)
 
-        self._gdf.plot(legend=include_legend, ax=self.ax, **kwargs)
+        self.ax = self._gdf.plot(legend=include_legend, ax=self.ax, **kwargs)
+
+        if __test:
+            return self
 
     def save(self, path: str) -> None:
         """Save figure as image file.
@@ -238,9 +375,13 @@ class ThematicMap(Map):
         if hasattr(self, "_background_gdfs"):
             self._actually_add_background()
 
-        if hasattr(self, "title") and self.title:
+        if self.title:
             self.ax.set_title(
-                self.title, fontsize=self.title_fontsize, color=self.title_color
+                self.title,
+                **(
+                    dict(fontsize=self.title_fontsize, color=self.title_color)
+                    | self.title_kwargs
+                ),
             )
 
     def _prepare_continous_plot(self, kwargs: dict) -> dict:
@@ -257,6 +398,13 @@ class ThematicMap(Map):
             return kwargs
 
         else:
+            if self.legend.rounding and self.legend.rounding < 0:
+                self.bins = prettify_bins(self.bins, self.legend.rounding)
+                self.bins = list({round(bin_, 5) for bin_ in self.bins})
+                self.bins.sort()
+                # self.legend._rounding_was = self.legend.rounding
+                # self.legend.rounding = None
+
             classified = self._classify_from_bins(self._gdf, bins=self.bins)
             classified_sequential = self._push_classification(classified)
             n_colors = len(np.unique(classified_sequential)) - any(self._nan_idx)
@@ -264,10 +412,13 @@ class ThematicMap(Map):
             self._bins_unique_values = self._make_bin_value_dict(
                 self._gdf, classified_sequential
             )
+
             colorarray = self._unique_colors[classified_sequential]
             kwargs["color"] = colorarray
 
-        if self.legend and not self.legend._rounding_has_been_set:
+        if (
+            self.legend and self.legend.rounding
+        ):  # not self.legend._rounding_has_been_set:
             self.bins = self.legend._set_rounding(
                 bins=self.bins, rounding=self.legend._rounding
             )
@@ -279,10 +430,13 @@ class ThematicMap(Map):
 
     def _prepare_categorical_plot(self, kwargs: dict) -> dict:
         """Map values to colors."""
-        self._get_categorical_colors()
-        colorarray = self._gdf["color"]
+        self._make_categories_colors_dict()
+        if self._gdf is not None and len(self._gdf):
+            self._fix_nans()
 
-        kwargs["color"] = colorarray
+        if self._gdf is not None:
+            colorarray = self._gdf["color"]
+            kwargs["color"] = colorarray
         return kwargs
 
     def _actually_add_legend(self) -> None:
@@ -310,7 +464,7 @@ class ThematicMap(Map):
     def _create_legend(self) -> None:
         """Instantiate the Legend class."""
         kwargs = {}
-        if self._black:
+        if self._dark:
             kwargs["facecolor"] = "#0f0f0f"
             kwargs["labelcolor"] = "#fefefe"
             kwargs["title_color"] = "#fefefe"
@@ -322,7 +476,7 @@ class ThematicMap(Map):
 
     def _choose_cmap(self) -> None:
         """Kwargs is to catch start and stop points for the cmap in __init__."""
-        if self._black:
+        if self._dark:
             self._cmap = "viridis"
             self.cmap_start = 0
             self.cmap_stop = 256
@@ -352,8 +506,8 @@ class ThematicMap(Map):
         ax = fig.add_subplot(1, 1, 1)
         return fig, ax
 
-    def _black_or_white(self) -> None:
-        if self._black:
+    def _dark_or_light(self) -> None:
+        if self._dark:
             self.facecolor, self.title_color, self.bg_gdf_color = (
                 "#0f0f0f",
                 "#fefefe",
@@ -367,23 +521,22 @@ class ThematicMap(Map):
             self.facecolor, self.title_color, self.bg_gdf_color = (
                 "#fefefe",
                 "#0f0f0f",
-                "#ebebeb",
+                "#dbdbdb",
             )
             self.nan_color = "#c2c2c2"
             if not self._is_categorical:
                 self.change_cmap("RdPu", start=23)
 
-        self._create_legend()
-
     @property
-    def black(self) -> bool:
+    def dark(self) -> bool:
         """Whether to use dark background and light text colors."""
-        return self._black
+        return self._dark
 
-    @black.setter
-    def black(self, new_value: bool):
-        self._black = new_value
-        self._black_or_white()
+    @dark.setter
+    def dark(self, new_value: bool):
+        self._dark = new_value
+        self._dark_or_light()
+        self._create_legend()
 
     @property
     def title_fontsize(self) -> int:

sgis/networkanalysis/closing_network_holes.py

@@ -44,7 +44,7 @@ def close_network_holes(
         NetworkAnalysis. These values must be filled before analysis.
 
     Examples:
-    --------
+    ---------
     Read road data with small gaps.
 
     >>> import sgis as sg
@@ -157,7 +157,7 @@ def close_network_holes_to_deadends(
         The input GeoDataFrame with new lines added.
 
     Examples:
-    --------
+    ---------
     Read road data with small gaps.
 
     >>> import sgis as sg

sgis/networkanalysis/cutting_lines.py

@@ -52,7 +52,7 @@ def split_lines_by_nearest_point(
         ValueError: If the crs of the input data differs.
 
     Examples:
-    --------
+    ---------
     >>> from sgis import read_parquet_url, split_lines_by_nearest_point
     >>> roads = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
     >>> points = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/points_oslo.parquet")
@@ -255,7 +255,7 @@ def cut_lines(
         This method is time consuming for large networks and low 'max_length'.
 
     Examples:
-    --------
+    ---------
     >>> from sgis import read_parquet_url, cut_lines
     >>> roads = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
     >>> roads.length.describe().round(1)
@@ -327,7 +327,7 @@ def cut_lines_once(
             Defaults to False.
 
     Examples:
-    --------
+    ---------
     >>> from sgis import cut_lines_once, to_gdf
     >>> import pandas as pd
     >>> from shapely.geometry import LineString

sgis/networkanalysis/directednetwork.py

@@ -29,7 +29,7 @@ def make_directed_network_norway(gdf: GeoDataFrame, dropnegative: bool) -> GeoDa
             to keep them.
 
     Examples:
-    --------
+    ---------
     2022 data for the municipalities of Oslo and Eidskog can be read directly like this:
 
     >>> import sgis as sg

sgis/networkanalysis/finding_isolated_networks.py

@@ -23,7 +23,7 @@ def get_connected_components(gdf: GeoDataFrame) -> GeoDataFrame:
         The GeoDataFrame with a new column "connected".
 
     Examples:
-    --------
+    ---------
     >>> from sgis import read_parquet_url, get_connected_components
     >>> roads = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
 
@@ -76,7 +76,7 @@ def get_component_size(gdf: GeoDataFrame) -> GeoDataFrame:
         A GeoDataFrame with a new column "component_size".
 
     Examples:
-    --------
+    ---------
     >>> from sgis import read_parquet_url, get_component_size
     >>> roads = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
 

sgis/networkanalysis/networkanalysis.py

@@ -57,7 +57,7 @@ class NetworkAnalysis:
         log: A DataFrame with information about each analysis run.
 
     Examples:
-    --------
+    ---------
     Read example data.
 
     >>> import sgis as sg
@@ -191,7 +191,7 @@ class NetworkAnalysis:
             straight lines between origin and destination.
 
         Examples:
-        --------
+        ---------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
@@ -479,7 +479,7 @@ class NetworkAnalysis:
                 that contain weights and all indices of 'origins' and 'destinations'.
 
         Examples:
-        --------
+        ---------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
@@ -692,7 +692,7 @@ class NetworkAnalysis:
             containing the indices of the origins and destinations GeoDataFrames.
 
         Examples:
-        --------
+        ---------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
@@ -820,7 +820,7 @@ class NetworkAnalysis:
             ValueError: if drop_middle_percent is not between 0 and 100.
 
         Examples:
-        --------
+        ---------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
@@ -966,7 +966,7 @@ class NetworkAnalysis:
             precice results.
 
         Examples:
-        --------
+        ---------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg
@@ -1093,7 +1093,7 @@ class NetworkAnalysis:
             service_area: Faster method where lines are not cut to get precice results.
 
         Examples:
-        --------
+        ---------
         Create the NetworkAnalysis instance.
 
         >>> import sgis as sg

sgis/networkanalysis/networkanalysisrules.py

@@ -50,7 +50,7 @@ class NetworkAnalysisRules:
             to 1, the weight will be equal to the straigt line distance.
 
     Examples:
-    --------
+    ---------
     Read testdata.
 
     >>> import sgis as sg

sgis/networkanalysis/traveling_salesman.py

@@ -32,7 +32,7 @@ def traveling_salesman_problem(
         List of Points making up the traveling salesman's path.
 
     Examples:
-    --------
+    ---------
     >>> import sgis as sg
     >>> from shapely.geometry import LineString
     >>> points = sg.to_gdf(