VARTOOLS: A Program for Analyzing Astronomical Time-Series Data

1. Introduction

• Time-domain surveys generate massive data flows, and new surveys are expected to increase the need for specialized analysis software.The paper cites LSST, TESS, PLATO, and HATPI as examples of upcoming surveys.Source: §1 · p. 1
• Vartools combines general-purpose light-curve analysis with batch-processing features, including command-to-command data flow, no per-light-curve human interaction, and native parallel processing.The paper contrasts this design with other general light-curve suites.Source: §1 · p. 1
• General-purpose platforms such as MATLAB, R, IDL, and Python are not typically tailored to astronomy and can require substantial bookkeeping and code for large datasets.Vartools can also be incorporated into pipelines built on these platforms.Source: §1 · p. 2

2. The Vartools Program

• Vartools reads a light curve, applies processing commands, and outputs resulting statistics to an ASCII table; it was developed primarily for pipelines processing large numbers of light curves.The article describes version 1.33; some features depend on external libraries.Source: §2 · p. 2

2.1.1. Input

• Users can supply one light curve or a list, with each curve stored as an ASCII file or binary FITS table and optional light-curve-dependent data in the list.Input formats are configurable, and shell commands can be applied to input files before reading.Source: §2.1.1 · p. 2

2.1.2. Data Flow

• Commands run in command-line order, and a single invocation can chain an arbitrary number, subject in practice to available memory.Parameters can be supplied globally, per light curve, from earlier command results, variables, or analytic expressions.Source: §2.1.2 · p. 2, prompt > vartools -l EXAMPLES /lc_list… · p. 3
• For very large batches, Vartools keeps each light curve in memory and writes it only when requested, reducing redundant disk access between pipeline steps.The paper notes that disk reads and writes often limit processing speed for hundreds of thousands or more files.Source: prompt > vartools -l EXAMPLES /lc_list… · p. 3

2.1.3. Parallelization

• Vartools assigns each light curve to a shared-memory thread for complete processing; individual commands are not parallelized, and output order may differ from input order.The authors describe this approach as appropriate when the number of light curves exceeds the number of processors.Source: §2.1.3 · p. 3

2.1.4. Variables

• Variables can refer to scalar or vector data from light curves, lists, or command results and can be used in expressions, flow control, and analytic fitting.The program also reserves names for time, magnitude or flux, uncertainty, and record number.Source: §2.1.4 · pp. 3–4

2.2. Commands

• The built-in commands cover periodic-signal searches, statistics, model fitting, filtering, simulation, light-curve manipulation, and data-flow control, with support for user-developed commands.The command selection reflects the authors’ research and is biased toward transiting-planet survey routines.Source: §2.2 · p. 4

2.2.1.1. -LS.

• The generalized Lomb–Scargle implementation handles non-uniform sampling, a floating mean, and non-uniform uncertainties, and reports peak significance measures.It uses the Press and Rybicki method to speed trigonometric sums; the paper describes its statistic as ranging from 0 for no signal to 1 for a perfectly sinusoidal signal.Source: §2.2.1.1 · p. 4, where χ2 · p. 4

2 LS(f)

• LS false-alarm estimates use a Horne–Baliunas bandwidth penalty, assume Gaussian white noise, and can be off by a few dex under highly nonuniform sampling.Monte Carlo calibration is needed when false-alarm accuracy better than 1 dex is required.Source: §2 · pp. 4–5

where LS is the value of the periodogram for a given peak,

• The LS routine reports periodogram peak significance using false-alarm probability and S/N, while -GetLSAmpThresh estimates the minimum detectable amplitude at a user-chosen threshold.The amplitude procedure scales and re-adds a fitted multi-harmonic signal until its fixed-period false-alarm probability reaches the threshold.Source: §2 · p. 5, where LS is the value of the… · p. 5, §2.2.1.2 · p. 5

2.2.1.3. -dftclean.

• -dftclean computes a DFT and can iteratively CLEAN significant peaks by subtracting shifted, scaled window functions until no peak exceeds the S/N threshold.Frequency sampling is set by nbeam and the observation baseline; the maximum frequency defaults to the Nyquist frequency.Source: §2.2.1.3 · p. 5

