docs: guides to the run log and the PDF reports, with example figures (4296ee36) · Commits · Gaetano Scandariato / PyAETNA

README.md

+3 −10

Changes for README.md: 3 added lines, 10 removed lines.
Original line number	Diff line number	Diff line
		@@ -171,18 +171,11 @@ Comprehensive documentation is available:

		- Output & Diagnostics. After a successful run, PyAETNA creates an output directory named `PyAETNAouts/` inside the specified `data.working_dir`. Every file is named `<config>_<kind>`, where `<config>` is the configuration file name without `.yaml`, so several configurations fitted to the same data keep separate outputs. The folder contains:

		- Log (`<config>_run.log`): The primary audit trail and diagnostic log for the execution pipeline. It includes:
		1. Initialization: Time-stamped logs of config parsing, path resolution, and data loading.
		2. Environment: JAX version, backend (CPU/GPU/TPU), and device acceleration diagnostics.
		3. Initialization Check: Walker positions, potential energies, and gradient norms immediately after the first step, with warnings for numerical issues.
		4. Convergence: Step-by-step progress for warmup, energy spread tests, and NUTS transition metrics (including ESS and divergence rates).
		5. Analysis: Execution logs for the reporting and physics derivation stages, including MCMC summary tables and goodness-of-fit metrics.
		6. Errors: Automated capture of Python warnings and detailed exception stack traces.
		7. Citations: Auto-generated BibTeX entries based on the active feature set used in the analysis.
		- Results (`<config>_results.json`): the run settings (sampler, device, precision, chains, draws, seed), the provenance (code revision, package versions), R-hat and ESS for every parameter, the fixed parameters, the MAP, the nested-sampling evidence, the instruments and the configuration.
		- Log (`<config>_run.log`): the record of the run: provenance and device, data and priors, the sampler's progress, the posterior summary with R-hat and effective sample sizes (or the Bayesian evidence), goodness of fit, derived quantities, warnings and the BibTeX entries to cite. [Reading the run log](docs/outputs/run_log.md) goes through it block by block and lists what to check first.
		- Results (`<config>_results.json`): the run settings (sampler, device, precision, chains, draws, seed), the provenance (code revision, package versions), R-hat and ESS for every parameter, the fixed parameters, the MAP, the goodness of fit (χ², maximum likelihood, AIC, AICc, BIC), the nested-sampling evidence, the instruments and the configuration.
		- Posterior samples (`<config>_samples.npz`): one array per parameter, shaped `(chain, draw)`, and the `potential_energy` of every draw when the sampler records it (NUTS, nested sampling).
		- Model components (`<config>_components.npz`): the data (`bjd`, `y`, `dy`, `instrument`, `visit`) and, on every data point, the MAP model and its components (`map/total`, `map/planet`, `map/gp_mean`, …), the posterior median (`median/…`) and the 16th–84th percentile band (`q16_84/…`).
		- Report (`<config>_report.pdf`) and, with a `physics:` section, physics report (`<config>_physics.pdf`): phase-folded fits, residuals, corner plots and derived quantities.
		- Report (`<config>_report.pdf`) and, with a `physics:` section, physics report (`<config>_physics.pdf`): phase-folded fits, residuals, corner plots and derived quantities. [Reading the PDF reports](docs/outputs/report.md) shows an example of every page and how to read it.
		- Checkpoint (`<config>_checkpoint.pckl`): the sampler state, used to resume a run and by the reports. It holds PyAETNA objects that a later version may not be able to open: keep the `.json` and `.npz` files as the record of a run.

		The `.json` and `.npz` files hold only numbers, strings and arrays, so they can be read with `json` and `numpy` (or any language) without PyAETNA; `PyAETNA.outputs` has loaders for them. To load, plot and rebuild the model from them, see the [Loading and plotting results](docs/load_binary_model.ipynb) notebook.

docs/config/index.md

+2 −0

Changes for docs/config/index.md: 2 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		@@ -22,6 +22,8 @@ The configuration documentation is organized into modular sections matching the
		- [Sampling Section](sampling.md) — The two sampling branches: nested sampling (posterior + Bayesian evidence) and MCMC (ensemble warmup, convergence test, NUTS/ESS/AIES), with pros and cons of each; floating point precision and checkpoints.
		- [Instruments Section](instruments.md) — Instrument identifiers and data types (`LC` vs `RV`).
		- [Reports Section](reports.md) — Post sampling analysis and diagnostic reports.

		To read what a run produces, see [Reading the run log](../outputs/run_log.md) and [Reading the PDF reports](../outputs/report.md).
		- [Detrending Section](detrending.md) — Normalization modes, detrending schemes.
		- [Multi-dimensional GP](multigp.md) — Joint modelling of RVs and activity indicators through one latent activity process (Rajpaul+2015 / Barragán+2022).
		- [Star Section](star.md) — Stellar parameters.

