pysits 2.0.0.dev2__tar.gz → 2.0.0.dev4__tar.gz

pysits-2.0.0.dev4/.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.dev4/.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.dev4/.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.dev2 → pysits-2.0.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pysits
-Version: 2.0.0.dev2
+Version: 2.0.0.dev4
 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
@@ -20,17 +20,27 @@ Requires-Dist: geopandas>=1.1.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: matplotlib>=3.10.1
 Requires-Dist: pandas>=2.2.3
+Requires-Dist: pandas>=2.3.3; python_version >= '3.14'
 Requires-Dist: pillow>=11.1.0
 Requires-Dist: pyarrow>=20.0.0
-Requires-Dist: rpy2<4.0.0,>=3.5.17
+Requires-Dist: rpy2<4.0.0,>=3.6.0
 Requires-Dist: shapely>=2.1.1
 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'
+Requires-Dist: pystac>=1.15.0; extra == 'dev'
 Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
 Requires-Dist: pytest-randomly>=3.16.0; extra == 'dev'
 Requires-Dist: pytest>=7.4.4; extra == 'dev'
+Requires-Dist: rasterio>=1.3.0; extra == 'dev'
+Requires-Dist: rioxarray>=0.18.2; extra == 'dev'
 Requires-Dist: ruff>=0.11.12; extra == 'dev'
+Requires-Dist: xarray>=2025.3.0; extra == 'dev'
 Provides-Extra: xarray
 Requires-Dist: affine>=2.4.0; extra == 'xarray'
 Requires-Dist: dask>=2025.3.0; extra == 'xarray'

{pysits-2.0.0.dev2 → pysits-2.0.0.dev4}/pyproject.toml

@@ -17,7 +17,7 @@
 
 [project]
 name = "pysits"
-version = "2.0.0.dev2"
+version = "2.0.0.dev4"
 description = "Python wrapper for the sits R package"
 readme = "README.md"
 requires-python = ">=3.10,<4"
@@ -58,8 +58,13 @@ classifiers = [
 ]
 
 dependencies = [
-    "rpy2>=3.5.17,<4.0.0",
+    # 3.6.0 is the first release distributing wheels. Earlier ones are
+    # source-only, so pip would compile rpy2 against the local R installation
+    "rpy2>=3.6.0,<4.0.0",
     "pandas>=2.2.3",
+    # pandas ships no wheels for Python 3.14 before 2.3.3. Without this floor
+    # pip builds pandas from source there, and the result segfaults.
+    "pandas>=2.3.3; python_version>='3.14'",
     "pillow>=11.1.0",
     "matplotlib>=3.10.1",
     "geopandas>=1.1.0",
@@ -90,6 +95,12 @@ dev = [
     "pytest-cov>=6.1.1",
     "pytest-randomly>=3.16.0",
     "cloudpickle>=3.1.1",
+    # 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.dev2 → pysits-2.0.0.dev4}/pysits/__init__.py

@@ -17,6 +17,10 @@
 
 """pysits module."""
 
+# Importing `backend.arrow` first selects the libarrow allocator, which must
+# happen before anything imports `pyarrow` or loads the R `arrow` package.
+# Keep this import above the others. See `pysits.backend.arrow`.
+from .backend import arrow as _arrow  # noqa: F401
 from .conversions.dsl.mask import MaskValue
 from .conversions.dsl.tuning import hparam
 from .settings import __version__

pysits-2.0.0.dev4/pysits/backend/arrow.py

@@ -0,0 +1,106 @@
+#
+# 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/>.
+#
+
+"""Arrow interoperability between R and Python.
+
+``pysits`` moves data between R and Python as Arrow IPC streams. That puts two
+independent builds of the libarrow C++ library in a single process: the one
+bundled in the R ``arrow`` package and the one bundled in ``pyarrow``. Their
+symbols collapse into a single namespace, so a call made through ``pyarrow``
+can be served by R's libarrow.
+
+Each build keeps a private ``mimalloc`` heap. When the two are mixed, a buffer
+allocated by one library is read back as zeroed memory by the other, and every
+transfer is silently corrupted instead of failing. Both builds also support the
+system allocator, which is shared, so selecting it keeps them interoperable.
+
+The allocator is chosen by libarrow the first time it initializes, so importing
+this module sets ``ARROW_DEFAULT_MEMORY_POOL``. It is imported before anything
+that pulls in ``pyarrow`` or the R ``arrow`` package.
+"""
+
+import os
+
+#
+# Allocator selected to keep R libarrow and pyarrow interoperable
+#
+ARROW_MEMORY_POOL_ENVVAR = "ARROW_DEFAULT_MEMORY_POOL"
+ARROW_MEMORY_POOL = "system"
+
+# Set on import: libarrow reads this once, when it initializes. A value already
+# present in the environment is left alone so users can override it.
+os.environ.setdefault(ARROW_MEMORY_POOL_ENVVAR, ARROW_MEMORY_POOL)
+
+#
+# Values transferred to R and back to verify the round-trip is lossless. A
+# mismatched pair of libarrow builds reads them back as zeros.
+#
+PROBE_COLUMN = "pysits_arrow_probe"
+PROBE_VALUES = [0.5, 1.5, 2.5]
+
+
+def check_arrow_memory_pool() -> None:
+    """Refuse to load R ``arrow`` package under an unshared allocator.
+
+    Called before the R ``arrow`` package is loaded. Corruption appears only
+    once both libarrow builds are in use, and is silent when it does, so the
+    configuration is rejected up front rather than probed for afterwards.
+
+    Raises:
+        RuntimeError: If the selected allocator is not the shared one.
+    """
+    selected = os.environ.get(ARROW_MEMORY_POOL_ENVVAR)
+
+    if selected == ARROW_MEMORY_POOL:
+        return
+
+    raise RuntimeError(
+        f"{ARROW_MEMORY_POOL_ENVVAR} is set to '{selected}', but pysits "
+        f"requires '{ARROW_MEMORY_POOL}'.\n\n"
+        "The R `arrow` package and `pyarrow` each bundle their own build of "
+        "the libarrow C++ library. Loaded together, they must use the system "
+        "allocator to share buffers. With any other allocator, data sent "
+        "between R and Python is silently replaced by zeros.\n\n"
+        f"Unset {ARROW_MEMORY_POOL_ENVVAR}, or set it before starting Python:\n\n"
+        f"    export {ARROW_MEMORY_POOL_ENVVAR}={ARROW_MEMORY_POOL}"
+    )
+
+
+def arrow_interop_error(observed: list) -> RuntimeError:
+    """Build the error raised when an Arrow round-trip loses data.
+
+    Args:
+        observed (list): Values read back from R for `PROBE_VALUES`.
+
+    Returns:
+        RuntimeError: Error describing the cause and how to resolve it.
+    """
+    import pyarrow as pa
+
+    pool = pa.default_memory_pool().backend_name
+
+    return RuntimeError(
+        "Data sent to R is coming back corrupted, so pysits cannot run.\n\n"
+        f"Sent {PROBE_VALUES}, received {observed}.\n\n"
+        "The R `arrow` package and `pyarrow` each bundle their own build of "
+        "the libarrow C++ library. Loaded together, they must use the system "
+        f"allocator to share buffers, but pyarrow is using '{pool}'.\n\n"
+        "This happens when pyarrow is initialized before pysits with a "
+        "different allocator. Either import pysits before pyarrow, or set the "
+        "environment variable before starting Python:\n\n"
+        f"    export {ARROW_MEMORY_POOL_ENVVAR}={ARROW_MEMORY_POOL}"
+    )

{pysits-2.0.0.dev2 → pysits-2.0.0.dev4}/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.dev2 → pysits-2.0.0.dev4}/pysits/backend/pkgs.py

@@ -17,6 +17,7 @@
 
 """backend packages."""
 
+from pysits.backend.arrow import check_arrow_memory_pool
 from pysits.backend.loaders import load_package
 from pysits.settings import __sitsver__
 
@@ -33,4 +34,9 @@ r_pkg_leaflet = load_package("leaflet")
 r_pkg_kohonen = load_package("kohonen")
 r_pkg_sf = load_package("sf")
 r_pkg_htmlwidgets = load_package("htmlwidgets")
+
+# `arrow` brings a second libarrow build into the process, so the allocator has
+# to be compatible before it is loaded. See `pysits.backend.arrow`.
+check_arrow_memory_pool()
+
 r_pkg_arrow = load_package("arrow")

{pysits-2.0.0.dev2 → pysits-2.0.0.dev4}/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.dev2 → pysits-2.0.0.dev4}/pysits/conversions/tibble.py

