PyAETNA v3.8 — Configuration Wizard

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.5Global 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.

Working directory. All relative paths in the config are resolved from here. Typically ./ for the directory containing the YAML file.
Path to the data file (relative to 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.
Reference zero-point for your input time column. When non-zero, report time-series labels use 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.

Names matching the INSTRUMENT column IDs in the data file. Order matters for 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).
Uncheck when the posterior is known to have a single peak or its peaks were found by an earlier run: NUTS and the ensemble then start from a saved peak (init_from_peaks), or else from the prior, which needs a longer adaptation or burn-in. Default: true.
The <config>_peaks.json of an earlier run: start from one of its peaks (init_peak, 1 = the best).
Rank of the saved peak to start from. Default: 1.
Instead of a saved peak: start near these values, one per free parameter (by the names of the samples file), as codes such as allesfitter start their walkers. Not together with init_from_peaks.
Half-width of the uniform ball around init_values, in the sampler's unbounded coordinates. Default: 1e-4.
Required: what to do when the peak search finds several significant peaks (e.g. period aliases). With 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
Prior draws from which the optimisations start, all at once. Default: 32.
A secondary peak counts as significant when its approximate evidence is at least this fraction of the best peak's. Default: 0.001.
L-BFGS iterations per start, at most; damped Newton steps with the exact curvature follow. Default: 500.
Truncate the priors of these free parameters to [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.
Run until the slowest parameter has this many independent draws and the chains agree (R-hat ≤ max_rhat, default 1.01), at most num_samples_if_* draws. For an ensemble, the run must also exceed 50 autocorrelation times.
Largest R-hat accepted by target_ess. Default: 1.01.

Nested Sampling

More live points give a smaller error on ln Z (∝ 1/√n_live) at proportionally higher cost. At least 50.
Stop when the remaining live points could change ln Z by less than this. Default: 0.1; at most 10.
Equally weighted posterior draws used by the reports. ln Z and its error are written to <config>_results.json.
▶

Advanced Nested-Sampling Settings

Optional — leave empty for the defaults
Coordinates in which the slice moves are made. constrained is the default and the recommended choice.
Slice steps per new live point, per free parameter. Default: 4, for an evidence bias below 0.1 nats; 3 is 1.3× faster with a bias of about 0.2 nats; 1 is enough when only the posterior is needed (do not compare its evidences).
How each slice step brackets the likelihood contour. adaptive is the default; with stepping_out, 2 steps per parameter are enough.
Same algorithm and evidence calibration; only the speed and the random numbers differ. Adaptive bracket only.
Fraction of live points replaced per iteration, in (0, 0.5]. Default: 0.1.
Safety cap on the number of iterations. Default: 100000.

Ensemble

Coefficient multiplied by n_free_params to determine the number of ensemble walkers. Must be ≥ 2. The actual walker count is the first even number ≥ coefficient × n_free_params (at least 3 × n_free_params when ESS uses KDEMove). Typical values: 3–5.
Optional: the exact number of walkers (even), instead of walkers_per_free_parameter, e.g. to match the ensemble of another code such as emcee.
Steps per walker (the maximum, with target_ess).
▶

Ensemble Move Strategy

Optional — defaults work well for most cases
Dict of move-name → weight for ESS. Default: {DifferentialMove: 0.7, KDEMove: 0.3}. Supported: DifferentialMove, KDEMove, GaussianMove, RandomMove. For faster CPU iterations, replace expensive KDEMove: {DifferentialMove: 0.8, RandomMove: 0.2}.
Dict of move-name → weight for AIES. Default: {DEMove: 0.5, StretchMove: 0.5}. Supported: DEMove, StretchMove.

NUTS

Number of NUTS chains; they start from different draws around the best peak, so R-hat compares independent starts. At least 2 with target_ess.
Adaptation steps (step size and, unless switched off, mass matrix), then discarded. At least 100.
Draws per chain (the maximum, with target_ess).

NUTS Tuning

Target NUTS acceptance probability. Higher → smaller steps, better exploration but slower. Valid range: [0.5, 0.99]. Recommended: 0.90–0.95 for difficult posteriors.
Maximum NUTS trajectory length (2^depth leapfrog steps). At least 5. Higher allows longer trajectories but uses more memory. Recommended: 8–12 for hard problems.
The mass matrix starts from the curvature of the best peak; unchecked, it is kept and only the step size adapts. Default: true.
Diagonal (default, unchecked): NUTS adapts one independent step-size scale per parameter. Memory-lean; works well when parameters are approximately uncorrelated.
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

JAX operates in float32 by default (~7 significant decimal digits). A timestamp such as 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.
Draws per block for NUTS and the ensembles: progress (and, with 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.
Uncheck to resume from the last checkpoint. Default: true.
Integer for reproducible runs. Leave empty for a seed taken from the system time.

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.

Uncheck to skip report generation entirely (e.g. the PDF already exists and you only want to re-run the physics step, or you want to inspect raw chains first). Default: 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.
Additional samples discarded from each chain start when generating plots/statistics. Does not require re-running sampling — it is a post-processing trim applied at report time. Set to 0 to use all production samples. Ignored for nested sampling. Required, even when the report is switched off.
Maximum points per trace plot. Integer for an evenly-spaced subset, or 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 cases
PyAETNA picks the posterior sample with the lowest potential energy — the same quantity the sampler minimises. When enabled (default), that sample is then refined with BFGS descending exactly the same energy, so the two are directly comparable. The descent runs in unconstrained space, so every iterate stays inside the prior support by construction, and the whole optimisation is JIT-compiled (GPU-friendly). Uncheck to report the best posterior sample unrefined.
Maximum BFGS iterations for the post-sampling MAP refinement. Default: 200. The refined point is kept whenever the energy strictly decreased, even if BFGS did not formally converge (reported as optimization_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.
Maximum number of posterior draws used to compute the 1σ confidence bands in all best-fit plots (best-fit overlay, per-transit TTV panels, transit overlay). Default: 1000. Lower values (e.g. 50–100) make the report significantly faster at the cost of slightly noisier bands — useful during development or when re-generating reports on large chains.
Multiplier for the adaptive sampling interval of the model curves in best-fit plots. Default: 1.0. Use values like 0.5 for extra smoothness in complex models, or > 1.0 for faster computation. Must be > 0.
Default: true. Uncheck to shorten the report of datasets with many visits.
False-alarm probability of the peaks in the periodograms of the residuals (astropy LombScargle).
Number of bootstrap resamplings. Default: 1000.

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

Stellar density in g/cm³. Controls the orbital semi-major axis via Kepler's third law. Use truncnorm to constrain within physical bounds. Global scope only.

Limb Darkening — Kipping q1, q2

Required when LC instruments are present. Also shown for RV-only fits with the Rossiter-McLaughlin effect, which needs the limb darkening of the spectrograph passband (PyAETNA uses q1 = 0.5, q2 = 0.1 if they are absent). Allowed scopes: global or per_instrument. The physics analysis step can convert q1, q2 back to u1, u2.
q1 ∈ [0,1]. 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).
q2 ∈ [0,1].

Light-Curve Dilution Optional

Fraction of the flux in the photometric aperture that comes from the host star, 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.
Contamination depends on the aperture and on the passband, so each instrument usually has its own D. Visits with different contamination (e.g. TESS sectors with different apertures) should be separate instruments.
One entry per LC instrument, taken from the instrument list. D must stay positive: use a fixed value, 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

Enable the RM anomaly for RV observations during transits. Activated automatically when 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.
When checked, 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.
Sky-projected equatorial rotation velocity. Given in km/s (converted to m/s internally). Typical range: 1–20 km/s for FGK stars. Use truncnorm if an external v sin i estimate is available, or uniform for an uninformative prior. Global scope only.
λ = 0 → aligned (prograde), λ = ±π → retrograde, λ = π/2 → polar orbit. Sign convention of Ohta et al. (2005), as in most RM codes (PyAETNA ≥ 4.0). 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.
The size of the RM anomaly depends on how the RVs were measured from the distorted lines, so each RV instrument declares its technique (different techniques can be combined): ccf — centre of a Gaussian fitted to the CCF (Boué et al. 2013): HARPS, HARPS-N, ESPRESSO, NIRPS, SOPHIE, CORALIE pipelines; template — maximum of the cross-correlation with a template (Hirano et al. 2011): iodine cell (HIRES, HDS, PFS), and approximately template matching (SERVAL, LBL). β is the width of the lines without rotation [km/s], thermal, microturbulent and instrumental broadening in quadrature, in the convention exp(−v²/β²) (β = √2 σ = FWHM/1.665). Sun-like star: ≈ 2.1 km/s with ESPRESSO, 2.3 with HARPS/HARPS-N, 2.6 at R = 90 000; for ccf fold in the macroturbulence as β² + ζ²/2. Keep it fixed: it is degenerate with v sin i. template also takes the macroturbulence ζ (2–6 km/s for FGK dwarfs) and the Lorentzian width γ (0.5–1.5 km/s); 0 = none. See documentation.
Leave unchecked unless the inclination is constrained (e.g. from asteroseismology or spot modelling). When absent, PyAETNA assumes i☆ = π/2, i.e. v sin i = v eq.
π/2 (90°) = edge-on stellar spin axis. Values < π/2 mean the stellar pole points toward the observer. 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-visit is the most common choice for photometry: each visit gets its own jitter parameter, all with the same prior. Per-instrument gives each instrument its own prior, which is needed when the instruments differ (the jitter of an RV instrument is in ln(m/s), that of a light curve in ln(relative flux)); tick per visit on an instrument to give each of its visits its own parameter (the hybrid [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

For an RV instrument the normalization is the systemic velocity, in km/s. When light curves and RVs are fitted together, use Per-instrument: the two need different priors (relative flux for LC, km/s for RV). Tick per visit to give each visit of that instrument its own offset (the hybrid [per_instrument, [per_visit, dist, p1, p2], [dist, p1, p2]] syntax).
Useful when ROLL_ANGLE wraps mid-visit. Default: false.
▶

Polynomial Detrending Optional

Skip if no polynomial detrending is needed
Define polynomial detrending against one or more data columns (e.g. time, centroid position, background). Each polynomial subsection defines coefficients c1 (linear), c2 (quadratic), etc. c0 is not allowed — use normalization for the baseline offset. Each coefficient declares its own scope inline: [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 needed
Periodic sin/cos detrending. Each harmonic c_k produces two parameters: name_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 needed
Non-parametric noise modelling via tinygp. Each GP must declare its target instruments. 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 indicators
Models several observables as linear projections of one latent activity process G(t) and its derivative Ġ(t): Δc(t) = Ac·G(t) + Bc·Ġ(t), under a single joint covariance. This is a stronger claim than the GP section above (“these datasets are one curve” rather than “these datasets wiggle alike”), so it is not a strict upgrade — use it for simultaneous, informative indicators measured from the same spectra (RV + BIS + log R′HK). For instrumental detrending, temporally disjoint datasets, or an uninformative indicator, the plain GP section is the right tool.

Indicators 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 needed
Hierarchical Errors-In-Variables (EIV) linear detrending against ancillary covariates with measurement errors (Kelly 2007, ApJ 665 1489). Each EIV block requires both a x_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.

The stellar priors below are used only by this step (they are not sampled): each is a fixed value, uniform or truncnorm (lower, upper, mean, sigma).

Limb Darkening Conversion

Default: true. Converts Kipping to physical quadratic limb darkening coefficients.

Orbital Derived Quantities

Planets for which to compute: ecc, omega_deg, a_Rs, inc_deg, T14_hrs, T23_hrs, ecl_phase, ecl_T14_hrs, ecl_T23_hrs. Leave empty to skip.

Stellar Mass and Radius

With the stellar density from the fit it gives the stellar radius; with radius_star it supersedes the fitted density. Also gives the planet masses from kRV. Leave empty to omit.
With the stellar density from the fit it gives the stellar mass; with mass_star it supersedes the fitted density. Leave empty to omit.

Phase Curve Analysis (Cowan & Agol 2011)

Planets for phase-curve analysis: delta_ecl, T0_K, T_night_K, T_day_K, Ab, epsilon. Requires amp_night / amp_day_minus_amp_night for listed planets and teff. Leave empty to skip.
Stellar effective temperature in Kelvin, needed to turn eclipse depths into brightness temperatures.
Source for eclipse-depth → brightness-temperature inversion. phoenix downloads a library spectrum automatically.
Selects the PHOENIX model. Leave empty for solar metallicity.
Scalar override for log₁₀(g [cm/s²]) for PHOENIX grid selection. Usually derived automatically from mass_star/radius_star. Only set if neither is provided.
Passband of each LC instrument, as an id of the SVO Filter Profile Service. 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 named BJD)
  • 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 the instruments list (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.

Generated YAML