pysits 1.5.3.dev0__py3-none-any.whl

pysits/backend/functions.py

@@ -0,0 +1,50 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""backend functions."""
+
+from pysits.backend.loaders import load_function_from_package
+
+# Base - plot
+r_fnc_plot = load_function_from_package("base::plot")
+
+# Base - set column
+r_fnc_set_column = load_function_from_package("base::$<-")
+
+# Base - summary (base)
+r_fnc_summary = load_function_from_package("base::summary")
+
+# Base - readRDS (base)
+r_fnc_read_rds = load_function_from_package("base::readRDS")
+
+# Base - system.file (base)
+r_fnc_system_file = load_function_from_package("base::system_file")
+
+# Base - set.seed (base)
+r_fnc_set_seed = load_function_from_package("base::set_seed")
+
+# Base - class (base)
+r_fnc_class = load_function_from_package("base::class")
+
+# Base - as.data.frame (base)
+r_fnc_as_data_frame = load_function_from_package("base::as_data_frame")
+
+# Base - colnames (base)
+r_fnc_colnames = load_function_from_package("base::colnames")
+
+# Base - rownames (base)
+r_fnc_rownames = load_function_from_package("base::rownames")

pysits/backend/loaders.py

@@ -0,0 +1,92 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""backend loaders."""
+
+from collections.abc import Callable
+from typing import Any
+
+from rpy2.robjects import r
+from rpy2.robjects.packages import importr
+
+
+def load_data_from_package(name: str, package: str, **kwargs) -> object:
+    """Load data from package.
+
+    This function loads data from a package. It uses `data` behind the scenes.
+
+    Args:
+        name (str): Dataset name.
+
+        package (str): Package name.
+
+        **kwargs: Additional arguments to pass to the function.
+    """
+    return r.data(name, package=package, **kwargs)
+
+
+def load_data_from_global(name: str) -> object:
+    """Load data from global environment.
+
+    This function loads data from the global environment.
+
+    Args:
+        name (str): Dataset name.
+    """
+    return r[name]
+
+
+def load_function_from_package(name: str) -> Callable[..., Any]:
+    """Load an R function from a specified package.
+
+    This function takes a fully qualified R function name in the format
+    'package::function' and returns a callable Python wrapper for that R function.
+
+    Args:
+        name (str): The fully qualified name of the R  function in the format
+                    'package::function'. For example, 'stats::median' or 'base::mean'.
+
+    Returns:
+        Callable[..., Any]: A Python callable that wraps the R function.
+                            The exact signature depends on the underlying R function.
+
+    Raises:
+        ValueError: If the ``name`` doesn't follow the 'package::function' format.
+
+        PackageNotFoundError: If the specified R package is not installed.
+
+        AttributeError: If the function doesn't exist in the specified package.
+
+    Examples:
+        >>> median_func = load_function_from_package('stats::median')
+        >>> result = median_func([1, 2, 3, 4, 5])
+    """
+    # Parse package and function
+    try:
+        package_name, func_name = name.split("::")
+
+    except ValueError as e:
+        raise ValueError(
+            f"Invalid function name format: {name}. "
+            "Expected format: 'package::function'"
+        ) from e
+
+    # Import the package
+    pkg = importr(package_name, on_conflict="warn")
+
+    # Return function
+    return getattr(pkg, func_name)

pysits/backend/pkgs.py

@@ -0,0 +1,35 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""backend packages."""
+
+from rpy2.robjects.packages import importr
+
+# system pakage
+r_pkg_base = importr("base")
+r_pkg_grdevices = importr("grDevices")
+
+# sits package
+r_pkg_sits = importr("sits")
+
+# sits-dependencies packages
+r_pkg_tibble = importr("tibble")
+r_pkg_leaflet = importr("leaflet")
+r_pkg_kohonen = importr("kohonen")
+r_pkg_sf = importr("sf")
+r_pkg_htmlwidgets = importr("htmlwidgets")
+r_pkg_arrow = importr("arrow")

pysits/conversions/__init__.py

@@ -0,0 +1,18 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""conversions module."""

pysits/conversions/clojure.py

