Single-Pulsar Playbook

This guide is a step-by-step manual for running the full single-pulsar workflow.

The goal is practical understanding. After working through these pages, a user should be able to:

• identify the files involved in each stage,

• place configuration keys in the correct file type,

• understand what each stage is intended to produce,

• build a usable single-pulsar branch with consistent system flags and jumps,

• run PQC in a controlled and reproducible way,

• explain the rationale behind a PQC configuration,

• keep detection and mutation conceptually separate.

The pages below are ordered in the recommended progression.

• Overview And Scope
  • What This Manual Covers
  • The Stages In Plain Terms
  • Minimum Single-Pulsar Story
  • Stage Output Matrix
  • Glossary
  • Why PQC Exists
  • Why FixDataset Exists
  • Non-Destructive First Rule
  • The End State
  • Related Documentation
• Files, Directories, And Config Roles
  • Three Different Trees
  • Raw Source-Data Tree
  • Canonical Ingested Dataset Tree
  • The pleb Config Tree
  • Which Keys Go In Which File
  • Recommended Single-Pulsar File Set
  • How Paths Resolve Across These Files
  • How Branches Fit Into The Picture
  • The Most Important Run Keys
  • What Not To Do
  • Minimal Naming Convention
  • How The Config Layers Work Together
  • A Minimal Mental Model
  • Related Documentation
• Ingest: Build The Canonical Pulsar Tree
  • What Ingest Does
  • Two Files Are Required
  • The Mapping JSON
  • How To Read The Mapping Keys
  • Why The Backend Key Matters
  • The Ingest Run Profile
  • How To Explain Each Ingest Run Key
  • Where The Data Ends Up
  • How To Run Ingest
  • What Ingest Does Not Do
  • What To Check After Ingest
  • Common Ingest Mistakes
  • Why This Stage Matters
  • Detailed Mapping Guidance
  • How Ingest Connects To The Next Stage
  • Related Documentation
• First FixDataset Pass: Build A Usable Single-Pulsar Branch
  • Why This Stage Comes Before PQC
  • The Step-1 Profile
  • What Each Key Is For
  • Why run_tempo2 Is Usually Disabled Here
  • What “Basic Par File With All The Jumps” Means
  • How To Run The First Pass
  • What To Inspect After The First Pass
  • How To Read The Outputs
  • What Jumps Mean In This Workflow
  • Common First-Pass Errors
  • What This Stage Usually Writes
  • How This Stage Connects To PQC
  • Related Documentation
• PQC Detection: Run QC Without Editing The Data
  • Why Run PQC At All
  • The Detect Profile
  • Why This Profile Still Has FixDataset Enabled
  • How To Explain The Main PQC Keys
  • How To Pick A First PQC Strategy
  • How To Decide Whether A Detector Family Belongs In The First Run
  • How To Run The Detect Stage
  • What To Inspect After PQC
  • What The QC Outputs Are For
  • What Not To Conclude Too Early
  • The Apply Stage Comes Later
  • How To Choose A Small First Detector Set
  • How This Relates To Action Policy
  • Related Documentation
• Backend-Specific PQC Profiles And Tuning
  • Why Backend-Specific Tuning Exists
  • Where The Override File Goes
  • How Matching Works
  • The Run-Profile Key That Activates Overrides
  • How To Decide What The Backend Key Should Be
  • A Simple Tuning Procedure
  • What To Tune First
  • What Usually Signals The Need For An Override
  • How To Explain Common Patterns
  • What Not To Use Backend Profiles For
  • A Minimal Tuning Example
  • Documentation Standard For Tuning
  • Related Documentation
• Single-Pulsar Three-Pass Workflow
  • The Three Passes
  • The Three Run Profiles
  • The QC-Apply Profile
  • How To Explain The QC-Apply Keys
  • Why The Apply Stage Uses Explicit Outlier Columns
  • How fix_qc_results_dir And fix_qc_branch Work Together
  • The Workflow File
  • How Run Directories And Branches Relate In The Workflow
  • How To Run The Workflow
  • When To Prefer Manual Runs Over The Workflow File
  • Why Branch Chaining Matters
  • Debugging Workflow Mode
  • Final Rule
  • Related Documentation
• Troubleshooting
  • Ingest Failures
  • Step-1 FixDataset Failures
  • PQC Detect Failures
  • Apply-Stage Failures
  • Workflow Failures
  • Minimal Debug Order
  • Related Documentation
• Quick Reference
  • Tracked Example Files
  • Main Commands
  • Useful Inspection Commands
  • Checklist By Stage
  • Related Documentation

How To Use This Manual

Do not skip directly to PQC.

The order matters:

1. start with the filesystem layout and config roles,

2. then ingest and the canonical data tree,

3. then the first FixDataset pass that creates a usable branch with consistent flags and jumps,

4. then pure detection with PQC,

5. then non-destructive QC application,

6. only then discuss tuning, backend-specific overrides, and workflows.

Core principle:

pleb coordinates stages and file movement. pqc is the detector layer used within that process. In practice, it is easier to understand the data tree and branch structure first, then QC.

Further reading:

• configuration system details: Configuration Guide

• layout of configs/: Configuration Layout

• CLI and mode entry points: Command-Line Interface, Running Pleb

• stage-level operational notes: PLEB Deep Dive