MuSCAT-db Pipeline Workflow

The database is a SQLite file (muscat.db) that stores observation metadata extracted from FITS headers. The pipeline has two stages:

1. Scan — muscat-db scan <inst> <yymmdd> reads every FITS file in the raw data directory, extracts HEADER keywords (OBJECT, FILTER, RA, DEC, EXPTIME, etc.), and writes a CSV log per CCD under $MUSCAT_OBSLOG_DIR (default $HOME/muscat/obslog). Calibration frames (bias, dark, flat) are excluded; only science frames are recorded.
2. Build — muscat-db build-db ingests all scanned CSV logs into SQLite with indexes on instrument, date, object, and filter. The resulting DB powers the web GUI's browse, search, and target discovery features.

The DB also persists background job state (photometry and transit fit runs), submitted LCO request IDs and monitoring progress, and guarded test-observation plans. The LCO monitor resumes after a server restart and uses a database lease so multiple web workers do not duplicate API polling, downloads, or ingestion.

The database is rebuilt automatically once per day at 5:00 PM local time via a cronjob:

30 17 * * * cd /path/to/muscat-db && uv run muscat-db build-db >> logs/build-db.log 2>&1

This re-scans all CSV observation logs under $MUSCAT_OBSLOG_DIR and rebuilds the summaries and targets tables to reflect any new or corrected scans. Log output is written to logs/build-db.log for troubleshooting.

To trigger a manual rebuild at any time, run muscat-db build-db from the repo root.

The prose pipeline processes calibrated FITS frames through a sequence of steps:

1. Band grouping — science frames are sorted into photometric bands using the FILTER header keyword
2. Reference construction — one real frame remains the alignment anchor: by default the first frame (self-reference) or the middle frame of the reference band (--ref_band); with --ref_select quality, the pipeline selects a clean anchor and uses registered catalogs from nearby candidates to reject transient detections (see FAQ below)
3. Source detection — point sources are identified on the anchor; quality mode retains only sources that recur across the candidate catalogs
4. Target identification — the target is located via WCS matching against the resolved sky coordinates (from MAST/SIMBAD name resolution)
5. Gaia-based aperture sizing — annulus and aperture radii are set to avoid contaminating sources
6. Parallel reduction — each frame is aligned, centroided, and photometered in parallel
7. Differential photometry — automatic selection and weighting of comparison stars (Broeg et al. 2005)
8. Time correction — JD-UTC is converted to BJD-TDB
9. Export — per-band CSV lightcurves, PNG diagnostics, optional GIF animation

By default (position) the reference frame is chosen positionally — the first frame for self-reference, or the middle frame of the reference band when --ref_band is set — with no check on whether that frame is actually any good (clouds, poor focus, and high airmass can all silently become the reference). --ref_select quality replaces this with a two-tier pre-check that runs before the full reduction:

1. Header triage (Tier 1, MuSCAT3/MuSCAT4/Sinistro only) — every frame's header is scanned without reading pixel data for BANZAI's per-frame FWHM estimate (L1FWHM), airmass, focus position, humidity, and background level. Frames with physically broken values (e.g. airmass > 3.5, humidity > 95%) are excluded, and a composite score dominated by FWHM identifies the best-quality anchor. The candidate window is then formed from viable frames nearest that anchor in time, limiting telescope drift.
2. Pixel validation and persistence (Tier 2, all instruments) — the local candidates (--ref_select_top_k, default 5) are run through the normal source-detection pipeline in parallel and ranked using target match, non-outlier star count, measured FWHM, and target saturation. Their catalogs are registered to the selected anchor, and a detection is retained only when it occurs in at least 60% of the registered catalogs (3 of 5 by default). This removes one-frame cosmic-ray and hot-pixel detections while preserving the WCS-selected or explicit target. MuSCAT/MuSCAT2 use a local window around the positional midpoint because they lack the BANZAI header proxy.

An explicit Reference frame ID always overrides quality selection. If fewer than two candidate catalogs can be registered, the pipeline safely keeps the anchor catalog instead of applying an unreliable persistence filter. The chosen frame, candidate comparison, registration status, and persistence counts are written to a *_ref_selection.txt sidecar (linked from the results page as "view ref selection") so the decision can be audited without re-running anything. Quality mode adds work roughly proportional to top-K, so it remains opt-in.

The automatic differential photometry algorithm (implemented in prose) optimally selects and weights comparison stars to minimize the scatter in the target's differential lightcurve:

