Findakin

Find a kin for every spectrum.

Findakin answers population questions about collections of astronomical spectra: which look alike, what structure they form, which stand out, which changed in time, and which representation (encoder) is the most physical. It is a local Python library built on spectro-kernel (one spectrum → one vector) and LanceDB (an embedded, versioned, columnar store with a vector index). No server, no account: your spectra stay on your disk.

Status: 0.2 alpha, API may still change. Findakin started as a hosted web application (FastAPI + MongoDB + Qdrant + React, retired in October 2026) and was rebuilt as a local-first library. Landing page: findakin.lelain.net · Documentation: findakin.lelain.net/docs.

spectro-kernel  = algorithms on ONE spectrum   (embeddings, I/O, lines, RV, reduction…)
Findakin        = questions on MANY spectra    (index, neighbours, clusters, anomalies,
                                                trajectories, encoder benchmarks)

Three stars of a pro-am campaign (STAROS) read back as spectra after ingestion, embedding and grouping. The documentation works through this population and through 566 SDSS stars, with provenance.

Install

pip install findakin                 # core: store, ingestion, kernel recipes, k-NN, analysis toolbox
pip install "findakin[viz]"          # + the Plotly views (maps, overlays, cluster means, trajectories…)
pip install "findakin[analysis]"     # + UMAP, HDBSCAN, self-organising maps (minisom)
pip install "findakin[vo]"           # + SSAP / Virtual Observatory connectors
pip install "findakin[encoders]"     # + local PyTorch encoders (spectro-kernel embed_pretrained)

Python ≥ 3.11.

Quick start

from findakin import Store

st = Store.open("~/findakin/store")                 # a directory; created if missing

# 1. ingest — FITS (BeSS / ISIS / specINTI / Demetra dialects), CSV, JSON, TXT.
#    Spectra are deduplicated by content; metadata (object, time, instrument,
#    observer, site, resolution, coverage) is extracted from the headers.
report = st.ingest_folder("~/spectra/staros", source="staros", tags=["campaign:staros"])
print(report)                                       # 406 files → 406 added, 0 duplicates, 0 errors

# 2. embed — any spectro-kernel strategy; several encoders coexist for the same spectra
enc = st.embed(strategy="dct", dim=256, norm_method="z_score")   # → 'dct:v1:256:nogrid:z_score'
enc_ll = st.embed(strategy="log_lambda", dim=256)                 # Doppler-robust recipe
# tip: with min_max the continuum term dominates the vector and every pair scores ≈ 0.99;
# z_score (zero mean) or continuum_subtracted let the lines drive the similarity.

#    a named common grid, stored once: every spectrum resampled on 6545–6580 Å, the sharper
#    ones degraded to R = 8000 at constant R; encoders and flux matrices read the same rows
st.define_grid("halpha", 6545, 6580, resolution=8000)
st.apply_grid("halpha")                                           # 399 added; 345 degraded, 35 coarser, 19 R unknown
enc_ha = st.embed(strategy="dct", dim=64, norm_method="z_score", grid="halpha")   # → 'dct:v1:64:halpha:z_score'
st.create_index(enc)                                              # a vector index, for 10^5+ vectors

# 3. ask
st.neighbours("~/spectra/new_alfdra.fits", k=10, encoder=enc)          # k-NN by file…
st.neighbours(some_id, k=10, encoder=enc, where="resolution > 15000")   # …or by id, filtered
ids, X = st.vectors(enc, where="series_id = 'alf dra'")                 # numpy matrix for analysis

from findakin.analysis import cluster_embeddings, cluster_stability, detect_anomalies, decompose, series_trajectory
res = cluster_embeddings(X, method="agglomerative", n_clusters=2)     # Ward; linkage kept for a dendrogram
cluster_stability(X, method="agglomerative", n_clusters=2)           # is the partition reproducible?
weird = detect_anomalies(X, method="urf", contamination=0.05)        # unsupervised random forest weirdness
stack = st.flux_matrix(grid="halpha", where="series_id = 'alf Dra'") # the spectra on the grid
pca = decompose(stack.flux, "pca", n_components=5)                   # eigenspectra + reconstruction error
ids_s, t, XS = st.series("alf Dra", enc)                              # one series in time order
tr = series_trajectory(XS, t, ids=ids_s, period=51.42)               # outliers, change points, orbital phase

# 4. look — every view is a Plotly figure (pip install "findakin[viz]")
from findakin import viz
viz.cluster_spectra(stack.wavelength, stack.flux, res.labels)        # clusters read back as spectra
viz.leakage_view(project_embeddings(X).points, meta, by=("object", "instrument"))
viz.trajectory_plot(tr, x="phase", y=pca.weights[:, 0])             # the orbit, folded

Every method is glue over scikit-learn, scipy, astropy, minisom or plotly, cites its reference in the docstring, and returns a result aligned with the input ids.

Same verbs on the command line:

findakin ingest ~/spectra/alphadra --source staros --tag campaign:alphadra
findakin embed --strategy dct --dim 256
findakin grid define halpha --wl-min 6545 --wl-max 6580 --resolution 8000 && findakin grid apply halpha
findakin embed --strategy dct --dim 64 --norm-method z_score --grid halpha
findakin index dct:v1:256:nogrid:min_max
findakin search ~/spectra/new_alfdra.fits -k 10 -e dct:v1:64:halpha:z_score
findakin info

What is in the store

A LanceDB directory, versioned, rebuildable from your files:

series_id groups spectra that form a trajectory in time: an object followed over epochs (default), a night of sky spectra (series_from="night", e.g. aurorae), or a folder.

Roadmap (short)

Phase 0 — store, ingestion, kernel encoders, k-NN, CLI ✅ · Phase 2a — population toolbox (clusters + stability, URF anomalies, eigenspectra / NMF, trajectories, SOM), stored results, Plotly views ✅ · Phase 1 — named common λ grids in the store (flux__<grid>, resolution matching at constant R), vector indexes ✅ · Phase 2b — named populations, SIMBAD aliases, notebook templates · Phase 3 — learned encoders registry, benchmark with an instrument-leakage score · Phase 4 — findakin-mcp over the store · Phase 5 — thin HTTP façade for applications.

Development

uv venv .venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest -q
ruff check src tests

The landing page lives in website/ (Vite + React, deployed separately).

License

MIT — © 2026 Matthieu Le Lain.