pydune.math.histogram#

histogram(*args, bins=None, range=None, axis=None, weights=None, density=False, block_size='auto')[source]#

Histogram applied along specified axis / axes.

Parameters:

  • args (array_like) – Input data. The number of input arguments determines the dimensionality of the histogram. For example, two arguments produce a 2D histogram. All args must have the same size.

  • bins (int, str or numpy array or a list of ints, strs and/or arrays, optional) –

    If a list, there should be one entry for each item in args. The bin specifications are as follows:

    • If int; the number of bins for all arguments in args.

    • If str; the method used to automatically calculate the optimal bin width for all arguments in args, as defined by numpy histogram_bin_edges.

    • If numpy array; the bin edges for all arguments in args.

    • If a list of ints, strs and/or arrays; the bin specification as above for every argument in args.

    When bin edges are specified, all but the last (righthand-most) bin include the left edge and exclude the right edge. The last bin includes both edges.

    A TypeError will be raised if args or weights contains dask arrays and bins are not specified explicitly as an array or list of arrays. This is because other bin specifications trigger computation.

  • range ((float, float) or a list of (float, float), optional) –

    If a list, there should be one entry for each item in args. The range specifications are as follows:

    • If (float, float); the lower and upper range(s) of the bins for all arguments in args. Values outside the range are ignored. The first element of the range must be less than or equal to the second. range affects the automatic bin computation as well. In this case, while bin width is computed to be optimal based on the actual data within range, the bin count will fill the entire range including portions containing no data.

    • If a list of (float, float); the ranges as above for every argument in args.

    • If not provided, range is simply (arg.min(), arg.max()) for each arg.

  • axis (None or int or tuple of ints, optional) – Axis or axes along which the histogram is computed. The default is to compute the histogram of the flattened array

  • weights (array_like, optional) – An array of weights, of the same shape as a. Each value in a only contributes its associated weight towards the bin count (instead of 1). If density is True, the weights are normalized, so that the integral of the density over the range remains 1.

  • density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Note that the sum of the histogram values will not be equal to 1 unless bins of unity width are chosen; it is not a probability mass function.

  • block_size (int or 'auto', optional) – A parameter which governs the algorithm used to compute the histogram. Using a nonzero value splits the histogram calculation over the non-histogram axes into blocks of size block_size, iterating over them with a loop (numpy inputs) or in parallel (dask inputs). If 'auto', blocks will be determined either by the underlying dask chunks (dask inputs) or an experimental built-in heuristic (numpy inputs).

Returns:

  • hist (array) – The values of the histogram.

  • bin_edges (list of arrays) – Return the bin edges for each input array.

See also

numpy.histogram, numpy.bincount, numpy.searchsorted