pysits 2.0.0.dev3__tar.gz → 2.0.0.dev5__tar.gz

pysits-2.0.0.dev5/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "disabledMcpjsonServers": [
+    "geo-infrastructure"
+  ]
+}

pysits-2.0.0.dev5/.github/actions/setup-pysits/action.yml

@@ -0,0 +1,43 @@
+name: Set up pysits
+description: R with the sits stack, and uv-managed Python
+
+inputs:
+  python-version:
+    description: Python version to run pysits on
+    required: true
+
+runs:
+  using: composite
+
+  steps:
+    - uses: r-lib/actions/setup-r@v2
+      with:
+        Ncpus: '4'
+
+    # R is installed under `/opt/R`, which the dynamic loader does not search.
+    # `rpy2` links against `libR.so` at import, so without this it falls back
+    # to ABI mode and then fails to load R's own base packages
+    - name: Put libR on the loader path
+      shell: bash
+      run: |
+        echo "LD_LIBRARY_PATH=$(R RHOME)/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" >> "$GITHUB_ENV"
+
+    - uses: r-lib/actions/setup-r-dependencies@v2
+      with:
+        packages: |
+          github::e-sensing/sits@dev
+          any::arrow
+          any::earthdatalogin
+
+    # The `torch` R package ships without libtorch, and pysits disables the
+    # implicit download (`TORCH_INSTALL=0`), so without this operation
+    # the deep learning models would fail only once a test train one
+    - name: Install libtorch
+      shell: bash
+      run: Rscript -e 'torch::install_torch()'
+
+    # After R: `rpy2` has no Linux wheel and is compiled against it
+    - uses: astral-sh/setup-uv@v9.0.0
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: true

pysits-2.0.0.dev5/.github/workflows/ruff.yaml

@@ -0,0 +1,32 @@
+name: Code check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+  workflow_dispatch:
+    inputs:
+      reason:
+        required: false
+        description: 'Reason'
+        default: 'Manual trigger'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Run ruff
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/ruff-action@v4.1.0
+        with:
+          version-file: uv.lock

pysits-2.0.0.dev5/.github/workflows/tests.yaml

@@ -0,0 +1,80 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+  # Run every Saturday at 3:00 AM
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    - cron:  '0 3 * * 6'
+
+  workflow_dispatch:
+    inputs:
+      reason:
+        required: false
+        description: 'Reason'
+        default: 'Manual trigger'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+env:
+  # pak resolves `sits` from GitHub; without a token it shares the anonymous
+  # rate limit with every other runner
+  GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+
+    strategy:
+      # Report every version, so a single break does not hide the others
+      fail-fast: false
+      matrix:
+        # The suite trains various models on CPU. To reduce execution time,
+        # a change is only checked against floor and ceiling versions.
+        # The weekly test covers all other versions
+        python-version: ${{ fromJSON((github.event_name == 'push' || github.event_name == 'pull_request') && '["3.10", "3.14"]' || '["3.10", "3.11", "3.12", "3.13", "3.14"]') }}
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: ./.github/actions/setup-pysits
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install pysits
+        run: uv sync --locked --extra dev
+
+      - name: Run tests
+        run: uv run pytest
+
+  latest-dependencies:
+    name: Latest dependencies
+    # `uv.lock` pins what `test` runs against, so a release that breaks pysits
+    # stays invisible there until someone relocks. This resolves from scratch.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: ./.github/actions/setup-pysits
+        with:
+          python-version: '3.14'
+
+      - name: Install pysits, ignoring the lockfile
+        run: uv sync --upgrade --extra dev
+
+      - name: Run tests
+        run: uv run pytest

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pysits
-Version: 2.0.0.dev3
+Version: 2.0.0.dev5
 Summary: Python wrapper for the sits R package
 Project-URL: Homepage, https://github.com/e-sensing/pysits
 Project-URL: Issue Tracker, https://github.com/e-sensing/pysits/issues
@@ -29,6 +29,7 @@ Provides-Extra: dev
 Requires-Dist: affine>=2.4.0; extra == 'dev'
 Requires-Dist: cloudpickle>=3.1.1; extra == 'dev'
 Requires-Dist: dask>=2025.3.0; extra == 'dev'
+Requires-Dist: ipykernel>=6.29.0; extra == 'dev'
 Requires-Dist: odc-stac>=0.5.3; extra == 'dev'
 Requires-Dist: planetary-computer>=1.0.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.6.0; extra == 'dev'

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/pyproject.toml

@@ -17,7 +17,7 @@
 
 [project]
 name = "pysits"
