Metadata-Version: 2.5
Name: fasthep-render
Version: 2026.8.1
Summary: Rendering sinks and style helpers for FAST-HEP workflows.
Author: FAST-HEP contributors
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fasthep-flow
Requires-Dist: fasthep-toolbench
Requires-Dist: hist
Requires-Dist: jinja2
Requires-Dist: markdown-it-py
Requires-Dist: matplotlib
Requires-Dist: mplhep
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# fasthep-render

[![CI](https://github.com/FAST-HEP/fasthep-render/actions/workflows/ci.yml/badge.svg)](https://github.com/FAST-HEP/fasthep-render/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/fasthep-render)](https://pypi.org/project/fasthep-render/)
[![Python Versions](https://img.shields.io/pypi/pyversions/fasthep-render)](https://pypi.org/project/fasthep-render/)
[![Documentation Status](https://readthedocs.org/projects/fasthep-render/badge/?version=latest)](https://fasthep-render.readthedocs.io/en/latest/)
[![Discussions](https://img.shields.io/static/v1?label=Discussions\&message=Ask\&color=blue\&logo=github)](https://github.com/FAST-HEP/fasthep/discussions)

<p align="center">
  <a href="https://github.com/FAST-HEP/fasthep">
    <picture>
      <source
        media="(prefers-color-scheme: dark)"
        srcset="https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-white.png"
      >
      <source
        media="(prefers-color-scheme: light)"
        srcset="https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-black.png"
      >
      <img
        alt="FAST-HEP"
        src="https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-black.png"
        width="500"
      >
    </picture>
  </a>
</p>

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

The Python import namespace is:

```python id="zlm9e4"
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:

```bash id="8w8c26"
pip install fasthep
```

## Installation

Install directly:

```bash id="51vrbp"
pip install fasthep-render
```

Development environment:

```bash id="1zwf1u"
pixi install
pixi run ci
```

## Minimal example

Example render specification:

```yaml id="n8d4uo"
render:
  NumberOfJets:
    renderer: histogram
    style:
      title: Jet multiplicity
      x_label: Number of jets
      y_label: Events
```

Example Python usage:

```python id="xskmwo"
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:

```yaml
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](https://fast-hep.github.io)

API documentation for this package:

* [https://fasthep-render.readthedocs.io/en/latest/](https://fasthep-render.readthedocs.io/en/latest/)

## Repository

Main FAST-HEP repository and project links:

* [https://github.com/FAST-HEP/fasthep](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.
