GeDS for Python

This package provides a Python interface to the GeDS R package. The R package is the sole implementation of the statistical methods. Python supplies a scikit-learn-style API, pandas/NumPy conversion, environment diagnostics, and model serialization.

Requirements

• R 4.4 or newer (R 4.6.1 is used for development)
• GeDS 0.3.6 or newer
• Python 3.10 or newer

Install the Python package, including the optional plotting dependency used in the example:

python -m pip install "geds-python[plot]"

Install the R package separately, using R 4.6.1 or another supported R installation:

install.packages("GeDS")

The wrapper discovers the newest R installation under Program Files/R on Windows or uses Rscript from PATH on other platforms. Set R_HOME to select a particular R installation. If GeDS is installed in a non-default R library, set GEDS_R_LIBRARY to that library directory before importing geds.

The Python and R packages have independent release cycles. geds-python checks the installed GeDS version when its backend first starts and reports the selected R installation and package library through geds.diagnostics().

Check the backend before fitting:

import geds

print(geds.diagnostics())

Example

Install the optional plotting dependency with python -m pip install "geds-python[plot]", then fit and visualize a nonlinear regression:

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd

from geds import GeDSRegressor

rng = np.random.RandomState(123)
n = 500


def f_1(x):
    return (10 * x / (1 + 100 * x**2)) * 4 + 4


x = np.sort(rng.uniform(-2.0, 2.0, size=n))
means = f_1(x)
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")
ax.plot(
    grid_x,
    f_1(grid_x),
    color="0.25",
    linestyle=":",
    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.legend()
fig.tight_layout()
plt.show()

With GeDS 0.3.6 and R 4.6.1, this seeded example fits 16 internal knots. The dashed vertical lines show how GeDS places more knots around the sharp variation near zero while retaining knots across the wider domain.

GeDSRegressor delegates to GeDS::NGeDS(). For exponential-family models, use GeDSGeneralizedRegressor, which delegates to GeDS::GGeDS().

Choose spline and parametric components explicitly for mixed data:

model = GeDSRegressor(
    spline_features=["x"],
    linear_features=["group"],
).fit(X, y)

Spline features must be numeric. Parametric features may be numeric or categorical; their encoding is performed by the R package so fitting and prediction use R's native factor semantics.

Fitted estimators contain a serialized R model and can be saved with model.save(path) and restored with GeDSRegressor.load(path). As with any pickle-based format, only load files from trusted sources.

Development

Clone the repository, then install the development dependencies and run the integration tests with:

git clone https://github.com/emilioluissaenzguillen/GeDS-python.git
cd GeDS-python
python -m pip install -e ".[dev]"
python -m pytest
python -m build

The tests start an embedded R session and therefore require a working GeDS installation; they do not substitute or reimplement any GeDS calculations.

Contact

For questions about the Python interface, contact Emilio L. Sáenz Guillén at emilioluissaenzguillen@gmail.com.