{ "schema_version": "1", "spectrokernel_version": "0.8.1", "site_url": "https://docs.spectrokernel.io/", "server": { "name": "spectro-kernel", "instructions": "spectro-kernel exposes a catalogue of astronomical spectroscopy algorithms.\n\nTypical workflow:\n 1. create_session() -> session_id\n 2. load_spectrum(session_id, path) load a FITS/ASCII spectrum\n 3. call analysis tools (normalize_polynomial, snr_der, fit_gaussian_line, ...)\n each one takes session_id and an optional params object\n 4. get_session_state(session_id) inspect accumulated results\n\nUse list_algorithms / describe_algorithm to discover tools and their parameters, or\nrun_preset to execute a whole pipeline at once. The catalogue is also readable as\nresources: spectro://algorithms, spectro://algorithms/{name}, spectro://recipes,\nspectro://recipes/{name} and spectro://llms.txt (a short map of this server)." }, "count": 142, "n_session_tools": 13, "n_algorithm_tools": 129, "tools": [ { "name": "create_session", "description": "Create a new working session and return its id.\n\n Every other tool needs a session_id. Call this first.", "input_schema": { "additionalProperties": false, "properties": {}, "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "end_session", "description": "Discard a working session and free its memory.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "load_spectrum", "description": "Load a spectrum file (FITS or ASCII, local path or http(s) URL) into a session.\n\n The spectrum becomes the session's working spectrum, ready for the analysis tools.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "path": { "type": "string" } }, "required": [ "session_id", "path" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "load_spectrum_from_url", "description": "Download a spectrum from *url* and load it as the session's working spectrum.\n\n Use after ``request_upload_url`` (with the returned ``download_url``) or\n with any reachable http(s) URL. The file type is inferred from the URL\n suffix; pass ``format_hint`` (\"fits\" or \"ascii\") to override.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "url": { "type": "string" }, "format_hint": { "default": "", "type": "string" } }, "required": [ "session_id", "url" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "request_upload_url", "description": "Return a presigned URL the client can PUT a file to, plus the GET URL.\n\n Use this when a spectrum is too large to inline in MCP. The client uploads\n with HTTP PUT, then calls ``load_spectrum_from_url`` with the returned\n ``download_url``. Requires SPECTRO_MCP_S3_BUCKET (+ optional endpoint)\n configured on the server.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "default": "application/octet-stream", "type": "string" } }, "required": [ "session_id", "filename" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "get_session_state", "description": "Return a summary of everything currently held in a session's context.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "get_spectrum_preview", "description": "Return a downsampled preview of the session's current spectrum (50 samples).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "get_spectrum_data", "description": "Return the session spectrum as JSON arrays, at most ``max_points`` samples.\n\n Heavier than ``get_spectrum_preview`` — use this when the caller needs\n to plot or re-analyse the spectrum client-side and the 50-point\n preview is too coarse. Returns ``{wavelength, flux, uncertainty,\n wavelength_unit, flux_unit, meta, downsampled, npix_total,\n npix_returned, stride}``. Spectra longer than ``max_points`` (default\n 20000) are stride-downsampled (every k-th sample) and flagged\n ``downsampled: true``; pass ``max_points=0`` to get every pixel.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "max_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 20000 } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "list_algorithms", "description": "List the available spectroscopy algorithms, optionally filtered by category.", "input_schema": { "additionalProperties": false, "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null } }, "type": "object" }, "output_schema": { "properties": { "result": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true }, "kind": "session" }, { "name": "describe_algorithm", "description": "Return the full details (parameters, inputs, outputs) of one algorithm.", "input_schema": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "get_algorithm_source", "description": "Return the source code of one algorithm's wrapper class.\n\n Useful when the agent (or its user) wants to audit what the wrapper\n does — especially for algorithms backed by an external library\n (astropy, easyspec, scipy). The response carries the repository-\n relative path, a GitHub permalink, the declared backend, and the\n source as a UTF-8 string. The absolute path on disk (``path``) is\n only filled in when the server runs locally (stdio mode).", "input_schema": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "list_presets", "description": "List every preset available on this server (bundled + installed collections).", "input_schema": { "additionalProperties": false, "properties": {}, "type": "object" }, "output_schema": { "properties": { "result": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true }, "kind": "session" }, { "name": "run_preset", "description": "Run a complete preset pipeline against a session's context in one call.\n\n ``variables`` binds the preset's declared variables (its instrument /\n observer profile); ``list_presets`` says how many a preset declares and\n ``describe`` them via the preset's page or ``spectro preset show``.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "preset_name": { "type": "string" }, "variables": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id", "preset_name" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "session" }, { "name": "activity_index_caii_hk", "description": "Mount Wilson S index from the Ca II H & K cores, plus R'_HK when B−V is given.\n\nS = alpha · 8 · (H + K) / (R + V) where H, K, R, V are fluxes integrated (flux × Å) through the HKP-2 passbands : K 3933.664 Å and H 3968.470 Å triangular with 1.09 Å FWHM (2.18 Å base), V 3891.07–3911.07 Å and R 3991.07–4011.07 Å rectangular. Each sample is weighted by its transmission and its pixel width, so the value is sampling-independent ; band edges fall on the nearest pixel centre. The spectrum must cover 3891–4011 Å (air wavelengths), be at rest wavelength (correct the radial velocity first) and have at least 3 samples inside the 1.09 Å FWHM of each H / K triangle (pixels ≲ 0.36 Å). s_index is an INSTRUMENTAL S : bring it onto the Mount Wilson scale with a linear fit against standard stars, then pass the (a, b) of S_MW = a·S + b as s_index_calibration. s_index_error propagates the spectrum's uncertainty array (None without one). log_rhk is written only when b_v is given ; it applies Noyes et al. 1984 to the calibrated S (log C_cf = 1.13(B−V)³ − 3.91(B−V)² + 2.84(B−V) − 0.47 + blue-end term, R_HK = 1.34e-4·C_cf·S, log R_phot = −4.898 + 1.918(B−V)² − 2.893(B−V)³). The photospheric correction is calibrated on 0.44 < B−V < 0.82 : outside that range log_rhk is still written but flagged in the message. Rejects (no log_rhk) when R_HK ≤ R_phot. Metrics are prefixed for provenance: s_index_alpha and s_index_calibrated echo the inputs. v2.0.0: masked samples (Spectrum1D.mask) are ignored — dropped from the passband integrals (and their transmission from the weight sum) like non-finite ones.\n\nParameters — pass as the 'params' object:\n- alpha (default 2.3): Mount Wilson calibration constant α in S = α·8·(H+K)/(R+V). 2.3 (Lovis et al. 2011) by default ; Duncan et al. 1991 use 2.4.\n- b_v (default None): Johnson B−V colour of the star. When given, log R'_HK (Noyes et al. 1984) is computed ; valid for 0.44 < B−V < 0.82.\n- s_index_calibration (default None): Optional [a, b] such that S_MW = a·S_inst + b, applied before the R'_HK conversion and reported as s_index_calibrated.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Vaughan, Preston & Wilson 1978, PASP 90, 267 — HKP-2 : triangular 1.09 Å FWHM H and K passbands, 20 Å R and V bands, S = α(H+K)/(R+V).; Duncan et al. 1991, ApJS 76, 383 — Mount Wilson survey ; α = 2.4 and the 8× H/K exposure ratio of HKP-2.; Noyes et al. 1984, ApJ 279, 763 — R'_HK = R_HK − R_phot with R_HK = 1.34e-4·C_cf·S and the C_cf / R_phot polynomials in B−V.; Middelkoop 1982, A&A 107, 31 — log C_cf polynomial adopted by Noyes.; Lovis et al. 2011, arXiv:1107.5325 — S from échelle spectra (α = 2.3) and S_MW = 1.111·S_HARPS + 0.0153 calibration.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "activity", "category_title": "Stellar activity", "summary": "Mount Wilson S index from the Ca II H & K cores, plus R'_HK when B−V is given.", "docs_url": "https://docs.spectrokernel.io/algorithms/activity/activity_index_caii_hk/" }, { "name": "activity_index_halpha", "description": "Hα activity index : mean core flux over the sum of two reference-band fluxes.\n\nI_Hα = F_Hα / (F_1 + F_2) with F the pixel-width-weighted MEAN flux in each rectangular band (6562.008–6563.608 Å core ; 6545.495–6556.245 Å and 6575.935–6584.685 Å references). Band edges fall on the nearest pixel centre. The spectrum must cover 6545.5–6584.7 Å in the star's rest frame with at least 3 samples in the core band. The index is instrument-dependent : use it to follow one star's chromospheric variability, not to compare instruments. halpha_index_error propagates the uncertainty array (absent without one). For a Ca II H & K equivalent see activity_index_caii_hk. v2.0.0: masked samples (Spectrum1D.mask) are ignored — dropped from the passband means (and their pixel width from the weight sum) like non-finite ones.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Gomes da Silva et al. 2011, A&A 534, A30 — Hα index : 1.6 Å core on 6562.808 Å, reference bands 6550.87 ± 5.375 Å and 6580.31 ± 4.375 Å.; Boisse et al. 2009, A&A 495, 959 — Hα index definition for HD 189733.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "activity", "category_title": "Stellar activity", "summary": "Hα activity index : mean core flux over the sum of two reference-band fluxes.", "docs_url": "https://docs.spectrokernel.io/algorithms/activity/activity_index_halpha/" }, { "name": "air_to_vacuum", "description": "Convert the wavelength axis from air to vacuum wavelengths.\n\nλ_vac = λ_air · n(λ_air) with the VALD3 closed-form inverse of Morton 2000 (coefficients 8.336624212083e-5, 2.408926869968e-2/(130.1065924522 - s²), 1.599740894897e-4/(38.92568793293 - s²), s = 1e4/λ[Å]). Acceptance: Hα 6562.79 → 6564.603 Å. Valid above ~2000 Å.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Piskunov N., VALD3 'Air to vacuum conversion' (Uppsala VALD wiki, https://www.astro.uu.se/valdwiki/Air-to-vacuum%20conversion) — closed-form inverse fit n(λ_air) of the Morton 2000 relation.; Morton 2000, ApJS 130, 403 — air/vacuum dispersion relation n(λ_vac).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "correction", "category_title": "Corrections", "summary": "Convert the wavelength axis from air to vacuum wavelengths.", "docs_url": "https://docs.spectrokernel.io/algorithms/correction/air_to_vacuum/" }, { "name": "aperture_photometry", "description": "Differential aperture photometry on ``ctx.image`` (photutils).\n\nProvide the target's (x, y) pixel coordinates and one or more comparison stars. The differential magnitude for each comparison is -2.5 * log10(target_flux / comp_flux); positive means the target is fainter than the comparison.\n\nParameters — pass as the 'params' object:\n- target_xy (default None) [required]: Target (x, y) pixel coordinates (length-2 list).\n- comparison_xy (default None) [required]: List of (x, y) coordinates for comparison stars.\n- aperture_radius (default 5.0): Aperture radius (pixels) for source extraction.\n- annulus_in_radius (default 8.0): Inner radius of the sky annulus (pixels).\n- annulus_out_radius (default 12.0): Outer radius of the sky annulus (pixels).\n\nRequires in the session context: image\n\nBackend: photutils.\nReferences: Bradley et al. — Astropy Photutils (https://photutils.readthedocs.io/).; AAVSO Guide to CCD Photometry.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "advanced", "category_title": "Advanced", "summary": "Differential aperture photometry on ``ctx.image`` (photutils).", "docs_url": "https://docs.spectrokernel.io/algorithms/advanced/aperture_photometry/" }, { "name": "atmospheric_extinction_correct", "description": "Remove atmospheric extinction : F_0 = F · 10^(0.4 · k(λ) · X) with a mean site curve.\n\nF_0(λ) = F(λ) · 10^(0.4 · k(λ) · X). curve='kpno' (default) uses the IRAF KPNO mean extinction table (82 nodes, 3200–10400 Å, mag/airmass) reproduced verbatim ; per the file's own note its last four nodes, 8708–10400 Å, are CTIO values) — a MEAN curve for a 2 km site, not a nightly measurement : expect a few 0.01 mag/airmass of aerosol scatter, and prefer a curve measured at your own site. curve='custom' reads ctx.extras[extinction_table_key] : a Spectrum1D whose flux is k(λ), a dict with 'wavelength_aa' and 'k_mag' lists, or an (N, 2) array. The curve is linearly interpolated onto the spectrum ; samples outside the curve's wavelength range take the nearest end value (counted in metrics.n_outside_curve). Airmass precedence : the airmass parameter, then the FITS AIRMASS keyword, then the geometry (RA/DEC + DATE-OBS at mid-exposure + site latitude/longitude/elevation from parameters or the SITELAT/SITELONG/SITEELEV, LAT-OBS/LONG-OBS/ALT-OBS or OBS-LAT/OBS-LONG/OBS-ELEV keywords) with astropy AltAz (no refraction) and Kasten & Young 1989 Eq. 3 (X(0°) = 0.99971, X(60°) = 1.99429, X(80°) = 5.586, X(90°) = 37.92 — 0.1–0.3 % below sec z at 45–60°) ; the brick fails when none is available. Wavelengths must be in Ångström. The uncertainty is multiplied by the same factor (curve and airmass taken as noise-free). The correction removes the smooth continuum extinction only — the O2 / H2O telluric bands are handled by remove_telluric_division.\n\nParameters — pass as the 'params' object:\n- airmass (default None): Airmass X of the observation. None ⇒ FITS AIRMASS keyword, then computed from the geometry (Kasten & Young 1989).\n- curve (default 'kpno'): 'kpno' (IRAF KPNO mean table, default) or 'custom' (user table in extras).\n- extinction_table_key (default 'extinction_table'): ctx.extras key holding the user extinction table when curve='custom' (Spectrum1D with flux = k mag/airmass, {'wavelength_aa', 'k_mag'} dict, or (N, 2) array).\n- ra_deg (default None): Target right ascension (deg) for the geometric airmass ; None ⇒ FITS RA.\n- dec_deg (default None): Target declination (deg) for the geometric airmass ; None ⇒ FITS DEC.\n- obstime (default None): Start-of-exposure time (ISO-8601) ; None ⇒ FITS DATE-OBS.\n- exposure_seconds (default None): Exposure duration (s) — the airmass is evaluated at mid-exposure ; None ⇒ FITS EXPTIME, then 0.\n- latitude_deg (default None): Observer geodetic latitude (deg) ; None ⇒ SITELAT-style keywords.\n- longitude_deg (default None): Observer geodetic longitude (deg, east positive) ; None ⇒ SITELONG-style keywords.\n- elevation_m (default None): Observer elevation (m) ; None ⇒ SITEELEV-style keywords, then 0.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Hayes & Latham 1975, ApJ 197, 593 — mean atmospheric extinction (Rayleigh + aerosol + ozone) and the 10^(0.4 k X) correction.; Kasten & Young 1989, Applied Optics 28, 4735 — airmass formula X = 1/[cos z + 0.50572 (96.07995 − z)^−1.6364] (Eq. 3).; Tody 1986, Proc. SPIE 627, 733 — IRAF ; the built-in curve is onedstds$kpnoextinct.dat (KPNO mean extinction, 3200–10400 Å).; Hardie 1962, in Astronomical Techniques (ed. Hiltner), Univ. of Chicago Press, ch. 8 — extinction linear in airmass.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "correction", "category_title": "Corrections", "summary": "Remove atmospheric extinction : F_0 = F · 10^(0.4 · k(λ) · X) with a mean site curve.", "docs_url": "https://docs.spectrokernel.io/algorithms/correction/atmospheric_extinction_correct/" }, { "name": "balmer_decrement_extinction", "description": "Nebular extinction c(Hβ), E(B−V) and A_V from the observed Hα/Hβ Balmer decrement.\n\nR_obs = F(Hα)/F(Hβ) with F = |amp|·|σ|·√(2π) per line (window ±8 Å). c(Hβ) = log10(R_obs / R_int) / (1 − A(Hα)/A(Hβ)) — the reddening function f(λ) = A(λ)/A(Hβ) − 1 (f(Hβ) = 0) is taken from the law ; E(B−V) = 2.5 c(Hβ) / [R_V · A(Hβ)/A_V] and A_V = R_V E(B−V). law='CCM89' (default) is evaluated in-module from Cardelli et al. 1989 Eqs. 3a-3b (for R_V = 3.1 : A(Hα)/A(Hβ) = 0.7025, f(Hα) = −0.2975, A(Hβ)/E(B−V) = 3.609, c(Hβ) = 1.444 E(B−V)) ; 'F99' / 'G23' use dust_extinction (reduction extra). intrinsic_ratio defaults to 2.86 (Osterbrock & Ferland 2006 Table 4.4, Case B, 1e4 K, 1e2 cm⁻³ ; use 2.75 at 2e4 K, 3.04 at 5e3 K, or ~3.1 for AGN narrow-line regions). A ratio below intrinsic_ratio gives a negative extinction : c(Hβ), E(B−V) and A_V are clamped to 0 and the `clamped` flag of extras.balmer_decrement is set. Stellar Balmer absorption under Hβ is NOT corrected — subtract the stellar continuum first for galaxies. The line fluxes must be on the same flux scale (relative flux calibration is enough ; an uncalibrated instrumental response biases the ratio). Uncertainty : none is propagated — the shared Gaussian-line primitive returns fluxes without errors ; from Eq. 3, δc(Hβ) = δR / (R · ln 10 · |f(Hα)|) = 1.46 δR/R for CCM89 at R_V = 3.1 (a 5 % ratio error is δc ≈ 0.07, δE(B−V) ≈ 0.05), the intrinsic ratio and the law being taken as exact. v2.0.0: masked samples (Spectrum1D.mask) are ignored — excluded from both line windows like non-finite ones.\n\nParameters — pass as the 'params' object:\n- lambda_halpha (default 6562.82): Rest wavelength (Å) of Hα (default NIST air 6562.82, as bpt).\n- lambda_hbeta (default 4861.33): Rest wavelength (Å) of Hβ (default NIST air 4861.33, as bpt).\n- window (default 8.0): Half-width (Å) of the Gaussian fit window around each line.\n- intrinsic_ratio (default 2.86): Intrinsic (Hα/Hβ)_int : 2.86 = Case B at 1e4 K, 1e2 cm⁻³ (Osterbrock & Ferland 2006 Table 4.4).\n- rv (default 3.1): R_V = A_V / E(B−V) of the extinction law (3.1 diffuse ISM).\n- law (default 'CCM89'): Extinction law for f(λ) : 'CCM89' (built in), 'F99' or 'G23' (dust_extinction).\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Osterbrock & Ferland 2006, Astrophysics of Gaseous Nebulae and AGN, 2nd ed., University Science Books — Table 4.4 (Case B Hα/Hβ = 2.86 at T_e = 1e4 K, n_e = 1e2 cm⁻³) and §7.2 (c(Hβ), f(λ)).; Cardelli, Clayton & Mathis 1989, ApJ 345, 245 — Eqs. 3a-3b, A(λ)/A_V optical polynomial (built-in law).; Kramida et al., NIST ASD — air rest wavelengths Hα 6562.82 Å, Hβ 4861.33 Å (the values used by bpt_line_ratios).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "nebular", "category_title": "Nebular diagnostics", "summary": "Nebular extinction c(Hβ), E(B−V) and A_V from the observed Hα/Hβ Balmer decrement.", "docs_url": "https://docs.spectrokernel.io/algorithms/nebular/balmer_decrement_extinction/" }, { "name": "barycentric_correction", "description": "Compute the barycentric (or heliocentric) correction and Julian date, and shift the spectrum.\n\nThe observer location defaults to the geocentre; set latitude/longitude/elevation for the diurnal term (up to ~0.5 km/s). Uses astropy's SkyCoord.radial_velocity_correction and Time.light_travel_time. kind='barycentric' (default) emits metrics.bjd_tdb and a BJD_TDB header card; kind='heliocentric' emits metrics.hjd_utc, an HJD card and the BeSS BSS_VHEL card (BSS_VHEL is heliocentric *by definition* — the kernel refuses to fill it from a barycentric velocity, the two differ by up to ~13 m/s). BSS_VHEL carries the applied velocity when apply_shift is true, else 0 (BeSS convention for an uncorrected product). The Julian date is computed at MID-exposure: start time + exposure_seconds/2, falling back to the FITS EXPTIME when the parameter is null, and to 0 (start = mid) when neither exists.\n\nParameters — pass as the 'params' object:\n- ra_deg (default None): Target right ascension (deg); falls back to the FITS RA keyword.\n- dec_deg (default None): Target declination (deg); falls back to the FITS DEC keyword.\n- obstime (default None): Start-of-exposure time (ISO-8601); falls back to FITS DATE-OBS.\n- latitude_deg (default 0.0): Observer geodetic latitude (deg).\n- longitude_deg (default 0.0): Observer geodetic longitude (deg, east positive).\n- elevation_m (default 0.0): Observer elevation above the ellipsoid (m).\n- apply_shift (default True): If true, Doppler-shift the wavelength axis to the chosen frame.\n- kind (default 'barycentric'): 'barycentric' (default; emits BJD_TDB) or 'heliocentric' (emits HJD and the BeSS BSS_VHEL card).\n- exposure_seconds (default None): Exposure duration (s), used to compute the Julian date at mid-exposure; null falls back to the FITS EXPTIME keyword, then to 0.\n\nRequires in the session context: spectrum\n\nBackend: astropy.\nReferences: astropy.coordinates SkyCoord.radial_velocity_correction; Wright & Eastman 2014, PASP 126, 838 — barycentric correction precision; Eastman, Siverd & Gaudi 2010, PASP 122, 935 — BJD_TDB as the unambiguous time standard (HJD/UTC ambiguities reach the minute).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "correction", "category_title": "Corrections", "summary": "Compute the barycentric (or heliocentric) correction and Julian date, and shift the spectrum.", "docs_url": "https://docs.spectrokernel.io/algorithms/correction/barycentric_correction/" }, { "name": "bias_combine", "description": "Combine a stack of bias frames into one master bias.\n\nParameters — pass as the 'params' object:\n- method (default 'median'): Combination method: 'median' (robust) or 'mean'.\n\nRequires in the session context: images\n\nBackend: numpy.\nReferences: Howell 2006 — Handbook of CCD Astronomy, ch. 4 (standard CCD reduction).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "master_creation", "category_title": "Master frames", "summary": "Combine a stack of bias frames into one master bias.", "docs_url": "https://docs.spectrokernel.io/algorithms/master_creation/bias_combine/" }, { "name": "bias_combine_easyspec", "description": "Combine bias frames into a master bias via ``easyspec.cleaning.master``.\n\nRequires the optional `reduction` extra. The matplotlib backend is forced to 'Agg' at import time so easyspec's plotting defaults never open a window in a server context.\n\nParameters — pass as the 'params' object:\n- bias_dir (default None): Directory containing the bias FITS files.\n- bias_paths (default None): List of bias FITS file paths (symlinked into a temp dir).\n- method (default 'median'): Stacking method passed to easyspec: median, mean, or mode.\n- header_hdu_entry (default 0): HDU extension where the FITS header lives.\n\nBackend: easyspec.\nReferences: easyspec — Lobão et al. (https://pypi.org/project/easyspec/).; easyspec.cleaning.cleaning.master.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "master_creation", "category_title": "Master frames", "summary": "Combine bias frames into a master bias via ``easyspec.cleaning.master``.", "docs_url": "https://docs.spectrokernel.io/algorithms/master_creation/bias_combine_easyspec/" }, { "name": "box_least_squares", "description": "Box least squares transit search (Kovács, Zucker & Mazeh 2002) via astropy.\n\nWraps astropy.timeseries.BoxLeastSquares. Durations are tried in turn at every period (pass the list expected for the target ; the reported depth is diluted when the true duration is shorter than the best box). The period grid is astropy's autoperiod grid (uniform in frequency with spacing min(duration)/baseline², bounds period_min / period_max defaulting to 2·max(duration) and baseline/3) unless n_periods is given, in which case n_periods frequencies are spaced uniformly between 1/period_max and 1/period_min. objective='likelihood' maximises the log-likelihood of the box model (astropy default) ; 'snr' maximises depth/depth_err. Point uncertainties are used as inverse-variance weights when the light curve carries them ; otherwise every point gets the same σ = 1.4826 × MAD(flux − median), the robust point-to-point scatter, so that depth_err and bls_snr are on the data's noise scale (astropy alone would assume σ = 1 and report a meaningless SNR ; the uniform weight leaves the period ranking identical to the unweighted fit). Regime : times in days (metric names say so), a detrended/normalised flux, at least ~2 transits inside the baseline ; period_min must exceed the longest duration. bls_snr is astropy's depth_snr = depth/depth_err at the best period — compare with the ≈ 6 detection level of Kovács et al. ; no false-alarm probability is computed.\n\nParameters — pass as the 'params' object:\n- time (default None): List of observation times; omit to use a light curve from the context.\n- flux (default None): List of flux values, paired with 'time'.\n- uncertainty (default None): Optional list of per-point flux uncertainties.\n- light_curve_key (default None): Key in ctx.light_curves to use when time/flux are omitted.\n- period_min (default None): Shortest trial period in days; null = 2 × longest duration.\n- period_max (default None): Longest trial period in days; null = baseline / 3.\n- duration_hours (default [1.0, 2.0, 4.0]): Transit duration(s) to try, in hours (single value or list).\n- n_periods (default None): Number of trial periods, uniform in frequency; null = astropy's autoperiod grid.\n- objective (default 'likelihood'): Quantity maximised over phase/depth/duration: one of ['likelihood', 'snr'].\n- output_key (default 'bls'): Key under which the power spectrum is stored in ctx.periodograms.\n\nBackend: astropy.\nReferences: Kovács, Zucker & Mazeh 2002, A&A 391, 369 — the box-fitting least squares algorithm: periodic alternation between two levels with a short low state of fractional length q ; detection driven by the effective SNR depth/σ (significant above ≈ 6 in their simulations).; astropy.timeseries.BoxLeastSquares — the wrapped implementation (likelihood / snr objectives ; depth, depth_err, depth_snr ; autoperiod grid heuristics).; Rousseeuw & Croux 1993, J. Am. Stat. Assoc. 88, 1273 — 1.4826 × MAD as a consistent robust estimate of σ for Gaussian noise, used as the uniform point uncertainty when the light curve carries none.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "timeseries", "category_title": "Time series", "summary": "Box least squares transit search (Kovács, Zucker & Mazeh 2002) via astropy.", "docs_url": "https://docs.spectrokernel.io/algorithms/timeseries/box_least_squares/" }, { "name": "bpt_line_ratios", "description": "Measure BPT line ratios + classify a galaxy (HII / Composite / Seyfert / LINER).\n\nBPT classification uses the [N II]/Hα plane only (the most-cited standard). Auxiliary log ratios log_oii_hb (3727/Hβ) and log_sii_ha ((6716+6731)/Hα) are reported for downstream analysis but not used for the class label. Override the default rest wavelengths via params['lines'] (dict). v1.1.0: extras['method'] (shared with the other nebular bricks) is also written as extras['bpt_method'], and line_fluxes / rest_wavelengths / fit_details as bpt_line_fluxes / bpt_rest_wavelengths / bpt_fit_details, so a pipeline keeps unambiguous provenance. v2.0.0: masked samples (Spectrum1D.mask) are ignored — excluded from every line window like non-finite ones.\n\nParameters — pass as the 'params' object:\n- window (default 8.0): Half-width (Å) of the fit window around each line.\n- lines (default {'ha': 6562.82, 'hb': 4861.33, 'oiii_5007': 5006.84, 'nii_6583': 6583.45, 'sii_6716': 6716.44, 'sii_6731': 6730.82, 'oii_3727': 3727.42}): Mapping of line keys to rest wavelengths (Å). Keys: ha, hb, oiii_5007, nii_6583, sii_6716, sii_6731, oii_3727.\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Baldwin, Phillips & Terlevich 1981, PASP 93, 5 — original BPT.; Kewley & Dopita 2001, ApJ 556, 121 — maximum-starburst line.; Kauffmann et al. 2003, MNRAS 346, 1055 — HII/AGN empirical split.; Cid Fernandes et al. 2010, MNRAS 403, 1036 — Seyfert/LINER cut.; Kewley et al. 2006, MNRAS 372, 961 — [S II], [O I] variants.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "nebular", "category_title": "Nebular diagnostics", "summary": "Measure BPT line ratios + classify a galaxy (HII / Composite / Seyfert / LINER).", "docs_url": "https://docs.spectrokernel.io/algorithms/nebular/bpt_line_ratios/" }, { "name": "ccf_bisector", "description": "Bisector of a CCF (or one line) and the Queloz et al. 2001 Bisector Inverse Slope.\n\nReads ctx.extras['ccf'] as written by cross_correlate_rv ({'lags_kms', 'ccf'}) — a Pearson peak whose baseline is the median of the outer baseline_fraction of the lag range on each side — or, when line_center_angstrom is given, one line of ctx.spectrum within ± window_angstrom converted to v = c·(λ − λ0)/λ0 with a straight continuum through the outer continuum_fraction of the window (absorption or emission, whichever excursion is larger). The depth profile runs from 0 (continuum) to 1 (core) ; the bisector is sampled on n_levels equally spaced depths in (0, 1) and stored in extras['ccf_bisector'] = {'depth', 'velocity_kms', 'source', ...} (None where a wing does not reach the level). bis_kms = mean bisector velocity over top_depth_range minus mean over bottom_depth_range (Queloz et al. 2001 : 10–40 % and 55–90 %) ; at least 3 valid levels are required in each zone, and the top_depth_range[0] level must be crossed on both wings inside the region excluded from the continuum / baseline anchors (fails when the wings do not reach the continuum inside the window). bisector_span_kms = v_bis(top_depth_range[0]) − v_bis(bottom_depth_range[1]) at the nearest sampled levels (Gray's velocity span between fixed depths). The measurement needs the profile sampled with at least ~10 points across the line (a cross_correlate_rv CCF at n_grid=4096 on 4000–7000 Å has 41 km/s bins : keep its default n_grid=None, which follows the native sampling) and a S/N high enough that the bisector scatter (≈ noise / slope of the wings) is below the effect sought. v2.0.0: in line mode masked samples (Spectrum1D.mask) are ignored — dropped like non-finite ones before the continuum fit and the bisection.\n\nParameters — pass as the 'params' object:\n- line_center_angstrom (default None): Rest-frame centre (Å) of a single line of ctx.spectrum to bisect. None (default) analyses the CCF in ctx.extras instead.\n- window_angstrom (default 5.0): Half-width (Å) of the line window on each side of the centre.\n- continuum_fraction (default 0.2): Fraction of each window edge used to anchor the straight continuum (line mode only).\n- ccf_key (default 'ccf'): Key of the CCF dict in ctx.extras (cross_correlate_rv writes 'ccf').\n- baseline_fraction (default 0.2): Fraction of the lag range, at each end, whose median defines the CCF baseline (CCF mode only).\n- n_levels (default 99): Number of equally spaced depth levels in (0, 1) at which to bisect.\n- top_depth_range (default None): [lo, hi] depth fractions of the 'top' zone ; default [0.10, 0.40] (Queloz et al. 2001).\n- bottom_depth_range (default None): [lo, hi] depth fractions of the 'bottom' zone ; default [0.55, 0.90] (Queloz et al. 2001).\n\nBackend: numpy.\nReferences: Queloz et al. 2001, A&A 379, 279 — bisector inverse slope BIS = v_top(10–40 % depth) − v_bottom(55–90 % depth) of the CCF.; Toner & Gray 1988, ApJ 334, 1008 — bisector by interpolating both wings at each flux level.; Gray 2005, The Observation and Analysis of Stellar Photospheres, 3rd ed., Cambridge UP — ch. 17, line bisectors and velocity span.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "activity", "category_title": "Stellar activity", "summary": "Bisector of a CCF (or one line) and the Queloz et al. 2001 Bisector Inverse Slope.", "docs_url": "https://docs.spectrokernel.io/algorithms/activity/ccf_bisector/" }, { "name": "classify_template_chi2", "description": "Spectral classification by χ² against a Pickles-style template atlas.\n\nCommon wavelength grid (default 3800–7500 Å at 2 Å step, matching pickles_atlas.canonical_grid()), running-median continuum normalisation (window 80 samples), unweighted χ² over the samples shared by observed + template. Templates with useable overlap < min_overlap are skipped. Confidence flags : ambiguous (χ²[1]/χ²[0] < 1.20) and teff_unstable (top-3 ΔT_eff > 500 K). Supply either `atlas` (an Atlas object, Python API) or `atlas_dir` (path to the Pickles .dat files, loaded with load_atlas_from_dir and cached per directory) ; `atlas` wins when both are given. The grid is always the atlas's own grid_aa : grid_lo / grid_hi / grid_step are accepted for backwards compatibility but currently UNUSED. Normalised templates are cached on Atlas.norm_cache (identical numbers, ~100× faster repeat calls). A descending observed wavelength axis is sorted before resampling.\n\nParameters — pass as the 'params' object:\n- atlas (default None): An Atlas instance (see classification.pickles_atlas.Atlas). Build with load_atlas_from_dir(path) or supply a custom {template_id → flux_on_grid} mapping plus meta. Python API only ; CLI/MCP callers use atlas_dir.\n- atlas_dir (default None): Directory holding the Pickles uk*.dat templates ; loaded with load_atlas_from_dir onto the canonical grid (cached). Ignored when atlas is given.\n- top_n (default 5): Number of best-fit matches to report (≥ 1).\n- min_overlap (default 0.6): Reject the run if observed-vs-grid overlap drops below this fraction.\n- continuum_window (default 80): Running-median window (samples) for continuum normalisation.\n- grid_lo (default 3800.0): Reserved (currently unused): the atlas's own grid_aa is used.\n- grid_hi (default 7500.0): Reserved (currently unused): the atlas's own grid_aa is used.\n- grid_step (default 2.0): Reserved (currently unused): the atlas's own grid_aa is used.\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Pickles 1998, PASP 110, 863 — UVKLIB stellar template atlas.; Cappellari 2017, MNRAS 466, 798 — pPXF full-spectrum fitting.; Koleva et al. 2009, A&A 501, 1269 — ULySS.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "classification", "category_title": "Spectral classification", "summary": "Spectral classification by χ² against a Pickles-style template atlas.", "docs_url": "https://docs.spectrokernel.io/algorithms/classification/classify_template_chi2/" }, { "name": "clip_cosmic_rays", "description": "Detect and replace cosmic-ray hits on ``ctx.image``.\n\nL.A.Cosmic detects cosmic-ray cores by Laplacian edge detection and replaces the affected pixels with a local median. The fallback path uses a 3x3 median filter as the reference: any pixel whose excess over the median exceeds `sigma` standard deviations is replaced by that local median.\n\nParameters — pass as the 'params' object:\n- sigma (default 5.0): Detection threshold in noise units.\n- gain (default 1.0): Detector gain in electrons/ADU (used by L.A.Cosmic).\n- readnoise (default 6.0): Detector read noise in electrons (used by L.A.Cosmic).\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: van Dokkum 2001, PASP 113, 1420 — L.A.Cosmic; McCully et al. — astroscrappy (https://github.com/astropy/astroscrappy)", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "cosmic_ray", "category_title": "Cosmic-ray rejection", "summary": "Detect and replace cosmic-ray hits on ``ctx.image``.", "docs_url": "https://docs.spectrokernel.io/algorithms/cosmic_ray/clip_cosmic_rays/" }, { "name": "clip_sigma", "description": "Remove outlier samples (cosmic rays, hot pixels) by iterative sigma clipping.\n\nParameters — pass as the 'params' object:\n- sigma (default 5.0): Clipping threshold, in standard deviations of the residual.\n- window (default 5): Median-filter window (samples) used to estimate the local baseline.\n- iterations (default 3): Maximum number of clipping iterations.\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Bevington & Robinson 2003, Data Reduction and Error Analysis for the Physical Sciences, 3rd ed., McGraw-Hill — Chauvenet's criterion / iterative rejection of samples beyond k·σ of the fit.; astropy.stats.sigma_clip — iterative σ-clipping about a robust centre (the same iterate-until-no-new-rejection scheme, applied here to the residual from a running median).; scipy.ndimage.median_filter — local baseline.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "transform", "category_title": "Transforms", "summary": "Remove outlier samples (cosmic rays, hot pixels) by iterative sigma clipping.", "docs_url": "https://docs.spectrokernel.io/algorithms/transform/clip_sigma/" }, { "name": "combine_spectra_arithmetic", "description": "Add, subtract, multiply or divide ``ctx.spectrum`` by a reference.\n\noperation ∈ {add, sub, mul, div}. For 'div', samples where |reference| < min_denominator become NaN (clamp on near-zero responses). Pass-through outside the reference domain matches IRAF sarith and prevents wing zero-out. v2.0.0 — uncertainty propagation (independent errors, Bevington & Robinson §3.2) : add/sub σ = sqrt(σ_s² + σ_r²) ; mul/div σ = |result| · sqrt((σ_s/s)² + (σ_r/r)²) when the reference carries an uncertainty (σ_r resampled as sqrt(interp(σ_r²))), else σ = σ_s · |r| (mul) or σ_s / |r| (div). Outside the reference domain σ passes through with the flux ; NaN samples get a NaN σ ; a science spectrum without uncertainty stays without one. No covariance between science and reference is assumed (a response derived from the same night's standard is treated as independent).\n\nParameters — pass as the 'params' object:\n- operation (default 'div'): One of 'add', 'sub', 'mul', 'div'.\n- min_denominator (default 5e-05): Division samples with |reference| below this become NaN. Ignored for non-div operations.\n- reference_path (default None): Path / URL of a FITS reference spectrum (loaded with read_fits).\n- reference_key (default 'reference_spectrum'): ctx.extras key holding a Spectrum1D reference.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Tody 1986, Proc. SPIE 627, 733 — IRAF sarith heritage.; Astropy Collaboration (Robitaille et al.) 2013, A&A 558, A33 — the astropy units layer whose arithmetic conventions this brick follows ; specutils arithmetic (documentation) is the reference implementation of spectrum ± × ÷ spectrum.; Bevington & Robinson 2003, Data Reduction and Error Analysis for the Physical Sciences, 3rd ed., McGraw-Hill — §3.2, propagation of errors through sums, products and quotients.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "transform", "category_title": "Transforms", "summary": "Add, subtract, multiply or divide ``ctx.spectrum`` by a reference.", "docs_url": "https://docs.spectrokernel.io/algorithms/transform/combine_spectra_arithmetic/" }, { "name": "compare_line_fits", "description": "Fit one spectral line with every profile in turn and pick the best one.\n\nUseful when you do not know whether a line is pressure-broadened (Lorentzian wings dominate), thermally / instrumentally broadened (Gaussian is enough), or genuinely mixed (Voigt). The wrapper picks no winner itself — it leaves all three fits on the context for you to compare.\n\nParameters — pass as the 'params' object:\n- line_center_angstrom (default None) [required]: Approximate line centre in Å (required).\n- window_angstrom (default 20.0): Half-width of the fit window on each side (Å).\n- profiles (default ['fit_gaussian_line', 'fit_lorentzian_line', 'fit_voigt_line']): Names of fit_*_line algorithms to run.\n- label_prefix (default ''): Prefix for the keys written to ctx.line_fits (defaults to '').\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Catalogue fit_*_line algorithms; this wrapper is composition only.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "line_fitting", "category_title": "Line fitting", "summary": "Fit one spectral line with every profile in turn and pick the best one.", "docs_url": "https://docs.spectrokernel.io/algorithms/line_fitting/compare_line_fits/" }, { "name": "compare_normalisations", "description": "Run every continuum-normalisation method on ``ctx.spectrum`` and collect them.\n\nThe Spectrum1D ``ctx.spectrum`` you pass in is *not* modified — only ``ctx.extras['normalisations']`` is populated. To then apply one of the results, copy it back into ``ctx.spectrum`` yourself. v2.0.0: masked samples (Spectrum1D.mask) are ignored by the pairwise RMS ; each method receives the mask and ignores those samples itself.\n\nParameters — pass as the 'params' object:\n- methods (default ['normalize_polynomial', 'normalize_percentile', 'normalize_max', 'normalize_edges']): Names of normalisation algorithms to run (defaults to the 4 native ones).\n- per_method_params (default {}): Optional dict {method_name: {param: value}} for non-default params.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Catalogue normalise_* algorithms; this wrapper is composition only.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "continuum", "category_title": "Continuum", "summary": "Run every continuum-normalisation method on ``ctx.spectrum`` and collect them.", "docs_url": "https://docs.spectrokernel.io/algorithms/continuum/compare_normalisations/" }, { "name": "compare_smoothings", "description": "Run every smoothing kernel on ``ctx.spectrum`` and collect the results.\n\nPairwise residual RMS between any two smoothings is recorded in ``ctx.metrics`` so the caller can see how much the kernel choice actually matters on this particular spectrum.\n\nParameters — pass as the 'params' object:\n- methods (default ['smooth_savgol', 'smooth_gaussian']): Names of smoothing algorithms to run (defaults to the 2 native ones).\n- per_method_params (default {}): Optional dict {method_name: {param: value}} for overrides.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Catalogue smooth_* algorithms; this wrapper is composition only.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "smoothing", "category_title": "Smoothing", "summary": "Run every smoothing kernel on ``ctx.spectrum`` and collect the results.", "docs_url": "https://docs.spectrokernel.io/algorithms/smoothing/compare_smoothings/" }, { "name": "compare_snr_methods", "description": "Run every SNR estimator on ``ctx.spectrum`` and collect their numbers.\n\nEach method writes to ``ctx.metrics``; this wrapper aggregates them into ``ctx.extras['snr_methods']`` so a downstream caller (or an MCP agent) can compare at a glance. The wrapper itself does not mutate ``ctx.spectrum`` ; each method runs on a slim context holding a copy of the spectrum only.\n\nParameters — pass as the 'params' object:\n- methods (default ['snr_der', 'snr_edge', 'snr_linear_fit']): Names of SNR algorithms to run (defaults to the 3 native ones).\n- per_method_params (default {}): Optional dict {method_name: {param: value}} for overrides.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Catalogue snr_* algorithms; this wrapper is composition only.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "quality", "category_title": "Quality / SNR", "summary": "Run every SNR estimator on ``ctx.spectrum`` and collect their numbers.", "docs_url": "https://docs.spectrokernel.io/algorithms/quality/compare_snr_methods/" }, { "name": "correct_slant_affine", "description": "Make monochromatic lines parallel to the rows by a horizontal shear.\n\nscipy.ndimage.affine_transform with shear [[1, 0], [-tan θ, 1]] and offset [0, tan θ · pivot_row], order=1 bilinear. Zero slant is a no-op.\n\nParameters — pass as the 'params' object:\n- slant_deg (default 0.0): Slant angle of monochromatic lines (degrees).\n- pivot_row (default 0): Row where the shear has zero displacement (use the trace row).\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: Howell 2006, Handbook of CCD Astronomy 2nd ed. §5.2 (Cambridge UP).; Tody 1986, Proc. SPIE 627, 733 — IRAF transform heritage.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "preprocessing", "category_title": "Preprocessing (2-D image)", "summary": "Make monochromatic lines parallel to the rows by a horizontal shear.", "docs_url": "https://docs.spectrokernel.io/algorithms/preprocessing/correct_slant_affine/" }, { "name": "correct_smile_polynomial", "description": "Undo smile curvature via the Schroeder even-order expansion.\n\nComputes the column-displacement field from the paraxial Seidel expansion, then resamples with scipy.ndimage.map_coordinates (order=1, zero-fill outside). Reference row is the optical axis (usually the science trace) — no displacement there.\n\nParameters — pass as the 'params' object:\n- reference_row (default 0) [required]: Optical-axis row y₀ (no lateral shift there); use the trace row.\n- smile_radius (default 0.0) [required]: Smile radius R in pixels (instrument-specific). 0 disables.\n- polynomial_order (default 6): Highest even power kept: one of 2, 4, 6.\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: Schroeder 2000, Astronomical Optics 2nd ed. ch.15 §15.3 — off-axis aberration expansion.; Bottema 1980, Appl. Opt. 19, 444 — smile curvature in concave-grating spectrographs.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "preprocessing", "category_title": "Preprocessing (2-D image)", "summary": "Undo smile curvature via the Schroeder even-order expansion.", "docs_url": "https://docs.spectrokernel.io/algorithms/preprocessing/correct_smile_polynomial/" }, { "name": "correct_tilt_affine", "description": "Re-align the slit with the detector columns by a vertical shear.\n\nscipy.ndimage.affine_transform with shear matrix [[1, -tan θ], [0, 1]], order=1 bilinear, zero-fill outside. The offset re-centres the shear on the image so the centre column remains in place. Pair with correct_slant_affine and correct_smile_polynomial in a long-slit preset.\n\nParameters — pass as the 'params' object:\n- tilt_deg (default 0.0): Tilt angle of the slit vs. detector columns (degrees).\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: Howell 2006, Handbook of CCD Astronomy 2nd ed. §5.2 (Cambridge UP).; Tody 1986, Proc. SPIE 627, 733 — IRAF transform heritage.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "preprocessing", "category_title": "Preprocessing (2-D image)", "summary": "Re-align the slit with the detector columns by a vertical shear.", "docs_url": "https://docs.spectrokernel.io/algorithms/preprocessing/correct_tilt_affine/" }, { "name": "cosmic_ray_remove_easyspec", "description": "Cosmic-ray (and optional gain) correction via ``CR_and_gain_corrections``.\n\nParameters — pass as the 'params' object:\n- target_path (default None): Science FITS; falls back to ctx.image.\n- gain (default None): Detector gain (e-/ADU); null reads it from the FITS header.\n- gain_header_entry (default 'GAIN'): Header keyword for the gain when 'gain' is null.\n- readnoise (default None): Read noise (electrons); null reads it from the FITS header.\n- readnoise_header_entry (default 'RDNOISE'): Header keyword for the read noise when 'readnoise' is null.\n- sigclip (default 5.0): Sigma threshold for cosmic-ray detection (easyspec default 5).\n\nBackend: easyspec.\nReferences: easyspec.cleaning.cleaning.CR_and_gain_corrections.; van Dokkum 2001, PASP 113, 1420 — L.A.Cosmic.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "cosmic_ray", "category_title": "Cosmic-ray rejection", "summary": "Cosmic-ray (and optional gain) correction via ``CR_and_gain_corrections``.", "docs_url": "https://docs.spectrokernel.io/algorithms/cosmic_ray/cosmic_ray_remove_easyspec/" }, { "name": "cross_correlate_rv", "description": "Measure radial velocity by cross-correlation against a template spectrum.\n\nTemplate comes from `template_path` (FITS), `template_key` (a Spectrum1D under ctx.extras), `ctx.extras['template_spectrum']` or `ctx.spectra[0]` — first match wins. By default the brick subtracts a running-median continuum from both observed and template (continuum_subtract=True) — the Tonry-Davis CCF only behaves correctly on continuum-normalised inputs ; with raw flux the SED slope dominates the correlation and biases the RV toward zero. Disable with continuum_subtract=False when the caller has already normalised the spectrum. The RV error is the Tonry-Davis 1979 formula ; it underestimates the true error for asymmetric CCFs (multi-component blended templates) — for a physics-grounded floor see rv_precision_bouchy (Bouchy, Pepe & Queloz 2001). v3.0.0: n_grid defaults to None — the log-λ grid follows the finest native Δlnλ of the two spectra over the overlap (capped at 2^18 samples). The former default of 4096 samples (41 km/s per sample on 4000-7000 Å) under-sampled finely sampled spectra and the parabolic refinement did not recover the loss : on a 30 000-px synthetic (σ_line 0.15 Å, S/N 100) an injected +10 km/s came back as +0.9 km/s with n_grid=4096 and as +9.97 km/s on the native grid ; pass n_grid=4096 explicitly to reproduce the pre-3.0.0 numbers. σ_v is a lower bound at coarse grids because it ignores the interpolation error. Masked samples (Spectrum1D.mask) of either spectrum are skipped like NaN when resampling (v3.0.0). Descending wavelength axes are sorted before resampling. DEPRECATED: the ctx.spectra[0] template fallback violates the 'second spectrum in ctx.extras' convention and will be removed in a future major release — it is flagged in the message, in extras['template_source'] and via a DeprecationWarning.\n\nParameters — pass as the 'params' object:\n- template_path (default None): Path / URL of a template FITS spectrum to load.\n- template_key (default None): Key in ctx.extras where a Spectrum1D template is stored.\n- n_grid (default None): Number of log-wavelength samples on which to interpolate. null/None (default since v3.0.0) derives it from the finest native Δlnλ of the two spectra inside the overlap (capped at 2^18) ; 4096 reproduces the pre-3.0.0 grid (41 km/s per sample on 4000-7000 Å, under-sampled for most spectra).\n- vmin_kms (default -800.0): Lower bound of the velocity search range (km/s).\n- vmax_kms (default 800.0): Upper bound of the velocity search range (km/s).\n- continuum_subtract (default True): If True (default), subtract a running-median continuum from both observed and template before correlation — the Tonry-Davis 1979 prerequisite. Disable only when the spectra are already continuum-normalised.\n- continuum_window (default 101): Running-median window (samples on the log-λ grid) for the continuum estimator. Must be odd ≥ 3; the brick rounds up if even. Ignored when continuum_subtract is False.\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Tonry & Davis 1979, AJ 84, 1511 — fundamental CCF method for RV; r-value, σ_v = 3·w/(8·(1+r)) error formula (§III), and the requirement of continuum-normalised inputs (§II).; Bouchy, Pepe & Queloz 2001, A&A 374, 733 — photon-limited RV precision (see also: rv_precision_bouchy).; scipy.signal.correlate — cross-correlation engine.; scipy.ndimage.median_filter — running-median continuum.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "radial_velocity", "category_title": "Radial velocity", "summary": "Measure radial velocity by cross-correlation against a template spectrum.", "docs_url": "https://docs.spectrokernel.io/algorithms/radial_velocity/cross_correlate_rv/" }, { "name": "dark_combine", "description": "Combine a stack of dark frames into a master dark.\n\nPixel-wise median (robust default) or σ-clipped mean over the stack. require_uniform_exptime=True (the default) ensures every input has the same EXPTIME — otherwise a non-uniform mix would render the master un-scalable by exposure time. Pass bias_key to subtract a master bias from each frame before combining. v2.0.0 (method='mean' with sigma_clip only): the σ-clip scale is 1.4826·MAD about the per-pixel median; when the MAD is 0 (integer-ADU darks with ~1 ADU read noise) it now falls back to 1.2533 × the mean absolute deviation about the median, and keeps all values when that is 0 too. v1 floored the scale at machine epsilon, which rejected every value ≠ median and turned the clipped mean into a median ([10,10,10,11,12], σ=3: v1 → 10.0, v2 → 10.6; a cosmic ray [10,10,10,11,1000] is still rejected → 10.25). method='median' is unchanged.\n\nParameters — pass as the 'params' object:\n- method (default 'median'): 'median' (robust default) or 'mean' (with optional sigma_clip).\n- bias_key (default None): ctx.extras key for a master bias to subtract from each frame before combining. None = no pre-subtraction.\n- require_uniform_exptime (default True): When True, refuse to combine frames with non-uniform EXPTIME (otherwise a scale_by_exptime downstream would be undefined).\n- sigma_clip (default None): σ threshold for σ-clipped mean (method='mean' only). None or ≤0 disables clipping.\n\nRequires in the session context: images\n\nBackend: numpy.\nReferences: Howell 2006 — Handbook of CCD Astronomy, ch. 4 (CCD reduction).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "master_creation", "category_title": "Master frames", "summary": "Combine a stack of dark frames into a master dark.", "docs_url": "https://docs.spectrokernel.io/algorithms/master_creation/dark_combine/" }, { "name": "dark_combine_easyspec", "description": "Combine dark frames into a master dark via ``easyspec.cleaning.master``.\n\nParameters — pass as the 'params' object:\n- dark_dir (default None): Directory containing the dark FITS files.\n- dark_paths (default None): List of dark FITS file paths.\n- method (default 'median'): Stacking method: median, mean, or mode.\n- header_hdu_entry (default 0): HDU extension where the FITS header lives.\n\nBackend: easyspec.\nReferences: easyspec — Lobão et al. (https://pypi.org/project/easyspec/).; easyspec.cleaning.cleaning.master.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "master_creation", "category_title": "Master frames", "summary": "Combine dark frames into a master dark via ``easyspec.cleaning.master``.", "docs_url": "https://docs.spectrokernel.io/algorithms/master_creation/dark_combine_easyspec/" }, { "name": "dark_subtract", "description": "Subtract a master dark from ``ctx.image``.\n\nReads the master dark from ``ctx.extras['master_dark']`` (an ImageFrame) or from ``dark_key`` if you stored it under a different key.\n\nParameters — pass as the 'params' object:\n- dark_key (default 'master_dark'): Key in ctx.extras where the master dark is stored.\n- scale_by_exptime (default True): Scale the dark by EXPTIME(science)/EXPTIME(dark) before subtracting.\n\nRequires in the session context: image\n\nBackend: numpy.\nReferences: Howell 2006 — Handbook of CCD Astronomy, ch. 4.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "preprocessing", "category_title": "Preprocessing (2-D image)", "summary": "Subtract a master dark from ``ctx.image``.", "docs_url": "https://docs.spectrokernel.io/algorithms/preprocessing/dark_subtract/" }, { "name": "denoise_gaussian_2d", "description": "Separable isotropic Gaussian smoothing of ``ctx.image``.\n\nscipy.ndimage.gaussian_filter(sigma), default mode 'reflect'. Isotropic — the same σ is applied to rows and columns. For anisotropic smoothing, pass a tuple via the underlying scipy API directly.\n\nParameters — pass as the 'params' object:\n- sigma (default 0.0): Gaussian σ in pixels (isotropic). 0 = no-op.\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: Lindeberg 1994, Scale-Space Theory in Computer Vision (Kluwer).; scipy.ndimage.gaussian_filter — separable Gaussian implementation.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "preprocessing", "category_title": "Preprocessing (2-D image)", "summary": "Separable isotropic Gaussian smoothing of ``ctx.image``.", "docs_url": "https://docs.spectrokernel.io/algorithms/preprocessing/denoise_gaussian_2d/" }, { "name": "denoise_median_2d", "description": "Square median filter over ``ctx.image``, optionally banded by rows.\n\nscipy.ndimage.median_filter(size=kernel_size) over rows [row_lo, row_hi). Outside the band the original pixels are kept.\n\nParameters — pass as the 'params' object:\n- kernel_size (default 3): Square kernel size, odd integer ≥ 3.\n- row_lo (default 0): First row (inclusive); 0 ⇒ top of image.\n- row_hi (default 0): Last row (exclusive); 0 ⇒ bottom of image.\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: Tukey 1977, Exploratory Data Analysis (Addison-Wesley) — rank-order filtering for impulse noise.; scipy.ndimage.median_filter — multi-dim median implementation.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "preprocessing", "category_title": "Preprocessing (2-D image)", "summary": "Square median filter over ``ctx.image``, optionally banded by rows.", "docs_url": "https://docs.spectrokernel.io/algorithms/preprocessing/denoise_median_2d/" }, { "name": "deredden_interstellar", "description": "Deredden a spectrum for interstellar dust : F_0 = F / 10^(−0.4 A(λ)), CCM89 / F99 / G23.\n\nF_0(λ) = F(λ) / extinguish(λ) with extinguish(λ) = 10^(−0.4 · E(B−V) · R_V · A(λ)/A_V) from dust_extinction.parameter_averages.(Rv=rv).extinguish(λ, Ebv=ebv). Validity (fails outside, no extrapolation) : CCM89 and F99 1000–33 333 Å with R_V ∈ [2.0, 6.0] ; G23 912 Å – 32 μm with R_V ∈ [2.3, 5.6]. ebv ≥ 0 (ebv = 0 is the identity). Wavelengths must be in Ångström. Uncertainty : σ_0 = σ / extinguish(λ) — E(B−V) and R_V are taken as exact. Acceptance : 5500 Å, CCM89, R_V = 3.1, E(B−V) = 0.1 ⇒ factor 1.3300 (A_V = 0.31, A(5500)/A_V = 0.99885). Requires the 'reduction' extra (pip install 'spectro-kernel[reduction]').\n\nParameters — pass as the 'params' object:\n- ebv (default None) [required]: Colour excess E(B−V) in magnitudes (≥ 0).\n- rv (default 3.1): Total-to-selective extinction ratio R_V = A_V / E(B−V) (3.1 diffuse ISM).\n- law (default 'CCM89'): Extinction law : 'CCM89' (default), 'F99' or 'G23'.\n\nRequires in the session context: spectrum\n\nBackend: dust_extinction.\nReferences: Cardelli, Clayton & Mathis 1989, ApJ 345, 245 — CCM89 R_V-dependent extinction law (default).; Fitzpatrick 1999, PASP 111, 63 — F99 law.; Gordon et al. 2023, ApJ 950, 86 — G23 law (912 Å – 32 μm).; dust_extinction (astropy affiliated), https://dust-extinction.readthedocs.io — the package that evaluates the laws (wrapped, not re-implemented).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "correction", "category_title": "Corrections", "summary": "Deredden a spectrum for interstellar dust : F_0 = F / 10^(−0.4 A(λ)), CCM89 / F99 / G23.", "docs_url": "https://docs.spectrokernel.io/algorithms/correction/deredden_interstellar/" }, { "name": "detect_lines", "description": "Detect emission/absorption peaks, optionally matched to a named catalogue.\n\nBlind mode (catalog=None) returns continuum, signed amplitude, SNR (|amp| / noise), FWHM (from scipy.signal.peak_widths at half-maximum), and the MAD-robust noise level used for the threshold. Catalogue mode preserves the v1.1.0 behaviour: each detection is labelled with the nearest catalogue line within tolerance_angstrom. v2.0.0: masked samples (Spectrum1D.mask) are ignored — they are removed, together with non-finite ones, before the continuum, noise and peak search in both modes.\n\nParameters — pass as the 'params' object:\n- catalog (default 'balmer'): Reference catalogue: 'balmer', 'telluric', 'nebular', 'aurorae', or None for blind mode (no identification).\n- kind (default 'both'): Which features to look for: emission, absorption or both.\n- prominence_sigma (default 5.0): Peak prominence threshold, in units of the noise level.\n- tolerance_angstrom (default 5.0): Maximum detection-to-catalogue separation for a match (Å).\n- continuum_window (default 101): Median-filter window (samples, odd ≥ 3) used to estimate the continuum before MAD noise computation in blind mode.\n- min_separation_angstrom (default 2.0): Minimum spacing between detections (Å). Forwarded to find_peaks(distance=…) in blind mode.\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: scipy.signal.find_peaks — prominence-thresholded peak detection.; Press, Teukolsky, Vetterling & Flannery 2007, Numerical Recipes, 3rd ed., Cambridge UP — §10.2, parabolic interpolation through three points (vertex refinement of the peak position).; Hampel 1974, J. Am. Stat. Assoc. 69, 383 — Median Absolute Deviation (blind-mode noise level: 1.4826 · MAD).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "line_detection", "category_title": "Line detection", "summary": "Detect emission/absorption peaks, optionally matched to a named catalogue.", "docs_url": "https://docs.spectrokernel.io/algorithms/line_detection/detect_lines/" }, { "name": "detect_trace", "description": "Detect the spectral trace on ``ctx.image`` and expose it on ``ctx.extras[\"trace\"]``.\n\nSibling of the trace step inside extract_spectrum_boxcar / extract_spectrum_optimal — but standalone, pure-numpy, and exposing the result on ctx.extras so the geometry and sky bricks (subtract_sky_2d, correct_smile_polynomial, correct_slant_affine) can resolve their hand-tuned row parameters from a measured value rather than a config file. Required at the head of an 'automatic' reduction preset; the manual mode that pre-fills row parameters from a config remains valid.\n\nParameters — pass as the 'params' object:\n- method (default 'argmax'): Per-slice centroid method: 'argmax' (integer pixel) or 'centroid' (sub-pixel).\n- poly_order (default 2): Polynomial order of the fitted trace y(x).\n- search_half_width (default 40): Half-window (rows) around the global peak in which each slice searches for its local maximum.\n- n_slices (default 20): Number of column slices sampled across the dispersion axis.\n- min_snr (default 5.0): Minimum trace SNR (peak above background / off-trace std). The algorithm fails rather than silently writing a bad trace.\n- output_key (default 'trace'): ctx.extras key that receives the trace dict.\n\nRequires in the session context: image\n\nBackend: scipy.\nReferences: Tody 1986, Proc. SPIE 627, 733 — IRAF apall / aptrace heritage.; scipy.signal.find_peaks — global peak of the collapsed spatial profile.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "extraction", "category_title": "Extraction (2-D to 1-D)", "summary": "Detect the spectral trace on ``ctx.image`` and expose it on ``ctx.extras[\"trace\"]``.", "docs_url": "https://docs.spectrokernel.io/algorithms/extraction/detect_trace/" }, { "name": "disentangle_sb2", "description": "Separate the spectra of the two components of an SB2 spectroscopic binary.\n\nImplements the iterative alternating subtraction of Bagnuolo & Gies 1991 (not the SVD of Simon & Sturm 1994 nor the Fourier method of Hadrava 1995, cited as background). All observations are resampled onto a common log-wavelength grid so that a Doppler shift is a constant number of samples ; at each iteration the current estimate of one component is removed from every observation in the other component's rest frame, and the new estimate is the average of the residuals. Stores ``primary_spectrum`` and ``secondary_spectrum`` in ``ctx.extras``. CAVEAT — additive continuum degeneracy: only the SUM of the two continua is constrained by the data, so the split of the continuum level between the components is arbitrary (the secondary typically comes out near a continuum of ~0 and the primary near the total) ; the line profiles are correct but a light-ratio prior is needed to renormalise each component to its own continuum. ``metrics['disentangle_residual_rms']`` (v1.1.0) is the RMS of observation − (shifted primary + shifted secondary) after the last iteration, over the finite samples. Descending wavelength axes and non-finite samples are handled before resampling.\n\nParameters — pass as the 'params' object:\n- v1_kms (default None) [required]: List of per-spectrum primary velocities (km/s, length = len(ctx.spectra)).\n- v2_kms (default None) [required]: List of per-spectrum secondary velocities (km/s, same length).\n- n_iter (default 30): Number of iterations of the alternating subtraction.\n- n_grid (default 4096): Number of log-wavelength samples on the common grid.\n\nRequires in the session context: spectra\n\nBackend: numpy.\nReferences: Bagnuolo & Gies 1991, ApJ 376, 266 — iterative alternating-subtraction ('tomographic') separation of composite spectra: the method implemented here.; Simon & Sturm 1994, A&A 281, 286 — wavelength-domain spectral separation by singular-value decomposition (background).; Hadrava 1995, A&AS 114, 393 — Fourier-domain disentangling (background).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "advanced", "category_title": "Advanced", "summary": "Separate the spectra of the two components of an SB2 spectroscopic binary.", "docs_url": "https://docs.spectrokernel.io/algorithms/advanced/disentangle_sb2/" }, { "name": "doppler_shift", "description": "Doppler-shift the wavelength axis by a radial velocity.\n\nParameters — pass as the 'params' object:\n- velocity_kms (default None) [required]: Radial velocity in km/s (positive = redshift).\n\nRequires in the session context: spectrum\n\nBackend: astropy.\nReferences: Classical (non-relativistic) Doppler relation: lambda' = lambda * (1 + v/c); Speed of light from astropy.constants", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "correction", "category_title": "Corrections", "summary": "Doppler-shift the wavelength axis by a radial velocity.", "docs_url": "https://docs.spectrokernel.io/algorithms/correction/doppler_shift/" }, { "name": "doppler_tomogram", "description": "Doppler tomogram of a binary from N phase-resolved spectra.\n\nBack-projection of N phase-resolved spectra onto the (V_x, V_y) plane. Pixels are averaged over the phases that contribute (NaN-aware mean) so the phase-coverage footprint does not bleed into the brightness map. JD_mid is read from each spectrum's meta['jd_mid'], falling back to meta['dateobs'] + meta['exptime_s'] via astropy.time.Time. Descending wavelength axes are sorted before interpolation. v2.0.0: the projection now follows Marsh & Horne 1988 Eq. 1, v = γ − Vx·cos(2πφ) + Vy·sin(2πφ) ; v1.x used γ − Vx·sin(2πφ) + Vy·cos(2πφ), so a spot with RV curve γ + K·sin(2πφ) (the secondary) landed at (−K, 0) instead of (0, +K). Maps produced by v1.x are rotated by −90° (Vx, Vy) → (Vy, −Vx) relative to v2 / the literature convention.\n\nParameters — pass as the 'params' object:\n- period_days (default None) [required]: Orbital period of the binary (days).\n- epoch_hjd (default None) [required]: Reference epoch HJD of phase 0 (days).\n- gamma_kms (default 0.0): Systemic velocity (km/s) added to the back-projection.\n- line_center_aa (default 6562.82): Rest wavelength (Å) of the line to tomogram.\n- velocity_window_kms (default 1000.0): Half-extent (km/s) of the V_x/V_y axes.\n- n_velocity (default 121): Number of velocity samples per axis (odd, 11–401).\n\nBackend: numpy.\nReferences: Marsh & Horne 1988, MNRAS 235, 269 — Doppler tomography by back-projection (§2).; Horne 1985, MNRAS 213, 129 — MEM tomographic reconstruction (not implemented; cited for completeness).; Marsh 2001, Lecture Notes in Physics 573 — astrotomography review.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "advanced", "category_title": "Advanced", "summary": "Doppler tomogram of a binary from N phase-resolved spectra.", "docs_url": "https://docs.spectrokernel.io/algorithms/advanced/doppler_tomogram/" }, { "name": "embed_band_power", "description": "Embed a spectrum as the integrated flux in N adjacent wavelength bands.\n\nEquivalent to converting a spectrum into a 'virtual photometric catalogue' with N synthetic broad bands. Very cheap and well-suited to indexing very heterogeneous datasets (different dispersions, resolutions, telescopes). Non-finite (NaN/inf) samples are dropped before integration — the trapezoidal band integral uses the actual wavelengths, so this is sampling-independent — and a descending wavelength axis is sorted first (band edges are taken from the finite samples). v3.0.0: masked samples (Spectrum1D.mask) are ignored — dropped like non-finite ones before integration.\n\nParameters — pass as the 'params' object:\n- n_bands (default 16): Number of bands; also the output dim. Typically 8–32.\n- spacing (default 'log'): Band edges in wavelength: 'linear' or 'log'.\n- log_flux (default True): Take log10(integrated_flux + epsilon) before L2 norm.\n- epsilon (default 1e-12): Small floor added before log_flux to keep zero bands finite.\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Connolly et al. 1995, AJ, 110, 1071 — photometric SED classification.; Bolzonella et al. 2000, A&A, 363, 476 — band-power feature vectors for spectro-photometric classification.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Embed a spectrum as the integrated flux in N adjacent wavelength bands.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_band_power/" }, { "name": "embed_continuum_subtracted", "description": "Subtract the polynomial continuum, then embed the line residual.\n\nUses the symmetric sigma-clipped polynomial continuum helper from ``algorithms._common``; the residual (flux - continuum) is then passed to one of the standard embedding recipes. Set ``norm_method='none'`` to skip a second normalisation step — the residual already has zero mean. Non-finite samples (NaN/inf) make the brick fail cleanly: the DCT/resampling recipes act on the sample index, so bad pixels cannot be dropped — replace them first (clip_sigma / clip_cosmic_rays interpolate over outliers). v2.0.0: masked samples (Spectrum1D.mask) are refused the same way.\n\nParameters — pass as the 'params' object:\n- dim (default 256): Output vector length (positive integer).\n- strategy (default 'dct'): Recipe applied to the residual: one of ('naive', 'dct', 'multiscale_dct').\n- continuum_order (default 3): Polynomial degree for the continuum fit (2-5 typical).\n- sigma_clip (default 3.0): Sigma threshold for the continuum-fit clip (default 3.0).\n- norm_method (default 'none'): Pre-embedding flux normalisation: one of ('none', 'min_max', 'z_score', 'continuum'). Defaults to 'none' because the residual is already zero-centred.\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Sousa et al. 2007, A&A, 469, 783 — continuum-normalised spectra for stellar parameter retrieval.; Worthey et al. 1994, ApJS, 94, 687 — line-strength indices on continuum-flattened spectra.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Subtract the polynomial continuum, then embed the line residual.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_continuum_subtracted/" }, { "name": "embed_lick_indices", "description": "Embed a spectrum as the canonical Lick/IDS line-strength indices.\n\nEach index is the equivalent width (or magnitude, for molecular indices) of a feature passband measured against a pseudo-continuum interpolated between two sidebands. The fixed-order vector and the human-readable index names (in extras.embedding_provenance.names) make this the most interpretable embedding the kernel exposes. Non-finite (NaN/inf) samples are dropped before the passband integrals (trapezoidal on the actual wavelengths, hence sampling-independent) and a descending wavelength axis is sorted first. v3.0.0: masked samples (Spectrum1D.mask) are ignored — dropped like non-finite ones before the passband integrals.\n\nParameters — pass as the 'params' object:\n- l2_normalise (default False): L2-normalise the output vector. False by default to preserve the physical units (Å / magnitudes). Set True for similarity search.\n- nan_fill (default 0.0): Value to substitute for indices that cannot be measured (passband outside the spectrum's wavelength range).\n\nRequires in the session context: spectrum\n\nBackend: numpy.\nReferences: Worthey et al. 1994, ApJS, 94, 687 — definition of the Lick/IDS index system.; Worthey & Ottaviani 1997, ApJS, 111, 377 — revised passband definitions and atmospheric corrections.; Trager et al. 1998, ApJS, 116, 1 — extended index list for old stellar populations.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Embed a spectrum as the canonical Lick/IDS line-strength indices.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_lick_indices/" }, { "name": "embed_log_lambda", "description": "Resample to a uniform log-λ grid, then embed.\n\nThe grid spacing is set so the output length is exactly ``dim``. Wavelengths must be strictly positive (the log of a non-positive value is undefined); the algorithm fails fast with a clear error otherwise. Non-finite (NaN/inf) samples are dropped before the resampling — the log-λ interpolation is sampling-independent, so this is safe — and a descending wavelength axis is sorted first. v2.0.0: masked samples (Spectrum1D.mask) are ignored — dropped like non-finite ones before the resampling (which bridges the gap linearly).\n\nParameters — pass as the 'params' object:\n- dim (default 256): Output vector length AND number of log-λ samples (positive integer).\n- strategy (default 'naive'): Recipe applied to the resampled flux: one of ('naive', 'dct', 'multiscale_dct').\n- norm_method (default 'min_max'): Pre-embedding flux normalisation: one of ('none', 'min_max', 'z_score', 'continuum').\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Tonry & Davis 1979, AJ, 84, 1511 — radial velocities from cross-correlation in log-λ space.; Baldry et al. 1999, ApJ, 521, 167 — Doppler invariance of log-wavelength representations.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Resample to a uniform log-λ grid, then embed.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_log_lambda/" }, { "name": "embed_pretrained", "description": "Embed a spectrum with a local pre-trained PyTorch model.\n\nOn the first call for a given model_path the file's SHA-256 is computed and recorded in the provenance dict; subsequent calls reuse the loaded model object (cached on the algorithm instance). Non-finite samples (NaN/inf) make the brick fail cleanly — replace bad pixels before inference (clip_sigma / clip_cosmic_rays interpolate over outliers). v2.0.0: masked samples (Spectrum1D.mask) are refused the same way.\n\nParameters — pass as the 'params' object:\n- model_path (default None) [required]: Filesystem path to the PyTorch model file (.pt / .pth) (REQUIRED). The user is responsible for downloading or training the model; the kernel only loads what's already on disk.\n- model_id (default 'user_model'): Human-readable identifier captured in the provenance dict alongside the SHA-256 hash; lets the similarity layer track which model version produced which vector.\n- input_length (default 1024): Number of pixels the model expects. The spectrum is resampled to this length before being fed to the model.\n- device (default 'cpu'): Torch device ('cpu' or 'cuda:0' if a GPU is present).\n\nRequires in the session context: spectrum\n\nBackend: pytorch.\nReferences: Bishop 2006, 'Pattern Recognition and Machine Learning' — embedding via learned representations.; Naul et al. 2018, Nat. Astron. 2, 151 — RNN autoencoders for irregular astronomical time series (analogous architecture).", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Embed a spectrum with a local pre-trained PyTorch model.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_pretrained/" }, { "name": "embed_remote", "description": "Embed a spectrum via a remote HTTPS inference endpoint.\n\nThe endpoint contract is documented in the module docstring. Any service that respects it (including a self-hosted spectro-kernel MCP cloud running embed_pretrained server-side) can be plugged in. The user is responsible for the endpoint URL and (optionally) an API key; the kernel doesn't ship any defaults. v2.0.0: masked (Spectrum1D.mask) and non-finite samples make the brick fail before any request is sent, like the local recipes — replace bad pixels first (clip_sigma / clip_cosmic_rays interpolate over them).\n\nParameters — pass as the 'params' object:\n- endpoint (default None) [required]: Full HTTPS URL of the inference endpoint (REQUIRED).\n- model (default 'default'): Model identifier passed in the request body.\n- api_key (default None): Bearer token for the endpoint. Falls back to the SPECTRO_EMBED_API_KEY environment variable when null (on a shared server only for hosts listed in SPECTRO_EMBED_ENDPOINT_ALLOW).\n- dim (default 256): Requested output dimension (the server may ignore this hint).\n- timeout_s (default 30.0): HTTP request timeout in seconds (default 30).\n\nRequires in the session context: spectrum\n\nBackend: httpx.\nReferences: MCP-style stateless inference endpoints — see e.g. HuggingFace Inference API, OpenAI embedding endpoints, Replicate.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Embed a spectrum via a remote HTTPS inference endpoint.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_remote/" }, { "name": "embed_spectrum", "description": "Compute a fixed-length, L2-normalised embedding of a spectrum.\n\nThe actual maths lives in ``spectro_kernel.embeddings`` so a downstream service can batch-embed thousands of spectra without paying the per-call audit-trail overhead — but go through this algorithm if you want the ProcessingStep + content-hash record alongside the vector. Older strategy names ('pca', 'autoencoder') still work but emit a DeprecationWarning. Non-finite samples (NaN/inf) make the brick fail cleanly: the recipes act on the sample index, so bad pixels cannot be dropped — replace them first (clip_sigma / clip_cosmic_rays interpolate over outliers). v2.0.0: masked samples (Spectrum1D.mask) are refused the same way, since ignoring them is impossible here.\n\nParameters — pass as the 'params' object:\n- dim (default 256): Output vector length (positive integer).\n- strategy (default 'naive'): Embedding recipe: one of ('naive', 'dct', 'multiscale_dct'). Older names 'pca' and 'autoencoder' are accepted as aliases with a DeprecationWarning.\n- norm_method (default 'min_max'): Pre-embedding flux normalisation: one of ('none', 'min_max', 'z_score', 'continuum'). ``none`` skips normalisation (useful when the spectrum is already normalised by an upstream pipeline step).\n\nRequires in the session context: spectrum\n\nBackend: scipy.\nReferences: Ahmed, Natarajan & Rao 1974, 'Discrete Cosine Transform', IEEE Trans. Computers, C-23, 90.; Bu et al. 2014, ApJS, 211, 28 — z-score standardisation for spectra.; Sharma et al. 2020, MNRAS, 491, 2280 — min-max rescaling of stellar spectra.; Sanchez-Saez et al. 2021, AJ, 162, 206 — spectral representations for anomaly detection.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Compute a fixed-length, L2-normalised embedding of a spectrum.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_spectrum/" }, { "name": "embed_wavelets", "description": "Embed a spectrum via a truncated discrete wavelet transform.\n\nReturns the first ``dim`` coefficients of the concatenated multi-level decomposition (approximation + level-L details + level-(L-1) details + … + level-1 details), zero-padded when the decomposition is shorter than dim, then L2-normalised. The ordering is stable: each output dimension always represents the same wavelet coefficient across all spectra, so cosine similarity is meaningful. Non-finite samples (NaN/inf) make the brick fail cleanly — the transform acts on the sample index, so bad pixels cannot be dropped ; replace them first (clip_sigma / clip_cosmic_rays interpolate over outliers). v3.0.0: masked samples (Spectrum1D.mask) are refused the same way.\n\nParameters — pass as the 'params' object:\n- dim (default 256): Output vector length (positive integer).\n- wavelet (default 'db4'): PyWavelets family name. Sensible choices: 'db1' (Haar - sharpest), 'db4' (default, smooth), 'sym8', 'coif5'.\n- level (default 5): Number of wavelet decomposition levels. Higher = coarser scales captured; bounded by log2(npix).\n\nRequires in the session context: spectrum\n\nBackend: pywavelets.\nReferences: Daubechies 1992, 'Ten Lectures on Wavelets', SIAM.; Mallat 2008, 'A Wavelet Tour of Signal Processing'.; Starck & Murtagh 2002, 'Astronomical Image and Data Analysis' — wavelet methods on astronomical signals.", "input_schema": { "additionalProperties": false, "properties": { "session_id": { "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null } }, "required": [ "session_id" ], "type": "object" }, "output_schema": { "additionalProperties": true, "type": "object" }, "kind": "algorithm", "category": "embedding", "category_title": "Embeddings", "summary": "Embed a spectrum via a truncated discrete wavelet transform.", "docs_url": "https://docs.spectrokernel.io/algorithms/embedding/embed_wavelets/" }, { "name": "equivalent_width", "description": "Measure a line's equivalent width without assuming a profile shape.\n\nEW = ∫(1 − F/Fc) dλ over [centre − window, centre + window] with Fc a straight line through the outer `continuum_fraction` of the window on each side (trapezoidal integration on the actual wavelengths). metrics['equivalent_width_angstrom'] is kept as the flat key (last call wins) ; v1.1.0 also writes metrics['equivalent_width_angstrom[