BINNED_STATISTIC_2D
Overview
The BINNED_STATISTIC_2D
function computes a bidimensional binned statistic (mean, sum, median, etc.) for one or more sets of data. It generalizes the histogram2d function to support various statistics, allowing you to analyze the distribution of values within specified bins along two dimensions. For more details, see the scipy.stats.binned_statistic_2d documentation .
This example function is provided as-is without any representation of accuracy.
Usage
To use the function in Excel:
=BINNED_STATISTIC_2D(x, y, values, [statistic], [bins], [xlowerlimit], [xupperlimit], [ylowerlimit], [yupperlimit])
x
(2D list, required): Data to bin along the first dimension.y
(2D list, required): Data to bin along the second dimension.values
(2D list, required): Data to compute statistics on.statistic
(str, optional, default=‘mean’): Statistic to compute (‘mean’, ‘sum’, ‘median’, ‘count’, ‘std’, ‘min’, ‘max’).bins
(int, optional, default=10): Number of bins (applies to both dimensions).xlowerlimit
(float, optional): Lower bound for the x bin range.xupperlimit
(float, optional): Upper bound for the x bin range.ylowerlimit
(float, optional): Lower bound for the y bin range.yupperlimit
(float, optional): Upper bound for the y bin range.
The function returns a 2D list of statistic values for each bin, or an error message (string) if the input is invalid.
Examples
Example 1: Count in 2x2 Bins
Inputs:
x | y | values | statistic | bins | xlowerlimit | xupperlimit | ylowerlimit | yupperlimit |
---|---|---|---|---|---|---|---|---|
0.1 | 2.1 | 1 | count | 2 | 0 | 1 | 2 | 3 |
0.1 | 2.6 | 1 | ||||||
0.1 | 2.1 | 1 | ||||||
0.6 | 2.1 | 1 |
Excel formula:
=BINNED_STATISTIC_2D({0.1;0.1;0.1;0.6}, {2.1;2.6;2.1;2.1}, {1;1;1;1}, "count", 2, 0, 1, 2, 3)
Expected output:
y1 | y2 | |
---|---|---|
x1 | 2 | 1 |
x2 | 1 | 0 |
Example 2: Mean in 2x2 Bins
Inputs:
x | y | values | statistic | bins | xlowerlimit | xupperlimit | ylowerlimit | yupperlimit |
---|---|---|---|---|---|---|---|---|
0.1 | 2.1 | 10 | mean | 2 | 0 | 1 | 2 | 3 |
0.1 | 2.6 | 20 | ||||||
0.1 | 2.1 | 30 | ||||||
0.6 | 2.1 | 40 |
Excel formula:
=BINNED_STATISTIC_2D({0.1;0.1;0.1;0.6}, {2.1;2.6;2.1;2.1}, {10;20;30;40}, "mean", 2, 0, 1, 2, 3)
Expected output:
y1 | y2 | |
---|---|---|
x1 | 20 | 20 |
x2 | 40 |
Example 3: Sum in 2x2 Bins
Inputs:
x | y | values | statistic | bins | xlowerlimit | xupperlimit | ylowerlimit | yupperlimit |
---|---|---|---|---|---|---|---|---|
0.1 | 2.1 | 1 | sum | 2 | 0 | 1 | 2 | 3 |
0.1 | 2.6 | 2 | ||||||
0.1 | 2.1 | 3 | ||||||
0.6 | 2.1 | 4 |
Excel formula:
=BINNED_STATISTIC_2D({0.1;0.1;0.1;0.6}, {2.1;2.6;2.1;2.1}, {1;2;3;4}, "sum", 2, 0, 1, 2, 3)
Expected output:
y1 | y2 | |
---|---|---|
x1 | 4 | 2 |
x2 | 4 | 0 |
Example 4: Median in 2x2 Bins
Inputs:
x | y | values | statistic | bins | xlowerlimit | xupperlimit | ylowerlimit | yupperlimit |
---|---|---|---|---|---|---|---|---|
0.1 | 2.1 | 10 | median | 2 | 0 | 1 | 2 | 3 |
0.1 | 2.6 | 20 | ||||||
0.1 | 2.1 | 30 | ||||||
0.6 | 2.1 | 40 |
Excel formula:
=BINNED_STATISTIC_2D({0.1;0.1;0.1;0.6}, {2.1;2.6;2.1;2.1}, {10;20;30;40}, "median", 2, 0, 1, 2, 3)
Expected output:
y1 | y2 | |
---|---|---|
x1 | 20 | 20 |
x2 | 40 |
Python Code
from scipy.stats import binned_statistic_2d as scipy_binned_statistic_2d
def binned_statistic_2d(x, y, values, statistic='mean', bins=10, xlowerlimit=None, xupperlimit=None, ylowerlimit=None, yupperlimit=None):
"""
Computes a bidimensional binned statistic (mean, sum, median, etc.) for the input data.
Args:
x: 2D list or scalar of float values. Data to bin along the first dimension.
y: 2D list or scalar of float values. Data to bin along the second dimension.
values: 2D list or scalar of float values. Data to compute statistics on.
statistic: Statistic to compute ('mean', 'sum', 'median', 'count', 'std', 'min', 'max'). Default is 'mean'.
bins: Number of bins (integer, default 10).
xlowerlimit: Lower bound for the x bin range (optional).
xupperlimit: Upper bound for the x bin range (optional).
ylowerlimit: Lower bound for the y bin range (optional).
yupperlimit: Upper bound for the y bin range (optional).
Returns:
2D list of statistic values for each bin, or an error message (str) if input is invalid.
This example function is provided as-is without any representation of accuracy.
"""
# Convert scalars to 2D lists if needed
if not isinstance(x, list):
x = [[x]]
if not isinstance(y, list):
y = [[y]]
if not isinstance(values, list):
values = [[values]]
# Flatten 2D lists to 1D
try:
flat_x = [float(item) for row in x for item in (row if isinstance(row, list) else [row])]
flat_y = [float(item) for row in y for item in (row if isinstance(row, list) else [row])]
flat_values = [float(item) for row in values for item in (row if isinstance(row, list) else [row])]
except Exception:
return "Invalid input: x, y, and values must be 2D lists or scalars of numbers."
if len(flat_x) == 0 or len(flat_y) == 0 or len(flat_values) == 0:
return "Invalid input: x, y, and values must not be empty."
if len(flat_x) != len(flat_y) or len(flat_x) != len(flat_values):
return "Invalid input: x, y, and values must have the same length."
if statistic not in ('mean', 'sum', 'median', 'count', 'std', 'min', 'max'):
return "Invalid input: statistic must be one of 'mean', 'sum', 'median', 'count', 'std', 'min', 'max'."
try:
nbins = int(bins)
except Exception:
return "Invalid input: bins must be an integer."
if nbins < 1:
return "Invalid input: bins must be >= 1."
# Prepare range
range_arg = None
if (xlowerlimit is not None and xupperlimit is not None and
ylowerlimit is not None and yupperlimit is not None):
try:
range_arg = [(float(xlowerlimit), float(xupperlimit)), (float(ylowerlimit), float(yupperlimit))]
except Exception:
return "Invalid input: xlowerlimit, xupperlimit, ylowerlimit, yupperlimit must be numbers."
try:
if range_arg:
res = scipy_binned_statistic_2d(flat_x, flat_y, flat_values, statistic=statistic, bins=nbins, range=range_arg)
else:
res = scipy_binned_statistic_2d(flat_x, flat_y, flat_values, statistic=statistic, bins=nbins)
stat = res.statistic
except Exception as e:
return f"scipy.stats.binned_statistic_2d error: {e}"
# Return as 2D list (row-major)
return [[float(x) if x is not None else None for x in row] for row in stat.tolist()]