pkft 0.1.0a1__py3-none-any.whl

pkft/__init__.py

@@ -0,0 +1,3 @@
+"""pkft: Gaussian mixture peak finding for 1D data with uncertainties, served over FastAPI."""
+
+__version__ = "1.0.0"

pkft/api.py

@@ -0,0 +1,114 @@
+"""FastAPI tier. Browsers and agents read the same endpoints."""
+
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, PlainTextResponse
+from fastapi.staticfiles import StaticFiles
+
+from pkft import curves as curve_lib
+from pkft import mixture as mix
+from pkft.models import BicEntry, FitRequest, FitResponse, Peak, PeakCurve
+
+app = FastAPI(title="pkft", version="1.0.0")
+app.mount("/static", StaticFiles(directory=Path(__file__).parent / "static"), name="static")
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.get("/demo")
+def demo() -> FileResponse:
+    path = Path(__file__).parent / "data" / "demo-trayler-2020.csv"
+    return FileResponse(path, media_type="text/csv", filename="demo-trayler-2020.csv")
+
+
+def _fit_response(request: FitRequest) -> FitResponse:
+    values = [o.value for o in request.observations]
+    # Input errors reach the fit in one-sigma units.
+    errors = [o.standard_error / request.input_sigma for o in request.observations]
+    try:
+        result = mix.fit_mixture(values, errors, peak_count=request.peak_count)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    z = mix.Z_VALUES[request.confidence]
+    peaks: list[Peak] = []
+    curve_objs: list[PeakCurve] = []
+    for i, (mean, standard_error, proportion, proportion_error) in enumerate(
+        zip(result["means"], result["mean_standard_errors"], result["proportions"], result["proportion_standard_errors"]),
+        start=1,
+    ):
+        uncertainty = float(z * float(standard_error))
+        legend = (
+            f"{i},{mix.format_significant_digits(float(mean), request.significant_digits)},"
+            f"{mix.format_significant_digits(uncertainty, request.significant_digits)}"
+        )
+        peaks.append(
+            Peak(
+                peak=i,
+                value=float(mean),
+                standard_error=float(standard_error),
+                uncertainty=uncertainty,
+                proportion=float(proportion),
+                proportion_standard_error=float(proportion_error),
+                legend=legend,
+            )
+        )
+        grid, curve = curve_lib.peak_curve(float(mean), max(float(standard_error), 1e-12), float(proportion), request.sigma_range)
+        curve_objs.append(PeakCurve(peak=i, x_values=[float(v) for v in grid], y_values=[float(v) for v in curve]))
+
+    table = (
+        [BicEntry(peak_count=r["peak_count"], bic=r["bic"], log_likelihood=r["log_likelihood"]) for r in result["bic_table"]]
+        if result["bic_table"] is not None
+        else None
+    )
+    return FitResponse(
+        peak_count=result["peak_count"],
+        bic=result["bic"],
+        log_likelihood=result["log_likelihood"],
+        confidence=request.confidence,
+        method=result["method"],
+        peaks=peaks,
+        curves=curve_objs,
+        bic_table=table,
+    )
+
+
+@app.post("/fit", response_model=FitResponse)
+def fit(request: FitRequest) -> FitResponse:
+    return _fit_response(request)
+
+
+@app.post("/validate", response_model=FitRequest)
+def validate(request: FitRequest) -> FitRequest:
+    return request
+
+
+@app.get("/peaks.csv")
+def peaks_csv_placeholder() -> PlainTextResponse:
+    # Real CSV download is client-side from the last /fit response;
+    # this route exists so a stale bookmark explains itself.
+    return PlainTextResponse("Run POST /fit first; the UI offers Download Peaks (csv).\n", media_type="text/plain")
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(Path(__file__).parent / "static" / "index.html")
+
+
+@app.get("/mixture")
+def mixture_page() -> FileResponse:
+    return FileResponse(Path(__file__).parent / "static" / "index.html")
+
+
+def main() -> None:
+    import uvicorn
+
+    uvicorn.run("pkft.api:app", host="127.0.0.1", port=8000, reload=True)
+
+
+if __name__ == "__main__":
+    main()

