CorrectionLib

Warnings

• breaking Starting with v2.8.0, the `evaluate()` method will return flat `awkward` arrays when flat `awkward` arrays are passed as input. Previously, it would return `numpy` arrays in this scenario.
  Fix: If `numpy` array output is required, explicitly call `.to_numpy()` on the result, e.g., `my_correction.evaluate(...).to_numpy()`.
• breaking Versions of CorrectionLib prior to v2.6.0 exhibit silent wrong results for vectorized evaluation when used with `numpy` 2.0. This is a critical compatibility issue.
  Fix: Upgrade CorrectionLib to version 2.6.0 or higher to ensure correct vectorized evaluation with `numpy` 2.0+.
• breaking Since v2.6.0, the representation of infinities in bin edges for correction definitions has changed from floating-point values to string literals (`"inf"` or `"-inf"`). Older JSON files might not be forward-compatible without conversion.
  Fix: Update your correction JSON files to use `"inf"` or `"-inf"` strings for infinite bin edges as per the updated schema. Version 2.6.1 allows reading older JSONs for backwards compatibility, but authoring new ones should use strings.
• breaking Python 3.6 support has been officially dropped starting from v2.5.0. The library now requires Python 3.9 or newer.
  Fix: Ensure your environment is running Python 3.9 or a more recent compatible version.
• gotcha CorrectionLib migrated to `pydantic` v2 in v2.5.0. Users interacting directly with CorrectionLib's schema models (e.g., `correctionlib.schemav2.CorrectionSet`) should be aware of `pydantic` v1 vs v2 breaking changes, particularly method renames (e.g., `dict()` to `model_dump()`) and configuration changes.
  Fix: Consult the official `pydantic` v1 to v2 migration guide. `bump-pydantic` is a tool available to assist with automated code migration.
• gotcha When installing `correctionlib` and planning to use its C++ evaluator (e.g., from ROOT or a standalone executable), C++ ABI compatibility between the installed library and your environment is crucial. Mismatches can lead to linker errors.
  Fix: To avoid ABI issues, install `correctionlib` by forcing a source build within your environment: `pip install --no-binary=correctionlib correctionlib`. This ensures C++ components are compiled with compatible settings.

Install

• pip install correctionlib PyPI

Imports

• CorrectionSet

  from correctionlib import CorrectionSet

• schemav2

  from correctionlib import schemav2

Quickstart

This quickstart demonstrates how to define a simple 2D binned correction using CorrectionLib's JSON schema, save it to a file, and then load and evaluate it in Python. It shows how to retrieve a specific correction from a `CorrectionSet` and calculate the corrected value for given inputs.

import correctionlib
import os
import json

# Create a dummy JSON correction file content
correction_json_content = '''
{
  "schema_version": 2,
  "description": "Simple example corrections",
  "corrections": [
    {
      "version": 1,
      "name": "my_sf",
      "inputs": [
        {"name": "x", "type": "real"},
        {"name": "y", "type": "real"}
      ],
      "output": {"name": "scale_factor", "type": "real"},
      "data": {
        "nodetype": "binning",
        "input": "x",
        "edges": [0.0, 5.0, 10.0],
        "content": [
          {
            "nodetype": "binning",
            "input": "y",
            "edges": [0.0, 5.0, 10.0],
            "content": [
              0.9,
              1.0
            ]
          },
          {
            "nodetype": "binning",
            "input": "y",
            "edges": [0.0, 5.0, 10.0],
            "content": [
              1.1,
              1.2
            ]
          }
        ],
        "flow": "clamp"
      }
    }
  ]
}
'''

# Save the content to a temporary file
file_path = "example_correction.json"
with open(file_path, "w") as f:
    f.write(correction_json_content)

# Load the corrections from the file
corrections = correctionlib.CorrectionSet.from_file(file_path)

# Access a specific correction
my_correction = corrections["my_sf"]

# Evaluate the correction
# Example 1: x=3.0, y=2.0 (falls in first x-bin, first y-bin)
result1 = my_correction.evaluate(3.0, 2.0)
print(f"Correction for x=3.0, y=2.0: {result1}")

# Example 2: x=7.0, y=6.0 (falls in second x-bin, second y-bin)
result2 = my_correction.evaluate(7.0, 6.0)
print(f"Correction for x=7.0, y=6.0: {result2}")

# Clean up the temporary file
os.remove(file_path)