@@ -0,0 +1,68 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""Clojure utilities."""
+
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from pysits.backend.pkgs import r_pkg_sits
+from pysits.conversions.decorators import rpy2_fix_type, rpy2_fix_type_custom
+
+#
+# Generics
+#
+R = TypeVar("R")
+P = ParamSpec("P")
+
+
+#
+# Factory function
+#
+def closure_factory(
+    name: str, converters: dict[str, Callable[[Any], Any]] = {}
+) -> Callable[P, R]:
+    """Factory to create sits-based closure functions.
+
+    This function creates a closure that wraps R package sits functions,
+    making them callable from Python. It checks if the requested function
+    exists in the R sits package before creating the wrapper.
+
+    Args:
+        name (str): Name of the sits-based function to be wrapped from the R package.
+
+    Returns:
+        Callable[P, R]: A wrapped function that forwards calls to the R sits package.
+            The function accepts any arguments (*args, **kwargs) and returns the result
+            from the R function.
+
+    Raises:
+        ValueError: If the specified function name does not exist in the R sits package.
+    """
+    if not hasattr(r_pkg_sits, name):
+        raise ValueError(f"Invalid function: {name}")
+
+    # define method closure
+    @rpy2_fix_type_custom(converters)
+    @rpy2_fix_type
+    def _fnc(*args: P.args, **kwargs: P.kwargs) -> R:
+        return getattr(r_pkg_sits, name)(*args, **kwargs)
+
+    # set function name
+    _fnc.__name__ = name
+
+    return _fnc

pysits/conversions/common.py

@@ -0,0 +1,280 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""Common conversions."""
+
+from datetime import date, timedelta
+from pathlib import Path, PosixPath
+
+import rpy2.robjects as ro
+from geopandas import GeoDataFrame as GeoPandasDataFrame
+from pandas import DataFrame as PandasDataFrame
+from rpy2.rinterface_lib.sexp import NULLType
+from rpy2.robjects import pandas2ri
+from rpy2.robjects.robject import RObjectMixin
+
+from pysits.backend.pkgs import r_pkg_tibble
+from pysits.conversions.dsl.base import DSLObject
+from pysits.conversions.tibble import geopandas_to_tibble, pandas_to_tibble
+
+#
+# Type mapping dictionary
+#
+TYPE_CONVERSIONS = {
+    list: lambda obj: convert_list_like_to_r(obj),
+    tuple: lambda obj: convert_list_like_to_r(obj),
+    set: lambda obj: convert_list_like_to_r(list(obj)),
+    dict: lambda obj: convert_dict_like_to_r(obj),
+    bool: lambda obj: ro.BoolVector([obj]),
+    int: lambda obj: ro.IntVector([obj]),
+    float: lambda obj: ro.FloatVector([obj]),
+    str: lambda obj: ro.StrVector([obj]),
+    Path: lambda obj: ro.StrVector([obj.as_posix()]),
+    PosixPath: lambda obj: ro.StrVector([obj.as_posix()]),
+    PandasDataFrame: lambda obj: r_pkg_tibble.as_tibble(pandas_to_tibble(obj)),
+    GeoPandasDataFrame: lambda obj: geopandas_to_tibble(obj),
+}
+
+
+#
+# R epoch reference
+#
+EPOCH_START = date(1970, 1, 1)
+
+
+#
+# Base utilities
+#
+def _is_numeric(x: int | float) -> bool:
+    """Helper function to check if a value is numeric (int or float)."""
+    return isinstance(x, int | float)
+
+
+#
+# Base conversions
+#
+def convert_list_like_to_r(obj: list | tuple | set) -> ro.vectors.Vector:  # noqa: PLR0911
+    """
+    Converts a list-like object to the appropriate R vector type.
+
+    Args:
+        obj (list, tuple, set): The list-like Python object.
+
+    Returns:
+        An R-compatible vector.
+    """
+    if not obj:
+        return ro.vectors.ListVector({})
+
+    if all(isinstance(x, int) for x in obj):
+        return ro.vectors.IntVector(obj)
+
+    elif all(isinstance(x, float) for x in obj):
+        return ro.vectors.FloatVector(obj)
+
+    # Check if all elements are numeric (int or float)
+    elif all(_is_numeric(x) for x in obj):
+        return ro.vectors.FloatVector(obj)
+
+    elif all(isinstance(x, str) for x in obj):
+        return ro.vectors.StrVector(obj)
+
+    elif all(isinstance(x, bool) for x in obj):
+        return ro.BoolVector(obj)
+
+    else:
+        return ro.vectors.ListVector(
+            {str(i): convert_to_r(v) for i, v in enumerate(obj)}
+        )
+
+
+def convert_dict_like_as_list_to_r(obj: dict) -> ro.vectors.ListVector:
+    """Convert a Python dict to a ListVector."""
+    return ro.vectors.ListVector({str(k): convert_to_r(v) for k, v in obj.items()})
+
+
+def convert_dict_like_to_r(obj: dict) -> ro.vectors.Vector:
+    """Convert a Python dictionary to an R vector.
+
+    This function converts a Python dictionary to either a typed R vector or ListVector,
+    depending on the types of values in the dictionary:
+    - If all values are of the same type (e.g. all strings, all numeric), returns an
+      appropriate typed R vector with named elements
+    - Otherwise, returns an R ListVector with converted values
+
+    Args:
+        obj (dict): A Python dictionary to convert to an R vector.
+
+    Returns:
+        ro.vectors.Vector: Either a typed R vector (if all values are of same type) or
+            an R ListVector (for mixed value types). The resulting vector will
+            preserve the dictionary's keys as names in the R vector.
+    """
+    values = list(obj.values())
+    if not values:
+        return ro.vectors.ListVector({})
+
+    # Get data properties
+    has_unique_type = len(set(type(v) for v in values)) == 1
+    is_numeric = all(_is_numeric(v) for v in values)
+
+    # Handle homogeneous data
+    if has_unique_type or is_numeric:
+        vec = convert_list_like_to_r(values)
+        vec.names = list(obj.keys())
+
+        return vec
+
+    # For mixed data, use a list vector
+    return convert_dict_like_as_list_to_r(obj)
+
+
+def convert_to_r(obj):
+    """Convert Python objects to R-compatible objects for use with rpy2.
+
+    Args:
+        obj: The Python object to convert.
+
+    Returns:
+        An R-compatible object.
+
+    Raises:
+        TypeError: If the object type cannot be converted.
+    """
+    if obj is None:
+        return ro.r("NULL")  # Convert None to R's NULL
+
+    obj_type = type(obj)
+
+    # Handle ``SITSBase`` objects
+    if getattr(obj, "_instance", None):
+        # Sync instance with R
+        if getattr(obj, "_sync_instance", None):
+            obj._sync_instance()
+
+        return obj._instance
+
+    # Handle ``raw R`` / Expressions objects
+    if isinstance(obj, RObjectMixin | DSLObject):
+        return obj
+
+    # Check if the object type exists in the conversion dictionary
+    if obj_type in TYPE_CONVERSIONS:
+        return TYPE_CONVERSIONS[obj_type](obj)
+
+    raise TypeError(f"Cannot convert object of type {obj_type} to R format")
+
+
+def convert_to_python(obj, as_type="str"):
+    """Convert an R object to a Python representation.
+
+    Args:
+        obj (ro.Vector): The R object to convert.
+
+        as_type (str): The target Python type. Supported values:
+            - ``str``: Converts R string vector to Python list of strings;
+
+            - ``date``: Converts R DateVector to list of YYYY-MM-DD formatted strings;
+
+            - ``int``: Converts R numeric vector to Python list of integers;
+
+            - ``float``: Converts R numeric vector to Python list of floats;
+
+            - ``bool``: Converts R logical vector to Python list of booleans.
+
+    Returns:
+        list: Converted values as a Python list.
+
+    Raises:
+        ValueError: If the specified ``as_type`` is not supported.
+    """
+
+    def _convert(value, type_):
+        result = []
+
+        if isinstance(value, ro.ListVector):
+            for k, v in value.items():
+                result.append(
+                    {
+                        str(k): convert_to_python(v, type_),
+                    }
+                )
+
+        elif as_type and isinstance(value, ro.Vector):
+            for el in value:
+                if as_type == "str":
+                    result.append(str(el))
+
+                elif as_type == "date":
+                    result.append(
+                        (EPOCH_START + timedelta(days=int(el))).strftime("%Y-%m-%d")
+                    )
+
+                elif as_type == "int":
+                    result.append(int(el))
+
+                elif as_type == "float":
+                    result.append(float(el))
+
+                elif as_type == "bool":
+                    result.append(bool(el))
+
+        elif isinstance(value, ro.Vector):
+            result = pandas2ri.rpy2py(value)
+            names = value.names
+
+            if not isinstance(names, NULLType):
+                result = {str(k): v for k, v in zip(names, result)}
+
+        return result
+
+    return _convert(obj, as_type)
+
+
+#
+# Parameters conversions
+#
+def fix_reserved_words_parameters(**kwargs) -> dict:
+    """Fix reserved words parameters.
+
+    Args:
+        **kwargs: The keyword arguments to fix.
+
+    Returns:
+        dict: The fixed keyword arguments.
+    """
+    new_values = {}
+    keys_to_remove = []
+
+    for key, _ in kwargs.items():
+        # Assuming all reserved words end with "_"
+        if key.endswith("_"):
+            # Save key to remove
+            keys_to_remove.append(key)
+
+            # Save new value
+            new_values[key[:-1]] = kwargs[key]
+
+    # Remove keys that were converted
+    for key in keys_to_remove:
+        kwargs.pop(key)
+
+    # Add remaining kwargs
+    if new_values:
+        kwargs.update(new_values)
+
+    return kwargs

