spEXplore Documentation

spEXplore is an interactive browser tool for exploring and measuring one‑dimensional astronomical spectra (wavelength vs. flux). It lets you overlay spectral‑line markers, shift them with redshift and per‑line velocities, fit Gaussian line profiles (single or blended/multi‑component), read off line measurements with uncertainties, and collect the results into an exportable table.

Everything runs locally in your browser; your data never leaves your machine.

Table of contents

  1. Quick start
  2. Loading a spectrum
  3. The plot and navigation
  4. Wavelength frames: redshift and velocity
  5. Spectral line markers
  6. Line sets (line groups)
  7. Cleaning the spectrum: binning and deleting sections
  8. Profile fitting
  9. Fit measurements and their definitions
  10. Uncertainties
  11. Multi‑profile (blended line) fitting
  12. The results table
  13. Sessions: saving and restoring work

Quick start

  1. Go to the spEXplore app
  2. Load a two‑column ASCII spectrum (wavelength, flux) — click Load ASCII or drag‑and‑drop the file onto the plot.
  3. Optionally set the Redshift so that known features line up with the spectrum, and add or edit line markers.
  4. Click Fit profile, choose a fitting method, and click the requested points on the plot to fit a line.
  5. Read the measurements on the resulting fit card.
  6. Click Tabulate to assemble a results table, then Download CSV/JSON.
  7. Save Session to store everything (spectrum, lines, fits, table) in a single .spx file you can reload later.

Loading a spectrum

The tool reads plain two‑column ASCII files: the first column is wavelength, the second is flux. Accepted extensions include .txt, .dat, .ascii, .csv, .spec, and .flm. Columns may be separated by whitespace or commas.

  • Comment lines beginning with #, %, ;, or // are ignored.
  • Rows that do not contain two finite numbers are skipped.
  • Points are automatically sorted by increasing wavelength.

Wavelength units (λ units)

By default the wavelength column is assumed to be in Ångström (Å). If your file uses a different unit, choose it from the λ units selector; the tool multiplies every wavelength by the corresponding factor to convert to Å:

Selection Factor (× to get Å)
Å 1
nm 10
µm 10⁴
mm 10⁷
pm 0.01

All downstream quantities (axis, marker positions, fitted wavelengths, widths) are therefore expressed in Å.

The plot and navigation

The central panel draws the spectrum as flux vs. wavelength. Note that the x‑axis is the rest‑frame wavelength (see Wavelength frames).

Tools (top‑right of the plot):

  • Drag Zoom — toggle, then drag a rectangle to zoom into a region.
  • + / − — zoom in/out about the current center.
  • Reset — restore the auto‑scaled view that frames the whole spectrum.

A live readout (bottom‑left) shows the rest‑frame wavelength and flux under the cursor.

Binning

The Binning points control replaces each plotted point by a centered moving average over N neighbouring points, with the window truncated at the spectrum edges. Binning is purely a smoothing aid for visualization and also affects the data used for fitting, so the fit operates on the binned points you see. Set N = 1 for unbinned data.

Wavelength frames: redshift and velocity

The tool distinguishes three related wavelengths for any line, all connected by the relativistic Doppler relation.

1. Rest wavelength \(\lambda_\text{rest}\) — the intrinsic wavelength of the line.

2. Velocity shift. A per‑line radial velocity \(v\) shifts the rest wavelength by the relativistic Doppler formula

\[ \lambda_\text{shifted} = \lambda_\text{rest}\,\sqrt{\frac{1+\beta}{1-\beta}}, \qquad \beta = \frac{v}{c}.\]

The inverse (used to report a velocity from a measured wavelength) is

\[ v = c\,\frac{R^2 - 1}{R^2 + 1}, \qquad R = \frac{\lambda_\text{obs}}{\lambda_\text{rest}}.\]

3. Observed wavelength. Applying the overall redshift of the source / line-set \(z\) as \((1+z)\), and combining the doppler velocity shift, the observed wavelength is calculated. The observed wavelength of a line is

\[ \lambda_\text{obs} = \lambda_\text{rest}\,\sqrt{\frac{1+\beta}{1-\beta}}\;(1+z).\]

The plot works in the rest frame

The spectrum is displayed de‑redshifted to the rest frame: each observed data wavelength is mapped to

\[ \lambda_\text{rest-axis} = \frac{\lambda_\text{observed}}{1+z}.\]