1. Candidate pool — all detected stars (excluding the target) are considered as potential comparison stars
2. Iterative selection — starting with a first guess of the target lightcurve, the algorithm iterates between:
   • Building an optimal reference lightcurve as a weighted average of comparison stars
   • Computing the target's differential lightcurve by dividing its raw flux by this reference
   • Updating the comparison star weights based on their correlation with the current reference
3. Weights — stars with lower intrinsic scatter and higher correlation receive higher weights. To ensure robustness against outliers (e.g. cosmic rays, transient spikes), the weights are computed using a robust scale estimator, the Median Absolute Deviation (MAD) (i.e. weight $\propto 1/\text{MAD}$), rather than the standard deviation.
4. Convergence — the iteration continues until the target lightcurve stabilizes, typically within a few iterations

The key advantage is that no manual selection of comparison stars is needed — the algorithm handles both the choice and the relative weighting, and it can exclude bad comparison stars that would otherwise introduce noise.

The NaN Limitation: The matrix-based implementation of autodiff in prose requires a dense matrix with no NaNs. Because of this, we cannot easily mask out localized outliers (like a cosmic ray hitting a single comparison star on a single frame) by setting them to NaN without propagating that NaN to all other stars through the matrix multiplications.

Proposed Fix (Imputation): Instead of dropping the entire frame (which is wasteful) or using NaNs (which breaks the algebra), we can apply star-level sigma clipping on the flux matrix and impute/replace individual outlier points with the median flux of that star before running the autodiff calculation.

Implications:

• Zero Data Loss: We preserve the target and all other comparison stars' data at that epoch rather than throwing the whole frame away.
• No Outlier Propagation: Since the outlier is replaced by the median, it does not leak into the weighted artificial lightcurve and pollute other stars' differential lightcurves.
• Matrix Compatibility: The matrix remains fully dense and compatible with the vectorized NumPy operations.

The comparison stars used to compute the differential lightcurve of the target are determined as follows:

• max_num_stars Relation — During source detection, the pipeline is configured to detect and track exactly up to max_num_stars (default 10) of the brightest point sources across all frames. All comparison star candidates are chosen from this subset of tracked stars.
• Manual Selection — If explicit comparison star indices (--cID) are provided by the user, the pipeline validates that they are in-range and do not belong to the avoided/excluded list before using them directly.
• Automatic Selection (Broeg et al. 2005) — If no explicit IDs are provided, the pipeline executes the autodiff() algorithm. This algorithm dynamically determines and weights comparison stars from the candidate pool (excluding the target and any avoided stars) to minimize the scatter in the target's differential lightcurve.
• Avoided Stars — Stars can be manually excluded via --avoid_cids. Additionally, the pipeline automatically detects stars near the CCD edge (edge_cids) and adds them to the avoid pool to prevent edge-effect systematics from contaminating the comparison pool.

Optimal Comparison Stars:

• Candidate Pool: Taken from the tracked sources (up to max_num_stars), excluding the target and avoided stars.
• Iterative Weighting: The Broeg et al. 2005 algorithm assigns weights to each candidate star inversely proportional to their Median Absolute Deviation (MAD) (i.e., $w \propto 1/\text{MAD}$). Using MAD instead of standard deviation prevents transient outliers (like cosmic rays or hot pixels) from skewing the weight.
• Combination Optimization: Comparison stars are sorted by weight. The pipeline (in auto_diff_1d) starts with the highest-weighted star, iteratively adding the next-highest, and computes the binned white noise (binned_nanstd) of the target's resulting differential lightcurve. It retains the subset of comparison stars that minimizes this white noise.

Optimal Aperture Size:

• Aperture Grid: The pipeline runs photometry on a series of aperture radii (either defined by Gaia heuristics or custom parameters).
• Outlier Filtering: During evaluation, points that are $> 4\sigma$ from the median are temporarily clipped to avoid biasing the aperture metric.
• Noise Minimization (stddiff): For each aperture, the standard deviation of successive differences ($\sigma(\Delta f)$) is computed. This acts as a high-pass filter to remove slow trends (red noise, systematics, or the transit itself) and focus purely on high-frequency white noise. The aperture size that minimizes this metric is selected as the optimal aperture.