2.2.1.4. -aov.

• AoV fits phase-binned step functions, which can suit sharp features, while its relatively flexible model often yields lower detection significance than sinusoidal methods for other variables.The harmonic variant instead fits a multi-harmonic Fourier series and can use the AoV statistic to optimize the number of harmonics.Source: §2.2.1.4 · p. 5, §2.2.1.5 · p. 6

2.2.1.6. -BLS.

• BLS searches frequencies for periodic box-shaped dips and reports a signal-to-pink-noise statistic that accounts for white and red noise and the sampled transit count.The red-noise estimate uses residual scatter binned on the transit-duration timescale, compared with expected scatter for uncorrelated noise.Source: §2.2.1.6 · pp. 6–7

2.2.1.9. -wwz.

• BLS variants can fix transit duration and reference time, or fix the period; WWZ scans frequency and time shift to characterize quasi-periodic signals that evolve in amplitude or frequency.WWZ outputs the transform, amplitude, and effective sample size across tested frequency/time-shift combinations.Source: §2.2.1.7 · p. 7, §2.2.1.8 · p. 7, §2.2.1.9 · p. 7

2.2.2.2. -autocorrelation.

• The alarm statistic flags correlated variability, while the discrete autocorrelation function handles irregular sampling and is most useful for characterizing feature coherence timescales.The autocorrelation calculation bins pairs by lag and uses measurement uncertainties in its normalization, allowing heteroscedastic data.Source: §2.2.2.1 · p. 8, §2.2.2.2 · p. 8

2.2.2.4. -chi2bin.

• With -chi2bin, reduced χ2 rises as the moving-mean bin width increases for time-correlated variations, but stays statistically constant for pure white noise.The filter replaces each measurement with the local mean and reduces uncertainties by the amount expected for white noise.Source: the reduced χ2, for each light curve · p. 8, §2.2.2.4 · p. 8

2.2.2.5. -Jstet.

• The Stetson J command reports J, kurtosis K, and L; J is higher for time-correlated variability, while L enhances significance for non-Gaussian magnitudes and reduces it when observations are missing.The RMS command also reports the light curve’s scatter and its expected RMS from the supplied photometric uncertainties; -stats provides basic summaries such as means, medians, deviations, percentiles, extrema, and sums.Source: §2.2.2.5 · pp. 8–9, where wall is the maximum value of P w… · p. 9, §2.2.2.6 · p. 9

2.2.3.2. -Killharm.

• -Killharm fits fixed-frequency harmonic series and can report relative amplitudes and phases to characterize signal shape; -decorr is deprecated in favor of the more flexible -linfit.The harmonic series’ peak-to-peak amplitude is estimated by evaluating it across phase steps and refining the extrema with dbrent.Source: §2.2.3.1 · p. 9, §2.2.3.2 · p. 9, The amplitudes may also be specified… · p. 10

2.2.3.3. -linfit.

• -linfit fits user-specified linear combinations by SVD, suppressing poorly constrained parameter combinations; formal parameter uncertainties are valid only when supplied errors are correct and noise is uncorrelated and normally distributed.The implementation zeroes singular values below a tolerance of 10^-9 times the largest singular value.Source: The amplitudes may also be specified… · p. 10, §2.2.3.3 · p. 10, Here the N × Nparam design matrix A… · p. 10

2.2.3.4. -MandelAgolTransit.

• The Mandel–Agol transit fit supports transit and optional radial-velocity parameters, but uses a local search initialized by the user or BLS and is intended for candidate triage, not publication-quality fits.The approximate softened-transit model is parameterized by out-of-transit magnitude, depth, sharpness, period, reference mid-transit time, and duration.Source: §2.2.3.4 · pp. 10–11, §2.2.3.7 · p. 13

2.2.3.5. -microlens.

• The microlensing command fits a Wozniak et al. (2001) model with five free parameters using DHSX, while the single-spot model is deprecated in favor of the distributed -macula command.The spot model describes a circular, uniform-temperature spot and depends on spot geometry, stellar rotation, and limb-darkening and flux-ratio quantities.Source: §2.2.3.5 · p. 11, §2.2.3.8 · p. 13

