Skip to content

2D Distributions

The hera.utils.statistics module provides calcDist2d, a function that computes a normalized 2D histogram suitable for contour plots. It wraps matplotlib.pyplot.hist2d and adds several normalization modes.

Importing

from hera.utils.statistics import calcDist2d

Basic Usage

import numpy as np
import matplotlib.pyplot as plt
from hera.utils.statistics import calcDist2d

# Generate sample data
rng = np.random.default_rng(42)
x = rng.normal(0, 1, 5000)
y = 0.5 * x + rng.normal(0, 0.5, 5000)

x_mid, y_mid, hist = calcDist2d(x, y, bins=30)

plt.contourf(x_mid, y_mid, hist, levels=20, cmap="viridis")
plt.colorbar(label="Normalized density")
plt.xlabel("X")
plt.ylabel("Y")
plt.title("2D Distribution")
plt.show()

Using with a DataFrame

When your data lives in a pandas DataFrame, pass column names as strings and the DataFrame as data:

import pandas as pd
from hera.utils.statistics import calcDist2d

df = pd.DataFrame({"wind_speed": x, "temperature": y})

x_mid, y_mid, hist = calcDist2d("wind_speed", "temperature", data=df, bins=25)

Normalization Modes

The normalization parameter controls how the raw bin counts are scaled:

Mode Description
"max_normalized" Divide all bins by the maximum count so the peak equals 1. This is the default.
"density" Divide each bin count by the bin area (counts per unit area). The result is not divided by the total number of samples, so it does not integrate to 1.
"y_normalized" Normalize each y-bin so that its values across the x-bins sum to 1 (each row of the returned hist sums to 1). This is the distribution of x conditional on y; y-bins with no samples stay 0.

Any other value raises ValueError.

# Density normalization
x_mid, y_mid, hist = calcDist2d(x, y, bins=30, normalization="density")

# Row-normalized (distribution of x within each y-bin)
x_mid, y_mid, hist = calcDist2d(x, y, bins=30, normalization="y_normalized")

Restricting the Axis Range

Use x_range and y_range to limit the histogram to a specific region:

x_mid, y_mid, hist = calcDist2d(
    x, y,
    bins=40,
    x_range=(-2, 2),
    y_range=(-2, 2),
)

Both must be provided together as (lower, upper) tuples; if only one is given, it is silently ignored and the full data range is used.

bins is passed straight to matplotlib.pyplot.hist2d, so it can also be a (nx, ny) pair or explicit bin edges.

Return Values

calcDist2d returns three arrays:

  • x_mid -- 1D array of bin-center x-coordinates.
  • y_mid -- 1D array of bin-center y-coordinates.
  • hist -- 2D array of shape (len(y_mid), len(x_mid)) (the transposed hist2d matrix), ready for plt.contourf(x_mid, y_mid, hist).