A single line marker is drawn at \(\lambda_\text{rest}\) shifted only by its own velocity, \(\lambda_\text{rest}\sqrt{(1+\beta)/(1-\beta)}\). Consequently, when the global redshift equals the true source redshift, rest‑wavelength markers line up with the corresponding features in the data.

The Redshift control has both a numeric field and a fine slider. Editing either updates the rest‑frame mapping immediately.

Spectral line markers

The Line List holds line markers drawn as vertical dashed lines on the plot. Each single line has:

  • Show — visibility on the plot.
  • Line — a name; typing offers autocomplete from a built‑in catalogue of common lines, and selecting one fills its rest wavelength.
  • Rest wavelength (Å) — \(\lambda_\text{rest}\) (with a fine slider).
  • Velocity (km/s) — the per‑line radial velocity \(v\) (with a fine slider).
  • Shifted / Observed wavelength (Å) — a coupled field. In shifted display mode it shows \(\lambda_\text{shifted}=\lambda_\text{rest}\sqrt{(1+\beta)/(1-\beta)}\); in observed mode it shows \(\lambda_\text{obs}=\lambda_\text{shifted}(1+z)\). Editing this field back‑solves the velocity, keeping rest λ, velocity, and the shifted/observed value mutually consistent.
  • Color — marker colour.

Use Add Line to append a blank line, and the × to remove one. The Display Shifted λ / Display Observed λ selector switches what the coupled column shows.

Common line velocity

The Common line velocity (km/s) control sets the same velocity on all shown lines at once — convenient for shifting an entire set of expected lines to a common kinematic offset. If the currently shown lines do not already share one velocity, you are warned before their individual values are overwritten.

Line sets (line groups)

A line set is a single card representing many wavelengths of one species (for example, the Balmer series, or a set of Fe II lines). Add one with Add line set. A line‑set card has:

  • Line set — a name; autocomplete offers built‑in groups (H, He I, He II, C II/III/IV, N II–V, O I–VI, Na I, Mg I/II, Si II, S II, Ca II, Fe II/III, Telluric, Galaxy lines, Wolf–Rayet, …). Selecting one fills its wavelength list.
  • Rest (Å) — a comma‑separated list of rest wavelengths (freely editable).
  • Velocity (km/s) — one velocity applied to every line in the set.
  • Redshift — a per‑set redshift (see below).
  • Color — all lines of the set share this colour.

Every wavelength \(w\) in the set is drawn at the rest‑frame position

\[ x = \Big[\,w\,\frac{1+z_\text{set}}{1+z_\text{global}}\,\Big]\sqrt{\frac{1+\beta}{1-\beta}}, \qquad \beta = \frac{v_\text{set}}{c},\]

i.e. the line is placed at its own redshift \(z_\text{set}\), mapped into the rest‑frame axis (which is de‑redshifted by the global \(z_\text{global}\)), then shifted by the set velocity. When \(z_\text{set}=z_\text{global}\) the set sits at its rest wavelengths.

Redshift coupling. The per‑set redshift is one‑way tied to the global redshift: changing the top‑left Redshift pushes the new value into every shown set (you are warned if that would overwrite sets holding different redshifts). Editing a set's own redshift affects only that set and does not change the global value. This lets you place, say, host‑galaxy lines at one redshift and an intervening system at another.

Cleaning the spectrum: binning and deleting sections

Besides binning, you can mask spectral regions you do not want to see or fit through:

  • Click Delete section, then click two points on the plot. The wavelength range between them is removed from the displayed/fitted spectrum and listed under Deleted Sections.
  • Remove a masked region from that list to restore it.

Deletions are useful for excising cosmic rays, detector artefacts, or gaps before fitting.

Profile fitting

Click Fit profile to enter fitting mode, then click the points the chosen method requires (a prompt at the top of the plot guides each click). Each click is marked; after the final click the fit runs and a fit card appears.

The model

A fitted line is a single Gaussian on top of a local continuum \(C(\lambda)\):

\[ f(\lambda) = C(\lambda) + A\,\exp\!\left[-\frac{(\lambda-\mu)^2}{2\sigma^2}\right].\]

  • \(A\) — amplitude (height above continuum; negative for absorption),
  • \(\mu\) — line centre (mean),
  • \(\sigma\) — Gaussian width, related to the full width at half maximum by \(\text{FWHM} = 2\sqrt{2\ln 2}\,\sigma \approx 2.3548\,\sigma\).