2.2.3.6. -nonlinfit.

• -nonlinfit supports analytic nonlinear models, optional linear parameters, priors, constraints, and diagonal or non-diagonal observational covariance, including squared-exponential, exponential, and Matérn noise models.For non-diagonal covariances, it uses Cholesky decomposition and back-substitution with truncation to exploit the typically sparse, near-diagonal matrix and reduce computation.Source: §2.2.3.6 · p. 11, for some parameter a, they would… · pp. 11–12

where X2

• Nonlinear parameters can be optimized by amoeba’s local downhill-simplex search or by DEMCMC, which runs at least three simultaneous chains and accepts proposals according to their change in X2.DEMCMC can initialize around an amoeba minimum; chain summaries report parameter medians and standard deviations, with the first 10% excluded by default as burn-in.Source: for some parameter a, they would… · p. 12, where X2 · p. 12

2.2.4.2. -medianfilter.

• Median filtering subtracts or replaces each magnitude using a local statistic, while time restriction includes or excludes observations by time range, listed times, or image IDs.The median filter also permits average or uncertainty-weighted average statistics.Source: §2.2.4.2 · p. 13, §2.2.4.3 · p. 13

2.2.4.4. -SYSREM.

• SYSREM models light curves with shared trend vectors and iteratively solves their trend and response terms by linear least squares, using user-specified σ-clipping to limit outlier influence.Initial trend vectors may represent airmass or image positions; the procedure fits each assumed vector and its associated response before proceeding through the trends.Source: §2.2.4.4 · pp. 13–14

2.2.4.5. -TFA.

• TFA fits light curves using randomly selected ensemble templates, while signal-reconstruction mode also fits a specified signal, such as a periodic step function, fixed signal, or harmonic series.TFA commonly uses many more trend vectors than SYSREM; repeated template sets can be processed efficiently using matrix decompositions followed by back substitution.Source: §2.2.4.5 · p. 14, §2.2.4.6 · p. 14

2.2.5.1. -addnoise.

• Noise simulation offers white noise, Gaussian processes with squared-exponential, exponential, or Matérn covariance, and red noise with power spectrum proportional to 1/f^γ.The correlated Gaussian-process methods use a Cholesky decomposition; the red-noise method uses McCoy and Walden’s wavelet procedure, with −1 < γ < 1, and interpolates simulated uniform samples for nonuniform observation times.Source: §2.2.5.1 · pp. 14–15

2.2.5. Light Curve Simulation

• Signal-injection commands add harmonic and subharmonic series with user-selected or randomly drawn parameters, and copy light curves so each copy can be processed independently.Copies can support recovery-efficiency tests with injected signals or period-finding bandwidth corrections using pure-noise curves with the same sampling.Source: §2.2.5.3 · p. 15, §2.2.5.2 · p. 15

2.2.5.4. -Injecttransit.

• Transit injection uses the Mandel and Agol (2002) model, with user-specified or randomly drawn orbital, planetary, stellar, limb-darkening, and dilution parameters.The supported parameters include period, planet and star properties, inclination, eccentricity, periastron, limb-darkening coefficients, and optional light dilution; period and planet mass or radius may be drawn from several distributions.Source: §2.2.5.4 · p. 15

2.2.6. Light Curve Manipulation

• Manipulation commands bin light curves using selectable statistics, set magnitude uncertainties to measured scatter, convert differential flux to magnitudes, and transform uncertainties by a specified expression.Binning supports configurable bin counts or widths, time reporting, and statistics; empty bins are excluded.Source: §2.2.6.1 · pp. 15–16, §2.2.6.2 · p. 16, §2.2.6.4 · p. 16

2.2.6.3. -converttime.

• VARTOOLS time conversions have internal precision of ∼0.1 milliseconds near J2000.0, but do not support observations made off Earth’s surface.The precision estimate is based on comparison with conversions computed through the JPL HORIZONS interface.Source: §2.2.6.3 · p. 16

Where σ′

• For many datasets, the uncertainty transformation distributes χ2/dof values about unity, but it requires all light curves simultaneously and is incompatible with -parallel.The parameters a and b relate to effective gain and a constant magnitude error term, respectively.Source: Where σ′ · p. 16

