nestsar 0.1.0__py3-none-any.whl

nestsar/__init__.py

@@ -0,0 +1,13 @@
+"""Nested species-area relationship datasets from point observations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from nestsar._nest import Nest, random_nest
+from nestsar._sample import Sample, hull_area
+
+try:
+    __version__ = version("nestsar")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"
+
+__all__ = ["Nest", "Sample", "__version__", "hull_area", "random_nest"]

nestsar/_nest.py

@@ -0,0 +1,73 @@
+"""Nested samples: a sequence of ever-smaller subsets of one sample."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from nestsar._sample import Sample, hull_area
+
+
+@dataclass(frozen=True)
+class Nest:
+    """A nested sequence of sub-samples of one :class:`Sample`.
+
+    ``steps[i]`` holds the row indices into ``sample.points`` that remain at
+    step ``i``; ``steps[0]`` is every point and each later step is a subset
+    of the one before. Strategies differ only in which point they drop next.
+    """
+
+    sample: Sample
+    steps: tuple[np.ndarray, ...]
+
+    @property
+    def n_steps(self) -> int:
+        return len(self.steps)
+
+    def sample_at(self, step: int) -> Sample:
+        return self.sample.subset(self.steps[step])
+
+    def to_frame(self) -> pd.DataFrame:
+        """One row per step: ``step``, ``n_points``, ``area``, ``species``."""
+        points = self.sample.points
+        species = self.sample.data["species"].to_numpy()
+        keys = pd.MultiIndex.from_frame(self.sample.data[["lon", "lat"]])
+        rows = []
+        for i, idx in enumerate(self.steps):
+            kept = points[idx]
+            mask = keys.isin([tuple(p) for p in kept])
+            rows.append(
+                {
+                    "step": i,
+                    "n_points": len(idx),
+                    "area": hull_area(kept),
+                    "species": int(len(np.unique(species[mask]))),
+                }
+            )
+        return pd.DataFrame(rows)
+
+    def sar_data(self) -> pd.DataFrame:
+        """``area`` and ``species`` columns for ``sars``, dropping zero-area steps."""
+        frame = self.to_frame()
+        return frame.loc[frame["area"] > 0, ["area", "species"]].reset_index(drop=True)
+
+
+def random_nest(sample: Sample, min_points: int = 3, seed: int | None = None) -> Nest:
+    """Nest a sample by removing one point at a time, uniformly at random.
+
+    The baseline every other strategy is compared against. Stops when
+    ``min_points`` points remain.
+    """
+    n = sample.n_points
+    if n < min_points:
+        raise ValueError(f"Sample has {n} points; need at least {min_points}")
+    rng = np.random.default_rng(seed)
+    remaining = np.arange(n)
+    steps = [remaining.copy()]
+    while len(remaining) > min_points:
+        drop = rng.integers(len(remaining))
+        remaining = np.delete(remaining, drop)
+        steps.append(remaining.copy())
+    return Nest(sample=sample, steps=tuple(steps))

nestsar/_sample.py