• Test run — processes only the first 10 frames per band (configurable via --test_run_frames). The pipeline runs all stages (alignment, source detection, centroiding, photometry) but produces a short lightcurve. Used to verify settings, check alignment quality, and preview results before committing to a full reduction.
• Full run — processes every science frame in the data directory. Required for publishable lightcurves and transit fitting.

You can always re-run with --overwrite to replace a test run with a full run later.

• Reference image (*_ref.png) — the stacked reference frame with detected sources circled and the target marked. Verifies that sources are correctly identified and the target is at the right position.
• Apertures (*_apertures.png) — overplot of aperture radii and sky annuli on the reference. Check that the inner annulus excludes nearby stars and the outer annulus is within clean sky.
• Alignment (*_alignment.png) — shows the shift (dx, dy) computed for each frame relative to the reference. Large or discontinuous shifts may indicate guiding problems or a bad reference frame.
• Lightcurves (lightcurves.png) — multi-band raw and differential lightcurves side by side. The raw flux should be stable; the differential should be flat for non-variable targets. Trends in the differential suggest poor comparison star selection.
• Covariates (covariates.png) — systematics summary: FWHM, airmass, background, and centroid positions across the sequence. Correlations between these and the lightcurve can guide detrending choices.
• Stacks (stacks.png) — grouped thumbnail grid of one cutout per frame per band to quickly flag outliers (cosmic rays, clouds, tracking losses).

The pipeline queries the Gaia DR3 catalog around the target position to identify contaminating sources:

• Annulus sizing — the inner radius (R_in) is set to 6 × FWHM, the outer (R_out) to 10 × FWHM (capped at 100 pix). These values are then adjusted inward if a Gaia source brighter than 10% of the target flux falls within the annulus.
• Aperture grid — a series of radii from 1 × FWHM up to R_in in 2-pixel steps is generated, and the one that minimizes scatter on the brightest stars is selected individually per image.

When to override: for crowded fields where Gaia sources are too numerous (the annulus becomes unusably small), or for isolated bright targets where the heuristic is overly conservative. Use --aper_radii MIN,MAX,DR and --annulus RIN,ROUT to set custom values.

WCS (World Coordinate System) maps pixel coordinates to sky coordinates (RA, Dec). The pipeline needs it for two things:

• Target identification — the resolved target coordinates (from MAST/SIMBAD name resolution) are projected onto the image via WCS to locate the target's pixel position among the detected sources. Without WCS, the pipeline cannot automatically identify which star is the target.
• Gaia query — the target's sky position is used to query Gaia DR3 around the field for contamination analysis.

If WCS is missing from calibrated headers, --target_coord RA Dec can be passed instead — but source identification then relies on source ordering (brightest = target), which is unreliable for crowded fields.

The pipeline converts observation times from JD-UTC to BJD-TDB to remove the light-travel time variation caused by Earth's orbital motion around the Solar System barycenter:

