sars 0.1.0__tar.gz

sars-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python-version }}"
+      - run: pip install -e ".[dev]"
+      - run: pytest
+      - run: ruff check src/

sars-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

sars-0.1.0/.gitignore

@@ -0,0 +1,209 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+/.claude
+CLAUDE.md

sars-0.1.0/CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "sars: Species-Area Relationship curve fitting in Python"
+type: software
+authors:
+  - family-names: McMeen
+    given-names: John
+license: MIT
+repository-code: "https://github.com/jmcmeen/sars"
+keywords:
+  - species-area relationship
+  - SAR
+  - macroecology
+  - biodiversity
+  - ecology

sars-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

sars-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: sars
+Version: 0.1.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
+```
+
+## Quick start
+
+```python
+import sars
+
+# Fit the power-law SAR model
+import pandas as pd
+data = pd.DataFrame({"area": [1, 2, 5, 10, 50], "species": [10, 15, 25, 40, 80]})
+fit = sars.sar_power(data)
+print(fit)
+```
+
+## License
+
+MIT

sars-0.1.0/README.md

@@ -0,0 +1,27 @@
+# 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
+```
+
+## Quick start
+
+```python
+import sars
+
+# Fit the power-law SAR model
+import pandas as pd
+data = pd.DataFrame({"area": [1, 2, 5, 10, 50], "species": [10, 15, 25, 40, 80]})
+fit = sars.sar_power(data)
+print(fit)
+```
+
+## License
+
+MIT