2.2.6.6. -expr.

• -expr evaluates analytic expressions pointwise using light-curve variables, command outputs, and parameters, while users can add functions through libraries.Recognized functions and user-defined function support are described in the appendices and extension section.Source: §2.2.6.6 · pp. 16–17

2.2.6.7. -fluxtomag.

• Light-curve utilities convert fluxes to magnitudes, phase and sort observations, resample with several interpolation methods, and rescale uncertainties to make χ2/dof equal one.Resampling can use different interpolation methods for points close to and far from observations.Source: §2.2.6.9 · p. 17, §2.2.6.7 · p. 17, §2.2.6.8 · p. 17

2.2.7. Control of Data Flow

• Data-flow commands switch variables, conditionally execute commands, output light curves, and save or restore a light curve with its associated vectors.Conditionals may be nested, but are ignored by commands that process all light curves simultaneously and by save/restore commands.Source: §2.2.7.1 · p. 17, §2.2.7.2 · p. 17, §2.2.7.3 · p. 17

2.2.8.1. -findblends.

• -findblends fits a harmonic series to an input light curve and spatial matches, then identifies the source with the largest fitted flux amplitude as the most likely variable source.The procedure follows Hartman et al. (2011).Source: §2.2.8.1 · p. 17

2.3. User-Developed Extensions

• User-developed commands are loaded from compiled libraries through a standardized interface, while user-defined analytic functions are separately exposed to command-line expressions.Command algorithms may be written in languages callable from C; examples include Fast χ2, JKTEBOP, and Macula routines.Source: §2.3 · p. 17, §2.3.1 · p. 18, §2.3.2 · p. 18

2.3.2. User-Developed Functions

• User-developed functions are dynamically loaded from libraries and provide named analytic functions that take vectors of double-precision arguments and return a double-precision value.The -F option selects a library by name.Source: §2.3.2 · pp. 18–19

2.4. Options

• The command-line options configure light-curve input, parallel processing, random seeds, output, missing-file handling, and other processing behavior.The -parallel option processes multiple light curves in parallel; -bufferlines trades memory for less frequent output and reduced thread waiting.Source: §2.4 · p. 19

3.1. Searching a set of light curves for periodic variable stars with Lomb-Scargle

• The Lomb–Scargle example detects a 77.7776-day signal in one light curve and a 1.2344-day sinusoidal signal in another.The first example's strong linear trend is well-fit by a period longer than the data span.Source: §3.1 · p. 20, Figure 1 · p. 22

3.2. Processing a FITS-format light curve from Kepler

• The Kepler FITS example selects time, flux, and uncertainty columns, converts flux to magnitudes, calculates scatter and a Lomb–Scargle periodogram, and outputs a converted light curve.It uses -changevariable to select the flux and uncertainty variables.Source: §3.2 · p. 20

3.3. Running the BLS algorithm on a light curve to find transits and eclipses

• The BLS search recovers the example transit at 2.1232 days, with spectroscopic S/N 4.4 and S/Npink 14.5.The text identifies S/Npink as probably the most useful of the calculated metrics for selecting transit candidates.Source: §3.3 · p. 20

3.4. Simulating and Recovering a Transiting Planet Light Curve

• The simulation example adds time-correlated noise and an injected transit, recovers the transit with BLS, and fits a Mandel and Agol transit model.The paper notes that this procedure could be repeated millions of times to estimate survey detection efficiency.Source: §3.4 · p. 20

prompt > cat PER /2 .txt.ls

• Figure 1 presents the example periodogram as period versus log false-alarm probability and frequency versus LS statistic, alongside a phase-folded curve and a whitened periodogram.The periodogram file can report five peaks with whitening between successive peak searches.Source: §3.1 · p. 20, Figure 1 · p. 22

1 MODEL 0 fittrap \

• The transit simulation initializes a light curve with exponential correlated noise, injects a transit with specified orbital and stellar parameters, then uses BLS and a Mandel and Agol model fit for recovery.The noise uses ρ = 0.05 days and σr = σw = 0.0015 mag; the injected period is 2.123456 days.Source: §1 · p. 25

3.5. Searching a set of light curves for variable stars, while filtering noise

