Welcome to the PyAETNA Configuration Wizard
This wizard will guide you step-by-step through creating a valid PyAETNA YAML configuration file. Each section corresponds to a block in the configuration file. Required fields are marked with Required, while optional sections can be skipped with Optional.
The YAML preview on the right updates live as you fill in values. When you're done, copy or download the file. To change an existing configuration, use Load from File: the form is filled in from it, and whatever the form cannot show is kept unchanged in the output and listed above the preview.
Scope System Quick Reference
Every sampled parameter in PyAETNA declares a scope — how many independent copies are created:
param: 0.5 | Global fixed — single scalar value |
[global, dist, p1, p2] | Global sampled — one free parameter for all data |
[per_visit, dist, p1, p2] | Per-visit — independent param per visit |
[per_instrument, e1, e2, ...] | Per-instrument — one entry per instrument |
Supported distributions: uniform, normal, truncnorm, lognormal, beta, gamma, cauchy, exponential, studentt, laplace.
Math expressions like jnp.inf, 2*jnp.pi are accepted in scalar fields.
Named Priors Optional Global
Define reusable prior specifications. Reference them in other sections using "@name".
Multiple parameters referencing the same name are tied to a single shared latent value.
Entries must be scalar fixed values or scalar prior definitions (no scoped syntax allowed here).
Data Required
Define the path to your data file and working directory. The data file must be whitespace-delimited with columns:
TIME (time in days, preferably offset to small numbers; BJD is accepted as its former name), Y (flux or RV), SIGMA (uncertainty).
Optional columns: EXPTIME (default 0), VISIT (default 1), INSTRUMENT (default 1).
Any extra column (ROLL_ANGLE, CENTROID_X, BACKGROUND, …) becomes a detrending basis vector.
./ for the directory containing the YAML file.working_dir). The file should be whitespace-delimited with a header row naming each column. Lines starting with # are treated as comments. For multi-instrument datasets, all instruments must share the same column set — pad missing basis vectors with NaN.Time − <timeZeroPoint>. Leave 0 to omit this key.Instruments & Data Types Required
List your instrument names and their data types. The instruments list must match the unique INSTRUMENT column values in your data file (in order). Each instrument needs a type: LC (light curve) or RV (radial velocity).
If omitted, instrument names are auto-generated from the data, but explicit naming is strongly recommended.
per_instrument scope entries. Examples: CHEOPS, TESS or TESS, HARPS.LC = light curve (normalised flux), RV = radial velocity (m/s in the data file; the RV normalization, i.e. the systemic velocity, is given in km/s). Must have the same number of entries as instruments.Sampling Required Global
Configure the sampling: section. Three branches, chosen explicitly:
ns, nested sampling, the only route that gives the Bayesian evidence (ln Z) for model comparison;
nuts, the No-U-Turn Sampler; ess or aies, an ensemble sampler. Every branch
starts with a peak search: optimisations from many prior draws find the peaks of the posterior;
NUTS and the ensemble start from the best one, with the parameter scales of its curvature. The MCMC branches
report AIC/BIC only. The form shows only the keys that apply to the chosen sampler, and only those are written.
Sampler
ns: starts from the prior; gives the posterior and the evidence. It keeps only one of several separate peaks: run one peak at a time (see on_multiple_peaks).
nuts: gradient-based; chains start from draws around the best peak, with its curvature as mass matrix, then adapt.
ess/aies: gradient-free ensembles; walkers start from draws around the best peak; the burn-in is discarded in the reports (reports.discard_extra_warmup).init_from_peaks), or else from the prior, which needs a longer adaptation or burn-in. Default: true.<config>_peaks.json of an earlier run: start from one of its peaks (init_peak, 1 = the best).init_from_peaks.init_values, in the sampler's unbounded coordinates. Default: 1e-4.stop, PyAETNA writes <config>_peak<k>.yaml, one per peak, whose prior_bounds isolate it; run each (with ns, their evidences add up to the total).Peak Search and Convergence
Optional — leave empty for the defaults[low, high], keeping their shape: one peak of a posterior with several. The configurations written by on_multiple_peaks: stop set it for each peak.max_rhat, default 1.01), at most num_samples_if_* draws. For an ensemble, the run must also exceed 50 autocorrelation times.target_ess. Default: 1.01.Nested Sampling
0.1; at most 10.<config>_results.json.Advanced Nested-Sampling Settings
Optional — leave empty for the defaultsconstrained is the default and the recommended choice.adaptive is the default; with stepping_out, 2 steps per parameter are enough.Ensemble
KDEMove). Typical values: 3–5.walkers_per_free_parameter, e.g. to match the ensemble of another code such as emcee.target_ess).Ensemble Move Strategy
Optional — defaults work well for most cases{DifferentialMove: 0.7, KDEMove: 0.3}. Supported: DifferentialMove, KDEMove, GaussianMove, RandomMove. For faster CPU iterations, replace expensive KDEMove: {DifferentialMove: 0.8, RandomMove: 0.2}.{DEMove: 0.5, StretchMove: 0.5}. Supported: DEMove, StretchMove.NUTS
target_ess.target_ess).NUTS Tuning
true.Dense/full (checked): NUTS learns the full parameter covariance during warmup. Strongly improves mixing when parameters are strongly correlated (e.g.
rp_by_rs–impact). Cost: O(N²) memory. Optional, default false.Precision & Checkpointing
59445.1234567 already uses all 7 digits for the integer part, leaving virtually none for the fractional part after subtraction — causing errors of order minutes in transit timing.auto (recommended): activates float64 automatically when the ephemeris parameters suggest precision loss is likely.true: always float64 — safe for all use cases; ~20–30% slower on GPU.false: always float32 — fastest, but only safe for RV-only fits or when transit timing is not sampled.target_ess, the convergence test) is reported after each block, and the checkpoint, which allows resuming interrupted runs, is written after a block at most every 5 minutes. Required for every sampler; nested sampling checkpoints every minute on its own.true.Reports Required Global
Controls the PDF report generation after sampling. The report includes trace plots, corner plots, best-fit model overlays, and a summary statistics table. These settings affect the report only, not the sampling itself.
true. The report includes: trace plots per free parameter, corner/triangle plots, best-fit model overlays on the data, and a summary statistics table with medians plus 1-σ and 2-σ credible intervals.all to plot everything (can be slow for long chains). Required, even when the report is switched off.Advanced Report Settings
Optional — defaults work for most casesoptimization_partial). The log states which case occurred: hit the iteration limit — raise this value; line search stalled — raising it will not help, and the improved point is used anyway.true. Uncheck to shorten the report of datasets with many visits.LombScargle).Stellar Parameters Required Global
Stellar density is required (controls orbital scale a/R★). Limb darkening coefficients (q1, q2) are required when light-curve instruments are present and may be omitted for RV-only fits. The Kipping (2013) parametrisation maps q1, q2 ∈ [0,1] to physical quadratic limb darkening coefficients u1, u2. A light-curve dilution factor can be added for apertures contaminated by other stars.
Stellar Density
truncnorm to constrain within physical bounds. Global scope only.Limb Darkening — Kipping q1, q2
global or per_instrument. The physics analysis step can convert q1, q2 back to u1, u2.uniform(0, 1) gives a physically uninformative prior. Per-instrument: one prior per passband; an RV instrument needs one only for the RM effect (otherwise leave its fixed placeholder).Light-Curve Dilution Optional
D = Fhost / (Fhost + Fcontaminants); D = 1 means no contamination.
The planetary light-curve signal (transit, occultation, phase curve) of each LC instrument is multiplied by D,
so rp_by_rs stays the intrinsic radius ratio. LC instruments only.D is degenerate with
rp_by_rs (depth ≈ D × (Rp/R★)²): fix it, usually to 1,
for a reference light curve already corrected for contamination (e.g. TESS PDCSAP), and sample it for the
others with a shared rp_by_rs. Same convention as juliet's mdilution;
allesfitter's host_dil and EXOFASTv2's dilute equal 1 − D.uniform, truncnorm (lower bound ≥ 0) or beta; normal-type priors are refused.
D > 1 describes a light curve whose contamination was over-corrected. RV instruments receive a fixed
placeholder (1.0), which creates no parameter.Rossiter-McLaughlin Effect Optional
v_sin_i is present in the star block.
Requires at least one planet with kRV.The RM amplitude scales roughly as (Rp/Rs)² × v sin i. See documentation for details.
v_sin_i is added to the YAML star block, activating the
RM model for all RV instruments, and lambda_spin is added to every planet_<X> block.truncnorm if an external v sin i estimate is available,
or uniform for an uninformative prior. Global scope only.uniform(−π, π) is fully uninformative. Global scope only.
Written to every planet_<X> block (it is a planet parameter); edit the YAML for different
priors per planet. Without it, PyAETNA fixes λ at 0.truncnorm(lo, hi, mean, sigma) is recommended when external constraints exist.Log Jitter Required
White-noise jitter added in quadrature to SIGMA uncertainties: σ_total² = σ_orig² + exp(2 × log_jitter).
This accounts for underestimated error bars and astrophysical/instrumental noise not captured by the model.
The parameter is in log-scale; set to -jnp.inf to disable jitter entirely.
[per_instrument, [per_visit, dist, p1, p2], [dist, p1, p2]] syntax).
A fixed -jnp.inf disables the jitter.Detrending Normalization Required
Configure the baseline model: normalization is always required. Optionally add polynomial, Fourier series, and/or Gaussian Process detrending components against any data column. For RV instruments, normalization acts as the systemic velocity (γ) and is always applied additively.
Normalization Mode Required
multiplicative or additive for LC instruments. For RV instruments normalization is the systemic velocity (γ) and is always additive regardless of this setting.Normalization Prior Required
[per_instrument, [per_visit, dist, p1, p2], [dist, p1, p2]] syntax).false.Polynomial Detrending Optional
Skip if no polynomial detrending is needed[per_visit, dist, p1, p2], [global, dist, p1, p2], etc. Hybrid prior definition is supported: [per_instrument, [per_visit, dist, p1, p2], [dist, p1, p2]] where individual instruments may use per-visit sub-entries.Fourier Series Optional
Skip if no periodic detrending is neededname_ck_s (sin) and name_ck_c (cos).
The same prior applies to both components. Each harmonic declares its own scope inline: [per_visit, dist, p1, p2], [global, dist, p1, p2], or [per_instrument, [per_visit, dist, p1, p2], [dist, p1, p2]] (hybrid supported).Gaussian Processes Optional
Skip if no GP noise modelling is neededinstruments.
Multiple GPs per instrument are summed. Hyperparameters use scoped syntax (global or per_instrument).
O(N) kernels (quasiseparable): Matern32_quasisep, Matern52_quasisep, SHO, SHO_Quality, Cosine_quasisep.
O(N³) kernels (dense): ExpSquared (alias RBF), Matern32, Matern52, QuasiPeriodic, ExpSineSquared, Cosine, Constant.
An instrument cannot be in both a GP block and a multi-dimensional GP block.Multi-dimensional GP — Rajpaul (2015) / Barragán (2022) Optional
Skip unless jointly fitting RVs with activity indicatorsIndicators are ordinary extra columns in the same data file: each channel needs a value column and a matching
<NAME>_ERR column. No new data type, no format change.
There is no
log_gp_sigma: the latent process is unit-variance and all amplitude lives in
the per-channel A/B, otherwise (G, A, B) and (kG, A/k, B/k) would be indistinguishable.
EIV Linear Detrending — Kelly (2007) Optional
Skip if no errors-in-variables detrending is neededx_variable column and a matching
<x_variable>_ERR uncertainty column in the data file. The latent true covariate is modelled as a
Gaussian mixture of K components ( K=1 strongly recommended ).
The EIV slope is absorbed into the deterministic mean trend; EIV variance inflation is added in quadrature
to measurement errors (and, when active, to the GP diagonal). No separate intercept is needed — baseline
normalization is handled by the normalization prior above.
The latent-variable priors
mu_xi and log_tau are optional: if not provided, they are
assigned data-driven default priors and inherit the slope scope automatically.Planet Parameters Optional Global
Define zero or more planets. Each planet section configures ephemeris (transit time & period), orbital geometry (impact parameter, eccentricity), radius ratio, phase curve amplitudes, and RV semi-amplitude.
Planets are auto-detected by keys starting with planet_ (e.g. planet_b, planet_c).
If you have no planets to fit (e.g. pure detrending or jitter-only test), skip this step entirely.
Physics Analysis Optional
Activates the third pipeline step: derived physical quantities from the posterior.
Run only after confirming the sampling and observables report are good.
Produces a separate <config>_physics.pdf with corner plots of all derived quantities.
This entire section can be skipped if you only need the fit. You can add it later and re-run without re-sampling.
uniform or truncnorm (lower, upper, mean, sigma).Limb Darkening Conversion
true. Converts Kipping to physical quadratic limb darkening coefficients.Orbital Derived Quantities
Stellar Mass and Radius
radius_star it supersedes the fitted density. Also gives the planet masses from kRV. Leave empty to omit.mass_star it supersedes the fitted density. Leave empty to omit.Phase Curve Analysis (Cowan & Agol 2011)
amp_night / amp_day_minus_amp_night for listed planets and teff. Leave empty to skip.phoenix downloads a library spectrum automatically.TESS, CHEOPS, KEPLER and K2 are built in.Review & Export
Your configuration is complete! Review the YAML preview on the right panel. You can go back to any step to make changes — the preview updates live. Use Copy to Clipboard or Download to save your configuration file.
Next Steps
1. Check the list of warnings above the YAML preview, if any, then save the file in your working directory. PyAETNA needs the .yaml extension (.yml is refused).
2. Prepare your data file as a whitespace-delimited text file with a header row. Lines starting with # are treated as comments.
Mandatory columns:
TIME— the time column (BJD, or BJD minus an offset, in days; formerly namedBJD)Y— normalised photometric flux (LC) or radial velocity in m/s (RV)SIGMA— 1-σ measurement uncertainty on Y, same units as Y
Optional standard columns (with their defaults if absent):
EXPTIME— exposure time in days (default: 0, disables sub-exposure integration)VISIT— integer visit / orbit ID, 1-based; groups consecutive rows (default: all = 1)INSTRUMENT— integer instrument index, 1-based; must match the order declared in theinstrumentslist (default: all = 1)
Detrending basis vectors (any other column is auto-detected):
- Common examples:
ROLL_ANGLE,CENTROID_X,CENTROID_Y,BACKGROUND,SKY,AIRMASS, … - Any column beyond the standard ones above is automatically available as a detrending basis vector for polynomial or Fourier terms
- Pad missing basis vectors for instruments that lack them with
NaN
3. Run PyAETNA: pyaetna your_config.yaml
Tip: For the first run, use shorter chains (num_adapt_if_nuts: 200, num_samples_if_nuts: 500) to verify the model compiles and runs correctly before a full production run.