Skip to content

src/core/model.js ​

Parameter registry and likelihood construction shared by the UI, the worker and the tests.

Import: import { … } from './src/core/model.js' — no DOM, runs in Node and the browser.

PARAMS ​

js
const PARAMS

No description in the source.

STAR_PARAMS ​

js
const STAR_PARAMS

Stellar parameters that can be sampled when limb darkening is tied to the star.

autoSupersample ​

js
function autoSupersample(exptimeDays, values)

Sub-samples per exposure needed to resolve ingress: none while the exposure is short compared with ingress, otherwise an odd count giving steps under a third of it.

RV_PARAMS ​

js
const RV_PARAMS

Parameters of the star's motion and of each radial-velocity dataset, and the stellar mass and radius that turn periods and planet masses into orbit sizes when a/R* follows from Kepler's law.

MASS_PARAMS ​

js
const MASS_PARAMS

No description in the source.

ECC_PARAMS ​

js
const ECC_PARAMS

Optional parameterisation of the eccentricity: when both are defined for a planet they replace its ecc and omega.

LC_PARAMS ​

js
const LC_PARAMS

Optional terms of the light curve: extra white noise (per epoch, "jitlc@2") and light of other stars in the aperture.

RM_PARAMS ​

js
const RM_PARAMS

Rossiter–McLaughlin effect (rm.js): on when "vsini" is set; lambda is planet-scoped ("lambda@c") and falls back to the plain key.

ALIAS_PARAMS ​

js
const ALIAS_PARAMS
text
Period alias of a planet seen in a few widely spaced transits (aliases.js): P = palias / nalias, nalias a whole number
with a categorical prior over the aliases the data allow. Planet-scoped ("nalias@d"); on when nalias has a value or is free.

PARAM_BY_KEY ​

js
const PARAM_BY_KEY

No description in the source.

phaseKeysFor ​

js
function phaseKeysFor(ph = {})

Which phase-curve parameters a planet has for a phase description { mode: 'harmonic' | 'map', lmax }.

planetKey ​

js
const planetKey

Key of a planet-level parameter: the first planet (suffix '') is unscoped, others are "name@c".

jitterKey ​

js
const jitterKey

Key of the jitter of radial-velocity dataset d (0-based).

epochKey ​

js
const epochKey

Key of the airmass coefficient of epoch s (0-based) in a dataset with several epochs.

lcJitterKey ​

js
const lcJitterKey

Key of the light-curve jitter of epoch s (0-based) of nSeg epochs: "jitlc" for a single light curve, else "jitlc@<s+1>".

paramFor ​

js
const paramFor

Registry entry for a key, including per-epoch keys such as "a2@3".

activeParams ​

js
function activeParams(ldLaw, air, opts = {})
text
Which registry keys are active, and their display names. Every entry carries `group`
('planet' | 'ld' | 'baseline' | 'rv' | 'star'), `base` (the unscoped registry key) and, for planets, `planet` (its suffix).
air: true/false for a single light curve, or one flag per epoch. With several epochs each
     epoch that has an airmass column gets its own coefficient, "a2@1", "a2@2", ...
opts.planets: [{ sfx, letter }], the first with sfx '' (plain keys); others get "per@c", ...
opts.kepler:  a/R* follows from Kepler's law, so `ars` is not a parameter and M*, R* are
opts.mass:    list the planet mass (needed with velocities or opts.kepler)
opts.rv:      names of the radial-velocity datasets; adds the trend terms and one jitter each
opts.moons:   suffixes of the planets that have a moon; adds that moon's radius, period, phase, mass ratio and tilt
opts.phase:   { [sfx]: { mode, lmax } } for the planets whose own light is modelled (eclipse, phase curve, map)
opts.lcJitter: light-curve jitter, "jitlc" (or one per epoch, "jitlc@1", ...)   opts.dilution: one shared "dil"
opts.rm:      Rossiter–McLaughlin: "vsini" and each planet's "lambda" (group 'rv')
opts.alias:   suffixes of the planets whose period is an alias, palias / nalias: those two replace "per"

toTransitParams ​

js
function toTransitParams(v, ldLaw)
text
values {rprs, ars, ..., ld0..ld3} -> params object for makeTransit

A1_PRIOR_WIDTH ​

js
const A1_PRIOR_WIDTH

Width of the uniform prior on the baseline normalisation a1 ~ U(0, A1_PRIOR_WIDTH).

REG_PRIOR_WIDTH ​

js
const REG_PRIOR_WIDTH

Width of the uniform prior on each coefficient of a linear regressor (data.regressors), c ~ U(-W/2, W/2).

GAMMA_PRIOR_WIDTH ​