@@ -0,0 +1,114 @@
+"""Point observations of species, the input every nesting strategy starts from."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from shapely.geometry import MultiPoint
+
+COLUMNS = ("species", "lon", "lat")
+
+
+def _validate(df: pd.DataFrame) -> pd.DataFrame:
+    missing = [c for c in COLUMNS if c not in df.columns]
+    if missing:
+        raise KeyError(f"Missing column(s): {missing}. Need {list(COLUMNS)}.")
+    out = df.loc[:, list(COLUMNS)].reset_index(drop=True)
+    if len(out) == 0:
+        raise ValueError("Sample has no observations")
+    if out["species"].isna().any():
+        raise ValueError("species contains missing values")
+    lon = pd.to_numeric(out["lon"], errors="coerce")
+    lat = pd.to_numeric(out["lat"], errors="coerce")
+    if lon.isna().any() or lat.isna().any():
+        raise ValueError("lon and lat must be numeric with no missing values")
+    if ((lat < -90) | (lat > 90)).any():
+        raise ValueError("lat must be within [-90, 90]")
+    if ((lon < -180) | (lon > 180)).any():
+        raise ValueError("lon must be within [-180, 180]")
+    out["lon"] = lon.astype(float)
+    out["lat"] = lat.astype(float)
+    out["species"] = out["species"].astype(str)
+    return out
+
+
+@dataclass(frozen=True)
+class Sample:
+    """A set of georeferenced species observations.
+
+    Each row of ``data`` is one observation with columns ``species``, ``lon``,
+    and ``lat`` (decimal degrees). Several observations may share a point.
+
+    Build one with :meth:`from_df` or :meth:`from_csv`.
+    """
+
+    data: pd.DataFrame
+
+    @classmethod
+    def from_df(
+        cls,
+        df: pd.DataFrame,
+        species_col: str = "species",
+        lon_col: str = "lon",
+        lat_col: str = "lat",
+    ) -> Sample:
+        """Build a sample from a DataFrame, renaming columns as needed."""
+        renamed = df.rename(columns={species_col: "species", lon_col: "lon", lat_col: "lat"})
+        return cls(_validate(renamed))
+
+    @classmethod
+    def from_csv(cls, path: str | Path, **kwargs: str) -> Sample:
+        """Build a sample from a CSV file; ``kwargs`` are the column names for :meth:`from_df`."""
+        return cls.from_df(pd.read_csv(path), **kwargs)
+
+    @property
+    def n_observations(self) -> int:
+        return len(self.data)
+
+    @property
+    def n_species(self) -> int:
+        return int(self.data["species"].nunique())
+
+    @property
+    def points(self) -> np.ndarray:
+        """Distinct (lon, lat) points, shape (n_points, 2), in first-seen order."""
+        return self.data[["lon", "lat"]].drop_duplicates().to_numpy(dtype=float)
+
+    @property
+    def n_points(self) -> int:
+        return len(self.points)
+
+    @property
+    def area(self) -> float:
+        """Area of the convex hull of the points, in square degrees.
+
+        Zero when fewer than three distinct, non-collinear points remain.
+        Square degrees are not a physical area; they are fine for ordering
+        nested samples and for fitting within one sample, which is what the
+        nesting strategies need. A projected area is planned.
+        """
+        return hull_area(self.points)
+
+    def subset(self, point_indices: Sequence[int]) -> Sample:
+        """The observations at the given rows of :attr:`points`."""
+        keep = self.points[list(point_indices)]
+        mask = pd.MultiIndex.from_frame(self.data[["lon", "lat"]]).isin([tuple(p) for p in keep])
+        return Sample(self.data.loc[mask].reset_index(drop=True))
+
+    def __repr__(self) -> str:
+        return (
+            f"Sample(n_observations={self.n_observations}, n_points={self.n_points}, "
+            f"n_species={self.n_species}, area={self.area:.6g})"
+        )
+
+
+def hull_area(points: np.ndarray) -> float:
+    """Convex hull area of an (n, 2) array of (lon, lat) points, in square degrees."""
+    pts = np.asarray(points, dtype=float)
+    if len(pts) < 3:
+        return 0.0
+    return float(MultiPoint([tuple(p) for p in pts]).convex_hull.area)

nestsar-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: nestsar
+Version: 0.1.0
+Summary: Nested species-area relationship datasets from point observations
+Project-URL: Homepage, https://github.com/jmcmeen/nestsar
+Project-URL: Source, https://github.com/jmcmeen/nestsar
+Project-URL: Changelog, https://github.com/jmcmeen/nestsar/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/jmcmeen/nestsar/issues
+Author-email: John McMeen <johnmcmeen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Requires-Dist: sars>=0.7.10
+Requires-Dist: shapely>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff<0.18,>=0.17; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nestsar
+
+Nested species-area relationship datasets from point observations. Build a
+sequence of nested sub-samples from georeferenced species records and hand
+the resulting area and richness table to [sars](https://pypi.org/project/sars/)
+for curve fitting.
+
+```python
+import nestsar, sars
+
+sample = nestsar.Sample.from_csv("observations.csv")   # species, lon, lat
+nest = nestsar.random_nest(sample, seed=0)
+fit = sars.sar_power(nest.sar_data())
+```
+
+## Development
+
+```sh
+make install   # create .venv with dev tooling
+make check     # lint, format check, tests
+```

nestsar-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+nestsar/__init__.py,sha256=YpLZl-RjXYa4cTtPEqZX-LyKhcj_sKhhhta_hp-U6Zo,446
+nestsar/_nest.py,sha256=WJSCrkA5IBhWyCCt_gybdgZipOwonsubFzdCNqUDVH8,2499
+nestsar/_sample.py,sha256=1Twwsy0UyY2CKxxrz3ENkp8C1JfkaPeFifkx1gyqewE,4068
+nestsar-0.1.0.dist-info/METADATA,sha256=6NAA5QD9JwJTLc9zjqBm_5QRKY_sWbl8KxRmqRl_inM,1820
+nestsar-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+nestsar-0.1.0.dist-info/licenses/LICENSE,sha256=qzmCAeakObqZTPFNxWt_xwcfdG7J_3DWvuq_M9UnjFI,1068
+nestsar-0.1.0.dist-info/RECORD,,

nestsar-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

nestsar-0.1.0.dist-info/licenses/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.