sars-0.1.0/deploy.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# deploy.sh — build and publish sars to PyPI
+# Usage:
+#   ./deploy.sh          → publish to PyPI (production)
+#   ./deploy.sh --test   → publish to TestPyPI first (dry run)
+#
+# Requires: pip install build twine
+# Requires: .env file with PYPI_API_TOKEN set (see .env.example)
+
+set -euo pipefail
+
+# ── Load environment ──────────────────────────────────────────────────────────
+if [ ! -f .env ]; then
+  echo "Error: .env file not found. Copy .env.example and fill in your token."
+  exit 1
+fi
+export $(grep -v '^#' .env | xargs)
+
+if [ -z "${PYPI_API_TOKEN:-}" ]; then
+  echo "Error: PYPI_API_TOKEN not set in .env"
+  exit 1
+fi
+
+# ── Parse args ────────────────────────────────────────────────────────────────
+TEST_MODE=false
+if [ "${1:-}" = "--test" ]; then
+  TEST_MODE=true
+  echo "→ Test mode: publishing to TestPyPI"
+else
+  echo "→ Production mode: publishing to PyPI"
+fi
+
+# ── Preflight checks ──────────────────────────────────────────────────────────
+echo ""
+echo "── Preflight ────────────────────────────────────────────────────────────"
+
+# Confirm on the right branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$BRANCH" != "main" ] && [ "$TEST_MODE" = false ]; then
+  echo "Error: production deploys must be from main (currently on '$BRANCH')"
+  exit 1
+fi
+
+# Confirm clean working tree
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  echo "Error: uncommitted changes present. Commit or stash before deploying."
+  exit 1
+fi
+
+# Run tests
+echo "Running test suite..."
+pip install -e ".[dev]" -q
+pytest --tb=short -q
+echo "Tests passed."
+
+# Lint
+echo "Running ruff..."
+ruff check src/
+echo "Lint passed."
+
+# ── Get version ───────────────────────────────────────────────────────────────
+VERSION=$(python -c "import tomllib; f=open('pyproject.toml','rb'); d=tomllib.load(f); print(d['project']['version'])")
+echo ""
+echo "── Building sars v${VERSION} ─────────────────────────────────────────────"
+
+# Confirm with user on production deploy
+if [ "$TEST_MODE" = false ]; then
+  read -p "Publish sars v${VERSION} to PyPI? [y/N] " confirm
+  if [ "${confirm}" != "y" ] && [ "${confirm}" != "Y" ]; then
+    echo "Aborted."
+    exit 0
+  fi
+fi
+
+# ── Build ─────────────────────────────────────────────────────────────────────
+echo ""
+echo "── Building ─────────────────────────────────────────────────────────────"
+rm -rf dist/ build/
+python -m build
+echo "Build complete:"
+ls -lh dist/
+
+# ── Publish ───────────────────────────────────────────────────────────────────
+echo ""
+echo "── Publishing ───────────────────────────────────────────────────────────"
+
+if [ "$TEST_MODE" = true ]; then
+  TWINE_PASSWORD="${PYPI_API_TOKEN}" twine upload \
+    --repository testpypi \
+    --username __token__ \
+    dist/*
+  echo ""
+  echo "✓ Published to TestPyPI."
+  echo "  Install with: pip install --index-url https://test.pypi.org/simple/ sars==${VERSION}"
+else
+  TWINE_PASSWORD="${PYPI_API_TOKEN}" twine upload \
+    --username __token__ \
+    dist/*
+  echo ""
+  echo "✓ Published to PyPI."
+  echo "  Install with: pip install sars==${VERSION}"
+
+  # Tag the release
+  if ! git tag | grep -q "v${VERSION}"; then
+    git tag "v${VERSION}"
+    git push origin "v${VERSION}"
+    echo "  Git tag v${VERSION} pushed."
+  fi
+fi
+
+echo ""
+echo "Done."

sars-0.1.0/env.example

@@ -0,0 +1,12 @@
+# .env.example — copy to .env and fill in your values
+# NEVER commit .env to version control.
+# Add .env to .gitignore immediately.
+
+# PyPI API token — get from pypi.org/manage/account/token/
+# Scope: "Entire account" for first deploy; narrow to project after first publish.
+# Token format: pypi-AgEIcHlwaS5vcmcA...
+PYPI_API_TOKEN=pypi-your-token-here
+
+# TestPyPI token (optional) — get from test.pypi.org/manage/account/token/
+# Used with: ./deploy.sh --test
+# TESTPYPI_API_TOKEN=pypi-your-test-token-here

sars-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sars"
+version = "0.1.0"
+description = "Species-area relationship curve fitting in Python"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "John McMeen" }]
+requires-python = ">=3.9"
+keywords = ["species-area relationship", "SAR", "macroecology",
+            "biodiversity", "ecology", "biogeography"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "numpy>=1.22",
+    "scipy>=1.8",
+    "pandas>=1.4",
+    "matplotlib>=3.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov", "ruff", "mypy"]
+interactive = ["plotly>=5"]
+geo = ["geopandas>=0.12", "shapely>=2.0"]
+all = ["sars[interactive,geo]"]
+
+[project.urls]
+Homepage = "https://github.com/jmcmeen/sars"
+Repository = "https://github.com/jmcmeen/sars"
+Issues = "https://github.com/jmcmeen/sars/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sars"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=sars --cov-report=term-missing"

sars-0.1.0/src/sars/__init__.py

@@ -0,0 +1,14 @@
+"""sars — Species-area relationship curve fitting in Python.
+
+Conceptual mirror of the R `sars` package (Matthews et al. 2019),
+native to the Python scientific stack.
+"""
+
+from sars._io import load_galap
+from sars._models import SARFit, sar_power
+
+__all__ = [
+    "SARFit",
+    "sar_power",
+    "load_galap",
+]

sars-0.1.0/src/sars/_inference.py

@@ -0,0 +1,3 @@
+"""Multi-model inference, averaging, and bootstrap CI."""
+
+from __future__ import annotations

sars-0.1.0/src/sars/_io.py

@@ -0,0 +1,25 @@
+"""Data loading and I/O adapters."""
+
+from __future__ import annotations
+
+
+def load_galap():
+    """Load the Galapagos plant species-area dataset.
+
+    Returns the Preston (1962) 16-island dataset as shipped in the R sars
+    package (Albemarle/Isabela excluded).
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with columns 'area' and 'species'.
+
+    Raises
+    ------
+    NotImplementedError
+        Until the R reference data is generated and committed.
+    """
+    raise NotImplementedError(
+        "Run tests/r_reference/generate_r_reference.R first, "
+        "then this function will read from galap.csv"
+    )

sars-0.1.0/src/sars/_models.py

@@ -0,0 +1,196 @@
+"""SAR model definitions and fitting routines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import least_squares
+
+
+@dataclass
+class SARFit:
+    """Result of fitting a single SAR model.
+
+    Attributes
+    ----------
+    model : str
+        Short model identifier matching R sars function suffix (e.g. 'power').
+    params : dict[str, float]
+        Fitted parameter values keyed by parameter name.
+    r_squared : float
+        Coefficient of determination in arithmetic space.
+    aic : float
+        Akaike Information Criterion (normal log-likelihood convention).
+    aicc : float
+        AIC corrected for small sample size.
+    bic : float
+        Bayesian Information Criterion.
+    n : int
+        Number of observations used in fit.
+    converged : bool
+        Whether the NLS solver converged.
+    data : pd.DataFrame
+        Original data (columns: area, species).
+    """
+
+    model: str
+    params: dict
+    r_squared: float
+    aic: float
+    aicc: float
+    bic: float
+    n: int
+    converged: bool
+    data: pd.DataFrame
+
+    def predict(self, area: float | np.ndarray) -> np.ndarray:
+        """Predict species richness for given area value(s)."""
+        area = np.asarray(area, dtype=float)
+        if self.model == "power":
+            return self.params["c"] * area ** self.params["z"]
+        raise NotImplementedError(f"predict not yet implemented for '{self.model}'")
+
+    def __repr__(self) -> str:
+        p = "  ".join(f"{k}={v:.4f}" for k, v in self.params.items())
+        return (
+            f"SARFit(model='{self.model}', {p}, "
+            f"R²={self.r_squared:.4f}, AICc={self.aicc:.2f})"
+        )
+
+
+def _compute_ic(k: int, n: int, rss: float) -> tuple[float, float, float]:
+    """Compute AIC, AICc, and BIC from residual sum of squares.
+
+    Uses the normal log-likelihood convention consistent with R sars:
+        logL = -n/2 * log(2*pi*rss/n) - n/2
+
+    Parameters
+    ----------
+    k : int
+        Number of estimated parameters (including sigma).
+    n : int
+        Number of observations.
+    rss : float
+        Residual sum of squares.
+
+    Returns
+    -------
+    tuple[float, float, float]
+        (AIC, AICc, BIC)
+    """
+    # k already includes sigma in R sars convention
+    log_lik = -n / 2.0 * np.log(2.0 * np.pi * rss / n) - n / 2.0
+    aic = -2.0 * log_lik + 2.0 * k
+    # AICc correction
+    if n - k - 1 > 0:
+        aicc = aic + (2.0 * k * (k + 1.0)) / (n - k - 1.0)
+    else:
+        aicc = np.inf
+    bic = -2.0 * log_lik + k * np.log(n)
+    return aic, aicc, bic
+
+
+def sar_power(data: pd.DataFrame, grid_start: bool = True) -> SARFit:
+    """Fit the power law SAR model: S = c * A^z
+
+    The Arrhenius (1921) power model is the most widely used SAR model.
+    Fitted using nonlinear least squares in arithmetic space with a grid
+    of starting values to avoid local minima.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        DataFrame with columns 'area' (float, km²) and 'species' (int).
+    grid_start : bool
+        If True, use a grid of starting values. Recommended for all use.
+
+    Returns
+    -------
+    SARFit
+        Fitted model with params {'c': ..., 'z': ...}.
+
+    References
+    ----------
+    Arrhenius O (1921) Species and area. Journal of Ecology 9:95-99.
+    """
+    area = np.asarray(data["area"], dtype=float)
+    species = np.asarray(data["species"], dtype=float)
+    n = len(area)
+
+    def residuals(p: np.ndarray) -> np.ndarray:
+        c, z = p
+        return species - c * area**z
+
+    best_cost = np.inf
+    best_result = None
+
+    if grid_start:
+        # Grid of starting values — log-space OLS gives a good anchor
+        log_a = np.log(area)
+        log_s = np.log(np.maximum(species, 1e-10))
+        slope, intercept = np.polyfit(log_a, log_s, 1)
+        c_ols = np.exp(intercept)
+        z_ols = slope
+
+        # Build grid around OLS estimate + wide exploration
+        c_starts = np.array([c_ols * f for f in [0.1, 0.5, 1.0, 2.0, 5.0, 10.0]])
+        z_starts = np.array([z_ols * f for f in [0.1, 0.5, 1.0, 1.5, 2.0]])
+        c_starts = np.append(c_starts, [1.0, 10.0, 50.0, 100.0])
+        z_starts = np.append(z_starts, [0.1, 0.2, 0.3, 0.5, 0.8])
+    else:
+        c_starts = np.array([1.0, 10.0, 50.0])
+        z_starts = np.array([0.1, 0.3, 0.5])
+
+    for c0 in c_starts:
+        for z0 in z_starts:
+            if c0 <= 0:
+                continue
+            try:
+                result = least_squares(
+                    residuals,
+                    x0=[c0, z0],
+                    bounds=([1e-10, -5.0], [1e6, 5.0]),
+                    method="trf",
+                    max_nfev=2000,
+                )
+                if result.cost < best_cost:
+                    best_cost = result.cost
+                    best_result = result
+            except Exception:
+                continue
+
+    if best_result is None or not best_result.success:
+        return SARFit(
+            model="power",
+            params={"c": np.nan, "z": np.nan},
+            r_squared=np.nan,
+            aic=np.nan,
+            aicc=np.nan,
+            bic=np.nan,
+            n=n,
+            converged=False,
+            data=data,
+        )
+
+    c_fit, z_fit = best_result.x
+    rss = 2.0 * best_result.cost  # least_squares minimises 0.5 * sum(r^2)
+    ss_tot = np.sum((species - np.mean(species)) ** 2)
+    r_squared = 1.0 - rss / ss_tot
+
+    # k = number of model params + 1 for sigma (R sars convention)
+    k = 3  # c, z, sigma
+    aic, aicc, bic = _compute_ic(k, n, rss)
+
+    return SARFit(
+        model="power",
+        params={"c": c_fit, "z": z_fit},
+        r_squared=r_squared,
+        aic=aic,
+        aicc=aicc,
+        bic=bic,
+        n=n,
+        converged=True,
+        data=data,
+    )

sars-0.1.0/src/sars/_plots.py

@@ -0,0 +1,3 @@
+"""Plotting functions for SAR fits."""
+
+from __future__ import annotations

sars-0.1.0/src/sars/_threshold.py

@@ -0,0 +1,3 @@
+"""Threshold / piecewise SAR models."""
+
+from __future__ import annotations

sars-0.1.0/tests/conftest.py

@@ -0,0 +1,21 @@
+import pandas as pd
+import pytest
+from pathlib import Path
+
+REF = Path("tests/r_reference")
+
+
+@pytest.fixture(scope="session")
+def galap():
+    path = REF / "galap.csv"
+    if not path.exists():
+        pytest.skip("Run generate_r_reference.R first")
+    return pd.read_csv(path)
+
+
+@pytest.fixture(scope="session")
+def r_reference():
+    path = REF / "all_models_galap.csv"
+    if not path.exists():
+        pytest.skip("Run generate_r_reference.R first")
+    return pd.read_csv(path).set_index("model")

sars-0.1.0/tests/r_reference/generate_r_reference.R

@@ -0,0 +1,38 @@
+# Rscript tests/r_reference/generate_r_reference.R
+library(sars)
+
+# 1. Export the exact galap dataset (16 rows)
+write.csv(galap, "tests/r_reference/galap.csv", row.names = FALSE)
+cat("Exported galap:", nrow(galap), "rows\n")
+
+# 2. Fit all 20 models and export reference values
+models <- c("power","powerR","epm1","epm2","p1","p2","loga","koba",
+            "mmf","monod","negexpo","chapman","weibull3","asymp",
+            "ratio","gompertz","weibull4","betap","heleg","linear")
+
+results <- list()
+for (m in models) {
+  fn <- tryCatch(get(paste0("sar_", m)), error = function(e) NULL)
+  if (is.null(fn)) next
+  tryCatch({
+    fit <- fn(data = galap)
+    results[[m]] <- data.frame(
+      model     = m,
+      converged = isTRUE(fit$converged),
+      r2        = fit$R2,
+      aic       = fit$AIC,
+      aicc      = fit$AICc,
+      bic       = fit$BIC,
+      params    = paste(names(fit$par), round(fit$par, 6),
+                        sep = "=", collapse = "; ")
+    )
+  }, error = function(e) {
+    results[[m]] <<- data.frame(model=m, converged=FALSE,
+                                r2=NA, aic=NA, aicc=NA, bic=NA, params=NA)
+  })
+}
+
+df <- do.call(rbind, results)
+write.csv(df, "tests/r_reference/all_models_galap.csv", row.names = FALSE)
+cat("Reference table written.\n\nPower law:\n")
+print(sar_power(galap))

sars-0.1.0/tests/test_models.py

@@ -0,0 +1,29 @@
+import pandas as pd
+import pytest
+
+from sars import sar_power
+
+
+def test_power_law_spot_check():
+    """Quick sanity check using confirmed R values (no R script needed)."""
+    partial = pd.DataFrame({
+        "area":    [0.20, 0.90, 1.00, 1.80, 1.87, 4.40, 7.10,
+                    7.50, 18.00, 20.00],
+        "species": [  48,    7,   52,   14,   42,   22,  103,
+                        48,    79,   119],
+    })
+    fit = sar_power(partial)
+    assert fit.converged is True
+    assert 0.0 < fit.params["z"] < 1.0   # z must be in plausible SAR range
+    assert fit.params["c"] > 0
+    assert 0.0 < fit.r_squared <= 1.0
+
+
+def test_power_law_matches_r(galap, r_reference):
+    """Full validation: must match R sars::sar_power(galap) exactly."""
+    fit = sar_power(galap)
+    ref = r_reference.loc["power"]
+    assert fit.r_squared == pytest.approx(ref["r2"], abs=0.005)
+    assert fit.aicc == pytest.approx(ref["aicc"], abs=0.1)
+    assert fit.params["c"] == pytest.approx(33.1792, abs=0.05)
+    assert fit.params["z"] == pytest.approx(0.2832, abs=0.005)