The fit is performed on the continuum‑subtracted data inside the chosen fit window. For fixed \(\mu,\sigma\) the amplitude is obtained in closed form by linear least squares; \(\mu\) and \(\sigma\) are then refined by a direct search that minimizes the sum of squared residuals. The width is bounded below by a small fraction of the fit window and above by the window itself, so a single line cannot collapse to a spike or grow unbounded.

Continuum and fitting methods

The methods differ in how the local continuum and the fit window are defined. All continua are straight lines \(C(\lambda) = m\lambda + b\) (except the zero‑continuum method).

  • Two point — click two points; the continuum is the straight line through them and the profile is fit over the wavelength range between them.
  • Four point — two continuum points define the line, then two more points set the fit window (so the continuum anchors and the fit range are independent).
  • Six point — mark a left continuum range (two points) and a right continuum range (two points); the continuum is the least‑squares straight line through all data inside both ranges. Two further points set the fit window. This is the most robust continuum for noisy data.
  • Zero continuum — assumes the data is already continuum‑subtracted, so \(C(\lambda)\equiv 0\). Click only the two points bounding the fit window. (Pseudo‑equivalent width is undefined here and is reported as zero.)
  • Multi‑profile (2N + 4 point) — fits N Gaussians on a shared continuum; see Multi‑profile fitting.

The least‑squares continuum (six‑point and multi‑profile) through points \((\lambda_i, f_i)\) in the chosen ranges has slope and intercept

\[ m = \frac{n\sum \lambda_i f_i - \sum \lambda_i \sum f_i}{n\sum \lambda_i^2 - (\sum \lambda_i)^2}, \qquad b = \frac{\sum f_i - m\sum \lambda_i}{n}.\]

Automatic line identification

After a fit, the tool labels the profile with the nearest shown line marker whose on‑plot position lies within 3 % of the fitted centre \(\mu\), and copies that line's rest wavelength into the card (which enables the velocity columns). Line sets participate in this matching (the nearest individual set wavelength is used) unless you enable Use single lines only to auto‑pick fitted profile's wavelength in Fit options. You can always override the name and rest wavelength on the card by hand.

Fit options

  • Show full fit‑model — extend the drawn profile (and its continuum) to the full Gaussian extent, \(\mu \pm 3.8\,\sigma\), instead of only the clicked window.
  • Visualize 'FWHM (direct)' measurements — overlay the smoothed profile and the peak / half‑maximum crossing points used for the direct FWHM (see below).
  • Use single lines only to auto‑pick … — exclude line sets from automatic identification.

Fit measurements and their definitions

Each fit card reports two families of measurements: model‑based (analytic, from the fitted Gaussian) and direct (numerical, straight from the continuum‑subtracted data). Reporting both lets you check how well the Gaussian describes the actual line.

Model‑based measurements

  • Mean \(\mu\) — fitted line centre (Å).
  • FWHM \(= 2\sqrt{2\ln 2}\,\sigma\) (Å).
  • Height \(A\) — amplitude relative to the continuum (flux units, \(I\)).
  • Flux (integrated line flux) — the analytic Gaussian area

\[ F = A\,\sigma\sqrt{2\pi}\quad (I\cdot\text{Å}).\]

  • pEW — pseudo‑equivalent width, the continuum‑normalized line area

\[ \text{pEW} = \int \left(1 - \frac{f(\lambda)}{C(\lambda)}\right) d\lambda ,\]

integrated over the full model (\(\mu \pm 10\sigma\), where the Gaussian contribution is negligible at the limits). By this sign convention an absorption line has positive pEW and an emission line negative. pEW requires a non‑zero continuum.

Direct (data‑based) measurements

Let \(r(\lambda) = f(\lambda) - C(\lambda)\) be the continuum‑subtracted data.

  • Flux (direct) — trapezoidal integral of the residual over the data points:

\[ F_\text{direct} = \int r(\lambda)\,d\lambda \approx \sum_i \tfrac{1}{2}\,(r_i + r_{i+1})(\lambda_{i+1}-\lambda_i).\]

  • pEW (direct) — the data analogue of pEW:

\[ \text{pEW}_\text{direct} = \int \left(1 - \frac{f(\lambda)}{C(\lambda)}\right) d\lambda = -\int \frac{r(\lambda)}{C(\lambda)}\,d\lambda ,\]

