Skip to content

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.

loading the analyzer…

state ​

js
api.state()  // → object

What 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 ​

js
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 ​

js
api.examples()  // → array of { id, title, about, kinds, python }

The worked examples that can be opened.

loadExample ​

js
api.loadExample(id, options?)  // → true

Open a worked example. It opens with a stored posterior unless fresh is true, which builds it from its data instead.

ArgumentTypeDescription
id requiredstringExample id from examples().
optionsobjectOptions.
options.freshbooleanBuild the example from its data instead of opening the stored run.

lookup ​

js
api.lookup(name, kinds?)  // → true

Load a planet or host star from the bundled NASA Exoplanet Archive snapshot, with a simulated light curve as a stand-in for data.

ArgumentTypeDescription
name requiredstringPlanet or host name, for example "WASP-12 b".
kindsarray of stringKinds of data the analysis is for.

setValue ​

js
api.setValue(key, value)  // → nothing

Set the value of a model or stellar parameter.

ArgumentTypeDescription
key requiredstringParameter 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 requirednumberNew 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 ​

js
api.setFree(key, free)  // → nothing

Make a parameter free (sampled in the fit) or hold it fixed. a/R★ can never be free.

ArgumentTypeDescription
key requiredstringParameter 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 requiredbooleantrue to fit it, false to hold it.

setPrior ​

js
api.setPrior(key, prior)  // → nothing

Set 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.

ArgumentTypeDescription
key requiredstringParameter 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 requiredobjectA 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 requirednumberLower bound, or mean.
prior.b requirednumberUpper bound, or standard deviation.

setUse ​

js
api.setUse(use)  // → nothing

Choose which kinds of data enter the fit.

ArgumentTypeDescription
use requiredobjectAny of the three flags.
use.lcbooleanLight curve.
use.rvbooleanRadial velocities.
use.timingbooleanMid-transit and mid-eclipse times of the Timing tab.

setKepler ​

js
api.setKepler(on)  // → nothing

Tie 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.

ArgumentTypeDescription
on requiredbooleantrue to use Kepler’s law.

setSampler ​

js
api.setSampler(settings)  // → nothing

Change nested-sampling settings.

ArgumentTypeDescription
settings requiredobjectAny of the settings.
settings.nlivenumberLive points (50 to 4000).
settings.fracRemainnumberStop when this fraction of the evidence remains.
settings.seednumberRandom seed.
settings.maxCallsnumberBudget of likelihood calls.

setLimbDarkening ​

js
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.

ArgumentTypeDescription
options requiredobjectAny 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.bandstring or arrayBandpass: a name from state().limbDarkening.bands, or [min, max] in nm for a custom range (200 to 5500).
options.coeffsarray or stringThe 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 ​

js
api.addPlanet(options?)  // → the new planet’s letter

Add 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.

ArgumentTypeDescription
optionsobjectOptional letter and starting values.
options.letterstringOne lowercase letter not in use; the next free one by default.
options.valuesobjectPlanet parameters by name: rprs, ars, inc, per, tmid, ecc, omega, mplanet (Jupiter masses).

removePlanet ​

js
api.removePlanet(letter)  // → nothing

Remove a planet (not the first one) with its parameters, moon, own-light model and listed times.

ArgumentTypeDescription
letter requiredstringLetter of the planet to remove.

showPlanet ​

js
api.showPlanet(letter)  // → nothing

Choose the planet the sliders, the system view and the folded plots show.

ArgumentTypeDescription
letter requiredstringPlanet letter.

loadLightCurve ​

js
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).

ArgumentTypeDescription
text requiredstringFile contents.
namestringName to show for it.

addLightCurveEpoch ​

js
api.addLightCurveEpoch(text, name?)  // → { epochs }

Add another light curve of the same planet as a further epoch, fitted together with what is loaded.

ArgumentTypeDescription
text requiredstringFile contents.
namestringName of the epoch.

addRadialVelocities ​

js
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.

ArgumentTypeDescription
text requiredstringFile contents.
namestringName of the set.

findRadialVelocities ​

js
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.

ArgumentTypeDescription
namestringPlanet 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 ​

js
api.addRadialVelocitySet(id)  // → array of { name, points, source } for the sets added

Add 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.

ArgumentTypeDescription
id requiredstring or arrayA set id from findRadialVelocities().sets, or an array of them.

setEccentricityParameters ​

js
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.

ArgumentTypeDescription
sqrtE requiredbooleantrue for √e cos ω, √e sin ω; false for e, ω.

setupJointFit ​

js
api.setupJointFit()  // → array of the free parameter keys

Set 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 ​

js
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.

ArgumentTypeDescription
spec requirednull or objectnull, or the model.

setTimings ​

js
api.setTimings(text)  // → { times }

Replace the mid-transit times of the planet on show (Timing tab).

ArgumentTypeDescription
text requiredstringRows "time, uncertainty" or "epoch, time, uncertainty", times in days (BJD).

simulate ​

js
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.

ArgumentTypeDescription
optionsobjectAny of the settings; the rest keep their last values.
options.noise_ppmnumberWhite noise per exposure, ppm.
options.cadence_minnumberCadence, which is also the exposure time, minutes.
options.spannumberLength of each simulated observation in hours, centred on mid-transit. It must exceed the transit duration.
options.baseline_hrnumberAlternative to span: out-of-transit time on each side of the transit, hours.
options.seednumberRandom seed.
options.epochsnumberNumber of transits to observe (1 to 200); more than one makes a multi-epoch dataset.
options.epoch_stepnumberOrbits between one simulated transit and the next.
options.airmassbooleanAdd an airmass trend, as on a ground-based night.

