Metadata-Version: 2.4
Name: mars-earth
Version: 1.0.4
Summary: A Pure Python Implementation of Multivariate Adaptive Regression Splines
Author-email: Dylan A Mordaunt <dylan@mordaunt.dev>
Maintainer-email: Dylan A Mordaunt <dylan@mordaunt.dev>
License: Apache-2.0
Project-URL: Homepage, https://github.com/edithatogo/mars
Project-URL: Documentation, https://edithatogo.github.io/mars/
Project-URL: Repository, https://github.com/edithatogo/mars
Project-URL: Changelog, https://github.com/edithatogo/mars/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/edithatogo/mars/issues
Keywords: mars,multivariate adaptive regression splines,machine learning,scikit-learn,regression,classification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.4.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.3.0; extra == "pandas"
Provides-Extra: cli
Requires-Dist: pandas>=1.3.0; extra == "cli"
Requires-Dist: click>=8.0.0; extra == "cli"
Requires-Dist: rich>=12.0.0; extra == "cli"
Provides-Extra: profiling
Requires-Dist: scalene>=1.5.0; extra == "profiling"
Requires-Dist: py-spy>=0.3.0; extra == "profiling"
Provides-Extra: dev
Requires-Dist: uv>=0.1.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: pytest-sugar>=0.9.0; extra == "dev"
Requires-Dist: hypothesis>=6.90.0; extra == "dev"
Requires-Dist: mutmut>=2.4.0; extra == "dev"
Requires-Dist: nbmake>=1.4.0; extra == "dev"
Requires-Dist: diff-cover>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: ty>=0.0.30; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: bandit>=1.7.6; extra == "dev"
Requires-Dist: safety>=2.4.0; extra == "dev"
Requires-Dist: mkdocs>=1.5.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
Requires-Dist: mike>=2.0.0; extra == "dev"
Requires-Dist: python-semantic-release>=9.0.0; extra == "dev"
Requires-Dist: pandas>=1.3.0; extra == "dev"
Requires-Dist: tox>=4.11.0; extra == "dev"
Dynamic: license-file

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

![CI](https://github.com/edithatogo/mars/actions/workflows/ci.yml/badge.svg)
![Security](https://github.com/edithatogo/mars/actions/workflows/security.yml/badge.svg)
![Code Quality](https://github.com/edithatogo/mars/actions/workflows/code-quality.yml/badge.svg)
![Documentation](https://github.com/edithatogo/mars/actions/workflows/docs.yml/badge.svg)
![Code Coverage](https://codecov.io/gh/edithatogo/mars/branch/main/graph/badge.svg)
![PyPI](https://img.shields.io/pypi/v/mars.svg)
![Python Version](https://img.shields.io/pypi/pyversions/mars.svg)
![License](https://img.shields.io/github/license/edithatogo/mars.svg)

**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/](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:

```bash
pip install mars
```

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

```bash
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:

```bash
pip install "mars[pandas]"
```

After installation you can check the installed version:

```bash
mars --version
```

## Running Tests

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

```bash
# 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:

```bash
pytest

```

## Usage

### Quick demos

Run the included demo scripts to see `mars` in action:

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

### Basic API

```python
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](https://github.com/edithatogo/mars/tree/docs)
- **Research Paper**: The academic paper describing mars is available in the [paper branch](https://github.com/edithatogo/mars/tree/paper)

For usage examples and tutorials, check the [examples directory](examples/) in this main branch.

## Contributing

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

## Citing mars

If you use mars in your research, please cite it as follows:

```bibtex
@software{mars2026,
  author = {Mordaunt, Dylan A.},
  title = {mars: A Pure Python Implementation of Multivariate Adaptive Regression Splines},
  year = {2026},
  url = {https://github.com/edithatogo/mars},
  version = {1.0.1},
  license = {Apache-2.0},
}
```

A `CITATION.cff` file is also included in the repository for easy citation management.

## License

This project is licensed under the [Apache 2.0 License](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.
