lsapy 0.1.0.dev0__py3-none-any.whl

lsapy/__init__.py

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

lsapy/criteria.py

@@ -0,0 +1,72 @@
+"""Suitability Criteria definition."""
+
+from typing import Optional, Union, Any
+import xarray as xr
+
+from lsapy.functions import SuitabilityFunction, MembershipSuitFunction, DiscreteSuitFunction
+
+__all__ = ["SuitabilityCriteria"]
+
+class SuitabilityCriteria:
+    def __init__(
+            self,
+            name: str,
+            indicator: xr.Dataset | xr.DataArray,
+            func: Union[SuitabilityFunction, MembershipSuitFunction, DiscreteSuitFunction],
+            weight: Optional[Union[int,float]] = 1,
+            category: Optional[str] = None,
+            long_name: Optional[str] = None,
+            description: Optional[str] = None
+
+    ) -> 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._from_indicator = _get_indicator_description(indicator)
+    
+    def __repr__(self) -> str:
+        attrs = []
+        attrs.append(f"name='{self.name}'")
+        attrs.append(f"indicator={self.indicator.name}")
+        attrs.append(f"func={self.func}")
+        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}'")
+        return f"{self.__class__.__name__}({', '.join(attrs) if attrs else ''})"
+        
+    
+    def compute(self) -> xr.DataArray:
+        if self.func.func_method == 'discrete': # need to vectorize the discrete function
+            sc : xr.DataArray = xr.apply_ufunc(self.func.map, self.indicator).rename(self.name)
+        else:
+            sc : xr.DataArray = self.func.map(self.indicator).rename(self.name)
+        return sc.assign_attrs(dict({k: v for k, v in self.attrs.items() if k not in ['name', 'func_method', 'from_indicator']},
+                                    **{'history': f"func_method: {self.func}; from_indicator: [{self._from_indicator}]", 'compute': 'done'}))
+    
+    
+    @property
+    def attrs(self):
+        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,
+                    'from_indicator': self._from_indicator
+                }.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.py

