correctionlib

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 on this page — 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

correctionlib on PyPI

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

Evidence: correctionlib-2.9.0-cp310-cp310-macosx_11_0_arm64.whl; correctionlib-2.9.0-cp310-cp310-macosx_11_0_universal2.whl; correctionlib-2.9.0-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl; correctionlib-2.9.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl; correctionlib-2.9.0-cp310-cp310-musllinux_1_2_aarch64.whl; correctionlib-2.9.0-cp310-cp310-musllinux_1_2_x86_64.whl; correctionlib-2.9.0-cp310-cp310-win_amd64.whl; correctionlib-2.9.0-cp311-cp311-macosx_11_0_arm64.whl; correctionlib-2.9.0-cp311-cp311-macosx_11_0_universal2.whl; correctionlib-2.9.0-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl; correctionlib-2.9.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl; correctionlib-2.9.0-cp311-cp311-musllinux_1_2_aarch64.whl; correctionlib-2.9.0-cp311-cp311-musllinux_1_2_x86_64.whl; correctionlib-2.9.0-cp311-cp311-win_amd64.whl; correctionlib-2.9.0-cp311-cp311-win_arm64.whl; correctionlib-2.9.0-cp312-cp312-macosx_11_0_arm64.whl; correctionlib-2.9.0-cp312-cp312-macosx_11_0_universal2.whl; correctionlib-2.9.0-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl; correctionlib-2.9.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl; correctionlib-2.9.0-cp312-cp312-musllinux_1_2_aarch64.whl

Tags

More Scientific/Engineering packages