pkft/curves.py

@@ -0,0 +1,56 @@
+"""Density-curve helpers mirroring the R ``p.data`` / ``p.pks`` overlays.
+
+All curves are plain Gaussians evaluated in numpy so the FastAPI tier and the
+vanilla-JS frontend (which reimplements ``normal_pdf`` in JS) agree. Counts
+follow the R convention: per-observation PDFs are divided by ``n`` so the
+summed PDF integrates to ~1.
+"""
+
+import math
+
+import numpy as np
+
+
+def normal_pdf(x: np.ndarray, mean: float, standard_deviation: float) -> np.ndarray:
+    x = np.asarray(x, dtype=float)
+    if standard_deviation <= 0:
+        raise ValueError("standard deviation must be > 0")
+    return np.exp(-0.5 * ((x - mean) / standard_deviation) ** 2) / (standard_deviation * math.sqrt(2.0 * math.pi))
+
+
+def grid_for(values: np.ndarray, errors: np.ndarray, sigma_range: float, n: int = 400) -> np.ndarray:
+    lo = float(np.min(values) - sigma_range * np.mean(errors))
+    hi = float(np.max(values) + sigma_range * np.mean(errors))
+    if not math.isfinite(lo) or not math.isfinite(hi) or lo == hi:
+        lo, hi = float(np.min(values)) - 1.0, float(np.max(values)) + 1.0
+    return np.linspace(lo, hi, n)
+
+
+def sumpdf(x: np.ndarray, values: np.ndarray, errors: np.ndarray) -> np.ndarray:
+    """Mean of per-observation Gaussians (R ``d.s`` / ``sumd``)."""
+    x = np.asarray(x, dtype=float)
+    total = np.zeros_like(x, dtype=float)
+    for v, e in zip(values, errors):
+        total += normal_pdf(x, float(v), float(e))
+    return total / max(len(values), 1)
+
+
+def normal_curve(x: np.ndarray, values: np.ndarray, errors: np.ndarray) -> np.ndarray:
+    """Single Gaussian at the sample mean/sd (R ``d.n`` overlay)."""
+    if len(values) < 2:
+        return np.zeros_like(np.asarray(x, dtype=float))
+    m = float(np.mean(values))
+    sd = float(np.std(values, ddof=1))
+    if sd <= 0:
+        return np.zeros_like(np.asarray(x, dtype=float))
+    return normal_pdf(x, m, sd)
+
+
+def peak_curve(mean: float, standard_error: float, proportion: float, sigma_range: float) -> tuple[np.ndarray, np.ndarray]:
+    """Weighted component curve over :math:`\\mu \\pm \\mathrm{sigrange} \\cdot \\mathrm{se}` (R ``d.norm``)."""
+    step = max(standard_error / 10.0, 1e-12)
+    lo, hi = mean - sigma_range * standard_error, mean + sigma_range * standard_error
+    if lo == hi:
+        lo, hi = mean - 1.0, mean + 1.0
+    x = np.arange(lo, hi + step / 2.0, step)
+    return x, normal_pdf(x, mean, max(standard_error, 1e-12)) * proportion

pkft/data/demo-trayler-2020.csv

