Examples

Compare two branches of a data set

This example compares timing residuals between a reference branch and a candidate branch after updating a timing model.

home_dir = "/data/epta"
singularity_image = "/images/tempo2.sif"
dataset_name = "EPTA"
branches = ["main", "candidate-update"]
reference_branch = "main"
results_dir = "results"
jobs = 4

Run:

pleb --config pipeline.toml

Interpretation:

• Residual plots and change reports highlight pulsars where the update shifts residual structure or changes reduced chi-square.

• Look for frequency-dependent residuals that might indicate unmodeled DM variations or scattering. [Keith2013] [Cordes2016]

Param-scan for DM derivatives

If a pulsar lacks a binary model and shows elevated reduced chi-square, use the built-in scan profile to test DM derivatives:

pleb --config pipeline.toml --param-scan --scan-typical --scan-dm-threshold 2.0

The scan evaluates candidates by \(\\Delta\\chi^2\) and highlights models that reduce residual structure. [Edwards2006] [Hobbs2006]

QC-assisted outlier review

Enable QC to detect outliers and transient residual behavior:

pleb --config pipeline.toml --qc

After the run, inspect QC plots grouped by backend. Backend-specific clusters of outliers can indicate instrumental offsets or calibration issues. [Manchester2005] [Coles2011]

Generate a QC-only report from an existing run directory:

pleb qc-report --run-dir results/run_2024-01-01 --backend-col group