quantized-lab 0.8.0__py3-none-any.whl

quantized/routes/spectral.py

@@ -0,0 +1,54 @@
+"""Thin FFT spectral route. Wraps ``calc.spectral.fft_spectral`` for the ROI
+gadget family's FFT mode (gap #34): a single-record magnitude/PSD/phase
+spectrum of one region's rows. The "complex" output type never crosses the
+wire (numpy complex isn't JSON-serializable — see CLAUDE.md's jsonencode
+notes); only magnitude/psd/phase are exposed here. Validate -> call ->
+serialize; no business logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.spectral import fft_spectral
+from quantized.routes._payload import to_jsonable
+
+router = APIRouter(prefix="/api/spectral", tags=["spectral"])
+
+# "complex" is deliberately excluded (see module docstring).
+_OUTPUT_TYPES = ("psd", "magnitude", "phase")
+
+
+class FftRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    window: str = "hanning"
+    output_type: str = "magnitude"
+    sided: str = "one"
+    detrend: str = "mean"
+
+
+@router.post("/fft")
+def fft(req: FftRequest) -> dict[str, Any]:
+    """Single-record FFT spectrum (magnitude/psd/phase) of (x, y)."""
+    if req.output_type not in _OUTPUT_TYPES:
+        raise HTTPException(status_code=422, detail=f"unsupported output_type: {req.output_type}")
+    try:
+        result = fft_spectral(
+            np.asarray(req.x, dtype=float),
+            np.asarray(req.y, dtype=float),
+            window=req.window,
+            output_type=req.output_type,
+            sided=req.sided,
+            detrend=req.detrend,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    # Drop the window-function array: same length as the input, internal detail
+    # the caller never plots (keeps the response small).
+    out = {k: v for k, v in result.items() if k != "window"}
+    return to_jsonable(out)  # type: ignore[no-any-return]

quantized/routes/statplots.py

@@ -0,0 +1,99 @@
+"""Thin routes for statistical-plot primitives (ORIGIN_GAP_PLAN #16).
+
+All math lives in ``quantized.calc.statplots``; these adapters only validate,
+call, and serialize. The same payloads feed the interactive stage and the
+matplotlib export path.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.statplots import (
+    grouped_box_stats,
+    histogram,
+    qq_plot,
+    violin_kde,
+)
+from quantized.routes._payload import to_jsonable
+
+router = APIRouter(prefix="/api/statplots", tags=["statplots"])
+
+
+def _wrap(result: dict[str, Any]) -> dict[str, Any]:
+    return to_jsonable(result)  # type: ignore[no-any-return]
+
+
+class BoxRequest(BaseModel):
+    groups: list[list[float]]
+    labels: list[str] | None = None
+    whis: float | str = 1.5
+
+
+@router.post("/box")
+def box_route(req: BoxRequest) -> dict[str, Any]:
+    """Box/whisker stats for one or more groups (matplotlib-compatible)."""
+    try:
+        return _wrap(grouped_box_stats(req.groups, labels=req.labels, whis=req.whis))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class ViolinRequest(BaseModel):
+    data: list[float]
+    bw_method: str | float = "scott"
+    n_points: int = 128
+    cut: float = 2.0
+
+
+@router.post("/violin")
+def violin_route(req: ViolinRequest) -> dict[str, Any]:
+    """Gaussian-KDE density for a violin plot."""
+    try:
+        return _wrap(
+            violin_kde(
+                np.asarray(req.data, dtype=float),
+                bw_method=req.bw_method, n_points=req.n_points, cut=req.cut,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class QQRequest(BaseModel):
+    data: list[float]
+    dist: str = "norm"
+
+
+@router.post("/qq")
+def qq_route(req: QQRequest) -> dict[str, Any]:
+    """Quantile-quantile / probability-plot coordinates against a distribution."""
+    try:
+        return _wrap(qq_plot(np.asarray(req.data, dtype=float), dist=req.dist))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class HistogramRequest(BaseModel):
+    data: list[float]
+    bins: str | int = "fd"
+    density: bool = False
+    fit: str | None = None
+
+
+@router.post("/histogram")
+def histogram_route(req: HistogramRequest) -> dict[str, Any]:
+    """Histogram with a data-driven bin rule and an optional fit overlay."""
+    try:
+        return _wrap(
+            histogram(
+                np.asarray(req.data, dtype=float),
+                bins=req.bins, density=req.density, fit=req.fit,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc

quantized/routes/stats.py

@@ -0,0 +1,418 @@
+"""Thin statistics routes. Wraps ``calc.stats`` (no toolbox, golden vs MATLAB).
+
+Each handler validates, converts to ndarray, calls the pure function, and
+serializes the (array-bearing) result dict via ``to_jsonable``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.stats import (
+    anova1,
+    descriptive_stats,
+    lin_regress,
+    pca_analysis,
+    t_test,
+)
+from quantized.calc.stats_dist import (
+    fit_distribution,
+    fit_distributions,
+    required_n,
+    t_test_power,
+)
+from quantized.calc.stats_multivar import (
+    correlation_matrix,
+    multiple_regression,
+    partial_correlation,
+    stepwise_regression,
+)
+from quantized.calc.stats_tests import (
+    anderson_darling,
+    friedman,
+    kruskal_wallis,
+    ks_normal,
+    ks_two_sample,
+    levene,
+    mann_whitney,
+    shapiro_wilk,
+    sign_test,
+    wilcoxon_signed_rank,
+)
+from quantized.routes._payload import to_jsonable
+
+router = APIRouter(prefix="/api/stats", tags=["stats"])
+
+
+class DescriptiveRequest(BaseModel):
+    x: list[float]
+
+
+class RegressionRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    order: int = 1
+    alpha: float = 0.05
+
+
+class TTestRequest(BaseModel):
+    x: list[float]
+    y: list[float] | None = None
+    mu: float = 0.0
+    paired: bool = False
+    alpha: float = 0.05
+    tail: str = "both"
+
+
+class AnovaRequest(BaseModel):
+    groups: list[list[float]]
+    alpha: float = 0.05
+
+
+class PCARequest(BaseModel):
+    data: list[list[float]]
+    center: bool = True
+    scale: bool = False
+    num_components: int = 0
+
+
+class TwoSampleRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    alternative: str = "two-sided"
+
+
+class PairedOrOneSampleRequest(BaseModel):
+    x: list[float]
+    y: list[float] | None = None
+    mu: float = 0.0
+    alternative: str = "two-sided"
+
+
+class GroupsRequest(BaseModel):
+    groups: list[list[float]]
+
+
+class LeveneRequest(BaseModel):
+    groups: list[list[float]]
+    center: str = "median"
+
+
+class OneSampleRequest(BaseModel):
+    x: list[float]
+
+
+class KSNormalRequest(BaseModel):
+    x: list[float]
+    loc: float | None = None
+    scale: float | None = None
+
+
+class MultiRegressionRequest(BaseModel):
+    predictors: list[list[float]]  # k same-length columns
+    y: list[float]
+    alpha: float = 0.05
+
+
+class CorrelationRequest(BaseModel):
+    columns: list[list[float]]
+    method: str = "pearson"
+
+
+class PartialCorrelationRequest(BaseModel):
+    columns: list[list[float]]
+
+
+def _wrap(result: dict[str, Any]) -> dict[str, Any]:
+    return to_jsonable(result)  # type: ignore[no-any-return]
+
+
+@router.post("/descriptive")
+def descriptive(req: DescriptiveRequest) -> dict[str, Any]:
+    """Descriptive statistics of a 1-D array (NaNs dropped)."""
+    try:
+        return _wrap(descriptive_stats(np.asarray(req.x, dtype=float)))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/regression")
+def regression(req: RegressionRequest) -> dict[str, Any]:
+    """Polynomial least-squares regression with inference."""
+    try:
+        return _wrap(
+            lin_regress(
+                np.asarray(req.x, dtype=float),
+                np.asarray(req.y, dtype=float),
+                order=req.order,
+                alpha=req.alpha,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/ttest")
+def ttest(req: TTestRequest) -> dict[str, Any]:
+    """Student's t-test (one-sample / paired / Welch two-sample)."""
+    try:
+        y = np.asarray(req.y, dtype=float) if req.y is not None else None
+        return _wrap(
+            t_test(
+                np.asarray(req.x, dtype=float),
+                y,
+                mu=req.mu,
+                paired=req.paired,
+                alpha=req.alpha,
+                tail=req.tail,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/anova")
+def anova(req: AnovaRequest) -> dict[str, Any]:
+    """One-way ANOVA on a list of group vectors."""
+    try:
+        groups = [np.asarray(g, dtype=float) for g in req.groups]
+        return _wrap(anova1(groups, alpha=req.alpha))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/pca")
+def pca(req: PCARequest) -> dict[str, Any]:
+    """Principal component analysis via SVD."""
+    try:
+        return _wrap(
+            pca_analysis(
+                np.asarray(req.data, dtype=float),
+                center=req.center,
+                scale=req.scale,
+                num_components=req.num_components,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/mann-whitney")
+def mann_whitney_route(req: TwoSampleRequest) -> dict[str, Any]:
+    """Mann-Whitney U test (independent two-sample rank test)."""
+    try:
+        return _wrap(
+            mann_whitney(
+                np.asarray(req.x, dtype=float),
+                np.asarray(req.y, dtype=float),
+                alternative=req.alternative,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/wilcoxon")
+def wilcoxon_route(req: PairedOrOneSampleRequest) -> dict[str, Any]:
+    """Wilcoxon signed-rank test (paired, or one-sample vs mu)."""
+    try:
+        y = np.asarray(req.y, dtype=float) if req.y is not None else None
+        return _wrap(
+            wilcoxon_signed_rank(
+                np.asarray(req.x, dtype=float), y, mu=req.mu, alternative=req.alternative
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/kruskal")
+def kruskal_route(req: GroupsRequest) -> dict[str, Any]:
+    """Kruskal-Wallis H test on a list of group vectors."""
+    try:
+        return _wrap(kruskal_wallis([np.asarray(g, dtype=float) for g in req.groups]))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/friedman")
+def friedman_route(req: GroupsRequest) -> dict[str, Any]:
+    """Friedman test (k treatments x n blocks, equal lengths)."""
+    try:
+        return _wrap(friedman([np.asarray(g, dtype=float) for g in req.groups]))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/sign-test")
+def sign_test_route(req: PairedOrOneSampleRequest) -> dict[str, Any]:
+    """Sign test (paired, or one-sample vs mu) via exact binomial."""
+    try:
+        y = np.asarray(req.y, dtype=float) if req.y is not None else None
+        return _wrap(
+            sign_test(np.asarray(req.x, dtype=float), y, mu=req.mu, alternative=req.alternative)
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/shapiro")
+def shapiro_route(req: OneSampleRequest) -> dict[str, Any]:
+    """Shapiro-Wilk normality test."""
+    try:
+        return _wrap(shapiro_wilk(np.asarray(req.x, dtype=float)))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/anderson")
+def anderson_route(req: OneSampleRequest) -> dict[str, Any]:
+    """Anderson-Darling normality test (critical-value table, no p)."""
+    try:
+        return _wrap(anderson_darling(np.asarray(req.x, dtype=float)))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/levene")
+def levene_route(req: LeveneRequest) -> dict[str, Any]:
+    """Levene / Brown-Forsythe equal-variance test."""
+    try:
+        return _wrap(
+            levene([np.asarray(g, dtype=float) for g in req.groups], center=req.center)
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/ks-normal")
+def ks_normal_route(req: KSNormalRequest) -> dict[str, Any]:
+    """One-sample KS test vs a normal distribution."""
+    try:
+        return _wrap(ks_normal(np.asarray(req.x, dtype=float), loc=req.loc, scale=req.scale))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/regression-multi")
+def regression_multi(req: MultiRegressionRequest) -> dict[str, Any]:
+    """Multiple linear regression (intercept + k predictors) with inference."""
+    try:
+        return _wrap(
+            multiple_regression(
+                [np.asarray(c, dtype=float) for c in req.predictors],
+                np.asarray(req.y, dtype=float),
+                alpha=req.alpha,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/correlation")
+def correlation(req: CorrelationRequest) -> dict[str, Any]:
+    """Pairwise Pearson/Spearman correlation matrix with p-values."""
+    try:
+        return _wrap(
+            correlation_matrix(
+                [np.asarray(c, dtype=float) for c in req.columns], method=req.method
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/partial-correlation")
+def partial_correlation_route(req: PartialCorrelationRequest) -> dict[str, Any]:
+    """Partial correlation of every pair controlling for all other columns."""
+    try:
+        return _wrap(partial_correlation([np.asarray(c, dtype=float) for c in req.columns]))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/ks-two-sample")
+def ks_two_sample_route(req: TwoSampleRequest) -> dict[str, Any]:
+    """Two-sample KS test."""
+    try:
+        return _wrap(
+            ks_two_sample(
+                np.asarray(req.x, dtype=float),
+                np.asarray(req.y, dtype=float),
+                alternative=req.alternative,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class FitDistRequest(BaseModel):
+    x: list[float]
+    dist: str | None = None  # None = fit all families, rank by AIC
+
+
+@router.post("/fit-distribution")
+def fit_distribution_route(req: FitDistRequest) -> dict[str, Any]:
+    """MLE distribution fit(s) with KS GOF; dist=None ranks all families."""
+    try:
+        x = np.asarray(req.x, dtype=float)
+        if req.dist is None:
+            return _wrap(fit_distributions(x))
+        return _wrap(fit_distribution(x, req.dist))
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class PowerRequest(BaseModel):
+    effect_size: float
+    n: int | None = None  # given -> power; omitted -> solve for n
+    power: float = 0.8
+    kind: str = "two-sample"
+    alpha: float = 0.05
+    tails: int = 2
+
+
+@router.post("/power")
+def power_route(req: PowerRequest) -> dict[str, Any]:
+    """t-test power at n, or the required n for a target power (exact nct)."""
+    try:
+        if req.n is not None:
+            return _wrap(
+                t_test_power(
+                    req.effect_size, req.n, kind=req.kind, alpha=req.alpha, tails=req.tails
+                )
+            )
+        return _wrap(
+            required_n(
+                req.effect_size, req.power, kind=req.kind, alpha=req.alpha, tails=req.tails
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class StepwiseRequest(BaseModel):
+    predictors: list[list[float]]
+    y: list[float]
+    criterion: str = "aic"
+    direction: str = "forward"
+
+
+@router.post("/stepwise")
+def stepwise_route(req: StepwiseRequest) -> dict[str, Any]:
+    """Stepwise predictor selection (AIC/BIC) over multiple regression."""
+    try:
+        return _wrap(
+            stepwise_regression(
+                [np.asarray(c, dtype=float) for c in req.predictors],
+                np.asarray(req.y, dtype=float),
+                criterion=req.criterion,
+                direction=req.direction,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc