themisim.query

themisim.query(site, datetime, frame, *, artifacts=None, results=24, min_score=None, prefilter=500, nprobe=64, diversify_seconds=30, engine=None)[source]

Find the frames most similar to (site, datetime, frame).

Parameters:

  • site (str) – Four-letter THEMIS site code (e.g. "fsmi").

  • datetime (str | datetime | date) – Identifies the hourly CDF; see _parse_hour() for accepted forms.

  • frame (int) – 0-based frame index within that hour’s CDF.

  • artifacts (str | Path, optional) – Directory holding index.faiss / manifest.parquet / vectors.f16.dat / vectors.meta.json. Defaults to $THEMIS_ASI_ARTIFACTS or ./data/artifacts. Ignored when an explicit engine is supplied.

  • results (int) – Search parameters, identical in meaning to the dashboard controls.

  • prefilter (int) – Search parameters, identical in meaning to the dashboard controls.

  • nprobe (int) – Search parameters, identical in meaning to the dashboard controls.

  • diversify_seconds (int) – Search parameters, identical in meaning to the dashboard controls.

  • min_score (float, optional) – Two ways to bound the result set. None (the default) is count mode: return the top results matches. A value in [0, 1] is threshold mode: ignore results and return every (diversified) match whose cosine similarity is at or above the cutoff, best first, capped at THRESHOLD_HIT_CAP for safety. In threshold mode the candidate pool is still the top prefilter FAISS matches, so raise prefilter to surface more low-cutoff hits.

  • engine (SearchEngine, optional) – Reuse a pre-built engine instead of the cached one (advanced use).

Returns:

Columns site, datetime, score, source_cdf — the same table (and formatting) the dashboard’s CSV export produces, best match first. The top row is normally the query frame itself (score ≈ 1.0).

Return type:

pandas.DataFrame