Histogramming, grouping, and binning#

Overview#

Histogramming (see sc.hist), grouping (using sc.groupby), and binning (see Binned data) all serve similar but slightly different purposes. Picking the optimal one of the three for a particular application may yield more natural code and better performance. Let us start by an example. Consider a table of scattered measurements:

[1]:

import numpy as np
import scipp as sc

N = 5000
values = 10 * np.random.rand(N)
table = sc.DataArray(
    data=sc.array(
        dims=['position'], unit=sc.units.counts, values=values, variances=values
    ),
    coords={
        'x': sc.array(dims=['position'], unit='m', values=np.random.rand(N)),
        'y': sc.array(dims=['position'], unit='m', values=np.random.rand(N)),
    },
)
table.values *= 1.0 / np.exp(5.0 * table.coords['x'].values)
sc.table(table['position', :5])

[1]:

Coordinates		Data
x [m]	y [m]	[counts]
0.354	0.166	1.398±2.861
0.193	0.778	1.418±1.927
0.106	0.389	5.479±3.049
0.899	0.982	0.000±0.211
0.027	0.369	7.959±3.018

We may now be interested in the total intensity (counts) as a function of 'x'. There are three ways to do this:

[2]:

xbins = sc.linspace('x', 0, 1, num=40, unit='m')
ds = sc.Dataset(
    {
        'histogram': table.hist(x=xbins),
        'groupby': table.groupby('x', bins=xbins).sum('position'),
        'bin': table.bin(x=xbins).bins.sum(),
    }
)
ds.plot()

[2]:

../../_images/user-guide_binned-data_histogramming-grouping-and-binning_3_0.svg

In the above plot we can only see a single line, since the three solutions yield exactly the same result (neglecting floating-point rounding errors):

hist sorts data points into ‘x’ bins, summing immediately.
groupby groups by ‘x’ and then sums (on-the-fly) all data points falling in the same ‘x’ bin.
bin sorts data points into ‘x’ bins. Summing all rows in a bin yields the same result as grouping and summing directly.

So in this case we get equivalent results, but the application areas differ, as described in more detail in the following sections.

Histogramming#

scipp.hist directly sums the data and is efficient. Limitations are:

When histogramming in more than one dimension, the implementation uses sc.bin internally, which may be less efficient and uses more memory.
Can only apply “sum” or “nansum” to accumulate into a bin. scipp.nanhist is currently implemented differently and uses sc.bin internally. It therefore uses more memory and may be less efficient.

We can also histogram binned data (since binning preserves the 'y' coord), to create 2-D (or N-D) histograms:

[3]:

binned = table.bin(x=xbins)
hist = binned.hist(y=30)
hist.plot()

[3]:

../../_images/user-guide_binned-data_histogramming-grouping-and-binning_5_0.svg

[4]:

hist

[4]:

scipp.DataArray (20.09 KB)

Dimensions:
- x: 39
- y: 30

Coordinates: (2)

(x [bin-edge])

float64

0.0, 0.026, ..., 0.974, 1.0

Values:
array([0.        , 0.02564103, 0.05128205, 0.07692308, 0.1025641 ,
       0.12820513, 0.15384615, 0.17948718, 0.20512821, 0.23076923,
       0.25641026, 0.28205128, 0.30769231, 0.33333333, 0.35897436,
       0.38461538, 0.41025641, 0.43589744, 0.46153846, 0.48717949,
       0.51282051, 0.53846154, 0.56410256, 0.58974359, 0.61538462,
       0.64102564, 0.66666667, 0.69230769, 0.71794872, 0.74358974,
       0.76923077, 0.79487179, 0.82051282, 0.84615385, 0.87179487,
       0.8974359 , 0.92307692, 0.94871795, 0.97435897, 1.        ])

(y [bin-edge])

float64

5.469e-05, 0.033, ..., 0.966, 1.000

Values:
array([5.46866083e-05, 3.33798341e-02, 6.67049816e-02, 1.00030129e-01,
       1.33355277e-01, 1.66680424e-01, 2.00005572e-01, 2.33330719e-01,
       2.66655867e-01, 2.99981014e-01, 3.33306162e-01, 3.66631309e-01,
       3.99956457e-01, 4.33281604e-01, 4.66606752e-01, 4.99931899e-01,
       5.33257047e-01, 5.66582194e-01, 5.99907342e-01, 6.33232489e-01,
       6.66557637e-01, 6.99882784e-01, 7.33207932e-01, 7.66533079e-01,
       7.99858227e-01, 8.33183374e-01, 8.66508522e-01, 8.99833669e-01,
       9.33158817e-01, 9.66483964e-01, 9.99809112e-01])

Data: (1)

(x, y)

float64

counts

25.892, 25.279, ..., 0.297, 0.099

σ = 5.295, 5.180, ..., 6.480, 3.735

Values:
array([[25.89248991, 25.27923351, 31.00970362, ..., 41.72445952,
         6.02805214, 30.7027413 ],
       [10.48241628, 13.78280101,  8.08930581, ..., 10.17775037,
        32.12292972, 13.1569997 ],
       [ 2.05669309, 19.97652573, 15.69071933, ...,  3.83414367,
        18.51394442, 12.6915688 ],
       ...,
       [ 0.12107013,  0.14580317,  0.15641146, ...,  0.19431067,
         0.23221217,  0.14670408],
       [ 0.26313962,  0.08665933,  0.16385021, ...,  0.18476415,
         0.09803213,  0.        ],
       [ 0.09643831,  0.24489284,  0.20106459, ...,  0.382861  ,
         0.29650272,  0.09898298]])

Variances (σ²):
array([[28.04223671, 26.8317314 , 33.24224979, ..., 44.40416095,
         6.47727702, 32.8621606 ],
       [13.25572563, 17.13030787, 10.27898266, ..., 12.73897097,
        39.32951854, 16.07716791],
       [ 2.69603584, 28.14993241, 21.55967974, ...,  5.35189495,
        24.58797524, 17.44119991],
       ...,
       [12.83274617, 16.10290935, 17.02339672, ..., 20.56355216,
        24.76329692, 16.56010983],
       [31.96533047, 10.80976355, 20.10368003, ..., 23.12863058,
        11.98807571,  0.        ],
       [13.84635738, 33.97350236, 27.90305274, ..., 52.74655453,
        41.99197956, 13.95321442]])

Another capability of hist is to histogram a dimension that has previously been binned with a different or higher resolution, i.e. different bin edges. Compare to the plot of the initial example:

[5]:

binned = table.bin(x=xbins)
binned.hist(x=100).plot()

[5]:

../../_images/user-guide_binned-data_histogramming-grouping-and-binning_8_0.svg

Histogramming, grouping, and binning#

Overview#

Histogramming#

Grouping#

Binning#