editData ​

js
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.

ArgumentTypeDescription
options requiredobjectAt least one edit.
options.remove_epochnumberNumber of the epoch to remove, counted from 1 as on the Data tab.
options.trimarray of numberKeep only points between two times [t0, t1], days relative to the time reference (or Julian dates).
options.clip_sigmanumberRemove points further than this many robust standard deviations (1.4826 × MAD, per epoch) from the current model.
options.bin_minnumberBin into inverse-variance weighted means over this many minutes.

setView ​

js
api.setView(options)  // → nothing

Choose what the plot under the system view shows.

ArgumentTypeDescription
options requiredobjectAny of the three.
options.view"lc" · "rv" · "phase" · "map" · "moon"Plot view.
options.foldbooleanFold on the period.
options.allPlanetsbooleanEvery planet’s folded panel side by side.

showTab ​

js
api.showTab(name)  // → nothing

Bring a tab of the side panel to the front.

ArgumentTypeDescription
name required"system" · "data" · "fit" · "results" · "timing"Tab.

setPhase ​

js
api.setPhase(options)  // → { mode, lmax } or null

Model the planet’s own light (secondary eclipse, phase curve, map) for the planet on show, or take it out with null.

ArgumentTypeDescription
options requirednull or objectnull removes the model. Otherwise the description of the brightness.

setMoon ​

js
api.setMoon(on)  // → { rmoon, permoon, phmoon, mmoon, imoon } or null

Give the planet on show a moon, or take it away.

ArgumentTypeDescription
on requiredboolean or objecttrue adds a moon with starting values, false removes it; an object sets the moon’s parameters.

setNbody ​

js
api.setNbody(options)  // → the N-body settings or null

Switch 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.

ArgumentTypeDescription
options requirednull or objectnull switches it off.

companionSearch ​

js
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 takes

Search 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.

ArgumentTypeDescription
optionsobjectOptional grid settings.
options.phasesnumberStarting phases tried per cell (default 8).
options.massesarray of numberCompanion masses to try, Jupiter masses.
options.ratiosarray of numberCompanion period over the planet’s period to try.
options.refinebooleanPolish the best cells (default true).

addCompanion ​

js
api.addCompanion(cell)  // → the new planet’s letter

Add 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.

ArgumentTypeDescription
cell requiredobjectThe object companionSearch returned.
cell.mass requirednumberM Jup.
cell.period requirednumberdays.
cell.tmid requirednumberdays relative to the time reference.
cell.incnumberdegrees.
cell.epoch requirednumberreference epoch.
cell.host requiredobjectPeriod and T mid of the transiting planet at the epoch.
cell.host.pernumber
cell.host.tmidnumber

run ​

js
api.run()  // → the object results() returns

Run the nested-sampling fit and wait for it. Resolves with the result summary; rejects with the reason it could not start or failed.

stop ​

js
api.stop()  // → nothing

Stop a running fit; it returns the posterior collected so far, marked as not converged.

progress ​

js
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 ​

js
api.results()  // → object or null

The current fit: medians and 68% intervals of the fitted parameters, derived quantities, evidence, chi-square, warnings. null when there is none.

derived ​

js
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 ​

js
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 ​

js
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.

ArgumentTypeDescription
idA requirednumberRun id from runs().
idB requirednumberRun id from runs().

restoreRun ​

js
api.restoreRun(id)  // → the object results() returns

Bring an earlier run back: its posterior, tables, priors and best-fit model.

ArgumentTypeDescription
id requirednumberRun id from runs().

figure ​

js
api.figure(view, options?)  // → a "data:image/png;base64,…" URL

A plot as a PNG image, drawn by the same code as the exported figures.

ArgumentTypeDescription
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.
optionsobjectOptional size and theme.
options.widthnumberWidth in CSS pixels (default 900).
options.heightnumberHeight in CSS pixels (default 540).
options.theme"light" · "dark"White or dark background (default light).
options.scalenumberPixels per CSS pixel (default 2).

exportSession ​

js
api.exportSession(withResult?)  // → session document

The whole analysis as a session document (docs/FORMAT.md): system, data, priors, sampler and, with a fit, the result.

ArgumentTypeDescription
withResultbooleanInclude the fit result (default true).

importSession ​

js
api.importSession(session)  // → the document

Load a session document. This replaces the system, the data and the set-up.

ArgumentTypeDescription
session requiredobjectA session document.

save ​

js
api.save(name?)  // → { id, name, … }

Save the analysis in this browser.

ArgumentTypeDescription
namestringName to save it under.

listSaved ​

js
api.listSaved()  // → array of { id, name, summary, updated }

The analyses saved in this browser.

openSaved ​

js
api.openSaved(id)  // → nothing

Open a saved analysis.

ArgumentTypeDescription
id requiredvalueId from listSaved().

deleteSaved ​

js
api.deleteSaved(id)  // → nothing

Delete a saved analysis from this browser.

ArgumentTypeDescription
id requiredvalueId from listSaved().

undo ​

js
api.undo()  // → nothing

Undo the last change.

redo ​

js
api.redo()  // → nothing

Redo the change that was undone.

MIT licensed · Kyle A. Pearson