lsapy 0.1.0__py3-none-any.whl

lsapy/__init__.py

@@ -0,0 +1,9 @@
+"""A Python package for Land Suitability Analysis."""
+
+from lsapy.criteria import SuitabilityCriteria
+from lsapy.functions import *
+from lsapy.lsa import LandSuitabilityAnalysis
+
+__author__ = "Baptiste Hamon"
+__email__ = "baptiste.hamon@pg.canterbury.ac.nz"
+__version__ = "0.1.0"

lsapy/core/__init__.py

@@ -0,0 +1 @@
+"""Core Module."""

lsapy/core/functions.py

@@ -0,0 +1,52 @@
+"""Suitability Function Utilities."""
+
+from collections.abc import Callable
+
+equations: dict[str, dict] = {}
+
+
+def declare_equation(type: str, alt_name: str | None = None) -> Callable:
+    """
+    Register an equation in the `equations` mapping under the specified type.
+
+    Parameters
+    ----------
+    type : str
+        The type of equation to register.
+    alt_name : str, optional
+        An alternative name for the equation (not currently supported).
+
+    Returns
+    -------
+    Callable
+        A decorator function that registers the equation.
+    """
+
+    # TODO: Support alternative names for equations
+    def _decorator(func: callable):
+        if type not in equations:
+            equations[type] = {}
+        equations[type].update({func.__name__: func})
+        return func
+
+    return _decorator
+
+
+def get_function_from_name(name: str) -> Callable:
+    """
+    Retrieve a function by its name from the registered equations.
+
+    Parameters
+    ----------
+    name : str
+        The name of the function to retrieve.
+
+    Returns
+    -------
+    Callable
+        The function corresponding to the given name.
+    """
+    for _, funcs in equations.items():
+        if name in funcs:
+            return funcs[name]
+    raise ValueError(f"Equation `{name}` not implemented.")

lsapy/criteria.py

