Browser API: window.__esl.api
The analyzer page exposes everything its panels do as plain functions on window.__esl.api. The headless checks, the assistant and your own scripts use the same surface. Every call that changes something is one undo step; a call that cannot do what was asked throws an Error that says why.
Times are days relative to state().lightCurve.timeReference; where a call takes a time, a value above 100000 is read as a Julian date (BJD) and converted.
Try it
The analyzer runs below, from this site. Write JavaScript against api and press Run; return a value to see it. Nothing leaves your browser.
state
api.state() // → objectWhat is loaded and how the fit is set up: planets, data, every parameter with its value, free flag and prior, limb darkening, optional models, sampler, whether a fit is running or finished.
describe
api.describe() // → array of { name, description, args: [{ name, required, schema }], parameters (JSON Schema of the arguments by name), returns }This list: every function of the API with a one-line description and the schema of its arguments.
examples
api.examples() // → array of { id, title, about, kinds, python }The worked examples that can be opened.
loadExample
api.loadExample(id, options?) // → trueOpen a worked example. It opens with a stored posterior unless fresh is true, which builds it from its data instead.
| Argument | Type | Description |
|---|---|---|
id required | string | Example id from examples(). |
options | object | Options. |
options.fresh | boolean | Build the example from its data instead of opening the stored run. |
lookup
api.lookup(name, kinds?) // → trueLoad a planet or host star from the bundled NASA Exoplanet Archive snapshot, with a simulated light curve as a stand-in for data.
| Argument | Type | Description |
|---|---|---|
name required | string | Planet or host name, for example "WASP-12 b". |
kinds | array of string | Kinds of data the analysis is for. |
setValue
api.setValue(key, value) // → nothingSet the value of a model or stellar parameter.
| Argument | Type | Description |
|---|---|---|
key required | string | Parameter key as listed by state().parameters: "rprs", "inc", "tmid", "per", "ecc", "omega", "mplanet", "ld0".."ld3", "a2"; a further planet is scoped by its letter ("per@c"), an epoch or velocity set by its number ("a2@2", "jit@rv1"); star: "teff", "feh", "logg", "mstar", "rstar", and the host’s "ra", "dec" (J2000 degrees: archive searches, time conversion) and 2MASS "jmag", "kmag" (TSM, ESM). |
value required | number | New value. Mid-transit times are days relative to the time reference or, above 100000, a Julian date (BJD), converted; this holds for every planet (tmid, tmid@c) |
setFree
api.setFree(key, free) // → nothingMake a parameter free (sampled in the fit) or hold it fixed. a/R★ can never be free.
| Argument | Type | Description |
|---|---|---|
key required | string | Parameter key as listed by state().parameters: "rprs", "inc", "tmid", "per", "ecc", "omega", "mplanet", "ld0".."ld3", "a2"; a further planet is scoped by its letter ("per@c"), an epoch or velocity set by its number ("a2@2", "jit@rv1"); star: "teff", "feh", "logg", "mstar", "rstar", and the host’s "ra", "dec" (J2000 degrees: archive searches, time conversion) and 2MASS "jmag", "kmag" (TSM, ESM). |
free required | boolean | true to fit it, false to hold it. |
setPrior
api.setPrior(key, prior) // → nothingSet the prior of a parameter. For a mid-transit time (tmid, tmid@c) bounds or a mean above 100000 are read as Julian dates (BJD) and converted.
| Argument | Type | Description |
|---|---|---|
key required | string | Parameter key as listed by state().parameters: "rprs", "inc", "tmid", "per", "ecc", "omega", "mplanet", "ld0".."ld3", "a2"; a further planet is scoped by its letter ("per@c"), an epoch or velocity set by its number ("a2@2", "jit@rv1"); star: "teff", "feh", "logg", "mstar", "rstar", and the host’s "ra", "dec" (J2000 degrees: archive searches, time conversion) and 2MASS "jmag", "kmag" (TSM, ESM). |
prior required | object | A prior: uniform between a and b, or normal with mean a and standard deviation b. |
prior.type required | "uniform" · "normal" | Kind of prior. |
prior.a required | number | Lower bound, or mean. |
prior.b required | number | Upper bound, or standard deviation. |
setUse
api.setUse(use) // → nothingChoose which kinds of data enter the fit.
| Argument | Type | Description |
|---|---|---|
use required | object | Any of the three flags. |
use.lc | boolean | Light curve. |
use.rv | boolean | Radial velocities. |
use.timing | boolean | Mid-transit and mid-eclipse times of the Timing tab. |
setKepler
api.setKepler(on) // → nothingTie a/R★ of every planet to Kepler’s law (M★, R★, period, planet mass) instead of holding a free value. Needed for joint transit and velocity fits.
| Argument | Type | Description |
|---|---|---|
on required | boolean | true to use Kepler’s law. |
setSampler
api.setSampler(settings) // → nothingChange nested-sampling settings.
| Argument | Type | Description |
|---|---|---|
settings required | object | Any of the settings. |
settings.nlive | number | Live points (50 to 4000). |
settings.fracRemain | number | Stop when this fraction of the evidence remains. |
settings.seed | number | Random seed. |
settings.maxCalls | number | Budget of likelihood calls. |
setLimbDarkening
api.setLimbDarkening(options) // → { law, mode, band, coeffs }Change how the star’s limb darkening is described: the law, whether the coefficients are sampled directly or follow the star (T eff, [Fe/H]), the bandpass, and the coefficients themselves.
| Argument | Type | Description |
|---|---|---|
options required | object | Any of the four; at least one. |
options.law | "uniform" · "linear" · "quadratic" · "kipping" · "sqrt" · "nonlinear" | Limb darkening law. |
options.mode | "coeffs" · "star" | "coeffs": the coefficients are parameters; "star": they follow T eff and [Fe/H] through the model-atmosphere table. |
options.band | string or array | Bandpass: a name from state().limbDarkening.bands, or [min, max] in nm for a custom range (200 to 5500). |
options.coeffs | array or string | The coefficients of the law, in order (as many as the law has), or "star" to set them from the stellar parameters and the band (a new band alone leaves the coefficients as they are). |
addPlanet
api.addPlanet(options?) // → the new planet’s letterAdd a planet to the system. Without values it is a copy of the planet on show at 2.3 times its period, to be edited.
| Argument | Type | Description |
|---|---|---|
options | object | Optional letter and starting values. |
options.letter | string | One lowercase letter not in use; the next free one by default. |
options.values | object | Planet parameters by name: rprs, ars, inc, per, tmid, ecc, omega, mplanet (Jupiter masses). |
removePlanet
api.removePlanet(letter) // → nothingRemove a planet (not the first one) with its parameters, moon, own-light model and listed times.
| Argument | Type | Description |
|---|---|---|
letter required | string | Letter of the planet to remove. |
showPlanet
api.showPlanet(letter) // → nothingChoose the planet the sliders, the system view and the folded plots show.
| Argument | Type | Description |
|---|---|---|
letter required | string | Planet letter. |
loadLightCurve
api.loadLightCurve(text, name?) // → { points, notes }Replace the light curve with one read from text (CSV or whitespace columns: time, flux, error, optional airmass; AAVSO and EXOTIC final light-curve files are recognised).
| Argument | Type | Description |
|---|---|---|
text required | string | File contents. |
name | string | Name to show for it. |
addLightCurveEpoch
api.addLightCurveEpoch(text, name?) // → { epochs }Add another light curve of the same planet as a further epoch, fitted together with what is loaded.
| Argument | Type | Description |
|---|---|---|
text required | string | File contents. |
name | string | Name of the epoch. |
addRadialVelocities
api.addRadialVelocities(text, name?) // → array of { name, points }Add radial velocities from text (time, velocity, uncertainty, optional instrument name). Each instrument becomes its own dataset.
| Argument | Type | Description |
|---|---|---|
text required | string | File contents. |
name | string | Name of the set. |
findRadialVelocities
api.findRadialVelocities(name?) // → { star, ra, dec, sets: [{ id, source, catalog, label, instrument, set, points, first, last (BJD), span_days, median_error (m/s), star (the catalogue’s name), separation_arcsec, reference, bibcode, doi, same_as (a source holding the same observations), added }], sources: [{ source, label, status: found|none|error, star, message, mirror, notes }] }Search the public radial-velocity archives (Keck/HIRES: Butler et al. 2017 and its correction by Tal-Or et al. 2019; ESO/HARPS RVBank, Trifonov et al. 2020; Lick, Fischer et al. 2014; all through VizieR) at the host star’s position. Takes a few seconds. Lists every set found, one per instrument era (each has its own zero point); nothing is loaded until addRadialVelocitySet.
| Argument | Type | Description |
|---|---|---|
name | string | Planet or host to search for; default the system on show. A different system is looked up in the catalogue for its position, but its sets can only be added once that system is loaded. |
addRadialVelocitySet
api.addRadialVelocitySet(id) // → array of { name, points, source } for the sets addedAdd one or more sets found by findRadialVelocities as velocity datasets, each with its own zero point and jitter; where they came from (catalogue, reference, bibcode, star name, retrieval time) is kept with the data and saved in the session. Refuses two sources that hold the same observations.
| Argument | Type | Description |
|---|---|---|
id required | string or array | A set id from findRadialVelocities().sets, or an array of them. |
setEccentricityParameters
api.setEccentricityParameters(sqrtE) // → { sqrtE, keys }Sample the eccentricity of the planet on show as e and ω, or as √e cos ω and √e sin ω (keys "secosw", "sesinw"; uniform priors on them are uniform in e and ω, without the edge at e = 0 or the wrap of ω). The orbit and what is free carry over.
| Argument | Type | Description |
|---|---|---|
sqrtE required | boolean | true for √e cos ω, √e sin ω; false for e, ω. |
setupJointFit
api.setupJointFit() // → array of the free parameter keysSet up a joint fit of the light curve, the radial velocities and any listed times: a/R★ from Kepler’s law, all loaded data in the fit, the planet masses, jitters, period, T mid, Rp/R★ and i free (e and ω too for eccentric orbits). Needs velocities and a dated light curve. One undo step.
setDetrend
api.setDetrend(spec) // → { names (linear terms in the model), dropped: [{ name, why }], kernel (its features or null) }Choose the systematics model of the light curve from the detector columns it carries (from the photometry page, or extra columns of a file: xc, yc, sky, fwhm, comp, pld1…): linear terms (each with its own coefficient per epoch, integrated out like the normalisation), a Legendre polynomial in time, PLD components, and a nearest-neighbour kernel on the detector position (built night by night; its ln Z is not comparable with a fit without it). null removes the model.
| Argument | Type | Description |
|---|---|---|
spec required | null or object | null, or the model. |
setTimings
api.setTimings(text) // → { times }Replace the mid-transit times of the planet on show (Timing tab).
| Argument | Type | Description |
|---|---|---|
text required | string | Rows "time, uncertainty" or "epoch, time, uncertainty", times in days (BJD). |
simulate
api.simulate(options?) // → { points, epochs, cadence_min, noise_ppm, span_hr }Replace the light curve with a simulated observation of the current system; the current values become the hidden truth marked on the posterior plot.
| Argument | Type | Description |
|---|---|---|
options | object | Any of the settings; the rest keep their last values. |
options.noise_ppm | number | White noise per exposure, ppm. |
options.cadence_min | number | Cadence, which is also the exposure time, minutes. |
options.span | number | Length of each simulated observation in hours, centred on mid-transit. It must exceed the transit duration. |
options.baseline_hr | number | Alternative to span: out-of-transit time on each side of the transit, hours. |
options.seed | number | Random seed. |
options.epochs | number | Number of transits to observe (1 to 200); more than one makes a multi-epoch dataset. |
options.epoch_step | number | Orbits between one simulated transit and the next. |
options.airmass | boolean | Add an airmass trend, as on a ground-based night. |
editData
api.editData(options) // → { points, removed, epochs, steps }Edit the loaded light curve: remove an epoch, trim to a time window, clip outliers against the current model, bin. Applied in that order. The earlier runs’ evidences stop being comparable.
| Argument | Type | Description |
|---|---|---|
options required | object | At least one edit. |
options.remove_epoch | number | Number of the epoch to remove, counted from 1 as on the Data tab. |
options.trim | array of number | Keep only points between two times [t0, t1], days relative to the time reference (or Julian dates). |
options.clip_sigma | number | Remove points further than this many robust standard deviations (1.4826 × MAD, per epoch) from the current model. |
options.bin_min | number | Bin into inverse-variance weighted means over this many minutes. |
setView
api.setView(options) // → nothingChoose what the plot under the system view shows.
| Argument | Type | Description |
|---|---|---|
options required | object | Any of the three. |
options.view | "lc" · "rv" · "phase" · "map" · "moon" | Plot view. |
options.fold | boolean | Fold on the period. |
options.allPlanets | boolean | Every planet’s folded panel side by side. |
showTab
api.showTab(name) // → nothingBring a tab of the side panel to the front.
| Argument | Type | Description |
|---|---|---|
name required | "system" · "data" · "fit" · "results" · "timing" | Tab. |
setPhase
api.setPhase(options) // → { mode, lmax } or nullModel the planet’s own light (secondary eclipse, phase curve, map) for the planet on show, or take it out with null.
| Argument | Type | Description |
|---|---|---|
options required | null or object | null removes the model. Otherwise the description of the brightness. |
setMoon
api.setMoon(on) // → { rmoon, permoon, phmoon, mmoon, imoon } or nullGive the planet on show a moon, or take it away.
| Argument | Type | Description |
|---|---|---|
on required | boolean or object | true adds a moon with starting values, false removes it; an object sets the moon’s parameters. |
setNbody
api.setNbody(options) // → the N-body settings or nullSwitch fits of mid-transit times and velocities to an N-body integration of the planets, or back to independent Keplerian orbits with null. Needs two planets with masses and the stellar mass.
| Argument | Type | Description |
|---|---|---|
options required | null or object | null switches it off. |
companionSearch
api.companionSearch(options?) // → { mass, period, tmid, inc, epoch, host: { per, tmid }, chi2, chi2_no_companion, delta_chi2, n_times, significant, period_ratio, simulations, seconds }: the best cell, in the form addCompanion takesSearch the mid-transit times of the planet on show for an unseen companion: N-body simulations on a grid of companion mass and period. Takes seconds to a minute. Needs at least eight times and the planet’s mass.
| Argument | Type | Description |
|---|---|---|
options | object | Optional grid settings. |
options.phases | number | Starting phases tried per cell (default 8). |
options.masses | array of number | Companion masses to try, Jupiter masses. |
options.ratios | array of number | Companion period over the planet’s period to try. |
options.refine | boolean | Polish the best cells (default true). |
addCompanion
api.addCompanion(cell) // → the new planet’s letterAdd the companion found by companionSearch as a planet, switch the N-body model on and free its mass, period and phase, ready for a fit of the times.
| Argument | Type | Description |
|---|---|---|
cell required | object | The object companionSearch returned. |
cell.mass required | number | M Jup. |
cell.period required | number | days. |
cell.tmid required | number | days relative to the time reference. |
cell.inc | number | degrees. |
cell.epoch required | number | reference epoch. |
cell.host required | object | Period and T mid of the transiting planet at the epoch. |
cell.host.per | number | |
cell.host.tmid | number |
run
api.run() // → the object results() returnsRun the nested-sampling fit and wait for it. Resolves with the result summary; rejects with the reason it could not start or failed.
stop
api.stop() // → nothingStop a running fit; it returns the posterior collected so far, marked as not converged.
progress
api.progress() // → { running, calls, logZ, eta_s (seconds left, a rough extrapolation; null early on), fraction (0 to 1), iterations, efficiency, elapsed_s }How far a running fit has come.
results
api.results() // → object or nullThe current fit: medians and 68% intervals of the fitted parameters, derived quantities, evidence, chi-square, warnings. null when there is none.
derived
api.derived() // → array of { section, label, value, minus, plus, unit, kind }The rows of the system table. After a fit: every row with its uncertainty and whether it was fitted, derived, input or fixed. Before a fit: the quantities that follow from the current values, without uncertainties.
runs
api.runs() // → array of { id, free (parameter keys), labels, model, n_free, logZ, logZerr, converged, chi2, n_data, bic, information, ncalls, same_data (as the data now loaded), showing, cautions }The fits made in this session.
compare
api.compare(idA, idB) // → { a, b, delta_lnZ (ln Z of a minus ln Z of b), delta_lnZ_err, comparable, preferred (run id or null), reading, words, cautions }Compare two runs of this session by their evidence, in the words the Results tab uses, with the cautions that apply.
| Argument | Type | Description |
|---|---|---|
idA required | number | Run id from runs(). |
idB required | number | Run id from runs(). |
restoreRun
api.restoreRun(id) // → the object results() returnsBring an earlier run back: its posterior, tables, priors and best-fit model.
| Argument | Type | Description |
|---|---|---|
id required | number | Run id from runs(). |
figure
api.figure(view, options?) // → a "data:image/png;base64,…" URLA plot as a PNG image, drawn by the same code as the exported figures.
| Argument | Type | Description |
|---|---|---|
view required | "lc" · "residuals" · "corner" · "rv" · "timing" · "phase" · "map" · "moon" · "system" | Which plot. "lc": light curve with model and residual strip; "residuals": residuals and their histogram; "corner": posterior (needs a fit; its height follows its width); "rv": radial velocities; "timing": O − C diagram; "phase": full-orbit phase curve; "map": brightness map; "moon": the moon’s effects; "system": the 3D system view as it is on screen. |
options | object | Optional size and theme. |
options.width | number | Width in CSS pixels (default 900). |
options.height | number | Height in CSS pixels (default 540). |
options.theme | "light" · "dark" | White or dark background (default light). |
options.scale | number | Pixels per CSS pixel (default 2). |
exportSession
api.exportSession(withResult?) // → session documentThe whole analysis as a session document (docs/FORMAT.md): system, data, priors, sampler and, with a fit, the result.
| Argument | Type | Description |
|---|---|---|
withResult | boolean | Include the fit result (default true). |
importSession
api.importSession(session) // → the documentLoad a session document. This replaces the system, the data and the set-up.
| Argument | Type | Description |
|---|---|---|
session required | object | A session document. |
save
api.save(name?) // → { id, name, … }Save the analysis in this browser.
| Argument | Type | Description |
|---|---|---|
name | string | Name to save it under. |
listSaved
api.listSaved() // → array of { id, name, summary, updated }The analyses saved in this browser.
openSaved
api.openSaved(id) // → nothingOpen a saved analysis.
| Argument | Type | Description |
|---|---|---|
id required | value | Id from listSaved(). |
deleteSaved
api.deleteSaved(id) // → nothingDelete a saved analysis from this browser.
| Argument | Type | Description |
|---|---|---|
id required | value | Id from listSaved(). |
undo
api.undo() // → nothingUndo the last change.
redo
api.redo() // → nothingRedo the change that was undone.