• The following example searches a set of light curves for variability after applying two different noise-filtering techniques.Its light curves include observation-level auxiliary information such as image coordinates and image-shape measurements.Source: §3.5 · p. 25

1 MODEL 0 fittrap \

• Figure 3 follows a simulated time-correlated-noise light curve through transit injection, BLS recovery, and a best-fit Mandel-Agol transit model.Source: Figure 3 · p. 27
• The workflow calculates five variability statistics on raw, decorrelated, and TFA-filtered light curves, processing the light curves in parallel.The statistics are RMS scatter, Generalized L-S, BLS, Stetson’s J, and harmonic AoV.Source: §1 · p. 27
• The command settings illustrate search choices, not recommended defaults; the authors say parameters should be considered against the light curves being analyzed.The example scans specified period and transit-duration ranges, with a higher-resolution AoV scan around each peak.Source: §1 · p. 27
• The procedure can produce 381 output columns; header-only output and shell utilities reformat column names for inspection and selection.Selection thresholds need adjustment to the survey’s noise properties.Source: §1 · p. 28

3.6. Trend-filtering while preserving stellar variability with signal-reconstruction TFA

• The example identifies a periodic signal, models it with a harmonic series, and compares non-reconstructive TFA with reconstructive TFA SR.The commands save and restore the light curve to apply both filtering approaches; TFA SR outputs coefficients and model trends.Source: §3.6 · p. 29

4”, “RMS

• 2.3 mmag rises to 7.2 mmag with non-reconstructive TFA, while reconstructive TFA SR reduces residual scatter to 2.1 mmag.Source: 4”, “RMS · p. 29
• TFA SR preserves the signal shape in the phase-folded light curve; the example is primarily intended to illustrate the command’s syntax and operation.Source: 4”, “RMS · p. 29
• The example’s noise filtering is not very effective; larger, intelligently chosen template sets sharing systematic trends would likely reduce residual scatter further.Source: 4”, “RMS · p. 29

1 EXAMPLES /OUTDIR1 1 EXAMPLES /OUTDIR1 \

• The example’s phase-folded light curves compare the input with non-reconstructive TFA and reconstructive TFA SR outputs.Source: Figure 4 · p. 31
• In the illustrated variable-star example, reconstructive TFA SR filters noise better than non-reconstructive TFA while preserving signal shape.Source: §1 · p. 31, Figure 4 · p. 31

3.7. Using the Weighted Wavelet Z-Transform to Characterize a Quasi-Periodic Signal

• The Weighted Wavelet Z-Transform example reveals a 0.3065 day^-1 signal centered at JD − 53725 = 10.174 that is absent later.A lower-significance signal near 0.2 day^-1 may be present earlier.Source: §3.7 · p. 31

3.8. Performing an MCMC fit of a non-linear function to a light curve

• The nonlinear-fit example uses a DEMCMC procedure to estimate free parameters and uncertainties, and outputs the full chain.The illustrative run stops after 10,000 links to limit computing time; the text says more links would typically be used.Source: §3.8 · pp. 31–32

3.9. Converting the times in a light curve from UTC to BJD

• The time-conversion example converts UTC observation times to TDB-corrected BJD using stellar coordinates, ephemeris and leap-second files, and observatory information.Source: §3.9 · p. 32

4.1. Test 1: ASCII vs. Binary I/O

• On the test machine, parsing a 1,000,000-row, three-column ASCII light curve took ∼2.3 s at 17-digit precision and 1.5 s at 8-digit precision; adding RMS calculation changed time negligibly.Reading a 1,000,000-row FITS light curve with three double-precision columns took ∼0.1 s, while outputting a 1,000,000-line ASCII light curve took ∼2 s.Source: §4.1 · pp. 35–36
• For one million points, ASCII input is approximately 20 times slower than FITS input and ASCII output approximately 10 times slower; storage is 56 MB versus 23 MB.These ratios assume three ASCII columns at 17-digit precision; changing precision or column count changes the scaling.Source: §0.2 · p. 36

4.2. Test 2: -LS

