geds-python 0.1.0a2__tar.gz → 0.1.0a3__tar.gz

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/CHANGELOG.md

@@ -6,6 +6,13 @@ The project follows [Semantic Versioning](https://semver.org/). Versions use
 the Python packaging form of pre-release identifiers, such as `0.1.0a1` for
 the first alpha release.
 
+## 0.1.0a3 - 2026-09-23
+
+- Add `python -m geds.check` for human-readable or JSON environment checks.
+- Add `geds.plot_fit()` for Python-native visualization of univariate fits and
+  internal knots.
+- Expand installation and R-library troubleshooting guidance.
+
 ## 0.1.0a2 - 2026-09-20
 
 - Preload R's core numerical DLLs on Windows so embedded R 4.6 can load

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use GeDS for Python, please cite this software and the GeDS methodology references."
 title: "GeDS for Python"
 type: software
-version: 0.1.0a2
-date-released: 2026-09-20
+version: 0.1.0a3
+date-released: 2026-09-23
 license: GPL-3.0-only
 repository-code: "https://github.com/emilioluissaenzguillen/GeDS-python"
 authors:

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: geds-python
-Version: 0.1.0a2
+Version: 0.1.0a3
 Summary: Python estimators backed by the GeDS R package
 Project-URL: Homepage, https://github.com/emilioluissaenzguillen/GeDS-python
 Project-URL: Repository, https://github.com/emilioluissaenzguillen/GeDS-python
@@ -29,6 +29,7 @@ Requires-Dist: rpy2<3.7,>=3.6.7
 Requires-Dist: scikit-learn>=1.4
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: matplotlib>=3.8; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Provides-Extra: plot
 Requires-Dist: matplotlib>=3.8; extra == 'plot'
@@ -75,12 +76,44 @@ selected R installation and package library through `geds.diagnostics()`.
 
 Check the backend before fitting:
 
+```console
+python -m geds.check
+```
+
+For a machine-readable report, use `python -m geds.check --json`. The same
+information is available inside Python:
+
 ```python
 import geds
 
 print(geds.diagnostics())
 ```
 
+### Selecting R and its package library
+
+Usually no configuration is necessary. If several R installations are
+available, select one before starting Python:
+
+```powershell
+$env:R_HOME = "C:\Program Files\R\R-4.6.1"
+python -m geds.check
+```
+
+```bash
+export R_HOME="/Library/Frameworks/R.framework/Resources"  # macOS
+# export R_HOME="/usr/lib/R"                               # Linux
+python -m geds.check
+```
+
+If GeDS is installed in a personal or otherwise non-default R library, set
+`GEDS_R_LIBRARY` to the directory that contains the `GeDS` folder. You can
+find that directory from R with `find.package("GeDS")`; use its parent
+directory as `GEDS_R_LIBRARY`.
+
+If the check reports that R is missing, install R or set `R_HOME`. If it finds
+R but not GeDS, start that same R installation and run
+`install.packages("GeDS")`, then rerun the check.
+
 ## Example
 
 Install the optional plotting dependency with
@@ -92,7 +125,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 
-from geds import GeDSRegressor
+from geds import GeDSRegressor, plot_fit
 
 rng = np.random.RandomState(123)
 n = 500
@@ -108,15 +141,13 @@ y = rng.normal(means, scale=0.1)
 X = pd.DataFrame({"x": x})
 
 model = GeDSRegressor(order=3).fit(X, y)
-grid_x = np.linspace(x.min(), x.max(), 500)
-grid = pd.DataFrame({"x": grid_x})
-fitted = model.predict(grid)
 knots = np.asarray(model.knots_, dtype=float)
 
 print("Internal knots:", knots)
 
 fig, ax = plt.subplots()
-ax.scatter(x, y, s=12, alpha=0.35, label="Data")
+plot_fit(model, X, y, ax=ax)
+grid_x = np.linspace(x.min(), x.max(), 500)
 ax.plot(
     grid_x,
     f_1(grid_x),
@@ -125,16 +156,7 @@ ax.plot(
     linewidth=2,
     label="True mean",
 )
-ax.plot(grid_x, fitted, linewidth=2, label="GeDS fit")
-for index, knot in enumerate(knots):
-    ax.axvline(
-        knot,
-        color="tab:red",
-        linestyle="--",
-        alpha=0.55,
-        label="Internal knots" if index == 0 else None,
-    )
-ax.set(xlabel="x", ylabel="y", title="GeDS spline regression")
+ax.set(ylabel="y")
 ax.legend()
 fig.tight_layout()
 plt.show()

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/README.md

@@ -37,12 +37,44 @@ selected R installation and package library through `geds.diagnostics()`.
 
 Check the backend before fitting:
 
+```console
+python -m geds.check
+```
+
+For a machine-readable report, use `python -m geds.check --json`. The same
+information is available inside Python:
+
 ```python
 import geds
 
 print(geds.diagnostics())
 ```
 
+### Selecting R and its package library
+
+Usually no configuration is necessary. If several R installations are
+available, select one before starting Python:
+
+```powershell
+$env:R_HOME = "C:\Program Files\R\R-4.6.1"
+python -m geds.check
+```
+
+```bash
+export R_HOME="/Library/Frameworks/R.framework/Resources"  # macOS
+# export R_HOME="/usr/lib/R"                               # Linux
+python -m geds.check
+```
+
+If GeDS is installed in a personal or otherwise non-default R library, set
+`GEDS_R_LIBRARY` to the directory that contains the `GeDS` folder. You can
+find that directory from R with `find.package("GeDS")`; use its parent
+directory as `GEDS_R_LIBRARY`.
+
+If the check reports that R is missing, install R or set `R_HOME`. If it finds
+R but not GeDS, start that same R installation and run
+`install.packages("GeDS")`, then rerun the check.
+
 ## Example
 
 Install the optional plotting dependency with
@@ -54,7 +86,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 
-from geds import GeDSRegressor
+from geds import GeDSRegressor, plot_fit
 
 rng = np.random.RandomState(123)
 n = 500
@@ -70,15 +102,13 @@ y = rng.normal(means, scale=0.1)
 X = pd.DataFrame({"x": x})
 
 model = GeDSRegressor(order=3).fit(X, y)
-grid_x = np.linspace(x.min(), x.max(), 500)
-grid = pd.DataFrame({"x": grid_x})
-fitted = model.predict(grid)
 knots = np.asarray(model.knots_, dtype=float)
 
 print("Internal knots:", knots)
 
 fig, ax = plt.subplots()
-ax.scatter(x, y, s=12, alpha=0.35, label="Data")
+plot_fit(model, X, y, ax=ax)
+grid_x = np.linspace(x.min(), x.max(), 500)
 ax.plot(
     grid_x,
     f_1(grid_x),
@@ -87,16 +117,7 @@ ax.plot(
     linewidth=2,
     label="True mean",
 )
-ax.plot(grid_x, fitted, linewidth=2, label="GeDS fit")
-for index, knot in enumerate(knots):
-    ax.axvline(
-        knot,
-        color="tab:red",
-        linestyle="--",
-        alpha=0.55,
-        label="Internal knots" if index == 0 else None,
-    )
-ax.set(xlabel="x", ylabel="y", title="GeDS spline regression")
+ax.set(ylabel="y")
 ax.legend()
 fig.tight_layout()
 plt.show()

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "geds-python"
-version = "0.1.0a2"
+version = "0.1.0a3"
 description = "Python estimators backed by the GeDS R package"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -42,7 +42,7 @@ dependencies = [
 
 [project.optional-dependencies]
 test = ["pytest>=8"]
-dev = ["build>=1.2", "pytest>=8"]
+dev = ["build>=1.2", "matplotlib>=3.8", "pytest>=8"]
 plot = ["matplotlib>=3.8"]
 
 [project.urls]

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/src/geds/__init__.py

@@ -2,12 +2,14 @@
 
 from ._backend import BackendUnavailableError, diagnostics
 from ._estimators import GeDSGeneralizedRegressor, GeDSRegressor
+from ._plotting import plot_fit
 
 __all__ = [
     "BackendUnavailableError",
     "GeDSGeneralizedRegressor",
     "GeDSRegressor",
     "diagnostics",
+    "plot_fit",
 ]
 
-__version__ = "0.1.0a2"
+__version__ = "0.1.0a3"

geds_python-0.1.0a3/src/geds/_plotting.py

@@ -0,0 +1,69 @@
+"""Optional Python-native plotting helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from sklearn.utils.validation import check_is_fitted
+
+
+def plot_fit(
+    estimator: Any,
+    X: Any,
+    y: Any | None = None,
+    *,
+    ax: Any | None = None,
+    grid_size: int = 500,
+    show_knots: bool = True,
+) -> Any:
+    """Plot a fitted univariate GeDS model and return its Matplotlib axes.
+
+    This helper only visualizes predictions already produced by GeDS; it does
+    not implement any statistical calculation in Python.
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError(
+            'Plotting requires Matplotlib; install "geds-python[plot]".'
+        ) from exc
+
+    check_is_fitted(estimator, "_r_model_")
+    frame, named_input = estimator._frame(X)
+    if frame.shape[1] != 1 or estimator.n_features_in_ != 1:
+        raise ValueError("plot_fit supports fitted models with one feature only.")
+    if grid_size < 2:
+        raise ValueError("grid_size must be at least 2.")
+    values = np.asarray(frame.iloc[:, 0], dtype=float)
+    if not np.isfinite(values).all():
+        raise ValueError("X must contain only finite values.")
+    grid_values = np.linspace(values.min(), values.max(), grid_size)
+    if named_input:
+        grid = pd.DataFrame({frame.columns[0]: grid_values})
+    else:
+        grid = grid_values.reshape(-1, 1)
+    fitted = estimator.predict(grid)
+
+    if ax is None:
+        _, ax = plt.subplots()
+    if y is not None:
+        response = np.asarray(y, dtype=float)
+        if response.ndim != 1 or len(response) != len(values):
+            raise ValueError("y must be one-dimensional and have the same length as X.")
+        ax.scatter(values, response, s=12, alpha=0.35, label="Data")
+    ax.plot(grid_values, fitted, linewidth=2, label="GeDS fit")
+    if show_knots and estimator.knots_ is not None:
+        knots = np.asarray(estimator.knots_, dtype=float).ravel()
+        for index, knot in enumerate(knots):
+            ax.axvline(
+                knot,
+                color="tab:red",
+                linestyle="--",
+                alpha=0.55,
+                label="Internal knots" if index == 0 else None,
+            )
+    ax.set(xlabel=str(frame.columns[0]), ylabel="Response", title="GeDS spline regression")
+    ax.legend()
+    return ax

geds_python-0.1.0a3/src/geds/check.py

@@ -0,0 +1,64 @@
+"""Command-line environment check for the Python/R bridge."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Sequence
+
+from ._backend import BackendUnavailableError, diagnostics
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m geds.check",
+        description="Check that Python can initialize R and load the GeDS package.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="print machine-readable JSON instead of the human-readable report",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the environment check and return a process exit code."""
+    args = _parser().parse_args(argv)
+    try:
+        information = diagnostics()
+    except BackendUnavailableError as exc:
+        if args.json:
+            print(json.dumps({"status": "error", "message": str(exc)}, indent=2))
+        else:
+            print("GeDS environment check: FAILED", file=sys.stderr)
+            print(str(exc), file=sys.stderr)
+            print(
+                "Set R_HOME if the intended R installation is not discovered, "
+                "and set GEDS_R_LIBRARY if GeDS is in a non-default R library.",
+                file=sys.stderr,
+            )
+        return 1
+
+    report = {"status": "ok", **information}
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        labels = {
+            "python": "Python",
+            "r_version": "R",
+            "r_home": "R home",
+            "rpy2_version": "rpy2",
+            "geds_version": "GeDS",
+            "geds_library": "GeDS library",
+            "minimum_geds_version": "Minimum GeDS",
+        }
+        print("GeDS environment check: OK")
+        for key, label in labels.items():
+            print(f"  {label}: {information[key]}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised as a module
+    raise SystemExit(main())

{geds_python-0.1.0a2 → geds_python-0.1.0a3}/tests/test_estimators.py

@@ -9,7 +9,9 @@ import pytest
 from sklearn.base import clone, is_regressor
 
 import geds
-from geds import GeDSGeneralizedRegressor, GeDSRegressor
+import geds.check as check_module
+from geds import GeDSGeneralizedRegressor, GeDSRegressor, plot_fit
+from geds.check import main as check_main
 
 
 def test_distribution_and_module_versions_match():
@@ -31,6 +33,29 @@ def test_diagnostics():
     assert info["minimum_geds_version"] == "0.3.6"
 
 
+def test_environment_check(capsys):
+    assert check_main([]) == 0
+    assert "GeDS environment check: OK" in capsys.readouterr().out
+
+
+def test_environment_check_json(capsys):
+    assert check_main(["--json"]) == 0
+    output = capsys.readouterr().out
+    assert '"status": "ok"' in output
+    assert '"geds_version"' in output
+
+
+def test_environment_check_failure(monkeypatch, capsys):
+    def unavailable():
+        raise geds.BackendUnavailableError("R was not found.")
+
+    monkeypatch.setattr(check_module, "diagnostics", unavailable)
+    assert check_main([]) == 1
+    error = capsys.readouterr().err
+    assert "GeDS environment check: FAILED" in error
+    assert "R_HOME" in error
+
+
 def test_ngeds_reference_values_and_pickle(tmp_path):
     frame = _r_reference_frame(
         """
@@ -60,6 +85,10 @@ def test_ngeds_reference_values_and_pickle(tmp_path):
     loaded = GeDSRegressor.load(model_path)
     np.testing.assert_array_equal(loaded.predict(frame[["X"]].iloc[:5]), prediction)
 
+    axes = plot_fit(estimator, frame[["X"]], frame["Y"], grid_size=50)
+    assert axes.get_title() == "GeDS spline regression"
+    assert len(axes.lines) == len(np.asarray(estimator.knots_).ravel()) + 1
+
 
 def test_ggeds_poisson_reference_values():
     frame = _r_reference_frame(