Skip to content

src/core/spectroscopy.js ​

text
Time-series spectroscopy: spectra per integration in, a transmission or emission spectrum out. No DOM.

  read      readX1dints(fits)        JWST Stage 2/3 `x1dints.fits` (both layouts, see below)
            parseSpectralText(text)  a plain "time x wavelength" table (CSV / ECSV / whitespace)
            mergeCubes([cube...])    segments in time, detectors in wavelength
  prepare   rejectOutliers, makeBins, binCube, whiteLight, applyCommonMode
  fit       fitWhiteLight (shared geometry, nested sampling) and fitChannel (depth per channel), both
            through buildProblem of model.js: the same likelihood as every other fit on the site
  products  spectrumTable, spectrumToECSV / spectrumToCSV, scaleHeight, toScaleHeights
  simulate  simulateSpectroscopy: Ariel- or JWST-like channels with a simple radiometric noise estimate
  session   spectroscopyToSession / spectroscopyFromSession (docs/FORMAT.md, "Spectroscopy")

A cube is { time (BJD_TDB, absolute, one per integration), wave (micron, ascending, one per column),
            flux, err (Float64Array nT * nW, integration-major; err may be null), bad (Uint8Array, 1 = unusable),
            lo, hi (optional column edges in micron: simulated channels), exptime (days), meta }.
A light curve here is { time (absolute), flux, err, exptime (days) } with flux normalised to a median of 1.

Not read: HST/WFC3 spatial scans and other 2-D spectral images (`spec2d`, `calints`, `rateints`): there is
no spectral extraction here. Start from extracted 1-D spectra.

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

readX1dints ​

js
function readX1dints(fits, opts = {})

A JWST time-series x1dints product (parseFits / openFits output) as a cube.

Two layouts exist. Pipeline versions up to 1.16 wrote one EXTRACT1D extension per integration (and per spectral order), each a table with one row per wavelength. Later versions (the files MAST serves after reprocessing, CAL_VER 1.17 and above) write one EXTRACT1D extension per order with one row per integration and vector columns (1272D), plus INT_NUM and TDB-MID per row. Both are read.

Times: TDB-MID of each row when present, else int_mid_BJD_TDB of the INT_TIMES extension matched by integration number (by position when the numbers are absent). Both are stored by the pipeline as BJD_TDB - 2400000.5. opts: { order (SPORDER to take when several are present, default the first), column ('FLUX' | 'SURF_BRIGHT') } Points with a non-finite flux or the DO_NOT_USE bit (1) of DQ are flagged in bad.

parseSpectralText ​