@@ -0,0 +1,266 @@
+"""Suitability Functions definitions."""
+
+from typing import Optional, Callable, Union, Any
+import warnings
+import matplotlib.pyplot as plt
+import numpy as np
+import xarray as xr
+from scipy.optimize import curve_fit
+
+
+__all__ = [
+    "SuitabilityFunction",
+    "MembershipSuitFunction",
+    "DiscreteSuitFunction"
+]
+
+
+class SuitabilityFunction:
+
+    def __init__(
+            self,
+            func: Optional[Callable] = None,
+            func_method: Optional[str] = None,
+            func_params: Union[dict[str, Any]] = {}
+    ):
+        if func_params is not None:
+            if func is None and func_method is None:
+                raise ValueError("If `func_params` is provided, `func` or `func_method` must also be provided.")
+
+        self.func = func
+        self.func_method = func_method
+        self.func_params = func_params
+        if func is None and func_method is not None:
+            self.func = _get_function_from_name(func_method)
+    
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(func={self.func.__name__}, func_method='{self.func_method}', func_params={self.func_params})"
+    
+
+    def __call__(self, x):
+        if self.func is None:
+            raise ValueError("No function has been provided.")
+        return self.func(x, **self.func_params)
+    
+    
+    def map(self, x):
+        return self(x)
+    
+
+    def plot(self, x) -> None:
+        plt.plot(x, self(x))
+
+
+    @property
+    def attrs(self):
+        if self.func_method == None and self.func_params == None:
+            return {}
+        return {k: v for k, v in {
+                    'func_method': self.func_method,
+                    'func_params': self.func_params
+                }.items() if v is not None}
+
+
+# ---------------------------------------------------------------------------- #
+# ------------------------ Membership functions ------------------------------ #
+# ---------------------------------------------------------------------------- #
+
+
+class MembershipSuitFunction(SuitabilityFunction):
+
+    def __init__(
+            self,
+            func: Optional[Callable] = None,
+            func_method: Optional[str] = None,
+            func_params: Optional[dict[str, int | float]] = None
+    ):
+        super().__init__(func, func_method, func_params)
+
+
+    @staticmethod
+    def fit(x, y = np.array([0,.25,.5,.75,1]), methods: str | list[str] = 'all', plot: bool = False):
+        return _fit_mbs_functions(x, y, methods, plot)
+
+
+def _prepare_for_fitting(methods:  str | list[str] = 'all'):
+    _types = ['sigmoid_like', 'gaussian_like']
+    _skipped = []
+
+    if methods == 'all':
+        methods = [f for t in _types for f in equations[t.replace('_like', '')]]
+    elif isinstance(methods, list) or isinstance(methods, str):
+        if isinstance(methods, str):
+            methods = [methods]
+        
+        _methods = []
+        for method in methods:
+            if method in _types:
+                [_methods.append(m) for m in equations[method.replace('_like', '')].keys()]
+            else:
+                try :
+                    _get_function_from_name(method)
+                    _methods.append(method)
+                except :
+                    _skipped.append(method)
+                    warnings.warn(f"`{method}` not found in equations. Skipped.", stacklevel=2)
+        methods = _methods
+        for m in ['sigmoid', 'vetharaniam2024_eq8']:
+            if m in methods:
+                methods.remove(m)
+                _skipped.append(m)
+                if m == 'sigmoid':
+                    warnings.warn("No parameters to determine for `sigmoid`. Skipped.", stacklevel=2)
+                if m == 'vetharaniam2024_eq8':
+                    warnings.warn("Fitting method does not support `vetharaniam2024_eq8`. Skipped.", stacklevel=2)
+    return methods, _skipped
+
+
+def _get_function_p0(method: str, x: np.ndarray) -> list[float]:
+    if method in equations['sigmoid']:
+        return [1, np.median(x)]
+    if method in equations['gaussian']:
+        return [1, np.median(x), 1]
+    return []
+
+
+def _fit_mbs_functions(x, y, methods: str | list[str] = 'all', plot: bool = False):
+    
+    skipped = []
+    methods, _skipped = _prepare_for_fitting(methods)
+    skipped.extend(_skipped)
+
+    if len(methods) == 0:
+        print(f"Skipped fitting for the following methods: {', '.join(skipped)}.")
+        raise ValueError("No methods to fit.")
+    else :
+        x_ = np.linspace(min(x), max(x), 100)
+        rms_errors = []
+        f_params = []
+        for method in methods:
+            try :
+                f = _get_function_from_name(method)
+                p0 = _get_function_p0(method, x)
+                popt, _ = curve_fit(f, x, y, p0=p0, maxfev=15000)
+                y_ = f(x_, *popt)
+                f_params.append(popt)
+                rmse = _rms_error(y,f(x, *popt))
+                rms_errors.append(rmse)
+                if plot:
+                    plt.plot(x_, y_, label=method + f' (RMSE={rmse:.2f})')
+            except:
+                skipped.append(method)
+                warnings.warn(f"Failed to fit `{method}`. Skipped.", stacklevel=2)
+        if plot:
+            plt.scatter(x, y, c='r')
+            plt.legend()
+            plt.show()
+
+        if len(skipped) > 0:
+            print(f"Skipped fitting for the following methods: {', '.join(skipped)}.")
+    f_best, p_best = _get_best_fit(methods, rms_errors, f_params)
+    return _get_function_from_name(f_best), p_best
+
+
+# ---------------------------------------------------------------------------- #
+# --------------------------- Discrete functions ----------------------------- #
+# ---------------------------------------------------------------------------- #
+
+class DiscreteSuitFunction(SuitabilityFunction):
+
+    def __init__(
+            self,
+            func_params: Optional[dict[str, int | float]] = None
+    ):
+        self.func = discrete
+        self.func_method = 'discrete'
+        self.func_params = func_params
+
+
+# ---------------------------------------------------------------------------- #
+# ---------------------------- Utility functions ----------------------------- #
+# ---------------------------------------------------------------------------- #
+
+equations : dict[str, dict] = {}
+
+
+def _get_function_from_name(name: str) -> callable:
+    for _type, funcs in equations.items():
+        if name in funcs:
+            return funcs[name]
+    raise ValueError(f"Equation `{name}` not implemented.")
+
+
+def equation(type: str):
+    """
+    Register an equation in the `equations` mapping under the specified type.
+
+    Parameters
+    ----------
+    type : str
+        The type of equation to register.
+    
+    Returns
+    -------
+    decorator
+        The decorator function.
+    """
+
+    def decorator(func: callable):
+        if type not in equations:
+            equations[type] = {}
+
+        equations[type].update({func.__name__: func})
+        return func
+    return decorator
+
+
+@equation('discrete')
+def discrete(x, rules: dict[str|int, int|float]) -> float:
+    return np.vectorize(rules.get, otypes=[np.float32])(x, np.nan)
+
+
+@equation('sigmoid')
+def logistic(x, a, b):
+    return 1 / (1 + np.exp(-a*(x - b)))
+
+
+@equation('sigmoid')
+def sigmoid(x):
+    return logistic(x, 1, 0)
+
+
+@equation('sigmoid')
+def vetharaniam2022_eq3(x, a, b):
+    return np.exp(a * (x - b)) / (1 + np.exp(a * (x - b)))
+
+
+@equation('sigmoid')
+def vetharaniam2022_eq5(x, a, b):
+    return 1 / (1 + np.exp(a * (np.sqrt(x) - np.sqrt(b))))
+
+
+@equation('gaussian')
+def vetharaniam2024_eq8(x, a, b, c):
+    return np.exp(-a * np.power(x - b, c))
+
+
+@equation('gaussian')
+def vetharaniam2024_eq10(x, a, b, c):
+    return 2 / (1 + np.exp(a * np.power(np.power(x, c) - np.power(b, c), 2)))
+
+
+def _rms_error(y_true, y_pred):
+    diff = abs(y_true - y_pred)
+    return np.sqrt(np.mean(diff**2))
+
+
+def _get_best_fit(methods, rmse, params, verbose=True):
+    best_fit = np.nanargmin(rmse)
+    if verbose:
+        print(f"""
+Best fit: {methods[best_fit]}
+RMSE: {rmse[best_fit]:.5f}
+Params: a={params[best_fit][0]}, b={params[best_fit][1]}
+""")
+    return methods[best_fit], params[best_fit]