js
const GAMMA_PRIOR_WIDTH

Width of the uniform prior on each radial-velocity zero point, gamma ~ U(-W/2, W/2), in m/s.

PLANET_FIELDS ​

js
const PLANET_FIELDS

Planet-level fields that may carry a planet scope, e.g. "per@c".

buildProblem ​

js
function buildProblem(spec)
text
Build the likelihood for a fit specification.
spec = { data: {t, f, e, airmass?, epoch?, segments?} | null, values, ldLaw, free: [{key, prior}],
         exptime, supersample, ldTie,
         planets?: ['', 'c', ...], kepler?: bool, rv?: [{t, v, e}], rvTref?, timing?: [{planet, kind, t, e}], timingNoise? }

Light curve:   flux = a1 * exp(a2 * airmass) * product over planets of transit_p(t)

a1 enters linearly, so it is integrated out analytically instead of being
sampled (EXOTIC takes the median of data/model):
    int exp(-chi2(a1)/2) da1 = exp(-chi2_min/2) * sqrt(2 pi / sum(m^2/sigma^2))
divided by the prior width. lnL also carries the ln(sigma) normalisation, so
the evidence returned by the sampler is a properly normalised marginal
likelihood that can be compared between models fitted to the same data.

Several epochs (nights, orbits, instruments observing the same star): data.epoch gives each
point's epoch index 0..n-1. The transits are shared; every epoch s has its own normalisation
a1_s and its own airmass coefficient, read from values["a2@" + (s+1)] and falling back to
values.a2 (a single light curve only ever reads values.a2). An epoch may carry its own
exposure (segments[s].exptime in days, segments[s].supersample). The likelihood is the
product over epochs, each with its a1 integrated out.

Linear regressors (systematics): data.regressors = [x_1, x_2, ...], each one value per point (time for a visit-long
slope, time squared, a centroid, ...), centred and scaled to order one within each epoch by the caller. The baseline
of epoch s is then  exp(a2 airmass) * (a1_s + sum_k c_sk x_k):  every epoch has its own coefficients, and because they
enter linearly like a1 they are integrated out together with it,
    int exp(-chi2/2) d^p beta = exp(-chi2_min/2) * sqrt((2 pi)^p / det A),   A = G^T W G,  G = model x [1, x_1, ...],
each c with the flat prior U(-REG_PRIOR_WIDTH/2, REG_PRIOR_WIDTH/2). Regressors that are collinear within an epoch
(a constant column, two copies) make A singular and the point is rejected.

