A generic correction library

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for ncsmith from gravatar.com ncsmith

Unverified details

These details have not been verified by PyPI
Project links
GitHub Statistics

View statistics for this project via Libraries.io, or by using our public dataset on Google BigQuery

Meta

License: BSD License (BSD 3-Clause License)

Author: Nick Smith

Maintainer: Nick Smith

Requires: Python >=3.7

Classifiers

Project description

correctionlib

Actions Status Documentation Status Code style: black

conda version PyPI version PyPI platforms

GitHub Discussion

Introduction

The purpose of this library is to provide a well-structured JSON data format for a wide variety of ad-hoc correction factors encountered in a typical HEP analysis and a companion evaluation tool suitable for use in C++ and python programs. Here we restrict our definition of correction factors to a class of functions with scalar inputs that produce a scalar output.

In python, the function signature is:

def f(*args: str | int | float) -> float:
    return ...

In C++, the evaluator implements this currently as:

double Correction::evaluate(const std::vector<std::variant<int, double, std::string>>& values) const;

The supported function classes include:

  • multi-dimensional binned lookups;
  • binned lookups pointing to multi-argument formulas with a restricted math function set (exp, sqrt, etc.);
  • categorical (string or integer enumeration) maps;
  • input transforms (updating one input value in place); and
  • compositions of the above.

Each function type is represented by a "node" in a call graph and holds all of its parameters in a JSON structure, described by the JSON schema. Possible future extension nodes might include weigted sums (which, when composed with the others, could represent a BDT) and perhaps simple MLPs.

The tool should provide:

  • standardized, versioned JSON schemas;
  • forward-porting tools (to migrate data written in older schema versions); and
  • a well-optimized C++ evaluator and python bindings (with numpy vectorization support).

This tool will definitely not provide:

  • support for TLorentzVector or other object-type inputs (such tools should be written as a higher-level tool depending on this library as a low-level tool)

Formula support currently includes a mostly-complete subset of the ROOT library TFormula class, and is implemented in a threadsafe standalone manner. The parsing grammar is formally defined and parsed through the use of a header-only PEG parser library. The supported features mirror CMSSW's reco::formulaEvaluator and fully passes the test suite for that utility with the purposeful exception of the TMath:: namespace. The python bindings may be able to call into numexpr, though, due to the tree-like structure of the corrections, it may prove difficult to exploit vectorization at levels other than the entrypoint.

Detailed instructions for installing and using this package are provided in the documentation.

Creating new corrections

A demo/tutorial of the features is available in the documentation and also available interactively on binder

The correctionlib.schemav2 module provides a helpful framework for defining correction objects and correctionlib.convert includes select conversion routines for common types. Nodes can be type-checked as they are constructed using the parse_obj class method or by directly constructing them using keyword arguments.

Developing

See CONTRIBUTING.md

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for ncsmith from gravatar.com ncsmith

Unverified details

These details have not been verified by PyPI
Project links
GitHub Statistics

View statistics for this project via Libraries.io, or by using our public dataset on Google BigQuery

Meta

License: BSD License (BSD 3-Clause License)

Author: Nick Smith

Maintainer: Nick Smith

Requires: Python >=3.7

Classifiers

Release history Release notifications | RSS feed

This version

2.5.0

2.4.0

2.3.3

2.3.1 yanked

Reason this release was yanked:

Missing dependency

2.2.2

2.2.1

2.1.0

2.0.0

2.0.0rc6 pre-release

2.0.0rc4 pre-release

2.0.0rc3 pre-release

1.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

correctionlib-2.5.0.tar.gz (3.9 MB view hashes)

Uploaded Source

Built Distributions

correctionlib-2.5.0-cp312-cp312-win_amd64.whl (544.7 kB view hashes)

Uploaded CPython 3.12 Windows x86-64

correctionlib-2.5.0-cp312-cp312-win32.whl (496.3 kB view hashes)

Uploaded CPython 3.12 Windows x86

correctionlib-2.5.0-cp312-cp312-musllinux_1_1_x86_64.whl (959.1 kB view hashes)

Uploaded CPython 3.12 musllinux: musl 1.1+ x86-64

correctionlib-2.5.0-cp312-cp312-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.12 musllinux: musl 1.1+ i686

correctionlib-2.5.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (453.4 kB view hashes)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

correctionlib-2.5.0-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl (472.4 kB view hashes)

Uploaded CPython 3.12 manylinux: glibc 2.17+ i686

correctionlib-2.5.0-cp312-cp312-macosx_10_14_x86_64.whl (367.3 kB view hashes)

Uploaded CPython 3.12 macOS 10.14+ x86-64

correctionlib-2.5.0-cp311-cp311-win_amd64.whl (544.3 kB view hashes)

Uploaded CPython 3.11 Windows x86-64