• Default method — astropy's light_travel_time function computes the barycentric correction using the target's sky coordinates and the observatory geocentric position (derived from the FITS header's SITE keyword or instrument defaults like Teide Observatory for MuSCAT2).
• barycorrpy option — when --use_barycorrpy is enabled, the barycorrpy package (a Python wrapper for Jason Eastman's barycorr) is used instead. It accounts for additional effects including Shapiro delay and Earth's precession/nutation.

The difference between the two methods is typically <0.1 seconds for MuSCAT observing cadences. barycorrpy is recommended for sub-minute transit timing measurements.

The pipeline identifies the target star among all detected sources by matching the resolved target coordinates (from MAST) against the WCS-transformed positions of every detected source, selecting the nearest match within a tolerance.

When to override — if the WCS solution is poor, if the field contains multiple stars at similar coordinates, or if MAST resolution failed and the fallback assumed the brightest star is the target. Set --tID N where N is the 0-indexed source number from the reference image (circled labels on the *_ref.png plot).

The pipeline auto-detects narrow-band observations by inspecting the obslog CSVs for known narrow-band filter names (g_narrow, Na_D, i_narrow, z_narrow). When narrow bands are present:

• The default band list is expanded from the four broadband filters (gp, rp, ip, zs) to include all detected narrow bands.
• Narrow-band frames are reduced with the same pipeline steps (alignment, centroiding, photometry) as broadband frames.
• Products are named with the narrow-band token so they don't collide with broadband outputs.

To override the auto-detection, specify bands explicitly with --bands gp rp Na_D.

Give the reduction a distinct Run name to isolate it under $MUSCAT_PROSE_DIR/<instrument>/<date>/_runs/<target>/<run_id>/. Run chips on the results page switch between saved reductions. The --overwrite option (enabled by default in the GUI) only replaces products in the selected run, which is useful when retrying the same configuration with changed apertures, bands, or reference settings. Use a new run name whenever the previous products must remain intact.

Both the photometry and transit-fit result pages have a Download all output button. It calls a server-side endpoint (/api/photometry/download-all/... or /api/transit-fit/download-all/...) that zips every product file for that run into a single archive and streams it back — no need to download plots and CSVs one at a time. For run-scoped reductions the zip walks the run directory recursively; legacy (non run-scoped) reductions zip the top-level files plus the out/ subdirectory. The temporary zip is written under the pipeline's tmpdir and deleted immediately after the response finishes streaming.

Default parameters are defined in src/muscat_db/photometry.py in the RUN_DEFAULTS dictionary. Key defaults:

• bands: gp, rp, ip, zs
• aper_radii: auto (Gaia heuristic)
• annulus: auto (Gaia heuristic)
• aper_unit: pix
• max_num_stars: 10
• min_star_separation: 10.0 pix
• avoid_nearby_star_mode: auto (max(2 x FWHM, 3 arcsec))
• cutout_size: 35 pix
• bin_size_minutes: 10.0
• gif_stride: 100
• test_run_frames: 10
• make_gif: True
• overwrite: True

These can be overridden individually in the GUI form or via command-line flags.

• pix — aperture radii and annulus dimensions are specified and applied in absolute pixel units. The same pixel values are used for every frame regardless of seeing conditions.
• fwhm — radii are specified as multiples of the FWHM measured on each frame. This adapts the aperture size to the actual seeing: in good seeing (small FWHM), the aperture shrinks to exclude more sky; in poor seeing (large FWHM), it expands to capture more of the star's flux.

Use pix when the PSF is stable and you want a fixed physical aperture. Use fwhm when seeing varies significantly across the sequence — it produces more consistent photometry at the cost of slightly more complex interpretation.

The pipeline reads the saturation level from the FITS header (SATURATE keyword or BSCALE/DATAMAX). During source detection, pixels above a configurable fraction of the saturation level are flagged. However:

• Detection — saturated sources are still detected but their centroids may be biased. The pipeline uses Gaussian2D centroiding which degrades on saturated cores.
• Photometry — aperture photometry on saturated stars underestimates the true flux because flux is lost in the saturated core. The pipeline does not apply a non-linearity correction.
• Comparison stars — the autodiff algorithm will naturally down-weight saturated comparison stars because they produce noisier differential lightcurves.

For heavily saturated targets, use shorter exposure sequences or apply a non-linearity correction externally before running the pipeline.

The --ref_band flag controls whether all bands are aligned to a single reference band or each band self-references its own first frame:

• Per-band self-reference (default, --ref_band not set) — each band creates its own reference frame from its first science frame. Alignment is within-camera only. Recommended for multi-camera instruments (MuSCAT3/4) where each band uses a separate CCD, because cross-camera registration would introduce interpolation artifacts from slightly different pointing and distortion.
• Single reference (--ref_band gp for example) — all bands align to the reference band's middle frame. This can introduce systematic offsets between bands because different cameras have different pixel scales, rotations, and distortions. The resulting lightcurves may show band-dependent systematics.

For MuSCAT2 (single CCD with filter wheel), both strategies work because all bands share the same detector. Per-band self-reference is still the default and generally recommended. For Sinistro, --ref_band is disabled in the GUI because simultaneous bands can be observed by different LCO telescopes with large pointing offsets, so mapping one band's reference catalog onto another can fail or produce invalid alignment.

The timer transit fitting pipeline models the transit lightcurve using PyMC's NUTS sampler:

1. Configuration — YAML files (fit.yaml, sys.yaml) specify stellar and planetary parameters, priors, detrending covariates, and sampler settings.
2. Data loading — photometry CSVs are read and merged with covariate data (FWHM, airmass, centroid offsets).
3. Prior initialization — stellar parameters (Teff, logg, metallicity) are sourced from the TOI catalog or manually entered; planetary priors (period, T0, duration, impact parameter) are set from known ephemerides or the TOI catalog.
4. Model assembly — a PyMC model is built with the transit model (batman or starry), limb darkening (quadratic or nonlinear), and systematics model (linear or GP).
5. Pre-optimization — L-BFGS finds the maximum a posteriori (MAP) solution to initialize the sampler.
6. MCMC sampling — NUTS sampler runs multiple chains (default 4) with several thousand tuning and production steps.
7. Post-processing — residual outliers are sigma-clipped, information criteria (BIC, AIC) are computed, and diagnostic plots (corner, trace, LD profile, fit) are generated.

The transit fitting pipeline supports two run modes to handle existing reduction results:

• New Fit (start fresh) — Sets clobber: true in the fit configuration. It discards any previous traces, runs L-BFGS MAP pre-optimization to find an initial solution, and starts MCMC sampling from scratch.
• Continue Sampling — Sets clobber: false. It loads the previous MCMC trace from saved pickle files and resumes sampling, appending new draws to the existing chain. This option is only available when a previous fit run exists.

Check the Secondary eclipse box in the Fitting Pipeline Options section before launching a fit. This sets secondary_eclipse: true in the fit.yaml configuration, which places the modeled event at orbital phase 0.5 rather than phase 0 (the primary transit). It is off by default and is independent of the New Fit / Continue Sampling run mode — combine it with a fresh set of lightcurves centered on the expected eclipse time.

The transit fit page has a Query Archive button that fetches stellar and planetary parameters from two sources:

• TOI Catalog (source=toi) — queries the TESS Objects of Interest table via the Exoplanet Archive TAP service. The target name is cleaned by removing the TOI prefix, leading zeros, and .01 suffix (e.g. TOI07475.01 → 7475), then matched against the toi column with fallback queries on toidisplay and substring matching. Returns Teff, logg, orbital period, transit midpoint, and transit duration.
• NASA Exoplanet Archive (source=nasa) — queries the pscomppars (Planetary Systems Composite Parameters) table by pl_name or hostname. Returns the same parameters plus metallicity, radius ratio, and impact parameter, with literature references.

The fetched values are used to pre-populate the priors in the YAML configuration, which can be edited before running the fit.

The timer transit fitting pipeline used here is distinct from the MuSCAT2 transit pipeline (Parvi et al.). Key differences:

When to use each:

• timer (here) — for rapid, reproducible multi-band transit analysis integrated with the MuSCAT-db photometry pipeline, with flexible detrending and modern Bayesian inference.
• MuSCAT2 pipeline — for standalone MuSCAT2-specific analysis, or when custom analytical models or emcee-specific workflows are preferred.

Both pipelines produce scientifically rigorous results; the choice depends on your data source and workflow integration needs.

There is no separate TTV page. TTV fitting lives on the Ephemeris page, in the Configure & Run TTV Fitting section below the O-C plot. A TTV signal is only meaningful relative to a reference linear ephemeris, so the fit is the last step of the O-C workflow rather than its own destination. The old /ttv-fit URL redirects to /ephemeris.

The harmonic engine fits the multi-harmonic near-resonant TTV model of Lithwick, Xie & Wu (2012), sampled with emcee:

1. Input assembly — transit centers behind the O-C plot (Tc, tc_unc, epoch per planet) are written to data.csv, with planet letters remapped to the integer indices harmonic expects. The dataset checkboxes and point exclusions that shape the linear fit shape the TTV fit too.
2. Configuration — config.ini carries an [INIT] section with the TTV amplitude, super-period, and phase reference (a_bc, a_cb, per_bc, t_bc) for each adjacent pair, plus optional [T14] (transit durations) and [OUTER] (non-transiting outer planet) sections.
3. Launch — options and INI are validated, the run directory is written, and the harmonic CLI runs as a background job in the conda harmonic environment. The exact command is shown in the run panel so it can be reproduced in a terminal.
4. Sampling — emcee runs with the configured walkers, steps, burn-in, thinning, processes, and seed, streaming harmonic.log live to the page. Completed results include a fit run log link that opens the full log in a new tab.
5. Outputs — posterior samples (samples.csv.gz), diagnostic plots (corner.png, trace.png, fit.png, init.png), and meta.yaml recording the muscat-db and harmonic versions plus the full option set.

TTV results are keyed on target alone — not instrument and date, unlike photometry — because a TTV fit spans every transit of that system regardless of which night or instrument produced each transit center. They live under $MUSCAT_TTV_DIR/<target>/_runs/<run_name>/ (default $HOME/ql/harmonic), mirroring the photometry _runs/ convention.

Naming a run keeps it isolated, so you can compare, say, a two-planet fit against a fit with a non-transiting outer planet. The run chips above the results switch between stored runs, and Delete Results is scoped to the run currently on screen rather than the name typed in the box. A run directory without samples.csv.gz is treated as empty and hidden from the chip list.

• Non-transiting outer planet — adds an outer perturber that never transits, inferring its properties from the TTVs it induces on the transiting planets. Requires an [OUTER] section in the INI.
• Phase offsets — lets each planet pair take its own relative phase instead of the default shared anti-phase. The default assumes the two TTV sinusoids are exactly anti-correlated (180° apart), which the Lithwick, Xie & Wu (2012) formalism gives in two limits: TTVs dominated by forced eccentricity, and TTVs dominated by free eccentricity. Between those limits the two contributions become comparable and, because the free-eccentricity term is complex, the pair's amplitudes rotate by different angles and the relative phase departs from 180°. Enable this when the system may sit in that intermediate regime.

The stellar mass field feeds the mass and eccentricity constraints derived from the fitted TTV amplitudes.

Run muscat-db htpasswd add <username> (it prompts for a password) or muscat-db htpasswd add <username> --password-stdin for scripting — never edit the htpasswd file by hand. muscat-db htpasswd list shows current users and muscat-db htpasswd delete <username> removes one. The file lives at /etc/nginx/.htpasswd-muscatdb by default (falling back to data/.htpasswd-muscatdb when nginx isn't installed, e.g. in dev) and is written 0640 root:www-data so only root and nginx's worker group can read the password hashes.

nginx sets X-Forwarded-User after a successful HTTP Basic Auth login and adds a private X-MuSCAT-Proxy-Secret header. In --nginx mode, the middleware requires a loopback peer, a valid username, and the matching proxy secret; protected requests fail with 401 otherwise. This prevents both remote header spoofing and direct local calls to uvicorn from impersonating nginx.

Per-user LCO tokens saved on /settings are encrypted at rest with Fernet symmetric encryption, keyed from MUSCAT_DB_SECRET. If that variable is unset (or changes), saving or reading a token fails with a 503 ("could not save LCO token" / "stored LCO token cannot be read") rather than silently storing or returning it in cleartext. Set a long, random MUSCAT_DB_SECRET before onboarding real users, and keep it stable across restarts (e.g. export it from the service environment or a `.env` file, not an ephemeral interactive shell) — rotating it makes previously-encrypted tokens permanently undecryptable, so affected users must re-save their token.

The FOV Optimizer evaluates possible telescope pointings using a grid-search algorithm over center offsets and position angles (PA). It queries the Gaia DR3 catalog and assigns utility weights to candidate comparison stars based on:

• Magnitude offset — Prefers stars slightly fainter than the target (ideal difference is 0.3 mag). Hard penalties are applied to stars brighter than the target (which would trigger early saturation and limit exposure times).
• Color similarity — Compares Gaia BP-RP colors to the target. Similar colors reduce systematic trends in differential photometry.
• Blending — Stars with close, similarly-bright neighbors (within 12 arcseconds) are penalized because crowding degrades aperture photometry accuracy.

The optimizer selects the center offset and rotation angle that maximize the cumulative weight of the captured stars while keeping the target safely inside the instrument's footprint edge (margin of 30 arcseconds).

An optional avoid brighter than Gmag threshold rejects any candidate pointing whose full footprint contains a star brighter than that limit (the science target itself is exempt). This is useful for steering the field away from a nearby saturating star that would otherwise bleed into the frame or degrade guiding.

• The grid search queries Gaia down to the avoidance magnitude (even if brighter than the normal comparison-star magnitude range) so it knows about every star that must be avoided.
• If every candidate pointing contains at least one too-bright star, the optimizer reports infeasibility explicitly rather than silently returning an unsafe pointing — try a fainter avoidance limit or a larger PA search step.
• Avoided stars are listed in the results (position, Gmag, separation) so you can confirm which sources drove the chosen pointing.

These planning shortcut buttons prefill target and instrument parameters, linking directly to the respective planning tool:

• Show FOV — Redirects to the FOV Optimizer page preloaded with the target coordinates and selected LCO instrument to compute optimal offsets.
• Show Exp — Redirects to the Exposure Calculator page. Under the hood, it queries the target observations history API (/api/exposure/target/{target}) to retrieve unique filters and exposure times previously used.

The exported Observed-minus-Calculated (O-C) summary CSV text now starts with descriptive comment lines (prefixed by #) explaining that the transit center times (TCs) are in Barycentric Dynamical Time (BJD_TDB). This makes it easy for automated scripts and external fitting tools to parse column formats (planet, epoch, tc, tc_unc) and track time-standard coordinates correctly.

Each target-scoped ephemeris field (RA/Dec, T0, period, duration) on the LCO Schedule page shows a small badge indicating where its value came from: NASA or TOI for a catalog lookup, AUTO for a fallback default, LINEAR/FIT for a value derived from a saved ephemeris view's linear fit, or manual once you've hand-edited it.

Switching targets blanks all four fields first — an empty field honestly means "no data for this target" rather than a stale value left over from whatever you looked at previously. Re-querying the same target preserves any field you've tagged manual instead of overwriting it, and a catalog miss no longer blanks coordinates you entered by hand.

LCO validates a request's configuration duration against target visibility across the entire request window, including pre/post padding — not just the bare transit shown in the window generator. Before a dry-run IPP check or live submission, the backend re-checks observability at the selected site over the full padded window and rejects the request with a specific reason (which window index, whether it is partially or fully unobservable, the request span in hours) instead of letting it fail opaquely at LCO.

If a window is flagged, regenerate windows with "Include padding in obs check" enabled, reduce the pre/post padding, pick a different window or site, or loosen the airmass/moon-separation constraints.

The LCO Schedule form and the /toi//nexsci catalog pages encode their current filter/form state into the URL hash fragment as you interact with them (e.g. /lco/schedule#proposal=TOM00001234&target=TOI-2000&kind=muscat3 or /toi#q=TOI-2000&planet=SuperEarth&star=M&sort=period:1), updated in place via history.replaceState() so it never adds browser-history entries.

On load, state is restored with this priority: URL hash > localStorage > built-in defaults. That means bookmarking or sharing the URL reproduces the exact view regardless of what is saved in the visiting browser's localStorage.

The target page has a collapsible NASA ADS Publications panel that queries the ADS search API for papers matching a text query (pre-filled with the target name). It requires an ADS API token — set ADS_API_TOKEN (or ADS_DEV_KEY/ADS_TOKEN) in .env, generated from your ADS token settings. A status dot on the panel shows whether the server has a token configured before you search; results link out to each paper's ADS abstract page by bibcode. No token is ever sent to the browser — the server holds it and proxies the query.

The /toi page left-joins the Boyle+2026 stellar-rotation catalog (final_catalog.feather, matched by TIC ID) onto the TOI table, adding rotation period (P_rot ± uncertainty), RUWE, contaminant/sector stats, and binarity flag columns. The Fast rotator (P_rot < 10 d) chip in the Rotation chip group filters to TOI hosts with a measured period below 10 days — fast-rotating host stars are more likely to show spot-crossing anomalies and higher photometric variability during a transit, which is useful context before scheduling. A dynamic note near the chip reports how many of the currently filtered targets have a measured P_rot, with a link to the source paper (arXiv:2603.05586).

The exposure calculator fits empirical coefficients (using muscat-db build-db or calibration runs) to predict how many stellar photoelectrons will hit the CCD per second for a star of a given magnitude. It then applies standard CCD noise models (Poisson noise of the source, sky background noise, dark current, and read noise) to compute either the exposure time to reach a target S/N or the estimated S/N for a specified exposure time. Key parameters include the instrument aperture, focus offset, and filter transmission band.

The catalog browsers query the SQLite database's targets table on load to compile a list of all objects that have already been ingested into muscat-db. In the Plotly scatter plots, these matched targets are rendered as prominent ★ star markers instead of standard circular dots. In the searchable tables, clicking these rows opens the local target details page, while unmatched catalog rows link out directly to their NASA Exoplanet Archive overview page.

FastAPI automatically generates interactive API documentation for all JSON endpoints:

• Swagger UI — Available at /docs. This interface allows you to interactively test endpoints directly from the browser.
• ReDoc — Available at /redoc. This provides a clean, read-only layout of the API specifications.

Additionally, modern documentation engines like Scalar can be served side-by-side or mounted to override /docs by returning a custom HTMLResponse that fetches the Scalar web components from its official CDN pointing to the /openapi.json schema.