plans.stochastic.binning

Histogram bin rules, class boundaries and classification.

Formulas use \(k\) for the number of bins, \(w\) for the bin width, \(n\) for the sample size and \(s\) for the standard deviation.

Functions

bins_equal(data, n_bins)	Calculates equally spaced (linear) bins for a 1D NumPy array.
bins_quantiles(data[, n_bins])	Calculates the numerical quantile boundaries (bins) for a 1D NumPy array.
classify(data[, bins, n_classes, scheme])	Classifies a 1D NumPy array into 0-indexed bins based on provided bin boundaries.
get_bins(data[, n_bins, scheme])	Get class boundaries by scheme.
get_histogram(data[, bins, rule])	Compute the histogram of the sample
get_nbins_by_rule(data[, rule])	Util function for rule-based nbins computation
get_nbins_density(n_units, data_range)	Compute the number of bins from a target bin width, with a minimum of one.
get_nbins_fd(data)	This function computes the number of bins for histograms using the Freedman-Diaconis rule, which takes into account the interquartile range (IQR) of the sample, in addition to its range.
get_nbins_scott(data)	This function computes the number of bins using the Scott rule, which is similar to the Freedman-Diaconis rule, but uses the standard deviation of the data to compute the bin runsize.
get_nbins_sturges(data)	This function computes the number of bins using the Sturges rule, which assumes that the data follows a normal distribution and computes the number of bins based on its data runsize.
quantiles_classify(data[, n_classes])	Classifies a 1D NumPy array into quantile classes.

plans.stochastic.binning.get_nbins_fd(data)

This function computes the number of bins for histograms using the Freedman-Diaconis rule, which takes into account the interquartile range (IQR) of the sample, in addition to its range.

\[w = 2 \, \mathrm{IQR} \, n^{-1/3}, \qquad k = \left\lceil \frac{\max(x) - \min(x)}{w} \right\rceil\]

Parameters:

data (numpy.ndarray) – vector of data without nan values

Returns:

number of bins for histogram using the Freedman-Diaconis rule

Return type:

int

plans.stochastic.binning.get_nbins_sturges(data)

This function computes the number of bins using the Sturges rule, which assumes that the data follows a normal distribution and computes the number of bins based on its data runsize.

\[k = \left\lceil \log_2 n + 1 \right\rceil\]

Parameters:

data (numpy.ndarray) – vector of data without nan values

Returns:

number of bins using the Sturges rule

Return type:

int

plans.stochastic.binning.get_nbins_scott(data)

This function computes the number of bins using the Scott rule, which is similar to the Freedman-Diaconis rule, but uses the standard deviation of the data to compute the bin runsize.

\[w = 3.5 \, s \, n^{-1/3}, \qquad k = \left\lceil \frac{\max(x) - \min(x)}{w} \right\rceil\]

Parameters:

data (numpy.ndarray) – vector of data without nan values

Returns:

number of bins using the Scott rule

Return type:

int

plans.stochastic.binning.get_nbins_density(n_units, data_range)

Compute the number of bins from a target bin width, with a minimum of one.

\[k = \max\left( 1, \left\lfloor \frac{x_1 - x_0}{w} \right\rfloor \right)\]

Parameters:

• n_units (float) – bin width, in data units

• data_range (list) – lower and upper values of the range

Returns:

number of bins

Return type:

int

plans.stochastic.binning.get_nbins_by_rule(data, rule=None)

Util function for rule-based nbins computation

Parameters:

• data (numpy.ndarray) – vector of data without nan values

• rule (str) – rule code (sturges, fd, scott). Anything else gives 10 bins.

Returns:

number of bins for histogram

Return type:

int

plans.stochastic.binning.get_histogram(data, bins=100, rule=None)

Compute the histogram of the sample

Parameters:

• data (numpy.ndarray) – vector of data without nan values

• bins (int) – number of bins

• rule (str) – rule to define the number of bins. Only used when bins is None.

Returns:

dataframe of histogram

Return type:

pandas.DataFrame

plans.stochastic.binning.get_bins(data, n_bins=5, scheme='equal')

Get class boundaries by scheme.

Parameters:

• data (numpy.ndarray) – vector of data without nan values

• n_bins (int) – number of classes

• scheme (str) – scheme code. Options: equal, linear, quantiles, quantile

Returns:

class boundaries

Return type:

numpy.ndarray

plans.stochastic.binning.bins_equal(data, n_bins)

Calculates equally spaced (linear) bins for a 1D NumPy array.

Parameters:

• data (numpy.ndarray) – The 1D NumPy array to analyze.

• n_bins (int) – The desired number of bins/intervals.

Returns:

A NumPy array containing the linear bin boundary values.

Return type:

numpy.ndarray

plans.stochastic.binning.bins_quantiles(data, n_bins=5)

Calculates the numerical quantile boundaries (bins) for a 1D NumPy array.

Parameters:

• data (numpy.ndarray) – The 1D NumPy array to analyze.

• n_bins (int) – The number of quantile classes.

Returns:

A NumPy array containing the quantile boundary values.

Return type:

numpy.ndarray

plans.stochastic.binning.classify(data, bins=None, n_classes=5, scheme='equal')

Classifies a 1D NumPy array into 0-indexed bins based on provided bin boundaries.

Values are assigned to class \(i\) if \(b_i \le x < b_{i+1}\). Values below bins[0] are assigned to class 0. Values at or above bins[-1] are assigned to the last class (len(bins) - 2).

Parameters:

• data (numpy.ndarray) – The 1D NumPy array to classify.

• bins (numpy.ndarray) – A 1D NumPy array specifying the sorted bin edges. Must contain at least two elements. If None, it is computed from the data.

• n_classes (int) – number of classes, used only if bins is None

• scheme (str) – scheme code, used only if bins is None. See get_bins().

Returns:

A 1D NumPy array of integers representing the 0-indexed class for each element in data.

Return type:

numpy.ndarray

plans.stochastic.binning.quantiles_classify(data, n_classes=5)

Classifies a 1D NumPy array into quantile classes.

Parameters:

• data (numpy.ndarray) – The 1D NumPy array to classify.

• n_classes (int) – The number of quantile classes.

Returns:

A 1D NumPy array containing the quantile class (0 to n_classes-1) for each element.

Return type:

numpy.ndarray