Nearest-neighbour kernel regression (systematics as a function of detector state): data.kernel = gaussianWeights(...)
from detrend.js ({ idx, w, k, n }, the k neighbours of every point in a feature space and their Gaussian weights). At
every evaluation the model m_i (transits x airmass term) is multiplied by S_i = sum_q w_iq f_j / m_j over the
neighbours j of i (EXOTIC's lc_fitter with features, Knutson et al. 2012, Lewis et al. 2013); a1 (and any regressors)
are then integrated out as before, with a1 close to 1 because S carries the normalisation. S depends on the data, so
the "likelihood" is the usual Gaussian one of these papers, not a generative model; its evidence is not comparable
with a fit without the kernel.

Light-curve jitter: values.jitlc [ppm] (several epochs: "jitlc@<s+1>", falling back to jitlc) is white noise added in
quadrature, sigma_i^2 = e_i^2 + jit_s^2. The weights and the normalisation -1/2 sum ln(2 pi sigma_i^2) then change with
it, which is what keeps it from growing freely; chi2ic adds sum ln(sigma_i^2 / e_i^2) as for the velocity jitter.

Dilution (third light): values.dil = d, the flux of other stars in the aperture over the target's (several epochs:
"dil@<s+1>", falling back to dil). The astrophysical model m (transits, the planets' own light, a moon) is replaced by
    (m + d) / (1 + d)
before the airmass term, the regressors and the kernel: out of transit it is still 1 and every depth is divided by
1 + d. In the other common convention, the fraction D of the light in the aperture that is not the target's
(1 - CROWDSAP for TESS), d = D / (1 - D).

Several planets: spec.planets lists key suffixes. The first planet is '' and reads the plain
keys (rprs, per, ...); planet 'c' reads "rprs@c", "per@c", ... and falls back to the plain key
for anything not given. Limb darkening belongs to the star and is shared.

A planet's own light: when values has "fpfs" (or "fpfs@c"), that planet's curve is the transit, the eclipse and the
phase curve of phasecurve.js, with spec.phase = { mode: 'harmonic' | 'map', lmax, ltt, angle, positive_map }.
A planet with a moon: when values has "rmoon" (or "rmoon@c"), that planet's transit is the planet-moon model of
exomoon.js (the pair about its barycentre, the union of the two discs on the star). An unbound or overlapping
configuration is outside the prior.

spec.kepler: a/R* of each planet is not a parameter but follows from Kepler's third law with
values.mstar [M Sun], values.rstar [R Sun] and the planet's mass, so photometry, velocities
and timing describe one orbit.

Radial velocities: v = gamma_d + sum_p K_p [cos(omega + nu) + e cos omega] + rvlin (t - tref) + rvquad (t - tref)^2
with K_p from "K" when given, else from mplanet, mstar, P, e, i (rv.js). Each dataset d has its
own zero point gamma_d, integrated out analytically like a1, and its own jitter "jit@rv<d>"
added in quadrature to the errors (the normalisation term keeps it from growing freely).
Rossiter–McLaughlin: when values.vsini [km/s] is set, every planet in front of the star adds the anomaly of rm.js
(flux-weighted velocity of the uncovered disc, integrated over the occulted area) with its projected obliquity
"lambda" (planet-scoped, falling back to the plain key, default 0) and its Rp/R*. Limb darkening is the fit's
(ld0..ld3 with spec.ldLaw) unless spec.rm = { ldLaw, ld } gives the spectrograph's band. With spec.nbody the anomaly
uses the Keplerian sky positions. Options of spec.rm (all off by default):
  method: 'ccf' with beta (km/s, dispersion of the local line: instrumental + thermal), zeta (km/s, macroturbulence,
          Gaussian approximation), beta0 (km/s, the measured out-of-transit CCF width; modelled when absent): the anomaly
          a Gaussian fit to the cross-correlation function measures (Hirano et al. 2010, Boué et al. 2013) instead of
          the first moment of the light;
  exptime (days; or each dataset's rv[d].exptime) and supersample (default 5): the anomaly averaged over the exposure
          (the Keplerian part is not averaged: its curvature over minutes is negligible).
A catalogue v sin i enters as an ordinary prior on "vsini" (rm.js vsiniPrior: normal truncated at 0).

spec.nbody = { epoch, event, dt, stepsPerOrbit, integrator, exactSync, corrector, photo, ltt, elements, linear }: the planets pull on
each other. Mid-transit and mid-eclipse times, radial velocities and the light curve then come from one N-body integration
(nbody.js) started from the planets' parameters, read as osculating elements at `epoch` (same time system as tmid). Every
planet needs a mass and the star its mass. With all planet masses zero this is the Keplerian model.
  Light curve (photodynamics; nbody.photo: false keeps Keplerian curves): each planet's sky position relative to the star is
  interpolated from the integration and passed to the transit kernel of transit.js, through the same exposure averaging.
  Needs R*: values.rstar, or without spec.kepler the first planet's orbit size divided by its a/R* (the other planets' a/R*
  are then not used). Planets are treated one at a time (the area two planets share on the disc is counted twice); a planet
  with its own light (fpfs) or a moon keeps its Keplerian curve.
  nbody.ltt: light-travel time across the system, referred to the plane through the barycentre: a transit is seen about
  a/c earlier than the geometric one and an eclipse a/c later (light curve and times alike).
  nbody.elements: 'mean' reads each planet's per and tmid as the straight line through its simulated mid-transit times over
  the span of the data (the observed ephemeris) and finds the osculating values by iteration (osculatingFromMean in nbody.js);
  these are nearly uncorrelated with the companions' parameters, so they can be sampled.
  nbody.linear: each planet's simulated times are shifted and stretched by a best-fitting straight line in epoch (profiled),
  so the T0 and period of a planet with times need not be sampled. Times only: leave it off when a light curve is in the fit.

Timing: mid-transit or mid-eclipse times of a planet, compared with tmid + E P (or the
superior conjunction + E P), E the nearest whole orbit; spec.timingNoise [d] is added in quadrature.

infoCriteria ​

js
function infoCriteria(chi2, k, n)
text
Information criteria: BIC = -2 ln L_max + k ln n, AIC = -2 ln L_max + 2k, with -2 ln L_max = chi2 + const. The constant is the
same for every model of the same data only while the error bars are fixed: with a free jitter pass detail().chi2ic
(chi2 + sum ln(1 + jitter^2 / sigma^2)) instead of chi2, or a model that inflates its errors always wins. redChi2 = chi2 / (n - k)
is meaningful with the plain chi2 only, and k must count the analytically fitted terms (prob.nlinear).

Also exported ​

MOON_PARAMS, moonKey, PHASE_PARAMS, PHASE_FIELDS, derived

MIT licensed · Kyle A. Pearson