Quickstart

Before you start

PQC expects a .par file and a sibling *_all.tim file produced by tempo2. Example: J1909-3744.par and J1909-3744_all.tim in the same directory.

How this actually loads data

PQC does not compute residuals from .par by itself. It requires both:

  • X.par

  • X_all.tim (same directory; discovered by filename convention)

The pipeline then performs two reads:

  1. libstempo loads timing arrays from the .par + _all.tim pair.

  2. PQC parses X_all.tim (including recursive INCLUDE files) to collect tim metadata/flags.

These are merged into a single table for QC.

CLI (fastest path)

pqc --par /path/to/J1909-3744.par --out results/J1909-3744_qc.csv

This writes:

  • the QC CSV output to results/J1909-3744_qc.csv

  • the run settings TOML to results/J1909-3744_qc.pqc_settings.toml

Python (notebook-friendly)

import pandas as pd
from pqc.pipeline import run_pipeline

df = run_pipeline("/path/to/J1909-3744.par")

# Quick sanity checks
print(df.columns)
print(df[["mjd", "resid", "sigma", "bad_point", "event_member"]].head())

Inspect results

# Keep only good points
good = df.loc[~df["bad_point"].fillna(False)].copy()

# Focus on event members (transients, steps, dips, solar/eclipses, etc.)
events = df.loc[df["event_member"].fillna(False)].copy()

# Save a filtered table
good.to_csv("results/J1909-3744_qc_good.csv", index=False)

What you get

The pipeline returns a pandas DataFrame with timing metadata, QC flags, and optional event annotations. Key columns include:

  • bad_point: aggregate bad measurement flag

  • event_member: aggregate event membership across enabled detectors

  • step_applicable and step_informative

  • dm_step_applicable and dm_step_informative

  • event-specific columns such as exp_dip_member, solar_event_member, eclipse_event_member, gaussian_bump_member, and glitch_member

Important semantics

Rows marked as astrophysical-event members are treated as non-outliers in bad_point. The compatibility field outlier_any remains available and is defined as bad_point OR event_member.

If you run via the CLI, a TOML settings file is also written alongside the CSV (same filename stem with .pqc_settings.toml). This captures the exact configuration used for the run.

Minimal statistical context

Residuals are the difference between observed and modeled TOAs:

\[R_i = t_i^{\mathrm{obs}} - t_i^{\mathrm{model}}\]

Many timing analyses assume (or approximate) independent Gaussian errors, so weights are often proportional to 1/sigma_i^2 and the usual chi-square statistic appears:

\[\chi^2 = \sum_i \left(\frac{R_i}{\sigma_i}\right)^2\]

PQC uses these same residuals and uncertainties but focuses on QC tasks such as outlier detection and event membership labeling rather than full model fitting [Edwards2006] [Vigeland2014].

References

[Edwards2006]

Edwards, R. T., Hobbs, G. B., & Manchester, R. N. (2006). “tempo2, a new pulsar timing package - II. The timing model and precision estimates.” MNRAS, 372(4), 1549-1574. citeturn0search0

[Vigeland2014]

Vigeland, S. J., & Vallisneri, M. (2014). “Bayesian inference for pulsar-timing models.” MNRAS, 440(2), 1446-1457. citeturn1search1