findakin 0.1.0__py3-none-any.whl

findakin/__init__.py

@@ -0,0 +1,19 @@
+"""Findakin — find a kin for every spectrum.
+
+spectro-kernel answers questions about *one* spectrum. Findakin answers questions about a
+*population* of spectra: which look alike, what structure they form, which stand out, which
+moved in time, and which representation (encoder) is the most physical.
+
+Everything lives in a local LanceDB store, versioned and rebuildable from your files.
+
+    from findakin import Store
+    st = Store.open("~/findakin/store")
+    st.ingest_folder("~/spectra/alphadra", source="staros")
+    enc = st.embed(strategy="dct", dim=256)
+    st.neighbours("~/spectra/new.fits", k=10, encoder=enc)
+"""
+
+from findakin.store import IngestReport, Store
+
+__version__ = "0.1.0"
+__all__ = ["Store", "IngestReport", "__version__"]

findakin/align.py

@@ -0,0 +1,292 @@
+"""Inter-instrument wavelength (λ) alignment — the project's common-grid layer.
+
+Why this module exists
+----------------------
+Findakin compares spectra by embedding them into a shared vector space. But two
+spectrographs sample λ very differently: an Alpy600 (R~600) and a LHIRES III
+(R~10000) produce spectra with different pixel grids, different coverage, and
+*wildly* different resolution. Embedding each one "as is" mixes physical content
+with instrument signature — the resulting distances are not comparable.
+
+This module resamples every spectrum of a project onto a **single common λ grid**
+(same sampling, same coverage, homogenised resolution) *before* the embedding is
+computed, so that all embeddings in a project live in one comparable space, even
+across instruments.
+
+The pipeline (``align_to_grid``) does, in this exact order:
+
+1. **Resolution matching** (optional, degrade-only). You can only *lower* resolution,
+   never invent it. If a target FWHM is set and the native spectrum is sharper than
+   the target, the native flux is convolved by the Gaussian kernel that brings it down
+   to the target FWHM. If the native spectrum is already coarser (or a FWHM is missing),
+   nothing is convolved.
+2. **Resampling** onto the common grid by linear interpolation, with NaN outside the
+   native coverage.
+3. **Coverage** = fraction of grid points that fall inside the native wavelength range.
+
+Units
+-----
+Findakin's FITS parser yields wavelengths in **Angstrom** (``wavelength_angstrom``),
+while ``CommonGrid`` is expressed in **nanometres** (the brief's convention, and the
+natural unit for log-λ spectroscopy). ``align_to_grid`` therefore accepts a
+``wavelength_scale_to_nm`` factor: pass ``0.1`` to convert Å→nm (1 nm = 10 Å).
+The default is ``1.0`` (input already in nm). The caller is responsible for telling
+``align`` what unit its wavelength array is in — see ``app.core.embedding`` for the
+wiring (it passes ``0.1`` because findakin stores Angstrom).
+
+Resampling choice
+-----------------
+We use **linear interpolation** (``np.interp``). It is robust, fast, monotonic, and
+introduces no ringing. It is *not* strictly flux-conserving (an integrating resampler
+would be), but for embedding/similarity — where the flux is normalised downstream
+anyway — linear interpolation onto a fixed grid is the standard, well-behaved choice.
+This is documented here so the tradeoff is explicit.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Literal
+
+import numpy as np
+from pydantic import BaseModel, Field
+
+# FWHM = 2*sqrt(2*ln2) * sigma  ≈ 2.3548 * sigma  (Gaussian).
+_FWHM_TO_SIGMA = 2.0 * np.sqrt(2.0 * np.log(2.0))  # ≈ 2.3548
+
+
+class CommonGrid(BaseModel):
+    """A project-wide common wavelength grid (in nanometres).
+
+    Two spectra aligned to the *same* ``CommonGrid`` share the same output axis,
+    coverage window, and (when ``target_fwhm_nm`` is set) resolution ceiling — which
+    is exactly what makes their embeddings comparable across instruments.
+
+    Attributes
+    ----------
+    lambda_min_nm, lambda_max_nm:
+        Grid bounds in nm.
+    n_points:
+        Number of grid samples.
+    spacing:
+        ``"log"`` (geometric, recommended in spectroscopy: constant Δλ/λ ⇔ constant
+        velocity step) or ``"linear"``.
+    target_fwhm_nm:
+        Optional resolution ceiling. If set, spectra sharper than this are degraded to
+        it before resampling; spectra already coarser are left untouched.
+    """
+
+    lambda_min_nm: float = Field(..., gt=0)
+    lambda_max_nm: float = Field(..., gt=0)
+    n_points: int = Field(..., gt=1)
+    spacing: Literal["linear", "log"] = "log"
+    target_fwhm_nm: float | None = Field(default=None, gt=0)
+
+    def hash(self) -> str:
+        """Short stable fingerprint of the grid, for the embedding signature.
+
+        Identical grids → identical hash; any change to bounds / n_points / spacing /
+        target FWHM changes it. Used so that two projects with *different* common grids
+        get different embedding signatures and are therefore refused for comparison."""
+        payload = (
+            f"{self.lambda_min_nm:.6g}:{self.lambda_max_nm:.6g}:"
+            f"{self.n_points}:{self.spacing}:"
+            f"{'' if self.target_fwhm_nm is None else format(self.target_fwhm_nm, '.6g')}"
+        )
+        return hashlib.sha256(payload.encode()).hexdigest()[:12]
+
+
+class AlignResult(BaseModel):
+    """Outcome of aligning one spectrum onto a :class:`CommonGrid`.
+
+    Attributes
+    ----------
+    flux:
+        Flux resampled onto the grid (same length as ``build_grid(grid)``). Points
+        outside the native coverage are ``NaN``.
+    coverage:
+        Fraction of grid points that fall inside the native wavelength range
+        (1.0 = the spectrum spans the whole grid).
+    resolution_matched:
+        ``True`` iff a Gaussian degradation to the target FWHM was actually applied.
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    flux: np.ndarray
+    coverage: float
+    resolution_matched: bool
+
+
+def build_grid(grid: CommonGrid) -> np.ndarray:
+    """Return the common wavelength axis (nm) for ``grid``.
+
+    ``linear`` → :func:`numpy.linspace`; ``log`` → :func:`numpy.geomspace`
+    (log-λ, recommended in spectroscopy)."""
+    if grid.spacing == "log":
+        return np.geomspace(grid.lambda_min_nm, grid.lambda_max_nm, grid.n_points)
+    return np.linspace(grid.lambda_min_nm, grid.lambda_max_nm, grid.n_points)
+
+
+def _gaussian_smooth(flux: np.ndarray, sigma_px: float) -> np.ndarray:
+    """Convolve ``flux`` by a Gaussian of width ``sigma_px`` pixels.
+
+    Uses ``scipy.ndimage.gaussian_filter1d`` when scipy is available; otherwise falls
+    back to a normalised numpy kernel (``np.convolve`` with edge padding) so the module
+    has no hard scipy dependency."""
+    if sigma_px <= 0:
+        return flux
+    try:
+        from scipy.ndimage import gaussian_filter1d
+
+        return gaussian_filter1d(flux, sigma=sigma_px, mode="nearest")
+    except Exception:  # pragma: no cover - exercised only without scipy
+        # Truncate the kernel at 4 sigma (matches scipy's default truncate=4.0).
+        radius = max(1, int(round(4.0 * sigma_px)))
+        x = np.arange(-radius, radius + 1, dtype=float)
+        kernel = np.exp(-0.5 * (x / sigma_px) ** 2)
+        kernel /= kernel.sum()
+        # Reflect-pad ("nearest"-like) to avoid edge darkening.
+        padded = np.pad(flux, radius, mode="edge")
+        return np.convolve(padded, kernel, mode="valid")
+
+
+def align_to_grid(
+    wavelength: np.ndarray,
+    flux: np.ndarray,
+    grid: CommonGrid,
+    *,
+    native_fwhm_nm: float | None = None,
+    wavelength_scale_to_nm: float = 1.0,
+) -> AlignResult:
+    """Align one spectrum onto the project common grid.
+
+    Parameters
+    ----------
+    wavelength, flux:
+        Native spectrum. ``wavelength`` may be decreasing (it is sorted internally) and
+        is interpreted in nm after multiplying by ``wavelength_scale_to_nm`` (pass
+        ``0.1`` for Angstrom input).
+    grid:
+        Target :class:`CommonGrid`.
+    native_fwhm_nm:
+        Native spectral resolution as a FWHM in nm. Only used for resolution matching;
+        if ``None``, the resolution step is skipped.
+    wavelength_scale_to_nm:
+        Multiplicative factor converting the input wavelength unit to nm
+        (1.0 = already nm; 0.1 = Angstrom→nm).
+
+    Returns
+    -------
+    AlignResult
+    """
+    wl = np.asarray(wavelength, dtype=float).ravel() * float(wavelength_scale_to_nm)
+    fl = np.asarray(flux, dtype=float).ravel()
+
+    target_axis = build_grid(grid)
+
+    # Degenerate inputs: nothing usable → all-NaN flux, zero coverage.
+    n = min(wl.size, fl.size)
+    if n == 0:
+        return AlignResult(
+            flux=np.full(grid.n_points, np.nan), coverage=0.0, resolution_matched=False
+        )
+    wl, fl = wl[:n], fl[:n]
+
+    finite = np.isfinite(wl) & np.isfinite(fl)
+    if not finite.any():
+        # All-NaN flux (or wavelength): return an all-NaN grid, no coverage.
+        return AlignResult(
+            flux=np.full(grid.n_points, np.nan), coverage=0.0, resolution_matched=False
+        )
+    wl, fl = wl[finite], fl[finite]
+
+    # Wavelengths may be decreasing (e.g. some echelle/IRAF products) — sort ascending.
+    order = np.argsort(wl)
+    wl, fl = wl[order], fl[order]
+
+    # --- Step 1: resolution matching (degrade-only) ---------------------------------
+    resolution_matched = False
+    if grid.target_fwhm_nm is not None and native_fwhm_nm is not None and wl.size >= 2:
+        # We can only DEGRADE: convolve only if the native spectrum is *sharper*
+        # (smaller FWHM) than the target. Upgrading resolution is impossible.
+        if native_fwhm_nm < grid.target_fwhm_nm:
+            # FWHM add in quadrature: the kernel that takes native→target has
+            # FWHM_kernel = sqrt(target^2 - native^2); convert to sigma in nm, then px.
+            sigma_nm = np.sqrt(grid.target_fwhm_nm**2 - native_fwhm_nm**2) / _FWHM_TO_SIGMA
+            d_lambda = float(np.median(np.diff(wl)))  # native median pixel step (nm)
+            if d_lambda > 0 and sigma_nm > 0:
+                sigma_px = sigma_nm / d_lambda
+                fl = _gaussian_smooth(fl, sigma_px)
+                resolution_matched = True
+        # else: native is already coarser/equal → cannot upgrade → leave flux untouched.
+
+    # --- Step 2: resample onto the common grid (linear interp, NaN outside) ---------
+    # np.interp needs strictly increasing x; collapse exact duplicate wavelengths.
+    if wl.size >= 2:
+        uniq = np.concatenate(([True], np.diff(wl) > 0))
+        if not uniq.all():
+            wl, fl = wl[uniq], fl[uniq]
+
+    resampled = np.interp(target_axis, wl, fl, left=np.nan, right=np.nan)
+
+    # --- Step 3: coverage = fraction of grid points inside the native range ---------
+    native_lo, native_hi = float(wl.min()), float(wl.max())
+    in_cov = (target_axis >= native_lo) & (target_axis <= native_hi)
+    coverage = float(np.count_nonzero(in_cov) / target_axis.size)
+
+    return AlignResult(flux=resampled, coverage=coverage, resolution_matched=resolution_matched)
+
+
+def suggest_grid(
+    spectra: list[tuple[np.ndarray, np.ndarray]],
+    *,
+    spacing: Literal["linear", "log"] = "log",
+    wavelength_scale_to_nm: float = 1.0,
+    native_fwhm_nm: list[float | None] | None = None,
+) -> CommonGrid:
+    """Propose a :class:`CommonGrid` from a sample of spectra.
+
+    Heuristic (per the brief):
+    - bounds = **intersection** of native coverages (so every spectrum spans the grid);
+      falls back to the union if the intersection is empty.
+    - ``n_points`` = median native point count.
+    - ``target_fwhm_nm`` = median native FWHM (if provided).
+
+    ``spectra`` is a list of ``(wavelength, flux)`` arrays in the same unit as
+    ``wavelength_scale_to_nm`` describes.
+    """
+    if not spectra:
+        raise ValueError("suggest_grid needs at least one spectrum")
+
+    mins, maxs, counts = [], [], []
+    for wl, _fl in spectra:
+        w = np.asarray(wl, dtype=float).ravel() * float(wavelength_scale_to_nm)
+        w = w[np.isfinite(w)]
+        if w.size == 0:
+            continue
+        mins.append(float(w.min()))
+        maxs.append(float(w.max()))
+        counts.append(int(w.size))
+
+    if not counts:
+        raise ValueError("suggest_grid: no spectrum had a usable wavelength axis")
+
+    lo_int, hi_int = max(mins), min(maxs)  # intersection
+    if hi_int <= lo_int:  # no common overlap → fall back to the union
+        lo_int, hi_int = min(mins), max(maxs)
+
+    n_points = int(np.median(counts))
+    target_fwhm = None
+    if native_fwhm_nm:
+        valid = [f for f in native_fwhm_nm if f is not None and f > 0]
+        if valid:
+            target_fwhm = float(np.median(valid))
+
+    return CommonGrid(
+        lambda_min_nm=lo_int,
+        lambda_max_nm=hi_int,
+        n_points=max(2, n_points),
+        spacing=spacing,
+        target_fwhm_nm=target_fwhm,
+    )

findakin/analysis/__init__.py

@@ -0,0 +1,37 @@
+"""Collection-level analysis over embedding vectors.
+
+Pure functions operating on a 2D array of embeddings ``X`` (as returned by
+``Store.vectors``), no persistent state:
+
+- Clustering        : K-Means / HDBSCAN / GMM, with optimal-k search
+- Anomaly detection : Isolation Forest / LOF / distance-based
+- Projection        : PCA / t-SNE / UMAP for 2D-3D visualisation
+
+Originally ported from the ``embspec`` prototype. Plotting helpers are not part of
+this package (phase 2 adds Plotly notebook helpers on top of these results).
+"""
+
+from .anomaly import AnomalyResult, detect_anomalies
+from .clustering import (
+    ClusteringResult,
+    OptimalKResult,
+    cluster_embeddings,
+    find_optimal_k,
+)
+from .projection import (
+    ProjectionResult,
+    extract_color_values,
+    project_embeddings,
+)
+
+__all__ = [
+    "AnomalyResult",
+    "detect_anomalies",
+    "ClusteringResult",
+    "OptimalKResult",
+    "cluster_embeddings",
+    "find_optimal_k",
+    "ProjectionResult",
+    "extract_color_values",
+    "project_embeddings",
+]