• -LS averaged 330 ms per light curve at 16,384 frequencies, or 38 ms with 10 processors; 2,048, 4,096, and 8,192 frequencies took 20, 48, and 110 ms.Parallelism applies across light curves, not within one curve; runtime is dominated by FFTs over sampled frequencies, with frequency-count jumps tied to powers of two.Source: §4.2 · pp. 36–37

4.3. Test 3: -BLS

• -BLS took 1.1 s per light curve (120 ms with 10 processes); 100,000 frequencies raised runtime tenfold, and doubling phase bins roughly doubled it.The expected scaling is a × Nf × Nobs + b × Nf × Nbin × Nbin,tr.Source: §4.3 · p. 37

4.4. Test 4: -aov

• The excerpt introduces an analogous -aov performance test but provides no execution-time result.The tests are described as similar to those for the other commands.Source: §4.4 · p. 37
• -aov takes 9.3 s per light curve for 16,384 frequencies, compared with 930 ms using 10 parallel processes; adding 2 or 3 harmonics raises runtime to 11 or 13 s.The test scans the same number of frequencies as -LS using a pure sinusoid; halving the frequency count halves processing time.Source: §4.4 · p. 37

4.5. Test 5: -wwz

• -wwz takes 1.3 s per light curve with 10 parallel processes for 249 frequencies at 311 time-shifts, and runtime doubles when either count doubles.This corresponds to 13 s per light curve per processor.Source: §4.5 · p. 38

4.6. Test 6: -fastchi2

• 54 ms per light curve for -fastchi2 at 16,384 frequencies is substantially faster than -LS at 330 ms, but -LS is faster at 2,048 or fewer frequencies.With 10 parallel processors, -fastchi2 takes 5.6 ms per light curve; at 2,048, 4,096, and 8,192 frequencies, it takes 34, 36, and 42 ms, respectively, while -LS takes 20 ms at 2,048 or fewer frequencies.Source: §4.6 · p. 38

5. Future Development

• New processing commands, including Fourier filtering and methods for stitching together light curves for a source, are under active development.These are identified as near-term development work.Source: §5 · p. 38
• Parallelization of individual commands and support for non-shared-memory operation, such as MPICH, are future development topics requiring more fundamental code changes.The current parallel-processing scope is limited to processing multiple light curves.Source: §5 · p. 38
• VARTOOLS may extend analytic expressions to support vector and matrix operations.Source: §5 · p. 38
• The developers are working on Python support for user-developed commands and functions, as well as a Python GUI for constructing pipelines and interacting with results.Source: §5 · p. 38

Appendix A. Command Syntax

• Commands require parameters in the stated order; brackets distinguish required from optional terms, quoted keywords are case-sensitive, and flags use 1 or 0.The command name includes a “-” prefix, and unquoted terms are values the user supplies.Source: Appendix A · p. 39
• Shared parameter syntax lets users fix a value globally, read it from the input file, or reuse a value from a prior command’s output.Input-file values can come from a specified column or the next unused column; prior output values can be identified by heading or column number.Source: Appendix A · p. 39
• The addnoise command offers square-exponential, exponential, Matérn, and wavelet correlated-noise models; optional time binning simulates noise independently per bin to speed long-baseline cases.The bintime option is described for cases where the light-curve span greatly exceeds the correlation timescale.Source: Appendix A · pp. 39–40
• The binlc command supports custom per-column binning statistics, shifts the first bin on request, and offers alternative binned-time definitions or a no-shrink mode.With tnoshrink, bincolumnsonly can restrict binning to listed columns and leave other vectors unchanged.Source: Appendix A · pp. 41–42
• For BLS, nobinnedrms speeds calculation but tends to suppress S/N for high-significance detections by calculating spectrum statistics from frequency maxima only.Without the option, statistics use all considered SR values, including non-optimizing transit epochs and durations.Source: Appendix A · p. 42
• BLS options can output best-fit models sampled uniformly in phase or time and sample the spectrum uniformly in period or log-period instead of frequency.The default spectrum sampling is uniform in frequency.Source: Appendix A · p. 43
• BLS command references cover fixed-period and fixed-duration/transit-center options, including parameters such as duration, epoch, and period bounds.The appendix identifies input-parameter tables for -BLSFixPer and -BLSFixDurTc.Source: Table A.7 · p. 43, Appendix A · p. 43, Table A.8 · p. 44
• Other entries document command inputs for clipping, detrending, and periodogram analysis, including moving-mean filter widths and DFT CLEAN options.Each moving-mean filter width is 2.0 times its bintime value, with bintime in minutes when light-curve times are in days.Source: Appendix A · pp. 44–45, Table A.11 · p. 45, Table A.14 · p. 46
• -converttime syntax specifies input and output time formats, time-system options, coordinates, proper motions, and observatory location.The “ppm” option supplies RA and Dec proper motions in milliarcseconds per year; by default, sources are assumed to have none.Source: Table A.12 · p. 45, Appendix A · p. 45
• -Injectharm syntax configures harmonic count and amplitude and phase sources, including list-based, fixed, or random amplitudes.Nharm = 0 includes only the fundamental mode; random amplitudes are drawn uniformly between minamp and maxamp.Source: Appendix A · p. 49

