mars: A Pure Python Implementation of Multivariate Adaptive Regression Splines (formerly pymars)

mars (formerly pymars) is a pure Python implementation of Multivariate Adaptive Regression Splines (MARS), inspired by the popular py-earth library by Jason Friedman and an R package earth by Stephen Milborrow. The goal of mars is to provide an easy-to-install, scikit-learn compatible version of the MARS algorithm without C/Cython dependencies.

Documentation

Complete documentation is available at: https://edithatogo.github.io/mars/ (once GitHub Pages is configured)

Key Features

• Pure Python: Easy to install and use across different platforms.
• Scikit-learn Compatible: Integrates with the scikit-learn ecosystem (estimators, pipelines, model selection tools).
• MARS Algorithm: Implements the core MARS fitting procedure, including:
  • Forward pass to select basis functions (both hinge and linear terms).
  • Pruning pass using Generalized Cross-Validation (GCV) to prevent overfitting.
  • Support for interaction terms (including interactions involving linear terms).
  • Refined minspan and endspan controls for knot placement, aligning more closely with py-earth behavior (e.g., minspan as a cooldown period).
• Feature Importance: Calculation of feature importances using methods like 'nb_subsets' (number of subsets in pruning trace), 'gcv' (GCV improvement), and 'rss' (RSS reduction).
• Regression and Classification: Provides EarthRegressor and EarthClassifier classes.
• Generalized Linear Models: The GLMEarth subclass fits logistic or Poisson models.
• Cross‑Validation Helper: The EarthCV class integrates with scikit‑learn's model selection utilities.
• Plotting Utilities: Simple diagnostics built on matplotlib.
• Advanced Interpretability: Partial dependence plots, Individual Conditional Expectation (ICE) plots, and model explanation tools.
• Comprehensive CLI: Command-line interface for model fitting, prediction, and evaluation.

Key Features

• Pure Python: Easy to install and use across different platforms.
• Scikit-learn Compatible: Integrates with the scikit-learn ecosystem (estimators, pipelines, model selection tools).
• MARS Algorithm: Implements the core MARS fitting procedure, including:
  • Forward pass to select basis functions (both hinge and linear terms).
  • Pruning pass using Generalized Cross-Validation (GCV) to prevent overfitting.
  • Support for interaction terms (including interactions involving linear terms).
  • Refined minspan and endspan controls for knot placement, aligning more closely with py-earth behavior (e.g., minspan as a cooldown period).
• Feature Importance: Calculation of feature importances using methods like 'nb_subsets' (number of subsets in pruning trace), 'gcv' (GCV improvement), and 'rss' (RSS reduction).
• Regression and Classification: Provides EarthRegressor and EarthClassifier classes.
• Generalized Linear Models: The GLMEarth subclass fits logistic or Poisson models.
• Cross‑Validation Helper: The EarthCV class integrates with scikit‑learn's model selection utilities.
• Plotting Utilities: Simple diagnostics built on matplotlib.
• Advanced Interpretability: Partial dependence plots, Individual Conditional Expectation (ICE) plots, and model explanation tools.
• Comprehensive CLI: Command-line interface for model fitting, prediction, and evaluation.

Project Status

This project is currently in the initial development phase. The core algorithm and scikit-learn compatibility are being built. See ROADMAP.md and TODO.md for more details on the development plan and progress.

Installation

Note: Install mars inside a Python virtual environment to silence pip warnings about running as root.

mars can be installed from TestPyPI:

pip install mars

To work with the latest source, clone the repository and install it in editable mode:

git clone https://github.com/edithatogo/mars.git
cd mars
pip install -e .

If you need to run scikit-learn's full estimator checks, install the optional pandas dependency:

pip install "mars[pandas]"

After installation you can check the installed version:

mars --version

Running Tests

Install the dependencies listed in requirements.txt before running the test suite. A small helper script is provided:

# Option 1: directly with pip
pip install -r requirements.txt

# To run the full scikit-learn estimator checks, install the optional pandas
# dependency as well:
pip install "mars[pandas]"

# Option 2: using the helper script
bash scripts/setup_tests.sh

After the dependencies are installed, run the tests with:

pytest

Usage

Quick demos

Run the included demo scripts to see mars in action:

python -m mars.demos.basic_regression_demo
python -m mars.demos.basic_classification_demo

Basic API

import numpy as np
import mars as earth

X = np.random.rand(100, 3)
y = np.sin(X[:, 0]) + X[:, 1]

model = earth.Earth(max_degree=1, penalty=3.0)
model.fit(X, y)
predictions = model.predict(X)

Documentation

The mars project uses a multi-branch documentation approach:

• Code Documentation: API and development documentation is available in the docs branch
• Research Paper: The academic paper describing mars is available in the paper branch

For usage examples and tutorials, check the examples directory in this main branch.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md and AGENTS.md for guidelines.

License

This project is licensed under the MIT License.

Acknowledgements

• Based on the work of Jerome H. Friedman on MARS.
• Inspired by the py-earth library (scikit-learn-contrib).
• Inspired by the R earth package.