@@ -0,0 +1,181 @@
+"""Suitability Criteria definition."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import xarray as xr
+
+from lsapy.functions import SuitabilityFunction
+
+__all__ = ["SuitabilityCriteria"]
+
+
+class SuitabilityCriteria:
+    """
+    A data structure for suitability criteria.
+
+    Suitability criteria are used to compute the suitability of a location from an indicator and based on a set of rules
+    defined by a suitability function. The suitability criteria can be weighted and categorized defining how it will be
+    aggregated with other criteria.
+
+    Parameters
+    ----------
+    name : str
+        Name of the suitability criteria.
+    indicator : xr.DataArray
+        Indicator on which the criteria is based.
+    func : SuitabilityFunction | MembershipFunction | DiscreteSuitFunction
+        Suitability function describing how the suitability of the criteria is computed.
+    weight : int | float | None, optional
+        Weight of the criteria used in the aggregation process if a weighted aggregation method is used.
+        The default is 1.
+    category : str | None, optional
+        Category of the criteria. The default is None.
+    long_name : str | None, optional
+        A long name for the criteria. The default is None.
+    description : str | None, optional
+        A description for the criteria. The default is None.
+    comment : str | None, optional
+        Additional information about the criteria.
+    is_computed : bool, optional
+        If the indicator data already contains the computed suitability values. Default is False.
+
+    Examples
+    --------
+    Here is an example using the sample soil data with the drainage class (DRC) as indicator for the criteria.
+
+    >>> from lsapy.utils import load_soil_data, load_climate_data
+    >>> from lsapy.functions import SuitabilityFunction
+    >>> from xclim.indicators.atmos import growing_degree_days
+
+    >>> soil_data = load_soil_data()
+    >>> sc = SuitabilityCriteria(
+    ...     name="drainage_class",
+    ...     long_name="Drainage Class Suitability",
+    ...     weight=3,
+    ...     category="soilTerrain",
+    ...     indicator=soil_data["DRC"],
+    ...     func=SuitabilityFunction(name="discrete", params={"rules": {"1": 0, "2": 0.1, "3": 0.5, "4": 0.9, "5": 1}}),
+    ... )
+
+    Here is another example using the sample climate data with the growing degree days (GDD)
+    as indicator for the criteria computing using the `xclim` package.
+
+    >>> clim_data = load_climate_data()
+    >>> gdd = growing_degree_days(clim_data["tas"], thresh="10 degC", freq="YS-JUL")
+    >>> sc = SuitabilityCriteria(
+    ...     name="growing_degree_days",
+    ...     long_name="Growing Degree Days Suitability",
+    ...     weight=1,
+    ...     category="climate",
+    ...     indicator=gdd,
+    ...     func=SuitabilityFunction(name="vetharaniam2022_eq5", params={"a": -1.41, "b": 801}),
+    ... )
+    """
+
+    def __init__(
+        self,
+        name: str,
+        indicator: xr.DataArray,
+        func: SuitabilityFunction | Callable = None,
+        weight: int | float | None = 1,
+        category: str | None = None,
+        long_name: str | None = None,
+        description: str | None = None,
+        comment: str | None = None,
+        is_computed: bool = False,
+    ) -> None:
+        self.name = name
+        self.indicator = indicator
+        self.func = func
+        self.weight = weight
+        self.category = category
+        self.long_name = long_name
+        self.description = description
+        self.comment = comment
+        self.is_computed = is_computed
+        self._from_indicator = _get_indicator_description(indicator)
+
+    def __repr__(self) -> str:
+        """Return a string representation for a particular criteria."""
+        attrs = []
+        attrs.append(f"name='{self.name}'")
+        attrs.append(f"indicator={self.indicator.name}")
+        attrs.append(f"func={self.func if self.func is not None else 'unknown'}")
+        attrs.append(f"weight={self.weight}")
+        if self.category is not None:
+            attrs.append(f"category='{self.category}'")
+        if self.long_name is not None:
+            attrs.append(f"long_name='{self.long_name}'")
+        if self.description is not None:
+            attrs.append(f"description='{self.description}'")
+        if self.comment is not None:
+            attrs.append(f"comment='{self.comment}'")
+        if self.is_computed:
+            attrs.append("is_computed=True")
+        return f"{self.__class__.__name__}({', '.join(attrs) if attrs else ''})"
+
+    def compute(self) -> xr.DataArray:
+        """
+        Compute the suitability of the criteria.
+
+        Returns a xarray DataArray with criteria suitability. The attributes of the DataArray describe how
+        the suitability was computed.
+
+        Returns
+        -------
+        xr.DataArray
+            Criteria suitability.
+        """
+        if self.is_computed:
+            sc = self.indicator
+        elif self.func is None:
+            raise ValueError("The suitability function is not defined. Please provide a valid function.")
+        else:
+            sc: xr.DataArray = xr.apply_ufunc(self.func, self.indicator)
+        return sc.rename(self.name).assign_attrs(
+            dict(
+                {
+                    k: v
+                    for k, v in self.attrs.items()
+                    if k not in ["name", "func_method", "from_indicator", "is_computed"]
+                },
+                **{
+                    "history": f"func_method: {self.func if self.func is not None else 'unknown'}; "
+                    f"from_indicator: [{self._from_indicator}]"
+                },
+            )
+        )
+
+    @property
+    def attrs(self) -> dict:
+        """
+        Dictionary of the criteria attributes.
+
+        Returns
+        -------
+        dict
+            Dictionary with the criteria attributes.
+        """
+        return {
+            k: v
+            for k, v in {
+                "name": self.name,
+                "weight": self.weight,
+                "category": self.category,
+                "long_name": self.long_name,
+                "description": self.description,
+                "func_method": self.func if self.func is not None else "unknown",
+                "from_indicator": self._from_indicator,
+                "is_computed": self.is_computed,
+            }.items()
+            if v is not None
+        }
+
+
+def _get_indicator_description(indicator: xr.Dataset | xr.DataArray) -> str:
+    if indicator.attrs != {}:
+        return f"name: {indicator.name}; " + "; ".join([f"{k}: {v}" for k, v in indicator.attrs.items()])
+    else:
+        return f"name: {indicator.name}"

lsapy/functions/__init__.py

@@ -0,0 +1,7 @@
+"""Suitability Functions Module."""
+
+from __future__ import annotations
+
+from lsapy.functions._discrete import *
+from lsapy.functions._suitability import SuitabilityFunction
+from lsapy.functions.membership import *

lsapy/functions/_discrete.py

@@ -0,0 +1,30 @@
+"""Discrete Function Module."""
+
+import numpy as np
+
+from lsapy.core.functions import declare_equation
+
+__all__ = ["discrete"]
+
+
+@declare_equation("categorical")
+def discrete(x, rules: dict[str | int, int | float]) -> np.ndarray:
+    """
+    Discrete suitability function.
+
+    This function maps the indicator values to a set of rules that define the suitability values.
+
+    Parameters
+    ----------
+    x : any
+        Indicator values to map.
+    rules : dict[str | int, int | float]
+        Rules to map the indicator values to suitability values. The keys correspond to the indicator values and the
+        values to its associated suitability values.
+
+    Returns
+    -------
+    np.ndarray
+        Suitability values.
+    """
+    return np.vectorize(rules.get, otypes=[np.float32])(x, np.nan)

lsapy/functions/_suitability.py

@@ -0,0 +1,158 @@
+"""Suitability Function Module."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import Any
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from lsapy.core.functions import get_function_from_name
+
+__all__ = [
+    "SuitabilityFunction",
+]
+
+
+class SuitabilityFunction:
+    """
+    Suitability Function.
+
+    Suitability function define how the criteria indicator is transformed into a suitability value. The suitability
+    function are available for continuous and discrete indicators. For continuous indicators, a membership function
+    is applied to convert indicator values into a suitability. For discrete indicators, a set of rules is mapped
+    on the indicator.
+
+    Parameters
+    ----------
+    func : Callable | None, optional
+        Function to compute the suitability value.
+    name : str | None, optional
+        Name of the implemented function to use. If `func` is provided, this parameter is ignored.
+    params : dict[str, Any], optional
+        Parameters of the function.
+
+    Examples
+    --------
+    >>> func = SuitabilityFunction(name="logistic", params={"a": 1, "b": 5})
+    >>> func(3)
+    array(0.11920292, dtype=float32)
+
+    ``SuitabilityFunction`` can also be used for discrete functions.
+
+    >>> func = SuitabilityFunction(name="discrete", params={"rules": {1: 0, 2: 0.1, 3: 0.5, 4: 0.9, 5: 1}})
+    >>> func(3)
+    array(0.5, dtype=float32)
+    """
+
+    def __init__(self, func: Callable | None = None, name: str | None = None, params: dict[str, Any] | None = None):
+        if func is None:
+            if name is None:
+                raise ValueError("Either `func` or `name` must be provided to define the suitability function.")
+            elif not isinstance(name, str):
+                raise TypeError("`name` must be a string when `func` is not provided.")
+            else:
+                self.func = get_function_from_name(name)
+        else:
+            if not isinstance(func, Callable):
+                raise TypeError("`func` must be a callable function.")
+            if name is not None:
+                warnings.warn("`name` is ignored when `func` is provided", stacklevel=2)
+            self.func = func
+
+        self.params = params
+
+    def __call__(self, x):
+        """Call the suitability function."""
+        if self.func is None:
+            raise ValueError("No function has been provided.")
+        if self.params:
+
+            def func(val):
+                """Wrap the function to include parameters."""
+                return self.func(val, **self.params)
+        else:
+
+            def func(val):
+                """Wrap the function without parameters."""
+                return self.func(val)
+
+        return np.vectorize(func, otypes=[np.float32])(x)
+
+    def __repr__(self):
+        """Return the string representation of the object."""
+        return f"{self.__class__.__name__}(func={self.func.__name__}, params={self.params})"
+
+    @property
+    def attrs(self) -> dict[str, Any]:
+        """
+        Dictionary of the suitability function attributes.
+
+        Returns
+        -------
+        dict
+            Dictionary containing the function name and parameters. If both are undefined, an empty dictionary
+            is returned.
+        """
+        return {k: v for k, v in {"func": self.func, "params": self.params}.items() if v is not None}
+
+    def map(self, x):
+        """
+        Map the suitability function.
+
+        This method converts the input values into suitability values for the defined function.
+
+        Parameters
+        ----------
+        x : any
+            Input values to map.
+
+        Returns
+        -------
+        any
+            Suitability values.
+
+        Raises
+        ------
+        ValueError
+            If no function has been provided.
+
+        Examples
+        --------
+        >>> from lsapy.functions import logistic
+
+        >>> sf = SuitabilityFunction(func=logistic, params={"a": 1, "b": 5})
+        >>> sf.map(3)
+        array(0.11920292, dtype=float32)
+
+        .. deprecated:: 0.1.0-dev2
+          `map` will be removed in LSAPy 0.1.0 because it is redundant with the `__call__` method.
+          Please use the `__call__` method directly instead.
+        """
+        warnings.warn(
+            "`map` is deprecated and will be removed in LSAPy 0.1.0. Use `__call__` directly instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return self(x)
+
+    def plot(self, x) -> None:
+        """
+        Basic plot of the suitability function.
+
+        Parameters
+        ----------
+        x : any
+            Input values to plot.
+
+        Examples
+        --------
+        >>> import numpy as np  # doctest: +SKIP
+        >>> from lsapy.functions import logistic
+
+        >>> sf = SuitabilityFunction(func=logistic, params={"a": 1, "b": 5})
+        >>> sf.plot(np.linspace(0, 10, 100))  # doctest: +SKIP
+        """
+        plt.plot(x, self(x))