Analysis repositories

FAST-HEP encourages analyses to be structured as installable Python packages rather than collections of standalone scripts.

This approach improves:

The recommended structure is intentionally similar to modern Python packaging practices.

A typical analysis repository may look like:

my-analysis/
├── author.yaml
├── pyproject.toml
├── README.md
├── src/
│   └── my_analysis/
│       ├── profiles/
│       │   └── registry.yaml
│       ├── transforms/
│       ├── hooks/
│       ├── sinks/
│       ├── sources/
│       └── __init__.py
├── tests/
└── data/

This structure allows the analysis to behave like a normal Python package while also exposing FAST-HEP workflow extensions.

Why package analyses?#

Historically, many HEP analyses evolved as collections of scripts and notebooks.

FAST-HEP instead encourages analyses to expose:

through standard Python packaging.

This makes analyses easier to:

Registries and profiles#

Analysis repositories typically expose a registry profile:

src/my_analysis/profiles/registry.yaml

which can then be activated in workflows:

use:
  profiles:
    - my_analysis:registry

This allows analyses to register:

without modifying FAST-HEP core packages.

For more detail, see:

Transforms#

Transforms contain reusable analysis logic.

Typical examples include:

Example structure:

transforms/
├── muons.py
├── jets.py
└── selections.py

Transforms are generally registered through the analysis registry.

Sources#

Sources introduce data into workflows.

Analysis repositories may provide:

Example:

sources/
└── toy_source.py

Hooks#

Hooks allow analyses to react to runtime lifecycle events.

Common use cases include:

Hooks intentionally remain separate from core analysis transforms.

Sinks#

Sinks consume produced artifacts and persist outputs.

Examples include:

Rendering integrations are currently also implemented through sink-style interfaces.

Testing#

Analysis repositories are encouraged to include automated tests.

Typical testing layers include:

FAST-HEP development tooling is designed to support cross-package integration testing through the fasthep-dev workspace.

Workshop examples#

The fasthep-workshop repository serves as a reference implementation of the recommended analysis structure.

It contains:

The workshop repository is intended to evolve alongside the FAST-HEP ecosystem and demonstrate recommended practices.

Future directions#

Planned tooling may eventually include:

The goal is to make it easier to create portable and reproducible analysis repositories with minimal boilerplate.

Design philosophy#

FAST-HEP encourages analyses to behave like modular software projects rather than isolated execution scripts.

This helps support:

while still allowing experiment-specific customisation where needed.

On this page