@@ -0,0 +1,49 @@
+sample,value,standard_error
+CV-13,17.634,0.016
+CV-13,17.629,0.025
+CV-13,17.603,0.029
+CV-13,17.599,0.019
+CV-13,17.592,0.020
+1CO,17.119,0.113
+1CO,17.119,0.113
+1CO,17.180,0.133
+1CO,17.240,0.103
+1CO,17.351,0.104
+1CO,17.401,0.123
+1CO,17.431,0.113
+1CO,17.492,0.123
+1CO,17.613,0.133
+KARG-15-08,17.118,0.155
+KARG-15-08,17.040,0.022
+KARG-15-08,17.032,0.039
+KARG-15-08,17.024,0.224
+KARG-15-08,17.020,0.015
+KARG-15-08,17.009,0.031
+KARG-15-08,16.989,0.089
+KARG-15-08,16.972,0.099
+KARG-15-08,16.969,0.041
+KARG-15-08,16.942,0.041
+KARG-15-08,16.929,0.041
+KARG-15-08,16.922,0.087
+KARG-15-09,17.028,0.032
+KARG-15-09,16.997,0.023
+KARG-15-01,16.854,0.012
+KARG-15-01,16.850,0.014
+KARG-15-01,16.849,0.016
+KARG-15-01,16.846,0.021
+KARG-15-01,16.836,0.015
+Toba-Blanca,16.883,0.018
+Toba-Blanca,16.859,0.038
+Toba-Blanca,16.823,0.030
+CV-10,16.877,0.029
+CV-10,16.833,0.025
+CV-10,16.760,0.034
+CV-10,16.751,0.057
+1CO3,16.397,0.088
+1CO3,16.468,0.098
+1CO3,16.601,0.086
+1CO3,16.644,0.081
+1CO3,16.656,0.083
+1CO3,16.667,0.113
+1CO3,16.678,0.079
+1CO3,16.685,0.082

pkft/mixture.py