evaluated by the trapezoidal rule over the data inside the fit window.

  • FWHM (direct) — measured from the data rather than from \(\sigma\). The continuum‑subtracted profile is first smoothed with a locally quadratic (Savitzky–Golay‑style) filter whose window scales with the number of points in the region; the strongest peak is located, the half‑maximum level is taken as half the peak value, and the FWHM is the separation of the two points where the smoothed profile crosses that level (found by linear interpolation between samples):

\[ \text{FWHM}_\text{direct} = \lambda_\text{right,½} - \lambda_\text{left,½}.\]

Direct measurements are robust to non‑Gaussian line shapes; large disagreements with the model values flag asymmetric or blended lines.

Visualize 'FWHM (direct)' measurements option in fit options can be turned on to show the smoothed line, and the point of peak value and the half-maximum level crossing points on the line.

Velocity measurements

When a rest wavelength is set for the profile fit-result card, two kinematic quantities are reported using the relativistic Doppler relations:

  • Mean velocity — the radial velocity of the line centre relative to its rest wavelength,

\[ v_\mu = c\,\frac{R^2-1}{R^2+1}, \qquad R = \frac{\mu}{\lambda_\text{rest}}.\]

  • FWHM velocity — the line width expressed as a velocity width,

\[ v_\text{FWHM} = \big|\,v(\mu + \tfrac{1}{2}\text{FWHM}) - v(\mu - \tfrac{1}{2}\text{FWHM})\,\big|,\]

with each edge converted to velocity by the same formula.

Uncertainties

Bootstrap errors

Parameter uncertainties come from a residual bootstrap. After the best fit, the fit residuals (data minus model) are resampled with replacement and added back to the model to create many synthetic datasets (300 by default); each is refit, and the reported error of a quantity is the sample standard deviation of its values across the resamples. This is applied to the mean, width (σ and FWHM), amplitude, pseudo‑equivalent width, and the direct measurements.

Propagated errors

The integrated Flux error is propagated analytically from the bootstrap errors of amplitude and width:

\[ \sigma_F = \sqrt{2\pi}\,\sqrt{(\sigma\,\sigma_A)^2 + (A\,\sigma_\sigma)^2}.\]

Velocity errors use the first‑order propagation of the wavelength error,

\[ \sigma_v \approx \frac{c}{\lambda_\text{rest}}\,\sigma_\lambda ,\]

accurate when \(\sigma_\lambda \ll \lambda_\text{rest}\) (the usual case).

Errors can be shown or hidden in the results table via Show errors.

Multi‑profile (blended line) fitting

The Multi‑profile (2N + 4 point) method fits N overlapping Gaussians on a common continuum:

\[ f(\lambda) = C(\lambda) + \sum_{k=1}^{N} A_k \exp\!\left[-\frac{(\lambda-\mu_k)^2}{2\sigma_k^2}\right].\]

How to use it:

  1. Set N components.
  2. Mark two continuum ranges, one on each side of the blend (four points → least‑squares continuum). The fit window is the gap between the two ranges.
  3. Mark a pair of points for each component (2N points). Each pair seeds one Gaussian: its centre is the midpoint of the pair, and the pair width is taken as the initial FWHM, i.e. \(\sigma_{0} = \text{width}/2.3548\).

The amplitudes of all components are solved jointly by linear least squares at each step (the model is linear in the \(A_k\) once the \(\mu_k,\sigma_k\) are fixed), while the centres and widths are refined together.

Results. Each component becomes its own fit card titled Multi profile K – Comp.1 … Comp.N (K is the group number); cards of one group share a background tint. A bold combined model curve (continuum + sum of all components) is drawn over the data, and disappears if you delete the components. Because the direct (data‑based) measurements cannot be attributed to a single component of a blend, they are not reported per component; the model‑based values (mean, FWHM, height, flux, pEW) and their bootstrap errors are.

Options:

  • Constrain components within mark regions — keep each component's centre inside the pair you marked and cap its width near the bracket width, with the search step scaled to the bracket. This strongly improves separation of closely overlapping lines, preventing components from drifting onto one another, swapping, or broadening to swallow the whole blend. For best results mark each pair at roughly the line's true width. When disabled, components are free within the whole fit window.
  • Calc pEW error — also bootstrap the per‑component pEW uncertainty. This is the most expensive part of the calculation (an integration per component per resample); turn it off to speed up fits with many components, in which case pEW is still reported but without an error.

