Metadata-Version: 2.4
Name: sars
Version: 0.4.0
Summary: Species-area relationship curve fitting in Python
Project-URL: Homepage, https://github.com/jmcmeen/sars
Project-URL: Repository, https://github.com/jmcmeen/sars
Project-URL: Issues, https://github.com/jmcmeen/sars/issues
Author: John McMeen
License: MIT License
        
        Copyright (c) 2026 John McMeen
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: SAR,biodiversity,biogeography,ecology,macroecology,species-area relationship
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.4
Requires-Dist: scipy>=1.8
Provides-Extra: all
Requires-Dist: geopandas>=0.12; extra == 'all'
Requires-Dist: plotly>=5; extra == 'all'
Requires-Dist: shapely>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: geo
Requires-Dist: geopandas>=0.12; extra == 'geo'
Requires-Dist: shapely>=2.0; extra == 'geo'
Provides-Extra: interactive
Requires-Dist: plotly>=5; extra == 'interactive'
Description-Content-Type: text/markdown

# sars

Species-area relationship curve fitting in Python.

A conceptual mirror of the R [`sars`](https://cran.r-project.org/package=sars) package (Matthews et al. 2019), native to the Python scientific stack.

## Installation

```bash
pip install sars
```

## Features

- **20 SAR models** — power, logarithmic, asymptotic, sigmoid, and more
- **Multi-model inference** — fit all models at once, ranked by AICc with Akaike weights
- **Model averaging** — weighted-average predictions across candidate models
- **Bootstrap confidence intervals** — percentile-based CIs for averaged predictions
- **R-validated** — all models tested against R `sars` package reference values

## Quick start

```python
import sars

# Load the built-in Galapagos dataset (Preston 1962)
galap = sars.load_galap()

# Fit a single model
fit = sars.sar_power(galap)
print(fit)
# SARFit(model='power', c=33.1792  z=0.2832, R²=0.4912, AICc=189.03)

# Fit all 20 models and compare
multi = sars.sar_multi(galap)
print(multi.summary[["model", "AICc", "delta_AICc", "weight"]].head())

# Model-averaged predictions
avg = sars.sar_average(galap)
predictions = avg.predict([1.0, 10.0, 100.0])

# Bootstrap confidence intervals
ci = sars.bootstrap_ci(galap, n_boot=100)
```

## Available models

| Type | Models |
| ------ | -------- |
| Non-asymptotic | `power`, `powerR`, `loga`, `linear`, `epm1`, `epm2`, `p1`, `p2` |
| Asymptotic convex | `koba`, `monod`, `negexpo`, `asymp`, `ratio` |
| Asymptotic sigmoid | `mmf`, `gompertz`, `weibull3`, `weibull4`, `chapman`, `betap`, `heleg` |

Each model has a dedicated function (e.g. `sars.sar_power()`, `sars.sar_negexpo()`) and returns a `SARFit` object with parameters, R², AIC, AICc, and BIC.