lsapy/lsa.py

@@ -0,0 +1,331 @@
+"""Land Suitability definition."""
+
+from typing import Optional, Any, Union
+import xarray as xr
+import numpy as np
+import pandas as pd
+import geopandas as gpd
+from shapely.geometry import mapping
+import rioxarray
+import regionmask
+
+from lsapy.criteria import SuitabilityCriteria
+from lsapy.statistics import statistics_summary, spatial_statistics_summary
+
+__all__ = ["LandSuitability"]
+
+
+class LandSuitability:
+    
+    def __init__(
+            self,
+            name: str,
+            criteria: dict[str, SuitabilityCriteria],
+            short_name: Optional[str] = None,
+            long_name: Optional[str] = None,
+            description: Optional[str] = None,
+    ) -> None:
+        self.name = name
+        self.criteria = criteria
+        self.short_name = short_name
+        self.long_name = long_name
+        self.description = description
+
+        self._sort_criteria_by_weight() # important if suitability as limited factor: return most weighted criteria if equals
+        self._criteria_name_list = [sc.name for sc in self.criteria.values()]
+        self._category_list = list(set([sc.category for sc in self.criteria.values()]))
+        self._get_params_by_category()
+
+
+    def __repr__(self) -> str:
+        if hasattr(self, 'data'):
+            return self.data.__repr__()
+        else:
+            attrs = []
+            for k, v in self.attrs.items():
+                if isinstance(v, str):
+                    v = f"'{v}'"
+                attrs.append(f"{k}={v}")
+            return f"{self.__class__.__name__}({', '.join(attrs) if attrs else ''})"
+    
+
+    @property
+    def attrs(self):
+        return {k: v for k, v in {
+                    'name': self.name,
+                    'criteria': self._criteria_name_list,
+                    'short_name': self.short_name,
+                    'long_name': self.long_name,
+                    'description': self.description,
+                }.items() if v is not None}
+
+
+    # def __getitem__(self, key: str) -> SuitabilityCriteria:
+    #     return self.criteria[key]
+
+
+    def compute_criteria_suitability(self, inplace: Optional[bool] = False) -> None | xr.Dataset:
+        sc_list = []
+        for _, sc in self.criteria.items():
+            print(f'Computing {sc.name}...')
+            if sc.indicator.attrs.get('compute', '') == 'done':
+                sc_list.append(sc.indicator.rename(sc.name))
+            else:
+                sc_list.append(sc.compute())
+        ls = xr.merge(sc_list, compat='override', combine_attrs='drop')
+        for sc in sc_list:
+            ls[sc.name].attrs = sc.attrs
+        ls.attrs = self.attrs
+        if inplace:
+            self.data = ls
+        else:
+            return ls
+    
+
+    def compute_category_suitability(
+            self, method: str,
+            keep_criteria: Optional[bool] = False,
+            inplace: Optional[bool] = False,
+            limit_var: Optional[bool] = False,
+    ) -> xr.Dataset:
+        if not hasattr(self, 'data'):
+            ds = self.compute_criteria_suitability()
+        else:
+            ds = self.data
+        
+        out = []
+        out_attrs = []
+        for category in self._category_list:
+            print(f'Computing {category}...')
+            sc_list = [sc for sc in self.criteria.values() if sc.category == category]
+            res = _aggregate_vars(ds[self._criteria_by_category[category]], method=method,
+                                  weights=[sc.weight for sc in sc_list], limit_var=limit_var)
+            if isinstance(res, xr.Dataset):
+                res = res.rename({'limiting_factor': f'{category}', 'limiting_var': f'{category}_var'})
+            else:
+                res = res.rename(f'{category}_suitability')
+            res.attrs.update({'long_name': f'{category.capitalize()} Suitability'})
+            out.append(res)
+            out_attrs.append(res.attrs)
+        out = xr.merge(out, compat='override', combine_attrs='drop')
+        if keep_criteria:
+            out = xr.merge([ds, out], compat='override', combine_attrs='drop')
+            for sc in ds.data_vars: # add attributes of criteria
+                out[sc].attrs = ds[sc].attrs
+        for i, category in enumerate(self._category_list): # add attributes of category suitability
+            out[f'{category}_suitability'].attrs = out_attrs[i]
+        
+        out.attrs.update(self.attrs)
+        if inplace:
+            self.data = out
+        else:
+            return out
+    
+
+    def compute_suitability(self,
+                            method: Union[str, dict[str,str]] = 'mean',
+                            by_category: Optional[bool] = False,
+                            keep_all: Optional[bool] = False,
+                            inplace: Optional[bool] = False,
+                            limit_var: Optional[bool] = False
+    ) -> xr.Dataset:
+        if isinstance(method, str):
+            cat_method, suit_method = method, method
+        elif isinstance(method, dict):
+            cat_method = method.get('category', 'mean')
+            suit_method = method.get('overall', 'mean')
+        else:
+            raise ValueError("Method must be a string or a dictionary.")
+        
+        if not hasattr(self, 'data'):
+            if by_category:
+                ds = self.compute_category_suitability(method=cat_method, keep_criteria=True, inplace=False, limit_var=limit_var)
+            else:
+                ds = self.compute_criteria_suitability(inplace=False)
+        else:
+            ds = self.data
+        
+        if by_category:
+            weights = [self.weights_by_category[category] for category in self._category_list]
+            on_vars = [f'{category}_suitability' for category in self._category_list]
+        else :
+            weights = [sc.weight for sc in self.criteria.values()]
+            on_vars = self._criteria_name_list
+        
+        print(f'Computing suitability...')
+        out = _aggregate_vars(ds[on_vars], method=suit_method, weights=weights, limit_var=limit_var).rename('suitability')
+        out.attrs.update({'long_name': 'Suitability'})
+        out_attrs = out.attrs
+
+        if keep_all:
+            out = xr.merge([ds, out], compat='override', combine_attrs='drop')
+            for sc in ds.data_vars: # add attributes of criteria
+                out[sc].attrs = ds[sc].attrs
+            out['suitability'].attrs = out_attrs
+        
+        out.attrs.update(self.attrs)
+        if inplace:
+            self.data = out
+        else:
+            return out
+    
+
+    def _sort_criteria_by_weight(self) -> dict[str, SuitabilityCriteria]:
+        self.criteria = dict(sorted(self.criteria.items(), key=lambda item: item[1].weight, reverse=True))
+
+
+    def _get_params_by_category(self):
+        self._get_criteria_by_category()
+        self._get_weights_by_category()
+    
+    
+    def _get_criteria_by_category(self) -> dict[str, list[str]]:
+        self._criteria_by_category = {category: [] for category in self._category_list}
+        for sc in self.criteria.values():
+            self._criteria_by_category[sc.category].append(sc.name)
+    
+
+    def _get_weights_by_category(self) -> dict[str, float | int]:
+        self.weights_by_category = {category: [] for category in self._category_list}
+        for category in self._category_list:
+            self.weights_by_category[category] = sum([sc.weight for sc in self.criteria.values() if sc.category == category])
+
+    
+    def mask(self, mask : Union[xr.DataArray, gpd.GeoDataFrame], inplace : Optional[bool] = False,
+          spatial_dims : Optional[tuple[str, str]] = None, crs : Optional[str] = None, invert : bool = False, **kwargs) -> xr.DataArray | xr.Dataset:
+        
+        if not hasattr(self, 'data'):
+            raise ValueError("Suitability must be computed first.")
+        
+        if inplace:
+            self.data = _mask_data(self.data, mask, spatial_dims=spatial_dims, crs=crs, invert=invert, **kwargs)
+        else:     
+            return _mask_data(self.data, mask, spatial_dims=spatial_dims, crs=crs, invert=invert, **kwargs)
+    
+
+    def statistics(
+            self,
+            on_vars: Optional[list] = None,
+            on_dims: Optional[list] = None,
+            on_dim_values: Optional[dict[str, Any]] = None,
+            bins : Optional[Union[list, np.ndarray]] = None,
+            bins_labels : Optional[list] = None,
+            all_bins : Optional[bool] = False,
+            cell_area : Optional[tuple[Union[float, str], str]] = None,
+            dropna: Optional[bool] = False,
+            **kwargs) -> pd.DataFrame:
+        
+        if not hasattr(self, 'data'):
+            raise ValueError("Suitability must be computed first.")
+        
+        return statistics_summary(self.data, on_vars=on_vars, on_dims=on_dims, on_dim_values=on_dim_values,
+                                  bins=bins, bins_labels=bins_labels, all_bins=all_bins,
+                                  cell_area=cell_area, dropna=dropna **kwargs)
+    
+
+    def spatial_statistics(
+            self,
+            areas : gpd.GeoDataFrame,
+            name : Optional[str] = 'area',
+            on_vars: Optional[list] = None,
+            on_dims: Optional[list] = None,
+            on_dim_values: Optional[dict[str, Any]] = None,
+            bins : Optional[np.ndarray] = None,
+            all_bins : Optional[bool] = False,
+            cell_area : Optional[tuple[Union[float, str], str]] = None,
+            mask_kwargs : dict = {},
+            stats_kwargs: dict = {}) -> pd.DataFrame:
+        
+        if not hasattr(self, 'data'):
+            raise ValueError("Suitability must be computed first.")
+        
+        return spatial_statistics_summary(self.data, areas, name=name, on_vars=on_vars, on_dims=on_dims, on_dim_values=on_dim_values,
+                                   bins=bins, all_bins=all_bins, cell_area=cell_area, mask_kwargs=mask_kwargs, stats_kwargs=stats_kwargs)
+
+
+def _mask_data(data : xr.DataArray | xr.Dataset, mask : Union[xr.DataArray, gpd.GeoDataFrame],
+          spatial_dims : Optional[tuple[str, str]] = None,
+          crs : Optional[str] = None, invert : bool = False, **kwargs) -> xr.DataArray | xr.Dataset:
+    
+    if isinstance(mask, gpd.GeoDataFrame):
+        mask = mask.to_crs(crs)
+        data = data.rio.set_spatial_dims(*spatial_dims).rio.write_crs(crs)
+        return data.rio.clip(mask.geometry.apply(mapping), invert=invert, **kwargs)
+    elif isinstance(mask, xr.DataArray):
+        if invert:
+            mask = ~mask
+        return data.where(mask, **kwargs)
+    else:
+        raise ValueError('mask must be a GeoDataFrame or DataArray')
+
+
+####################################################################################################
+# VARIABLES AGGREGATION FUNCTIONS
+####################################################################################################
+
+def vars_weighted_mean(ds: xr.Dataset, vars = None, weights = None) -> xr.DataArray:
+    if vars is None:
+        vars = list(ds.data_vars)
+    if weights is None:
+        weights = np.ones(len(vars))
+    
+    s = sum([ds[v] * w for v, w in zip(vars, weights)])
+    da: xr.DataArray = s / sum(weights)
+    return da.assign_attrs({
+        'method': 'Weighted Mean', 
+        'description': f"Weighted Mean of variables: {', '.join([f'{v} ({w})' for v, w in zip(vars, weights)])}."
+    }).rename('weighted_mean')
+
+def vars_mean(ds: xr.Dataset, vars = None) -> xr.DataArray:
+    if vars is None: vars = list(ds.data_vars)
+    da = vars_weighted_mean(ds, vars=vars)
+    return da.assign_attrs({'method': 'Mean', 'description': f"Mean of variables: {', '.join(vars)}."}).rename('mean')
+
+def vars_weighted_geomean(ds: xr.Dataset, vars = None, weights = None) -> xr.DataArray:
+    if vars is None:
+        vars = list(ds.data_vars)
+    if weights is None:
+        weights = np.ones(len(vars))
+
+    s = sum([np.log(ds[v]) * w for v, w in zip(vars, weights)])
+    da : xr.DataArray = np.exp(s / sum(weights))
+    return da.assign_attrs({
+        'method': 'Weighted Geometric Mean',
+        'description': f"Weighted Geometric Mean of variables: {', '.join([f'{v} ({w})' for v, w in zip(vars, weights)])}."
+    }).rename('weighted_geometric_mean')
+
+def vars_geomean(ds: xr.Dataset, vars = None) -> xr.DataArray:
+    if vars is None: vars = list(ds.data_vars)
+    da = vars_weighted_geomean(ds, vars=vars)
+    return da.assign_attrs({'method': 'Geometric Mean', 'description': f"Geometric Mean of variables: {', '.join(vars)}."}).rename('geometric_mean')
+
+def limiting_factor(ds: xr.Dataset, vars = None, limiting_var: Optional[bool] = True) -> xr.DataArray | xr.Dataset:
+    if vars is None:
+        vars = list(ds.data_vars)
+    
+    da = ds[vars].to_array()
+    mask = da.notnull().all(dim='variable')
+
+    lim = da.min(dim='variable', skipna=True).where(mask).rename('limiting_factor')
+    lim = lim.assign_attrs({'method': 'Limiting Factor', 'description': f"Value of limiting factor among variables: {', '.join(vars)}."})
+    if limiting_var:
+        lim_var = da.fillna(9999).argmin(dim='variable', skipna=True).where(mask).rename('limiting_var')
+        lim_var.attrs = {'method': 'Limiting Factor',
+                         'description': f"Limiting factor among: {', '.join(vars)}.",
+                         'legend': {f'{i}': v for i, v in enumerate(vars)}}
+        return xr.merge([lim, lim_var])
+    return lim.to_dataset()
+
+def _aggregate_vars(ds : xr.Dataset, method: str = 'mean', vars = None, weights = None, **kwargs) -> xr.DataArray | xr.Dataset:
+    if method.lower() == 'mean':
+        return vars_mean(ds, vars=vars)
+    elif method.lower() == 'weighted_mean':
+        return vars_weighted_mean(ds, vars=vars, weights=weights)
+    elif method.lower() == 'geomean':
+        return vars_geomean(ds, vars=vars)
+    elif method.lower() == 'weighted_geomean':
+        return vars_weighted_geomean(ds, vars=vars, weights=weights)
+    elif method.lower() == 'limit_factor':
+        return limiting_factor(ds, vars=vars, **kwargs)
+    else:
+        raise ValueError(f"Method '{method}' not recognized.")

