fasthep-render

fasthep-render provides plotting, table rendering, reporting, and visualization utilities for FAST-HEP workflows.

The Python import namespace is:

import fasthep_render

Scope

fasthep-render is responsible for:

• histogram rendering
• cutflow tables
• report generation
• plotting backends
• rendering registries
• artifact formatting
• summary visualizations
• workflow diagnostics output

It is the presentation and reporting layer of the FAST-HEP ecosystem.

Relationship to fasthep-flow

fasthep-flow provides:

• workflow compilation
• orchestration
• execution planning
• backend interfaces

fasthep-render provides:

• visualization
• report generation
• artifact formatting
• plotting implementations
• rendering specifications

In practice, most HEP users will use both packages together.

Recommended companion packages

• fasthep-flow

  • workflow language and execution engine

• fasthep-carpenter

  • HEP analysis transforms
  • histogramming
  • event processing

• fasthep-curator

  • dataset inspection
  • validation
  • metadata generation

• fasthep-cli

  • the unified fasthep command-line interface

Alternatively, install the meta package:

pip install fasthep

Installation

Install directly:

pip install fasthep-render

Development environment:

pixi install
pixi run ci

Minimal example

Example render specification:

render:
  NumberOfJets:
    renderer: histogram
    style:
      title: Jet multiplicity
      x_label: Number of jets
      y_label: Events

Example Python usage:

from fasthep_render.api import render_spec_file

render_spec_file(
    "render_specs/render_NumberOfJets.yaml",
    product="results/NumberOfJets.pkl",
    out="results/NumberOfJets.png",
)

Renderer implementations are organised by domain:

• fasthep_render.hist for histogram plots and render-side histogram transforms
• fasthep_render.graph for graph renderers and graph compile hooks
• fasthep_render.reports for document/template rendering
• fasthep_render.tables for tabular outputs

fasthep_render.api is the stable invocation boundary for standalone rendering and Flow-facing render sinks.

Comparison area normalisation

hep.render.comparison supports a small presentation-only option:

comparison:
  normalise: area

This scales each input histogram independently to unit visible-bin area before drawing the comparison, using the histogram API's density() implementation for the normalized visible-bin values. The renderer operates on histogram copies, so stored histogram artifacts keep their original weighted counts and can be reused by other render stages. Weighted variances are scaled with the copied histogram.

Zero-integral histograms are left unchanged and reported in renderer metadata. Negative visible-bin integrals are rejected because the area normalisation would be ambiguous. This option is intentionally narrow; a more general render transform mechanism may replace it later.

Design principles

fasthep-render focuses on:

• declarative rendering
• reusable render specifications
• backend-independent visualization
• registry-driven extensibility
• reproducible reports
• publication-oriented outputs

The package intentionally separates rendering and presentation concerns from workflow execution and analysis logic.

Documentation

Main FAST-HEP documentation:

• https://fast-hep.github.io

API documentation for this package:

• https://fasthep-render.readthedocs.io/en/latest/

Repository

Main FAST-HEP repository and project links:

• https://github.com/FAST-HEP/fasthep

Contributing

Contribution guidelines, development setup, and project-wide documentation are maintained centrally in the main FAST-HEP repository.

Legacy branch

Earlier rendering implementations existed inside the monolithic prototype repositories.

The current repository contains the standalone split-package rendering layer.

Status

FAST-HEP is currently in active pre-alpha development.

Interfaces may evolve rapidly while the package split and stabilization work continues.