docs/config/reports.md

+1 −0

Changes for docs/config/reports.md: 1 added line, 0 removed lines.
Original line number	Diff line number	Diff line
		@@ -3,6 +3,7 @@
		# Reports Configuration (`reports`)

		The `reports` section configures post-sampling diagnostic report generation, posterior plotting options, 1-σ confidence band evaluations, and adaptive plotting.
		How to read the result is explained in [Reading the PDF reports](../outputs/report.md) and [Reading the run log](../outputs/run_log.md).


		<!--, and post-sampling Maximum A Posteriori (MAP) optimization.-->

docs/outputs/img/bestfit_instrument_lc.png

0 → 100644

+41.4 KiB

Loading image diff...

docs/outputs/img/bestfit_instrument_rv.png

0 → 100644

+50.2 KiB

Loading image diff...

Original line number	Diff line number	Diff line
		@@ -171,18 +171,11 @@ Comprehensive documentation is available:

		- Output & Diagnostics. After a successful run, PyAETNA creates an output directory named `PyAETNAouts/` inside the specified `data.working_dir`. Every file is named `<config>_<kind>`, where `<config>` is the configuration file name without `.yaml`, so several configurations fitted to the same data keep separate outputs. The folder contains:

		- Log (`<config>_run.log`): The primary audit trail and diagnostic log for the execution pipeline. It includes:
		1. Initialization: Time-stamped logs of config parsing, path resolution, and data loading.
		2. Environment: JAX version, backend (CPU/GPU/TPU), and device acceleration diagnostics.
		3. Initialization Check: Walker positions, potential energies, and gradient norms immediately after the first step, with warnings for numerical issues.
		4. Convergence: Step-by-step progress for warmup, energy spread tests, and NUTS transition metrics (including ESS and divergence rates).
		5. Analysis: Execution logs for the reporting and physics derivation stages, including MCMC summary tables and goodness-of-fit metrics.
		6. Errors: Automated capture of Python warnings and detailed exception stack traces.
		7. Citations: Auto-generated BibTeX entries based on the active feature set used in the analysis.
		- Results (`<config>_results.json`): the run settings (sampler, device, precision, chains, draws, seed), the provenance (code revision, package versions), R-hat and ESS for every parameter, the fixed parameters, the MAP, the nested-sampling evidence, the instruments and the configuration.
		- Log (`<config>_run.log`): the record of the run: provenance and device, data and priors, the sampler's progress, the posterior summary with R-hat and effective sample sizes (or the Bayesian evidence), goodness of fit, derived quantities, warnings and the BibTeX entries to cite. [Reading the run log](docs/outputs/run_log.md) goes through it block by block and lists what to check first.
		- Results (`<config>_results.json`): the run settings (sampler, device, precision, chains, draws, seed), the provenance (code revision, package versions), R-hat and ESS for every parameter, the fixed parameters, the MAP, the goodness of fit (χ², maximum likelihood, AIC, AICc, BIC), the nested-sampling evidence, the instruments and the configuration.
		- Posterior samples (`<config>_samples.npz`): one array per parameter, shaped `(chain, draw)`, and the `potential_energy` of every draw when the sampler records it (NUTS, nested sampling).
		- Model components (`<config>_components.npz`): the data (`bjd`, `y`, `dy`, `instrument`, `visit`) and, on every data point, the MAP model and its components (`map/total`, `map/planet`, `map/gp_mean`, …), the posterior median (`median/…`) and the 16th–84th percentile band (`q16_84/…`).
		- Report (`<config>_report.pdf`) and, with a `physics:` section, physics report (`<config>_physics.pdf`): phase-folded fits, residuals, corner plots and derived quantities.
		- Report (`<config>_report.pdf`) and, with a `physics:` section, physics report (`<config>_physics.pdf`): phase-folded fits, residuals, corner plots and derived quantities. [Reading the PDF reports](docs/outputs/report.md) shows an example of every page and how to read it.
		- Checkpoint (`<config>_checkpoint.pckl`): the sampler state, used to resume a run and by the reports. It holds PyAETNA objects that a later version may not be able to open: keep the `.json` and `.npz` files as the record of a run.

		The `.json` and `.npz` files hold only numbers, strings and arrays, so they can be read with `json` and `numpy` (or any language) without PyAETNA; `PyAETNA.outputs` has loaders for them. To load, plot and rebuild the model from them, see the [Loading and plotting results](docs/load_binary_model.ipynb) notebook.