@@ -0,0 +1,194 @@
+"""Uncertainty-aware discrete mixture (Galbraith & Laslett 1993, IsoplotR ``peakfit`` spirit).
+
+Each observation :math:`x_i` carries a known analytical variance :math:`s_i^2`.
+Component :math:`j` is a discrete age :math:`\\mu_j` with mixing proportion :math:`\\pi_j`;
+the log-likelihood is :math:`\\ell = \\sum_i \\log \\sum_j \\pi_j \\, N(x_i \\mid \\mu_j, s_i^2)`.
+There is no per-component overdispersion term, so -- unlike a standard GMM --
+the model cannot collapse to zero variance and needs only numpy.
+
+``peak_count=0`` means automatic selection over 1..min(5, n) by BIC with
+:math:`p = 2k - 1` free parameters (:math:`k` means + :math:`k-1` proportions), matching the
+IsoplotR ``k='auto'`` convention (maximum 5). Results are not bit-identical
+to IsoplotR (different optimiser/initialisation) but maximise the same
+likelihood.
+"""
+
+import math
+
+import numpy as np
+
+Z_VALUES = {
+    "90%": 1.6448536269514729,
+    "95%": 1.959963984540054,
+    "98%": 2.32634787404084,
+    "99%": 2.5758293035489004,
+}
+
+AUTO_PEAK_MAX = 5
+PEAK_HARD_MAX = 25
+N_INIT = 10
+MAX_ITER = 500
+TOL = 1e-8
+
+
+def _norm_pdf(x: np.ndarray, mean: float, variance: np.ndarray) -> np.ndarray:
+    return np.exp(-0.5 * ((x - mean) ** 2) / variance) / np.sqrt(2.0 * math.pi * variance)
+
+
+def _fit_fixed_count(
+    values: np.ndarray,
+    errors: np.ndarray,
+    peak_count: int,
+    seed: int = 0,
+    n_init: int = N_INIT,
+) -> dict:
+    count = values.shape[0]
+    if peak_count < 1:
+        raise ValueError("peak_count must be >= 1")
+    if peak_count > count:
+        raise ValueError(f"peak_count={peak_count} exceeds observation count n={count}")
+    if np.any(errors <= 0):
+        raise ValueError("all standard errors must be > 0")
+
+    variances = errors**2
+    rng = np.random.default_rng(seed)
+    sort_order = np.argsort(values)
+    sorted_values = values[sort_order]
+
+    best_log_likelihood = -math.inf
+    best: dict | None = None
+
+    for init in range(n_init):
+        if init == 0:
+            # Quantile spread: deterministic, reproducible start.
+            positions = np.linspace(0, count - 1, peak_count).round().astype(int)
+            means = sorted_values[positions].astype(float) + rng.normal(0, 1e-9, size=peak_count)
+        else:
+            choice = rng.choice(count, size=peak_count, replace=False)
+            means = values[choice].astype(float) + rng.normal(0, np.mean(errors) * 0.05, size=peak_count)
+        proportions = np.full(peak_count, 1.0 / peak_count)
+        previous_log_likelihood = -math.inf
+        responsibilities = np.full((count, peak_count), 1.0 / peak_count)
+        for _ in range(MAX_ITER):
+            # E-step
+            component_likelihoods = np.empty((count, peak_count))
+            for j in range(peak_count):
+                component_likelihoods[:, j] = proportions[j] * _norm_pdf(values, means[j], variances)
+            row_totals = component_likelihoods.sum(axis=1, keepdims=True)
+            row_totals = np.maximum(row_totals, 1e-300)
+            responsibilities = component_likelihoods / row_totals
+            log_likelihood = float(np.sum(np.log(row_totals)))
+            # M-step
+            component_counts = responsibilities.sum(axis=0)  # (k,)
+            # Guard against empty components: reseed to a random point.
+            for j in range(peak_count):
+                if component_counts[j] < 1e-12:
+                    means[j] = float(rng.choice(values))
+                    component_counts[j] = 1e-12
+            proportions = component_counts / count
+            weights = responsibilities / variances[:, None]  # (n, k)
+            means = (weights * values[:, None]).sum(axis=0) / weights.sum(axis=0)
+            if abs(log_likelihood - previous_log_likelihood) < TOL * max(1.0, abs(log_likelihood)):
+                previous_log_likelihood = log_likelihood
+                break
+            previous_log_likelihood = log_likelihood
+        # Final likelihood at converged parameters.
+        component_likelihoods = np.empty((count, peak_count))
+        for j in range(peak_count):
+            component_likelihoods[:, j] = proportions[j] * _norm_pdf(values, means[j], variances)
+        log_likelihood = float(np.sum(np.log(np.maximum(component_likelihoods.sum(axis=1), 1e-300))))
+        if log_likelihood > best_log_likelihood:
+            best_log_likelihood = log_likelihood
+            best = {
+                "means": means.copy(),
+                "proportions": proportions.copy(),
+                "responsibilities": responsibilities.copy(),
+                "log_likelihood": log_likelihood,
+            }
+
+    assert best is not None
+    # Standard errors: means from weighted precision, proportions from multinomial.
+    weights = best["responsibilities"] / variances[:, None]
+    mean_standard_errors = 1.0 / np.sqrt(np.maximum(weights.sum(axis=0), 1e-300))
+    proportion_standard_errors = np.sqrt(np.maximum(best["proportions"] * (1.0 - best["proportions"]) / count, 0.0))
+    # Sort by ascending mean for stable peak numbering.
+    sort_order = np.argsort(best["means"])
+    return {
+        "means": best["means"][sort_order],
+        "proportions": best["proportions"][sort_order],
+        "mean_standard_errors": mean_standard_errors[sort_order],
+        "proportion_standard_errors": proportion_standard_errors[sort_order],
+        "log_likelihood": best["log_likelihood"],
+    }
+
+
+def bic(log_likelihood: float, peak_count: int, count: int) -> float:
+    """Bayes information criterion; :math:`p = 2k - 1` free parameters."""
+    params = 2 * peak_count - 1
+    return -2.0 * log_likelihood + params * math.log(count)
+
+
+def fit_mixture(
+    values: list[float] | np.ndarray,
+    errors: list[float] | np.ndarray,
+    peak_count: int = 0,
+    seed: int = 0,
+) -> dict:
+    """Fit 1..k discrete components. ``peak_count=0`` auto-selects by BIC over 1..min(5, n)."""
+    values_array = np.asarray(values, dtype=float)
+    error_array = np.asarray(errors, dtype=float)
+    count = values_array.shape[0]
+    if count == 0:
+        raise ValueError("no observations")
+    if np.any(~np.isfinite(values_array)) or np.any(~np.isfinite(error_array)):
+        raise ValueError("values and errors must be finite")
+    if np.any(error_array <= 0):
+        raise ValueError("all standard errors must be > 0")
+    if peak_count < 0 or peak_count > PEAK_HARD_MAX:
+        raise ValueError(f"peak_count must be in 0..{PEAK_HARD_MAX}")
+    if peak_count > count:
+        raise ValueError(f"peak_count={peak_count} exceeds observation count n={count}")
+
+    if peak_count == 0:
+        candidates = list(range(1, min(AUTO_PEAK_MAX, count) + 1))
+        table = []
+        fits = {}
+        for candidate in candidates:
+            fit = _fit_fixed_count(values_array, error_array, candidate, seed=seed)
+            score = bic(fit["log_likelihood"], candidate, count)
+            table.append({"peak_count": candidate, "bic": score, "log_likelihood": fit["log_likelihood"]})
+            fits[candidate] = fit
+        best_count = min(table, key=lambda r: r["bic"])["peak_count"]
+        out = fits[best_count]
+        return {
+            "peak_count": best_count,
+            "bic": next(r["bic"] for r in table if r["peak_count"] == best_count),
+            "log_likelihood": out["log_likelihood"],
+            "means": out["means"],
+            "proportions": out["proportions"],
+            "mean_standard_errors": out["mean_standard_errors"],
+            "proportion_standard_errors": out["proportion_standard_errors"],
+            "bic_table": table,
+            "method": "discrete-mixture-em(auto-bic)",
+        }
+    fit = _fit_fixed_count(values_array, error_array, peak_count, seed=seed)
+    return {
+        "peak_count": peak_count,
+        "bic": bic(fit["log_likelihood"], peak_count, count),
+        "log_likelihood": fit["log_likelihood"],
+        "means": fit["means"],
+        "proportions": fit["proportions"],
+        "mean_standard_errors": fit["mean_standard_errors"],
+        "proportion_standard_errors": fit["proportion_standard_errors"],
+        "bic_table": None,
+        "method": "discrete-mixture-em",
+    }
+
+
+def format_significant_digits(value: float, significant_digits: int) -> str:
+    """Format to ``significant_digits`` significant digits (R ``sigdig`` convention)."""
+    if not math.isfinite(value):
+        return str(value)
+    if value == 0:
+        return "0"
+    return f"{value:.{significant_digits}g}"

