heron Usage Guide

Getting started

heron is organised as a set of C++ modules with headers in include/ and implementation files in src/. The repository also ships small executables in apps/ and helper scripts in scripts/. When exploring the codebase, start by identifying the module that matches your task (for example ana/ for analysis-level tooling or io/ for data access).

The most effective way to learn the codebase is to trace a feature end-to-end: begin with a command-line executable, locate the module that implements the core logic, and then follow the associated headers to understand the data structures involved. This approach reveals how datasets, selections, and outputs are composed.

Prerequisites

Before extending heron, ensure you have:

  • A working C++ toolchain that matches the project’s build setup.

  • ROOT installed and available in your environment.

  • Familiarity with the module layout so you can place new logic in the appropriate directory.

If you are unsure where new code should live, start in ana/ for analysis orchestration and move outward to the supporting modules once responsibilities are clear.

Typical workflow

The common workflow when extending heron is:

  1. Add or update headers in the module include/ folder.

  2. Implement the corresponding source code in src/.

  3. Update or add an executable in apps/ if you need a command-line entry point.

  4. Add or update documentation in docs/ so that users can discover the feature.

When refactoring, try to keep public interfaces stable. Prefer adding new methods with clear, explicit parameters over changing existing signatures. This minimises disruption for downstream analysis code.

Module orientation

Use these cues to decide where new functionality should live:

  • Data access: io/ handles file I/O, tree layouts, provenance capture, and normalisation helpers.

  • Analysis configuration and selections: ana/ provides RDataFrame services, derived columns, and selection presets.

  • Plotting: plot/ keeps visualisation and plotting style logic separate from computation.

  • CLI drivers: apps/ hosts the command-line entry points.

Documentation checklist

Use this checklist when touching documentation:

  • Update docs/index.rst with any new pages or navigation entries.

  • Run sphinx-build docs _build to validate the site locally.

  • Ensure your branch is merged to the default branch so the GitHub Pages deployment workflow publishes the new site.

To keep documentation consistent and polished:

  • Use descriptive section headings and short introductory paragraphs.

  • Prefer structured lists over dense paragraphs.

  • Link back to relevant modules so readers can quickly navigate to the code.

  • Keep spelling in British English, matching the codebase.

Where to look for data definitions

Some module-level cues to help orient a new contributor:

  • io/ for input data layouts, provenance output, and SampleIO metadata.

  • ana/ for derived column definitions and selection logic.

  • apps/config/event_columns.tsv for the event output schema reference.

If you need to locate column naming conventions or event layouts, search within the io/ module first, then trace any references into ana/. The apps/config/event_columns.tsv file provides a reference list of tracked event columns.

Contributing notes

heron uses British-English spelling in code and documentation, and applies consistent naming for classes and functions. When adding new types, prefer explicit PascalCase names (Dataset, Selection, HistDef), and use lowercase_with_underscores for methods.

When authoring documentation pages:

  • Add a short overview section that states the purpose of the page.

  • Provide a clear list of responsibilities or expected outcomes.

  • Include references to relevant modules or executables to help readers pivot into the source code.