lsapy/statistics.py

@@ -0,0 +1,109 @@
+from typing import Any, Optional, Union
+import numpy as np
+import pandas as pd
+import geopandas as gpd
+import xarray as xr
+import regionmask
+
+
+def statistics_summary(
+        data: xr.DataArray | xr.Dataset,
+        on_vars: Optional[list] = None,
+        on_dims: Optional[list] = None,
+        on_dim_values: Optional[dict[str, Any]] = None,
+        bins : Optional[Union[list, np.ndarray]] = None,
+        bins_labels : Optional[list] = None,
+        all_bins : Optional[bool] = False,
+        cell_area : Optional[tuple[Union[float, str], str]] = None,
+        dropna: Optional[bool] = False,
+        **kwargs) -> pd.DataFrame:
+    
+    def _correct_lowest_cut_interal(x: pd.Series) -> pd.Series:
+            first_cat = x.cat.categories[0]
+            lf = first_cat.left + (abs(first_cat.left) - bins[0])
+            return x.cat.rename_categories({first_cat: pd.Interval(lf, first_cat.right, closed='both')})
+    
+    
+    if bins is not None and bins_labels is not None and (len(bins)-1 != len(bins_labels)):
+        raise ValueError('bins and bins_labels must have the same length')
+    
+    if on_dim_values is not None:
+        for dim, value in on_dim_values.items():
+            data = data.sel({dim: value})
+    
+    if on_vars is None:
+        on_vars = list(data.data_vars)
+    data = data[on_vars]
+    if on_dims is None:
+        on_dims = list(data.dims)
+        on_dims = [d for d in on_dims if d not in ['lat', 'lon', 'x', 'y']] # remove spatial dims
+    if cell_area:
+        cell_area, cell_unit = cell_area
+
+
+    df = data.to_dataframe().reset_index()
+    if len(on_dims) > 0:
+        df = df.drop(columns=[c for c in data.coords if c not in on_dims])
+    
+    df = df.melt(id_vars=on_dims)
+    _dims = ['variable'] + on_dims
+
+    if bins is not None:
+        df['bin'] = pd.cut(df['value'], bins=pd.Index(bins), **kwargs)
+        if 'include_lowest' in kwargs and kwargs['include_lowest'] == True:
+            df['bin'] = _correct_lowest_cut_interal(df['bin'])
+
+        if bins_labels is not None:
+            lab_mapping = dict(zip(df['bin'].cat.categories.astype(str), bins_labels))
+        _dims.append('bin')
+        if all_bins:
+            all_bins_inter = pd.Interval(df['bin'].cat.categories[0].left, df['bin'].cat.categories[-1].right, closed='both')
+            df_ = df.drop(columns=['bin']).assign(bin=all_bins_inter)
+            df_.loc[df['value'].isnull(), 'bin'] = np.nan
+            if bins_labels is not None:
+                lab_mapping.update({str(all_bins_inter) : 'all'})
+            df = pd.concat([df, df_])
+        df['bin'] = df['bin'].astype(str)
+
+    df_out = df.groupby(_dims, observed=False).describe().droplevel(0, axis=1).reset_index()
+
+    if bins_labels is not None:
+        bin_idx = np.where(df_out.columns == 'bin')[0][0]
+        df_out.insert(bin_idx + 1, 'bin_label', df_out['bin'].map(lab_mapping).values)
+
+    if cell_area:
+        df_out[f'area_{cell_unit}'] = df_out['count'] * cell_area
+    
+    if dropna:
+        return df_out.dropna()
+    return df_out
+
+
+def spatial_statistics_summary(
+        data: xr.DataArray | xr.Dataset,
+        areas : gpd.GeoDataFrame,
+        name : Optional[str] = 'area',
+        on_vars: Optional[list] = None,
+        on_dims: Optional[list] = None,
+        on_dim_values: Optional[dict[str, Any]] = None,
+        bins : Optional[np.ndarray] = None,
+        bins_labels : Optional[list] = None,
+        all_bins : Optional[bool] = False,
+        cell_area : Optional[tuple[Union[float, str], str]] = None,
+        dropna: Optional[bool] = False,
+        mask_kwargs : dict = {},
+        stats_kwargs: dict = {}) -> pd.DataFrame:
+    
+    regions = regionmask.from_geopandas(areas, name=name, **mask_kwargs)
+    mask = regions.mask_3D(data)
+
+    out = []
+    for r in mask.region.values:
+        df = statistics_summary(
+            data.where(mask.sel(region=r)), on_vars=on_vars, on_dims=on_dims, on_dim_values=on_dim_values,
+            bins=bins, bins_labels=bins_labels, all_bins=all_bins,
+            cell_area=cell_area ,dropna=dropna, **stats_kwargs
+        )
+        df.insert(0, name, regions[r].name)
+        out.append(df)
+    return pd.concat(out)