-version = "2.0.0.dev3"
+version = "2.0.0.dev5"
 description = "Python wrapper for the sits R package"
 readme = "README.md"
 requires-python = ">=3.10,<4"
@@ -98,6 +98,9 @@ dev = [
     # The test suite covers the xarray exporters and reads rasters directly
     "pysits[xarray]",
     "rasterio>=1.3.0",
+    # Used to render Quarto documents to check that figures reach a
+    # document with the geometry the document asked for
+    "ipykernel>=6.29.0",
 ]
 
 [tool.ruff]

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/pysits/backend/functions.py

@@ -25,6 +25,9 @@ from pysits.backend.loaders import (
 # Base - plot
 r_fnc_plot = load_function_from_package("base::plot")
 
+# Base - print
+r_fnc_print = load_function_from_package("base::print")
+
 # Base - set column
 r_fnc_set_column = load_function_from_package("base::$<-")
 

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/pysits/conversions/common.py

@@ -58,6 +58,12 @@ TYPE_CONVERSIONS = {
 EPOCH_START = date(1970, 1, 1)
 
 
+#
+# Prefixes of R expressions deparsed as text
+#
+R_DEPARSED_PREFIXES = ("c(", "list(")
+
+
 #
 # Base utilities
 #
@@ -197,6 +203,27 @@ def eval_r_language(obj):
     return obj
 
 
+def eval_r_deparsed(obj):
+    """Evaluate a deparsed R expression.
+
+    Args:
+        obj: The R object to evaluate.
+
+    Returns:
+        The evaluated R object. Objects that are not deparsed R expressions are
+        returned unchanged.
+    """
+    value = obj
+
+    if isinstance(value, ro.StrVector) and len(value) == 1:
+        value = value[0]
+
+    if isinstance(value, str) and value.startswith(R_DEPARSED_PREFIXES):
+        return ro.r(value)
+
+    return obj
+
+
 def convert_to_python(obj, as_type="str"):
     """Convert an R object to a Python representation.
 

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/pysits/conversions/decorators.py

@@ -94,6 +94,7 @@ def rpy2_fix_type_custom(
             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)
 
@@ -102,6 +103,7 @@ def rpy2_fix_type_custom(
             for k, v in kwargs.items():
                 if k in converters:
                     converted_kwargs[k] = converters[k](v)
+
                 else:
                     converted_kwargs[k] = v
 
@@ -112,6 +114,47 @@ def rpy2_fix_type_custom(
     return decorator
 
 
+def rpy2_fix_type_except(
+    *names: str,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Convert arguments to R-compatible objects, keeping some untouched.
+
+    Behaves like `rpy2_fix_type`, except for the named keyword arguments,
+    which reach the wrapped function exactly as they were given. This is
+    for arguments that configure pysits itself instead of the R call.
+    Converting those to R objects would strip them of the Python interface
+    the wrapped function needs.
+
+    Args:
+        *names (str): Names of the keyword arguments to leave untouched.
+
+    Returns:
+        Callable: A decorator that wraps a function to convert its
+                  arguments, minus the named ones.
+
+    Example:
+        >>> @rpy2_fix_type_except("image_args")
+        ... def my_function(data, image_args=None, **kwargs):
+        ...     # `data` and `kwargs` are R objects, `image_args` is a dict
+        ...     pass
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            kept = {name: kwargs.pop(name) for name in names if name in kwargs}
+
+            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, **kept)
+
+        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.
 

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/pysits/docs/content/plot.md

@@ -85,19 +85,34 @@ Args:
     area_spar (float): For embedding predictions, the smoothing parameter
         passed to the spline fit (default `0.6`); higher values produce
         smoother profiles.
+    image_args (dict): Geometry to render the figure with, with any of the
+        keys `width` and `height` (in inches), and `res` (in dots per
+        inch). See the notes on figure size below.
     **kwargs (dict): Further specifications for the plot. The keywords
         understood depend on the type of `x` (see below).
 
 Returns:
-    None: A plot appropriate to the type of `x` is drawn. Maps of cubes
-        yield color or B/W raster images (optionally overlaid with segment
-        boundaries for vector cubes); probability, uncertainty, and
-        variance cubes yield per-class or per-pixel maps; classified cubes
-        yield color maps where each pixel is colored by its label.
-        Chart-based plots (patterns, predictions, embeddings, clusters,
-        t-SNE, model diagnostics) render the corresponding plot. Some
-        methods (accuracy tables, SOM diagnostics, model summaries) are
-        called only for their side effect of drawing the plot.
+    SITSPlot | SITSPlotList: The rendered figure. Objects that produce
+        several figures, samples with more than one band or label, for
+        example, return a `SITSPlotList`, which behaves as a sequence of
+        `SITSPlot`.
+
+        Maps of cubes yield color or B/W raster images (optionally
+        overlaid with segment boundaries for vector cubes). Probability,
+        uncertainty, and variance cubes yield per-class or per-pixel maps.
+        Classified cubes yield color maps where each pixel is colored by
+        its label. Chart-based plots (patterns, predictions, embeddings,
+        clusters, t-SNE, model diagnostics) render the corresponding plot.
+
+        How the figure reaches the page depends on where the code runs.
+        In a notebook, or a Quarto document using the `jupyter` engine,
+        the returned figure is rendered as the result of the cell. In
+        RStudio, or a Quarto document using the `knitr` engine, the
+        figures are handed to `knitr` as it renders the chunk, so each
+        one becomes a document figure of its own, with its own caption,
+        cross-reference, and layout. Everywhere else plotting displays
+        nothing by itself: use `save` to write the figure to a file, or
+        `show` to open it in an image viewer.
 
 Notes:
         The set of valid keyword arguments depends on the type of `x`;
@@ -115,3 +130,14 @@ Examples:
     # Train a random forest model and plot its important variables
     rf_model = sits_train(samples_modis_ndvi, ml_method=sits_rfor())
     plot(rf_model)
+
+    # Render a larger figure, and write it to a file
+    figure = plot(rf_model, image_args={"width": 12, "height": 8})
+    figure.save("model.png")
+
+    # Set the size of every figure that follows
+    set_plot_options(width=8, height=5, dpi=150)
+
+    # Objects with several bands or labels produce one figure each
+    figures = plot(samples_l8_rondonia_2bands)
+    figures[0].save("first.png")

{pysits-2.0.0.dev3 → pysits-2.0.0.dev5}/pysits/models/data/tuning.py

@@ -21,14 +21,65 @@ from collections.abc import Callable
 from typing import Any
 
 from rpy2.rinterface_lib.sexp import NULLType
-from rpy2.robjects.vectors import ListVector
-
-from pysits.conversions.common import convert_to_python, eval_r_language
+from rpy2.robjects.vectors import (
+    BoolVector,
+    FloatVector,
+    IntVector,
+    ListVector,
+    StrVector,
+)
+
+from pysits.conversions.common import (
+    R_DEPARSED_PREFIXES,
+    convert_to_python,
+    eval_r_deparsed,
+    eval_r_language,
+)
 from pysits.models.data.base import SITSData
 from pysits.models.data.matrix import SITSConfusionMatrix
 from pysits.models.data.ts import SITSTimeSeriesModel
 
+#
+# Python types associated with each R vector type
+#
+HPARAM_TYPES = {
+    BoolVector: "bool",
+    IntVector: "int",
+    FloatVector: "float",
+    StrVector: "str",
+}
+
+
+#
+# Tuning results columns that are not hyper-parameters
+#
+TUNING_METRICS = ("accuracy", "kappa", "acc", "samples_validation")
+
+
+#
+# Utilities
+#
+def convert_hparam(value: Any) -> Any:
+    """Convert a hyper-parameter value from R to Python.
+
+    Args:
+        value: The hyper-parameter value to convert.
+
+    Returns:
+        Any: Converted Python object.
+    """
+    value = eval_r_deparsed(value)
+
+    for vector_type, as_type in HPARAM_TYPES.items():
+        if isinstance(value, vector_type):
+            return convert_to_python(value, as_type=as_type)
 
+    return convert_to_python(value)
+
+
+#
+# Classes
+#
 class SITSTuningResults(SITSData):
     """Base class for sits accuracy results."""
 
@@ -62,14 +113,13 @@ class SITSTuningResults(SITSData):
         if isinstance(values, NULLType):
             return [None for i in range(len(self._instance.rx2("accuracy")))]
 
-        # Check if value is a vector as string
+        # Check if value is a deparsed R expression (e.g., "c(128, 128, 128)")
         is_vector_as_string = any(
-            isinstance(x, str) and (x.startswith("c(") or x.startswith("list("))
-            for x in values
+            isinstance(x, str) and x.startswith(R_DEPARSED_PREFIXES) for x in values
         )
 
         if is_vector_as_string:
-            return list(values)
+            return [transform_func(eval_r_deparsed(x)) for x in values]
 
         if isinstance(values, ListVector):
             return [
@@ -138,47 +188,47 @@ class SITSTuningResults(SITSData):
         ]
 
     @property
-    def cnn_layers(self) -> list[float]:
+    def cnn_layers(self) -> list[list[float]]:
         """Get the CNN layer configurations from the tuning results.
 
         Returns:
-            A list of float values representing the CNN layer configurations.
+            A list with the CNN layer configuration of each trial.
         """
         return self._convert_from_r_list("cnn_layers", "float")
 
     @property
-    def cnn_kernels(self) -> list[float]:
+    def cnn_kernels(self) -> list[list[float]]:
         """Get the CNN kernel configurations from the tuning results.
 
         Returns:
-            A list of float values representing the CNN kernel configurations.
+            A list with the CNN kernel configuration of each trial.
         """
         return self._convert_from_r_list("cnn_kernels", "float")
 
     @property
-    def cnn_dropout_rates(self) -> list[float]:
+    def cnn_dropout_rates(self) -> list[list[float]]:
         """Get the CNN dropout rates from the tuning results.
 
         Returns:
-            A list of float values representing the CNN dropout rates.
+            A list with the CNN dropout rates of each trial.
         """
         return self._convert_from_r_list("cnn_dropout_rates", "float")
 
     @property
-    def dense_layer_nodes(self) -> list[float]:
+    def dense_layer_nodes(self) -> list[list[float]]:
         """Get the dense layer node configurations from the tuning results.
 
         Returns:
-            A list of float values representing the dense layer node configurations.
+            A list with the dense layer node configuration of each trial.
         """
         return self._convert_from_r_list("dense_layer_nodes", "float")
 
     @property
-    def dense_layer_dropout_rate(self) -> list[float]:
+    def dense_layer_dropout_rate(self) -> list[list[float]]:
         """Get the dense layer dropout rates from the tuning results.
 
         Returns:
-            A list of float values representing the dense layer dropout rates.
+            A list with the dense layer dropout rates of each trial.
         """
         return self._convert_from_r_list("dense_layer_dropout_rate", "float")
 
@@ -219,40 +269,33 @@ class SITSTuningResults(SITSData):
         return [eval_r_language(x).rclass[0] for x in self._instance.rx2("optimizer")]
 
     @property
-    def opt_hparams(self) -> list[dict[str, float]]:
+    def opt_hparams(self) -> list[dict[str, Any]]:
         """Get the optimizer hyperparameters from the tuning results.
 
         Returns:
             A list of dictionaries containing optimizer hyperparameters.
-            Each dictionary maps parameter names to their float values.
+            Each dictionary maps parameter names to their values.
         """
-        # Results
-        results = []
-
-        # Convert to Python
-        values = self._convert_from_r_list("opt_hparams", "float")
-
-        # Merge dict results
-        for value in values:
-            results.append({k: v for d in value for k, v in d.items()})
-
-        return results
+        return self._convert_attribute(
+            "opt_hparams",
+            lambda x: {str(k): convert_hparam(v) for k, v in x.items()},
+        )
 
     @property
-    def lr_decay_epochs(self) -> list[float]:
+    def lr_decay_epochs(self) -> list[list[float]]:
         """Get the learning rate decay epochs from the tuning results.
 
         Returns:
-            A list of float values representing the learning rate decay epochs.
+            A list with the learning rate decay epochs of each trial.
         """
         return self._convert_from_r_list("lr_decay_epochs", "float")
 
     @property
-    def lr_decay_rate(self) -> list[float]:
+    def lr_decay_rate(self) -> list[list[float]]:
         """Get the learning rate decay rates from the tuning results.
 
         Returns:
-            A list of float values representing the learning rate decay rates.
+            A list with the learning rate decay rates of each trial.
         """
         return self._convert_from_r_list("lr_decay_rate", "float")
 
@@ -283,9 +326,38 @@ class SITSTuningResults(SITSData):
         """
         return self._convert_from_r_list("verbose", "bool")
 
+    @property
+    def hparams(self) -> dict[str, list[Any]]:
+        """Get all the hyper-parameters tuned, one value per trial.
+
+        Returns:
+            A dictionary mapping each hyper-parameter name to its values.
+        """
+        return {
+            name: getattr(self, name)
+            for name in self._instance.names
+            if name not in TUNING_METRICS
+        }
+
     #
     # Dunder methods
     #
+    def __getattr__(self, name: str) -> list[Any]:
+        """Get a hyper-parameter with no property associated with it.
+
+        Args:
+            name: The name of the hyper-parameter to get.
+
+        Returns:
+            A list with the hyper-parameter values, one per trial.
+        """
+        if name.startswith("_") or name not in self._instance.names:
+            raise AttributeError(
+                f"'{type(self).__name__}' object has no attribute '{name}'"
+            )
+
+        return self._convert_attribute(name, convert_hparam)
+
     def __str__(self):
         """String representation."""
         return str(self._instance)