pysits/conversions/decorators.py

@@ -0,0 +1,148 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""Decorators."""
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from pysits.conversions.common import convert_to_r, fix_reserved_words_parameters
+
+#
+# Generics
+#
+T = TypeVar("T")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+#
+# Decorator
+#
+def rpy2_fix_type(func: Callable[P, R]) -> Callable[P, R]:
+    """Decorator function to convert arguments to R-compatible objects.
+
+    Args:
+        func (Callable): The function whose arguments should be converted.
+
+    Returns:
+        Callable: A wrapped function that receives converted arguments.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        kwargs = fix_reserved_words_parameters(**kwargs)
+        converted_args = [convert_to_r(arg) for arg in args]
+        converted_kwargs = {k: convert_to_r(v) for k, v in kwargs.items()}
+        return func(*converted_args, **converted_kwargs)
+
+    return wrapper
+
+
+def rpy2_fix_type_custom(
+    converters: dict[str, Callable[[Any], Any]],
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Convert arguments to R objects using parameter-specific converters.
+
+    Args:
+        converters (dict[str, Callable[[Any], Any]]): A dictionary mapping
+            parameter names to converter functions. Each converter function should
+            take a Python object and return an R-compatible object. Parameters not
+            found in this dictionary will be passed as is.
+
+    Returns:
+        Callable: A decorator that wraps a function to convert its arguments using the
+                  parameter-specific converters.
+
+    Example:
+        >>> converters = {
+        ...     "optimizer": convert_optimizer,
+        ...     "opt_hparams": convert_opt_hparams
+        ... }
+        >>> @rpy2_fix_type_custom(converters)
+        ... def my_function(optimizer, opt_hparams, other_arg):
+        ...     # optimizer and opt_hparams will use their specific converters
+        ...     # other_arg will use the default _convert_to_r
+        ...     pass
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Get the function's parameter names
+            param_names = inspect.signature(func).parameters.keys()
+            param_names = list(param_names)
+
+            # Convert positional arguments using their parameter names
+            converted_args = []
+            for i, arg in enumerate(args):
+                if i < len(param_names) and param_names[i] in converters:
+                    converted_args.append(converters[param_names[i]](arg))
+                else:
+                    converted_args.append(arg)
+
+            # Convert keyword arguments
+            converted_kwargs = {}
+            for k, v in kwargs.items():
+                if k in converters:
+                    converted_kwargs[k] = converters[k](v)
+                else:
+                    converted_kwargs[k] = v
+
+            return func(*converted_args, **converted_kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def function_call(r_function: Callable[P, R], output_wrapper: Callable[[R], T]):
+    """Decorator function to call an R function and post-process the result.
+
+    This decorator is used to wrap Python stub functions that serve as documentation
+    and type hint shells. The resulting function performs the following steps:
+
+    1. Converts all arguments to R-compatible types using `@rpy2_fix_type`.
+    2. Calls the provided R function (`r_function`) with converted arguments.
+    3. Wraps the result in a specified output Python class (`output_wrapper`).
+
+    This enables consistent logic while preserving per-function docstrings and
+    type hints for IDE support, autocompletion, and documentation generation.
+
+    Args:
+        r_function (Callable): The R function to be called via rpy2.
+
+        output_wrapper (Callable): A callable (usually a class) that wraps the
+                                   result returned by the R function.
+
+    Returns:
+        Callable: A decorator that wraps a Python function stub, providing the
+                    R execution logic.
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        @rpy2_fix_type
+        @functools.wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> T:
+            result = r_function(*args, **kwargs)
+            return output_wrapper(result)
+
+        return wrapped
+
+    return decorator