lsapy/utils.py

@@ -0,0 +1,28 @@
+"""
+Miscellaneous Utilities
+===============================
+
+...
+"""
+
+from pathlib import Path
+
+import xarray as xr
+
+def _load_data(name: str) -> xr.Dataset:
+    """Load a sample dataset for testing or example purposes."""
+    if name.lower() not in ['soil', 'climate']:
+        raise ValueError(f"Invalid data name: {name}. Must be one of 'soil' or 'climate'.")
+    
+    data_path = Path(__file__).parent / 'data'
+    return xr.open_dataset(data_path / f'{name.lower()}_sample.nc')
+
+
+def load_soil_data() -> xr.Dataset:
+    """Load soil dataset for testing or example purposes."""
+    return _load_data('soil')
+
+
+def load_climate_data() -> xr.Dataset:
+    """Load climate dataset for testing or example purposes."""
+    return _load_data('climate')

lsapy-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: lsapy
+Version: 0.1.0.dev0
+Summary: A Python package for Land Suitability Analysis.
+Keywords: LSAPy,Land Suitability Analysis,Spatial Analysis,GIS,Geography
+Author-email: Baptiste Hamon <baptiste.hamon@pg.canterbury.ac.nz>
+Maintainer-email: Baptiste Hamon <baptiste.hamon@pg.canterbury.ac.nz>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+License-File: LICENSE
+Project-URL: Homepage, https://github.com/baptistehamon/lsapy
+Project-URL: Issues, https://github.com/baptistehamon/lsapy/issues
+
+# LSAPy: Land Suitability Analysis for Python
+
+`lsapy` stands for Land Suitability Analysis (LSA) for Python. The package has been designed to perfom spatial and temporal LSA operating on [xarray](https://docs.xarray.dev/en/stable/) `DataArray` and `Dataset`.
+
+
+## Features
+- TODO

lsapy-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lsapy/__init__.py,sha256=MXu8EIXhOrPg7Aba-9nrQCU51QTRAWNKxDapzYcnzFs,284
+lsapy/criteria.py,sha256=f2piZaEecKsLBvIH4JhLNXDNfNKNXUp70r23oeHErcQ,2971
+lsapy/functions.py,sha256=WYfpUREOsrkv-70wme_zL_HArM_AI2b5YxU8vtee5NI,8382
+lsapy/lsa.py,sha256=sBx96OpTDeaSrcX9s8IB2k91CNl0WUIW9hVM6oP-Hqg,14339
+lsapy/statistics.py,sha256=62O57pqF1Pth4s1D0MbQEyobnxDGZ2bNatC2uVFnHH8,4269
+lsapy/utils.py,sha256=eezLr5l0gqqgFEglzsSnbwx7JqOlVeKK3G63qllAJrg,776
+lsapy/data/climate_sample.nc,sha256=ng2o7BxKLgzQWIl5fdiGWvdCQSeHeOO5-X3ciyD72Xo,52687793
+lsapy/data/soil_sample.nc,sha256=y7NpYV9VZKXwiYExynA0vF1KAn5rhsWqzwGJ4tFE-TQ,2535031
+lsapy-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=6kbiFSfobTZ7beWiKnHpN902HgBx-Jzgcme0SvKqhKY,1091
+lsapy-0.1.0.dev0.dist-info/WHEEL,sha256=_2ozNFCLWc93bK4WKHCO-eDUENDlo-dgc9cU3qokYO4,82
+lsapy-0.1.0.dev0.dist-info/METADATA,sha256=Vr0peYa--97JnnQKHtAsNb8SdreyYCs7espEr4XSemg,1145
+lsapy-0.1.0.dev0.dist-info/RECORD,,

lsapy-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.11.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lsapy-0.1.0.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.