---
id: correctionlib
version: "2.9.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# correctionlib — A generic correction library

License: permissive · Maintenance: active · Downloads: 786.5K/mo

## What it is and what it does

Correctionlib is a library for defining, storing, and evaluating correction factors—mathematical functions that adjust or transform scalar inputs to produce scalar outputs. It is widely used in high-energy physics to encode calibration factors, efficiency corrections, and other data-driven adjustments in a standardized, versioned JSON format. The library provides both a C++ evaluator and Python bindings, allowing corrections to be defined once and reused across analysis pipelines.

The package supports multiple function types: multi-dimensional binned lookups, binned lookups with formula-based outputs, categorical maps, input transforms, and compositions of these primitives. Formulas are parsed using a formal grammar and support a subset of ROOT's TFormula syntax. Corrections are validated against JSON schemas, and the library maintains backward compatibility across minor versions while allowing forward-incompatible additions (such as new node types in v2.9.0). It depends on numpy, pydantic, rich, and packaging.

Use it for:

- Store and evaluate physics calibration factors (e.g., lepton efficiency corrections) in a standardized JSON format shared across a collaboration.
- Apply multi-dimensional binned corrections to particle physics data during analysis, with formula-based outputs for complex transformations.
- Migrate correction data between schema versions using forward-porting tools to maintain compatibility across analysis code.
- Validate correction objects during construction using pydantic type checking before serializing to JSON.
- Compose simple correction nodes (binning, formulas, categorical maps) into complex correction graphs for detector response modeling.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a JSON-based format and evaluator for correction factors—functions that map scalar inputs to scalar outputs—commonly used in high-energy physics analysis, with C++ and Python bindings.

Yes. Correctionlib is actively maintained, has no known vulnerabilities, and is production-stable (Development Status 5). It is purpose-built for high-energy physics workflows and widely adopted in that domain. Install it if you work with HEP data or need a standardized, versioned correction-factor framework; the medium install friction is typical for compiled scientific packages and poses no practical barrier.

## Install

pip install correctionlib
uv add correctionlib
poetry add correctionlib

## Installing correctionlib

Before you install: Medium install friction due to compiled wheels for multiple platforms and Python versions (3.9–3.14). Active maintenance with a recent release (59 days ago) and no known vulnerabilities.

License in practice: BSD-3-Clause is permissive; you may use, modify, and distribute this package freely in commercial and private projects provided you include the license notice.

Quickstart:

pip install correctionlib

import correctionlib
from correctionlib.schemav2 import Correction, CorrectionSet

# Load a correction from JSON
corrections = correctionlib.CorrectionSet.from_file('corrections.json')
correction = corrections['my_correction']
result = correction.evaluate(1.5, 'category_a')

Requires Python 3.9 or later. Compiled wheels are provided for common platforms; installation on unsupported architectures may require building from source.

Verify before relying:

- Whether the C++ evaluator is exposed as a standalone library or only through Python bindings.
- Performance characteristics and typical evaluation latency for large correction graphs.
- Whether numpy vectorization is fully implemented or remains a future feature.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 786.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

correction factors evaluation, HEP physics corrections, binned lookup tables, formula evaluation library, physics data transformations, JSON correction schema, scalar function evaluation, physics-analysis, hep-tools, json-schema

[View on SkillFed](https://skillfed.io/packages/correctionlib) · [View on PyPI](https://pypi.org/project/correctionlib/)