@@ -36,6 +36,7 @@ from rpy2.robjects.conversion import localconverter
 from rpy2.robjects.vectors import DataFrame as RDataFrame
 from shapely import wkt
 
+from pysits.backend.arrow import PROBE_COLUMN, PROBE_VALUES, arrow_interop_error
 from pysits.backend.functions import r_fnc_class, r_fnc_set_column
 from pysits.backend.pkgs import r_pkg_base, r_pkg_sf, r_pkg_sits
 from pysits.models.frame import NestedFrame
@@ -90,6 +91,39 @@ def _sf_to_shapely(sf_object: RDataFrame) -> list:
 #
 # Arrow IPC helpers
 #
+def _check_arrow_interop() -> None:
+    """Verify that Arrow data is not corrupted once R's libarrow is loaded.
+
+    R libarrow only initializes on first use, so a probe is sent through R to
+    force it, and ``pyarrow`` is then re-tested. A mismatched pair of libarrow
+    builds corrupts the conversion of Python objects to Arrow arrays, returning
+    zeros instead of raising, which would silently damage every nested column.
+
+    Raises:
+        RuntimeError: If either transfer loses data.
+    """
+    probe = PandasDataFrame({PROBE_COLUMN: PROBE_VALUES})
+
+    # Forces R libarrow to initialize, and checks the Python -> R direction
+    r_probe = rpy2_globalenv["pysits_read_ipc_raw"](
+        robjects.vectors.ByteVector(_dataframe_to_ipc_bytes(probe))
+    )
+
+    # Load content from R
+    observed = list(r_probe.rx2(PROBE_COLUMN))
+
+    # If it is different, then given an error
+    if observed != PROBE_VALUES:
+        raise arrow_interop_error(observed)
+
+    # Both libarrow builds are live now: check the conversion of Python objects
+    # to Arrow arrays, which is the path nested columns depend on.
+    observed = pa.array(PROBE_VALUES).to_pylist()
+
+    if observed != PROBE_VALUES:
+        raise arrow_interop_error(observed)
+
+
 def _ensure_r_ipc_functions():
     """Define R-side IPC reader/writer/unnester functions once."""
     if "pysits_write_ipc_raw" in rpy2_globalenv:
@@ -162,6 +196,8 @@ def _ensure_r_ipc_functions():
         }
     """)
 
+    _check_arrow_interop()
+
 
 def _dataframe_to_ipc_bytes(df: PandasDataFrame) -> bytes:
     """Serialize a pandas DataFrame to Arrow IPC bytes.

{pysits-2.0.0.dev2 → pysits-2.0.0.dev4}/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")