js
function parseSpectralText(text, name = 'spectra')
text
A plain-text cube. Two shapes are recognised:
  long   one row per (time, wavelength): columns named like time|bjd|mjd|jd, wave*|wl|lambda, flux, and optionally
         err|error|sigma|unc (ECSV comment lines starting with # are skipped; the column line is the first other line)
  wide   one row per time: first column time, then one column per wavelength whose header is the wavelength in
         micron (optionally prefixed f_), then optionally the same number of error columns (prefixed e_)
Separators: comma, tab, semicolon or spaces. Wavelengths above 50 are taken to be nm and converted to micron.
Times below 2400000 that look like MJD (above 40000) get 2400000.5 added.

cubeToCSV ​

js
function cubeToCSV(cube)

The cube as text, one row per time: "time,f_<wl>...,e_<wl>...". parseSpectralText reads it back.

mergeCubes ​

js
function mergeCubes(list)

Join cubes: those with the same wavelength grid are segments and are appended in time; the resulting groups (detectors, orders) must then have the same times and are placed side by side in wavelength. Integrations that appear twice (same time within a tenth of the cadence) are kept once.

rejectOutliers ​

js
function rejectOutliers(cube, { window = 11, nsigma = 5, maxBadFrac = 0.2, spectral = true, colTolerance = 0.5, errFactor = 5 } = {})

Reject outliers in time, wavelength by wavelength: each column is compared with its running median over window integrations; points further than nsigma robust standard deviations (1.4826 x MAD of the differences) are flagged and, like the points already flagged in bad, replaced by the running median (their error by the column's median error). A column with more than maxBadFrac of its points flagged is dropped from every later sum, and so (unless spectral is false, or the columns are simulated channels) is a column that does not belong to the spectrum (see below). Returns a new cube with { replaced (count), deadColumns (count, all reasons), outlierColumns (count, the spectral test), colOk (Uint8Array) }; the input is not changed.

columnEdges ​

js
function columnEdges(cube)

Edges of the cube's columns in micron: given (simulated channels) or half-way between neighbouring wavelengths.

makeBins ​

js
function makeBins(cube, opts = {})
text
Wavelength bins on the cube's grid. A bin is a run of whole columns [j0, j1).
  { mode: 'R', R }           constant resolving power lambda / dlambda
  { mode: 'width', width }   constant width in micron
  { mode: 'n', n }           that many bins with equal numbers of columns
  { mode: 'columns', columns }   that many columns (detector pixels) per bin
  { mode: 'native' }         every column its own bin
  { mode: 'edges', edges }   explicit edges in micron
Common: wlMin, wlMax (micron) restrict the range. Bins never straddle a detector gap (cube.part) or a gap in
the wavelength grid wider than five columns. Bins left with no usable column are dropped.
Returns [{ lo, hi, wl (centre), j0, j1, ncol }] in micron.

pointScatter ​

js
function pointScatter(f)

Robust point-to-point scatter of a series: 1.4826 MAD of f[i] - (f[i-1] + f[i+1]) / 2, divided by sqrt(1.5).

binCube ​

js
function binCube(cube, bins)

Light curves of the bins: in every integration the fluxes of the bin's usable columns are summed and their errors added in quadrature; the series is then divided by its median. Integrations where any usable column is still flagged are dropped from that channel (after rejectOutliers there are none). Without errors in the cube the error of every point is the channel's point-to-point scatter (pointScatter). Returns [{ lo, hi, wl, ncol, time, flux, err, scale (the median that was divided out), exptime, errSource }].

whiteLight ​

js
function whiteLight(cube, { wlMin, wlMax } = {})

The white light curve: every usable column between wlMin and wlMax summed. With several detectors each is normalised first and they are averaged with inverse-variance weights.

applyCommonMode ​

js
function applyCommonMode(channels, white)

Common-mode correction: divide every channel by the white light curve's ratio to its fitted model (data / (transit x baseline)), which removes whatever all wavelengths share. The white curve's own noise is divided in too: it is added in quadrature to the channel's errors, and because it is the same in every channel it moves all depths together rather than adding scatter between them. ratio is one value per white-light point (time, ratio); channels are matched by time.

channelLimbDarkening ​

js
function channelLimbDarkening(table, star, lo, hi, law = 'quadratic')
text
Limb darkening coefficients for a channel from the wavelength-resolved table (expandSpectral of ldspec.js).
  star = { teff, logg, feh }, lo and hi in micron.
The table ends at 5.5 micron. A channel partly beyond it uses the part inside; a channel wholly beyond it uses
the reddest 200 nm of the table (limb darkening changes slowly there, but this is an extrapolation and
`extrapolated` is set). Returns { law, coeffs, clamped, extrapolated, coverage, band: [nm, nm] }.

baselineRegressors ​

js
function baselineRegressors(time, baseline = 'linear', extra = [], steps = [])

Regressors for the baseline of a light curve: time scaled to [-1, 1] ('linear'), plus its square ('quadratic'), plus any extra columns centred and scaled to unit variance, plus one step per entry of steps (times in the units of time).

lightCurveSpec ​

js
function lightCurveSpec(lc, sys, opts = {})
text
The fit specification (what buildProblem takes) for one light curve of a spectroscopic data set.
  lc      { time (absolute), flux, err, exptime (days) }
  sys     { rprs, ars, inc, per, tmid (absolute), ecc, omega, fpfs?, mstar?, rstar?, mplanet? }
  opts    { kind: 'transit' | 'eclipse', ldLaw, ld: [coefficients], baseline: 'none' | 'linear' | 'quadratic',
            regressors: [extra columns], steps: [absolute times of steps in the baseline], free: [{ key, prior }] (tmid priors absolute), kepler, errScale, tRef, sampler }
a/R* is a fixed value, or with opts.kepler follows from M*, R*, P; it is never free.
Returns { spec, tRef }.

errorScaleFor ​

js
function errorScaleFor(lc, mode = 'max')

How much the errors are scaled: 1 ('pipeline'), scatter / median error ('scatter'), or the larger of the two ('max').

defaultWhiteFree ​

js
function defaultWhiteFree(lc, sys, kind = 'transit')

Default priors of a white-light fit: Rp/R* (or Fp/F*), the mid-time and the inclination, uniform.

findStep ​

js
function findStep(time, resid, K = 12)
text
The largest step in a series of residuals: the difference between the means of the K points after and the K
points before each position. Returns { index (first point after the step), time (half-way between the two
points), size, significance (size over its standard error from the point-to-point scatter) }. A mirror-segment
tilt event in a JWST time series shows up as one; pass `time` to the fits as opts.steps = [time].

residualStats ​

js
function residualStats(resid, err, nFree = 0)

Residual statistics of a fitted light curve: rms, the mean error bar, chi2, and the time-averaging test (psd.js rmsVsBin).

fitWhiteLight ​

js
function async fitWhiteLight(lc, sys, opts = {}, onProgress = ()
text
White-light fit: the geometry all channels share. Nested sampling through buildProblem (fitRunner.js).
opts as lightCurveSpec, plus errorMode ('pipeline' | 'scatter' | 'max', default 'max') and free (defaults: defaultWhiteFree).
Returns { kind, parameters: [{ key, median, plus, minus, best }], values (the system at the best point, tmid absolute:
  pass it to fitChannel), depth: { median, plus, minus } (Rp/R*)^2 or Fp/F* (Rp/R*)^2, errScale, logZ, ncalls, converged,
  warnings, stats (residualStats), time, model (transit x baseline), baseline, detrended (flux / baseline), resid, ld, ldLaw }.

posterior1D ​

js
function posterior1D(loglike, a, b)

The posterior of ONE parameter on a grid: maximum by a scan and golden-section search, half-widths where ln L has fallen by 1/2, then 241 points over +-8 of those widths (clipped to [a, b]), integrated by the trapezoid rule. The prior is uniform on [a, b]. Returns { best, median, lo, hi (16th and 84th percentiles), lnZ (evidence with that prior), x, p (the grid and the normalised density) }.

fitChannel ​

js
function async fitChannel(ch, geo, opts = {})
text
One channel: the depth with the geometry of the white-light fit.
  ch    { lo, hi, wl, time, flux, err, exptime }
  geo   the system at the white-light solution (fitWhiteLight().values)
  opts  { kind, ldLaw, ld (this channel's coefficients), ldSigma (0: fixed; > 0: every coefficient free with a normal
          prior of that width), geometry: 'fixed' | 'prior' (tmid and inc free with normal priors geoPriors = { tmid: sd, inc: sd }),
          baseline, regressors, errorMode, keep (return the per-point arrays), sampler }
With only the depth free the posterior is computed on a grid (posterior1D): exact and deterministic. Anything
more goes to the nested sampler. Either way the likelihood is buildProblem's, with the baseline coefficients
integrated out analytically.
Returns { lo, hi, wl, kind, depth, depthPlus, depthMinus, value (Rp/R* or Fp/F*), valuePlus, valueMinus, best, method,
          rms, expected, ratio, beta, betaBin, chi2, redChi2, n, errScale, logZ, ld, [time, model, baseline, detrended, resid, binned] }.

fitChannels ​

js
function async fitChannels(channels, geo, opts = {}, onProgress = ()

All channels in turn (the page spreads them over workers instead). ldFor(ch) gives each channel's { law, coeffs }.

spectrumTable ​

js
function spectrumTable(results)

Rows of the spectrum from the channel fits: wavelength, bin edges, depth and its 1-sigma interval, and the noise columns.

spectrumToECSV ​

js
function spectrumToECSV(spectrum, meta = {})

The spectrum as ECSV (astropy reads it with Table.read(..., format='ascii.ecsv')). meta is written into the header.

spectrumToCSV ​

js
function spectrumToCSV(spectrum, meta = {})

The spectrum as CSV with # key: value comment lines for the metadata.

scaleHeight ​

js
function scaleHeight({ teq, mu = 2.3, mplanet, rplanet, g })
text
Pressure scale height H = k T / (mu m_u g) in metres, with g = G Mp / Rp^2.
  { teq [K], mu (mean molecular weight in atomic mass units, 2.3 for H2/He), mplanet [M Jup], rplanet [R Jup] } or { teq, mu, g [m/s^2] }
For interpretation only: T is taken to be the equilibrium temperature, and the atmosphere isothermal.

toScaleHeights ​

js
function toScaleHeights(spectrum, { H, rplanet, rstar })
text
The change of transit depth that one scale height of extra radius makes, 2 H Rp / R*^2 (first order in H / Rp),
and the spectrum expressed in scale heights above its minimum: n = (depth - min depth) / (2 H Rp / R*^2).
  { H [m], rplanet [R Jup], rstar [R Sun] }

photonRate ​

js
function photonRate({ teff, rstar, distance }, lo, hi)
text
Photons per second per square metre arriving from a star that radiates as a black body, between lo and hi (micron):
    N = pi (R* / d)^2 * integral of 2 c / lambda^4 / (exp(h c / lambda k T) - 1) d lambda
(pi B_lambda is the surface flux; dividing by the photon energy h c / lambda gives photons). Simpson's rule, 400 intervals.
  { teff [K], rstar [R Sun], distance [pc] }

toySpectrum ​

js
function toySpectrum(wl, { depth0, slope = 0, wl0 = 1, features = [] })
text
A toy depth spectrum for testing a retrieval of depths: a level, a slope and Gaussian features. It is not an
atmosphere model.   depth(wl) = depth0 + slope * ln(wl / wl0) + sum amp_k exp(-(wl - c_k)^2 / (2 s_k^2))
  { depth0, slope, wl0 (micron, default 1), features: [{ wl, sigma (micron), amp (depth units) }] }

simulateSpectroscopy ​

js
function simulateSpectroscopy(o)
text
Simulated spectroscopic light curves of one transit (or eclipse): a simple radiometric estimate, NOT a
reproduction of ArielRad, ExoSim, PandExo or any instrument simulator.

Noise of one exposure in one channel, relative to the star:
    N_e      = photonRate(star, lo, hi) * area * throughput * t_exp          detected photo-electrons
    sigma^2  = (1 + excess)^2 / N_e  +  floor^2 * (T14 / dt)
The first term is photon noise of the star alone (black body; no background, read noise, dark current,
saturation or pointing jitter), widened by `excess` (0.2 = 20% above photon noise). The second is white noise sized
so that it alone averages to `floor` (noiseFloorPpm) over one transit duration T14: a floor on what one transit
can reach. dt is the cadence and t_exp = dt * duty.

  o = { system: { rprs, ars, inc, per, tmid, ecc, omega, fpfs? }, star: { teff, rstar, distance, logg, feh },
        telescope: 'Ariel' | 'JWST' | { area, throughput, noiseFloorPpm }, area, throughput, noiseFloorPpm, excess (overrides),
        channels: [{ lo, hi, wl, name }] (default: instrumentChannels of the telescope), bands, simR,
        kind: 'transit' | 'eclipse', depth: (wl) => depth or a toySpectrum description (default: flat at rprs^2 or fpfs rprs^2),
        cadence [s] (60), duty (1), baselineHr (out-of-transit time each side, default one T14), slopePpmPerHr (0),
        ldFor: (lo, hi) => { law, coeffs } (default: quadratic 0.1, 0.1 everywhere; pass channelLimbDarkening), seed }
The cube's fluxes are in detected electrons per exposure, so a white light curve summed from it weights the
channels by their photons, as a real one does.
Returns { cube (columns are the channels, with lo / hi), truth: [{ wl, lo, hi, depth, rprs or fpfs, sigma (per point),
          electrons, ld }], inputs (everything that went in, with units), t14 }.

eclipseOffset ​

js
function eclipseOffset(sys)

Time from mid-transit to the next mid-eclipse (days): half a period for a circular orbit, shifted by about (2 P / pi) e cos(omega) otherwise.

spectroscopyToSession ​

js
function spectroscopyToSession(st)
text
A spectroscopic analysis as an ESL session document (docs/FORMAT.md). The white light curve is the session's
light curve, so the analyzer and runSession can open the file; everything else is in the "spectroscopy" block.
When a white-light fit exists the session's light curve is the DETRENDED one (flux / fitted baseline), because
the session format has no regressors; the raw one is kept in spectroscopy.white_light.
  st = { name, star, system (tmid absolute), kind, ldLaw, whiteLd, white (light curve), channels (light curves),
         bins (makeBins options), settings, whiteFit (fitWhiteLight result or null), spectrum (spectrumTable or null),
         source ({ kind, files, meta }), simulation (simulateSpectroscopy inputs + truth, or null) }

spectroscopyFromSession ​

js
function spectroscopyFromSession(doc)

The state spectroscopyToSession was given, from a session document. Throws when the document has no spectroscopy block.

MIT licensed · Kyle A. Pearson