• Harmonic injection allows subharmonics with amplitudes and phases optionally relative to the fundamental, and can output the model series at observation times.Source: Appendix A · pp. 49–50
• Transit injection can draw planet mass and orbital phase from input lists or random distributions, and choose sin(i) randomly subject to a transit.Source: Appendix A · pp. 50–51
• Transit parameters support either eccentricity and argument of periastron or e sin ω and e cos ω, plus selectable limb-darkening laws, dilution, and model output.Source: Appendix A · p. 51
• The linfit command fits an analytic function linear in its free parameters and can store, subtract, or output the best-fit model.Source: Appendix A · p. 53
• The bls option initializes parameters from the highest peak found by the most recent prior -BLS command.Source: Appendix A · p. 53
• The medianfilter command applies a high-pass filter by default, with median or average options, while replace instead performs a low-pass filter.Source: Appendix A · p. 55

Appendix A. Command Syntax

• Optional covariance settings for nonlinear fitting support correlated uncertainties with square-exponential, exponential, or Matérn covariance matrices.The command also exposes parameters for MCMC or amoeba fitting, priors, constraints, and output chains.Source: Appendix A · p. 56
• The -o command controls output destinations and naming, column formatting, binary FITS output, and whether existing files cause termination.By default, output light curves have time, magnitude, and error columns; a custom format can include other variables and printf-style precision.Source: Appendix A · p. 58
• The -Phase command supports AOV, Lomb–Scargle, BLS, or fixed-period phase assignment, with optional T0 and phase-variable settings.Its syntax also permits setting the starting phase.Source: Appendix A · p. 58
• The resampling “gaps” option lets the method for distant resampled times differ from the method used for nearby times.The separation can be specified using a previously calculated value or a value from the input light-curve list.Source: Appendix A · pp. 59–60
• The time-separation options can use a factor of the minimum separation, the median separation, or a specified percentile of input-light-curve separations.The percentile option orders the separations and uses the specified percentile to distinguish near from far points.Source: Appendix A · p. 60
• -restorelc returns the light curve to its state at a specified earlier -savelc call, while -restricttimes syntax includes date-bound, list, expression, and image-list forms.The restoration parameter is the savenumber-th call to -savelc.Source: Appendix A · p. 60
• -Starspot exposes fit flags for spot and stellar parameters, plus options to subtract the best-fit model from the light curve or write that model to a file.The fit flags cover a, b, spot angular radius, stellar-axis inclination, spot latitude and longitude, and constant magnitude.Source: Appendix A · pp. 62–63
• -SYSREM parameters control whether model light curves or final trends are output and whether light-curve uncertainties are used in fitting.When trend output is enabled, the output file contains times or image IDs followed by columns for each trend signal.Source: Appendix A · pp. 63–64
• -TFA and -TFA-SR support trend-list inputs and optional decorrelation against light-curve-specific signals, with flags controlling iterative versus simultaneous processing and trend application order.The syntax also provides options for coordinate columns, excluding nearby trend stars, correcting light curves, and writing coefficients or models.Source: Appendix A · p. 65