pkft/models.py

@@ -0,0 +1,62 @@
+"""Pydantic models for peak-fit requests and responses."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+ConfidenceLevel = Literal["90%", "95%", "98%", "99%"]
+
+
+class Observation(BaseModel):
+    sample: str | None = None
+    value: float = Field(description="Measured value in the data's own units")
+    standard_error: float = Field(gt=0, description="Analytical standard error (one sigma) in the same units as value")
+
+
+class FitRequest(BaseModel):
+    observations: list[Observation] = Field(min_length=1)
+    peak_count: int = Field(default=0, ge=0, le=25, description="Number of peaks; 0 asks for automatic selection by BIC (compares 1..5 peaks)")
+    significant_digits: int = Field(default=2, ge=1, le=6)
+    confidence: ConfidenceLevel = "95%"
+    input_sigma: int = Field(
+        default=1,
+        ge=1,
+        le=3,
+        description="Sigma level the input errors are quoted at (1, 2, or 3); each error is divided by this to reach one-sigma errors",
+    )
+    sigma_range: float = Field(default=3.0, ge=0.5, le=10.0, description="Half-width of returned peak curves in standard errors")
+
+
+class Peak(BaseModel):
+    peak: int
+    value: float
+    standard_error: float = Field(description="One-sigma standard error of the peak value")
+    uncertainty: float = Field(
+        description="Half-width of the confidence interval at the requested confidence level (z times the one-sigma standard error)"
+    )
+    proportion: float = Field(ge=0, le=1)
+    proportion_standard_error: float = Field(ge=0)
+    legend: str = Field(description="CSV line 'peak,value,uncertainty' rounded to significant digits")
+
+
+class PeakCurve(BaseModel):
+    peak: int
+    x_values: list[float]
+    y_values: list[float]
+
+
+class BicEntry(BaseModel):
+    peak_count: int
+    bic: float
+    log_likelihood: float
+
+
+class FitResponse(BaseModel):
+    peak_count: int
+    bic: float
+    log_likelihood: float
+    confidence: ConfidenceLevel
+    method: str
+    peaks: list[Peak]
+    curves: list[PeakCurve]
+    bic_table: list[BicEntry] | None = None