Reading ROOT files

Part 1 of 3 in Read Data

▶ 01. ROOT Files
○ 02. Datasets
○ 03. Remote Data

This tutorial shows how to read ROOT files with FAST-HEP.

1. Download the example files

pixi run fasthep download --json tutorials/data/CMS/Zmumu/files.json --destination data

The manifest downloads small Z → $\mu\mu$ datasets from the CMS experiment into data/CMS/Zmumu/.

2. Inspect the workflow

The important pieces of author.yaml are:

data:
  datasets:
    - name: data
      eventtype: data
      files:
        - data/CMS/Zmumu/data.root

sources:
  events:
    kind: root_tree
    tree: events
    branches:
      - NMuon
      - Muon_Px
      - Muon_Py
      - Muon_Pz
      - EventWeight

The workflow reads the events tree and records a schema snapshot.

3. Run the workflow

pixi run fasthep run tutorials/01-read-data/01-root-files/author.yaml --outdir build/tutorials/01-read-data/01-root-files

4. Inspect the outputs

Look at:

• build/tutorials/01-read-data/01-root-files/compile/normalized.yaml

• build/tutorials/01-read-data/01-root-files/compile/plan.yaml

• build/tutorials/01-read-data/01-root-files/reports/schema/

• build/tutorials/01-read-data/01-root-files/run_summary.yaml

5. What happened?

FAST-HEP resolved the dataset entry, read selected branches from the ROOT tree with the root_tree source, and ran a schema observer on the resulting event stream.

Expected outputs

This tutorial produces two outputs that are particularly useful when exploring a new dataset:

• the event schema, which describes the contents of the event stream

• the run summary, which records what FAST-HEP executed

Event schema

{
  "awkward_type": {
    "EventWeight": "float",
    "Muon_Px": "float[]",
    "Muon_Py": "float[]",
    "Muon_Pz": "float[]",
    "NMuon": "int32_t"
  },
  "entry_count": 1000,
  "envelope": {
    "unwrapped": false
  },
  "fields": [
    "NMuon",
    "Muon_Px",
    "Muon_Py",
    "Muon_Pz",
    "EventWeight"
  ],
  "inspected_python_type": "RootTreeSchema",
  "kind": "schema_snapshot",
  "metadata": {
    "dataset_name": "data",
    "file": "data/CMS/Zmumu/data.root",
    "part": "0_0",
    "partition_id": "events__data__0",
    "source": "events",
    "start": null,
    "stop": null
  },
  "node_id": "read.events",
  "python_type": "RootTreeSchema"
}

The schema describes the branches available in data/CMS/Zmumu/data.root, including their names and types.

Because this tutorial restricts the source to a small set of branches, only those branches appear in the schema report. In a real analysis, schema inspection is often used to explore unfamiliar datasets and identify the quantities needed for later stages.

Run summary

The run summary records what FAST-HEP processed and which modules were involved in the workflow execution.

Show run_summary.yaml

backend: local
strategy: default
success: true
execution:
  backend: local
  strategy: default
  profiles: []
  resources: {}
  pools: {}
  environment: {}
  config: {}
partitions:
- partition:
    id: events__data__0
    dataset: data
    file: data/CMS/Zmumu/data.root
    source: events
    part: '0_0'
    start: null
    stop: null
  outputs:
  - node: observe.hep_schema_snapshot.0.read_events
    port: report
    type: OutputResult
  - node: read.events
    port: stream
    type: RootTreeSchema
warnings: []
hooks:
  enabled:
  - kind: hep.dataset_context
    events:
    - partition_start
    calls: 1
    source: profile:fasthep_curator:default_context
    scope: global
  - kind: hep.error_report
    events:
    - on_node_error
    calls: 0
    source: profile:fasthep_curator:runtime_diagnostics
    scope: global
  - kind: hep.warning_capture
    events:
    - around_node
    calls: 2
    source: profile:fasthep_curator:runtime_diagnostics
    scope: global
summary_path: build/tutorials/01-read-data/01-root-files/run_summary.yaml
artifacts_path: build/tutorials/01-read-data/01-root-files/artifacts

At this stage the run summary is primarily useful as a diagnostic record. Later tutorials will show how FAST-HEP reports and summaries can be turned into more human-readable outputs.