• TFA iterations stop when the fractional r.m.s. change falls below “tfathresh” or after “maxiter” iterations.Source: Appendix A · p. 65
• The model signal to preserve can use a binned light curve, with “nbins” setting the number of bins.Source: Appendix A · p. 65
• Phase-binning can take its period from a prior AoV, LS, or BLS command, a light-curve list file, or a fixed value.Source: Appendix A · p. 65
• TFA can fit a file-based signal with free scale and offset parameters, or fit a harmonic-series signal simultaneously.Source: Appendix A · p. 65
• Harmonic models specify counts of harmonics and sub-harmonics, and can use a default light-curve-span period or a selected period source.Source: Appendix A · p. 65
• The WWZ command syntax includes frequency and tau parameters plus optional transform-output directories and formats.Source: Appendix A · p. 65, Table A.45 · p. 66

Appendix B. Columns Output By Each Command

• Output-column names combine a base name with the producing command number, with the column number prepended only when `-numbercolumns` is used.The command number distinguishes repeated calls to the same command.Source: Appendix B · p. 66
• For `fixcolumn`, a parameter can be identified by its column number or by its base column name followed by the command number.Source: Appendix B · p. 66

Appendix B. Columns Output By Each Command

• Tables list output-column information for commands including `-addnoise`, `-alarm`, and `-aov`.The appendix also includes entries for other commands, such as `-autocorrelation` and `-binlc`.Source: Table B.46 · p. 66, Table B.48 · p. 67, Table B.50 · p. 68
• For each BLS peak, the output includes its period and the number of points in an equal-size phase bin immediately following the transit.Source: ”$commandnum) · pp. 68–69
• `Mag` is the uncertainty-weighted mean magnitude used to calculate magnitude residuals for χ2.Source: ”$commandnum) · p. 70
• For each bin time, the reported reduced χ2 follows the light curve binning, and the mean magnitude is calculated using input uncertainties as weights.The output reports the quantities for each specified bin time.Source: ”$commandnum) · pp. 70–71
• Several command entries state that no columns are added to the output table.Source: ”$commandnum) · pp. 71–72

Appendix C. Analytic Functions, Constants, and Operators

• The interpreter reserves analytic-function, constant, and operator names, so they cannot be used as variable names.Source: Appendix C · p. 79
• The interpreter includes exponential, logarithmic, square-root, and absolute-value functions, as well as minimum and maximum operators.Source: Appendix C · p. 79
• Trigonometric functions specify whether inputs or outputs use radians or degrees; for example, `sin` takes radians while `sindegr` takes degrees.Source: Appendix C · pp. 79–80
• The listed functions include inverse trigonometric functions, with `atan2` and `atan2degr` returning four-quadrant angles in radians and degrees, respectively.Source: Appendix C · p. 80
• Other listed names include hyperbolic and error functions, random draws, the constants `PI` and `E`, and zero-based light-curve indices `NR` and `NF`.Source: Appendix C · p. 80

Appendix D. Justification for the -ensemblerescalesig procedure

• The procedure chooses a and b for the transformation in equation 91 so that χ2/dof = 1 for a typical transformed light curve.Source: Appendix D · p. 80
• It obtains a and b by solving the linear least-squares problem in equations 92–94.Source: Appendix D · p. 80
• The procedure is used by the `-ensemblerescalesig` command.Source: Appendix D · p. 80

NJD,i X

• The procedure seeks a and b that minimize a least-squares objective for a typical light curve’s reduced χ2 after transformation.The direct formulation is nonlinear and requires summing over observations in every light curve for each evaluation.Source: NJD,i X · p. 80, where the expected value of χ′2 · p. 80

where the expected value of χ′2

• The -ensemblerescalesig command approximates the transformed uncertainty to replace the costly nonlinear least-squares problem with a linear least-squares problem for a and b.The direct approach would require a sum over every observation in every light curve for each evaluation.Source: where the expected value of χ′2 · p. 80, ¯ RMSi · p. 81

In other words, rather than using the transformed value of σ2

• Instead of using each transformed uncertainty directly, the method scales individual uncertainties by the ratio of expected variances after and before transformation.Source: In other words, rather than using the… · p. 80

¯ RMSi

• The resulting expression can be treated as a linear least-squares problem for a and b.Source: ¯ RMSi · p. 81