correctionlib-2.5.0-cp311-cp311-win32.whl (495.2 kB view hashes)

Uploaded CPython 3.11 Windows x86

correctionlib-2.5.0-cp311-cp311-musllinux_1_1_x86_64.whl (961.2 kB view hashes)

Uploaded CPython 3.11 musllinux: musl 1.1+ x86-64

correctionlib-2.5.0-cp311-cp311-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.11 musllinux: musl 1.1+ i686

correctionlib-2.5.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (454.1 kB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

correctionlib-2.5.0-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl (472.2 kB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ i686

correctionlib-2.5.0-cp311-cp311-macosx_10_14_x86_64.whl (364.3 kB view hashes)

Uploaded CPython 3.11 macOS 10.14+ x86-64

correctionlib-2.5.0-cp310-cp310-win_amd64.whl (544.2 kB view hashes)

Uploaded CPython 3.10 Windows x86-64

correctionlib-2.5.0-cp310-cp310-win32.whl (495.2 kB view hashes)

Uploaded CPython 3.10 Windows x86

correctionlib-2.5.0-cp310-cp310-musllinux_1_1_x86_64.whl (961.3 kB view hashes)

Uploaded CPython 3.10 musllinux: musl 1.1+ x86-64

correctionlib-2.5.0-cp310-cp310-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.10 musllinux: musl 1.1+ i686

correctionlib-2.5.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (454.1 kB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

correctionlib-2.5.0-cp310-cp310-manylinux_2_17_i686.manylinux2014_i686.whl (472.2 kB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ i686

correctionlib-2.5.0-cp310-cp310-macosx_10_14_x86_64.whl (364.3 kB view hashes)

Uploaded CPython 3.10 macOS 10.14+ x86-64

correctionlib-2.5.0-cp39-cp39-win_amd64.whl (542.3 kB view hashes)

Uploaded CPython 3.9 Windows x86-64

correctionlib-2.5.0-cp39-cp39-win32.whl (495.2 kB view hashes)

Uploaded CPython 3.9 Windows x86

correctionlib-2.5.0-cp39-cp39-musllinux_1_1_x86_64.whl (961.1 kB view hashes)

Uploaded CPython 3.9 musllinux: musl 1.1+ x86-64

correctionlib-2.5.0-cp39-cp39-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.9 musllinux: musl 1.1+ i686

correctionlib-2.5.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (454.1 kB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

correctionlib-2.5.0-cp39-cp39-manylinux_2_17_i686.manylinux2014_i686.whl (472.0 kB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ i686

correctionlib-2.5.0-cp39-cp39-macosx_10_14_x86_64.whl (364.4 kB view hashes)

Uploaded CPython 3.9 macOS 10.14+ x86-64

correctionlib-2.5.0-cp38-cp38-win_amd64.whl (544.4 kB view hashes)

Uploaded CPython 3.8 Windows x86-64

correctionlib-2.5.0-cp38-cp38-win32.whl (495.3 kB view hashes)

Uploaded CPython 3.8 Windows x86

correctionlib-2.5.0-cp38-cp38-musllinux_1_1_x86_64.whl (960.9 kB view hashes)

Uploaded CPython 3.8 musllinux: musl 1.1+ x86-64

correctionlib-2.5.0-cp38-cp38-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.8 musllinux: musl 1.1+ i686

correctionlib-2.5.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (454.2 kB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.17+ x86-64

correctionlib-2.5.0-cp38-cp38-manylinux_2_17_i686.manylinux2014_i686.whl (471.5 kB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.17+ i686

correctionlib-2.5.0-cp38-cp38-macosx_10_14_x86_64.whl (364.3 kB view hashes)

Uploaded CPython 3.8 macOS 10.14+ x86-64

correctionlib-2.5.0-cp37-cp37m-win_amd64.whl (544.0 kB view hashes)

Uploaded CPython 3.7m Windows x86-64

correctionlib-2.5.0-cp37-cp37m-win32.whl (497.0 kB view hashes)

Uploaded CPython 3.7m Windows x86

correctionlib-2.5.0-cp37-cp37m-musllinux_1_1_x86_64.whl (964.2 kB view hashes)

Uploaded CPython 3.7m musllinux: musl 1.1+ x86-64

correctionlib-2.5.0-cp37-cp37m-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.7m musllinux: musl 1.1+ i686

correctionlib-2.5.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (454.3 kB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.17+ x86-64

correctionlib-2.5.0-cp37-cp37m-manylinux_2_17_i686.manylinux2014_i686.whl (474.0 kB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.17+ i686

correctionlib-2.5.0-cp37-cp37m-macosx_10_14_x86_64.whl (362.0 kB view hashes)

Uploaded CPython 3.7m macOS 10.14+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page