The results table

Click Tabulate to build a measurement table from the current fits, then grow it across many fits and files.

  • Tabulate captures the current visible fits as one row (replacing the table; you are warned if it would discard several existing rows).
  • Append row adds the current fits as an additional row — for example after loading a different spectrum — so you can collect measurements from many objects in one table.
  • Each row has an editable Label (defaulting to the file name)
  • The × deletes the row.

Columns are organized by line, grouped under each line's header with sub‑columns for the measurements. Lines align across rows by name; the same line fit twice in one row appears as separate column groups. Use Select Columns to choose which measurements appear, and Show errors to toggle the ± columns.

Averaging repeated lines

Enable Average same lines to combine, live, all fits of the same line (matched by rest wavelength) into one set of columns using an inverse‑variance weighted mean. For values \(x_i\) with errors \(\sigma_i\), weights \(w_i = 1/\sigma_i^2\):

\[ \bar x = \frac{\sum_i w_i x_i}{\sum_i w_i}, \qquad \sigma_{\bar x} = \frac{1}{\sqrt{\sum_i w_i}}.\]

The reported error combines this formal error with the scatter of the measurements about the weighted mean, added in quadrature:

\[ \sigma_\text{total} = \sqrt{\sigma_{\bar x}^2 + \sigma_\text{scatter}^2}, \qquad \sigma_\text{scatter}^2 = \frac{1}{n-1}\sum_i (x_i - \bar x)^2 .\]

Exporting

Download CSV writes the full table (all rows and columns, with a Label column and error columns when shown). Download JSON writes the same data as a list of row objects. Numeric values are formatted to about six significant figures, with errors rounded to a matching precision.

Error estimation

For partially blended spectral lines and P Cygni profiles, the local continuum level cannot be determined uniquely because neighboring spectral features contaminate the line profile. As a result, continuum placement introduces an additional source of uncertainty that is not captured by the formal fitting errors. To estimate this effect, the same line should be fitted multiple times using different plausible continuum selections.

When tabulating the results in spEXplore, the "Average Same Line" option can be used to combine these measurements automatically. This procedure accounts for both the statistical fitting uncertainties and the uncertainty associated with continuum placement. The underlying methodology is outlined below and may be useful to describe in publications using results derived from spEXplore.

For each profile fit, the uncertainty is estimated using bootstrap simulations, providing a statistical error that reflects the noise properties of the observed spectrum. However, this uncertainty does not account for variations arising from different continuum placements. For blended lines and complex profiles, continuum placement is often the dominant source of uncertainty, and therefore the bootstrap error alone can significantly underestimate the true uncertainty.

To incorporate both sources of error, multiple measurements are obtained using different plausible continuum selections. The final parameter value is taken as the weighted mean of the individual measurements..

\[ \bar{x}_w = \frac{\sum_i w_i x_i}{\sum_i w_i}, \qquad w_i = \frac{1}{\sigma_i^2},\]

where \(x_i\) and \(\sigma_i\) are the fitted parameter and its bootstrap-derived uncertainty, respectively.

The statistical uncertainty of the weighted mean is then

\[ \sigma_{\rm fit} = \left(\sum_i w_i\right)^{-1/2}.\]

The uncertainty associated with continuum placement is estimated from the standard deviation of the measurements obtained using the different continuum selections, denoted by \(s_{\rm cont}\).

The final uncertainty is obtained by combining the statistical fitting uncertainty and the continuum-placement uncertainty in quadrature,

\[ \sigma_{\rm tot} = \sqrt{ \sigma_{\rm fit}^2 + s_{\rm cont}^2 }.\]

This approach accounts for both the random uncertainty arising from spectral noise and the additional uncertainty introduced by the non-unique placement of the continuum in blended or otherwise complex line profiles.

However, if a line is isolated with clear continuum, then bootstrap-derived error from single measurement should be sufficient.

Sessions: saving and restoring work

Save Session writes a single .spx file containing everything needed to resume: the spectrum, file name, redshift, binning, wavelength unit, common velocity, all line markers and line sets, deleted sections, every fitted profile (including multi‑profile groups), the results table, display options, and column configuration. Load Session restores that state exactly.

The .spx file is compressed; it is self‑contained and portable between machines.