tensorplay._composite_funcs API

Computes a histogram of the values in a tensor.

bins can be an integer or a 1D tensor.

If bins is an int, it specifies the number of equal-width bins. By default, the lower and upper range of the bins is determined by the minimum and maximum elements of the input tensor. The range argument can be provided to specify a range for the bins.

If bins is a 1D tensor, it specifies the sequence of bin edges including the rightmost edge. It should contain at least 2 elements and its elements should be increasing.

Parameters:

• input (Tensor) – the input tensor.

• bins – int or 1D Tensor. If int, defines the number of equal-width bins. If tensor, defines the sequence of bin edges including the rightmost edge.

Keyword Arguments:

• range (tuple of float) – Defines the range of the bins.

• weight (Tensor) – If provided, weight should have the same shape as input. Each value in input contributes its associated weight towards its bin’s result.

• density (bool) – If False, the result will contain the count (or total weight) in each bin. If True, the result is the value of the probability density function over the bins, normalized such that the integral over the range of the bins is 1.

• out (Tensor, optional) – the output tensor. (tuple, optional): The result tuple of two output tensors (hist, bin_edges).

Returns:

1D Tensor containing the values of the histogram. bin_edges(Tensor): 1D Tensor containing the edges of the histogram bins.

Return type:

hist (Tensor)

Example:

>>> tensorplay.histogram(tensorplay.tensor([1., 2, 1]), bins=4, range=(0., 3.), weight=tensorplay.tensor([1., 2., 4.]))
(tensor([ 0.,  5.,  2.,  0.]), tensor([0., 0.75, 1.5, 2.25, 3.]))
>>> tensorplay.histogram(tensorplay.tensor([1., 2, 1]), bins=4, range=(0., 3.), weight=tensorplay.tensor([1., 2., 4.]), density=True)
(tensor([ 0.,  0.9524,  0.3810,  0.]), tensor([0., 0.75, 1.5, 2.25, 3.]))

This is a variant of tensorplay.quantile() that “ignores” NaN values, computing the quantiles q as if NaN values in input did not exist. If all values in a reduced row are NaN then the quantiles for that reduction will be NaN. See the documentation for tensorplay.quantile().

Parameters:

• input (Tensor) – the input tensor.

• q (float or Tensor) – a scalar or 1D tensor of quantile values in the range [0, 1]

• dim (int, optional) –

  the dimension to reduce. If None, all dimensions are reduced.

  keepdim (bool, optional): whether the output tensor has dim retained or not. Default: False.

Keyword Arguments:

• interpolation (str) – interpolation method to use when the desired quantile lies between two data points. Can be linear, lower, higher, midpoint and nearest. Default is linear.

• out (Tensor, optional) – the output tensor.

Example:

>>> t = tensorplay.tensor([float('nan'), 1, 2])
>>> t.quantile(0.5)
tensor(nan)
>>> t.nanquantile(0.5)
tensor(1.5000)
>>> t = tensorplay.tensor([[float('nan'), float('nan')], [1, 2]])
>>> t
tensor([[nan, nan],
        [1., 2.]])
>>> t.nanquantile(0.5, dim=0)
tensor([1., 2.])
>>> t.nanquantile(0.5, dim=1)
tensor([   nan, 1.5000])

Computes the q-th quantiles of each row of the input tensor along the dimension dim.

To compute the quantile, we map q in [0, 1] to the range of indices [0, n] to find the location of the quantile in the sorted input. If the quantile lies between two data points a < b with indices i and j in the sorted order, result is computed according to the given interpolation method as follows:

• linear: a + (b - a) * fraction, where fraction is the fractional part of the computed quantile index.

• lower: a.

• higher: b.

• nearest: a or b, whichever’s index is closer to the computed quantile index (rounding down for .5 fractions).

• midpoint: (a + b) / 2.

If q is a 1D tensor, the first dimension of the output represents the quantiles and has size equal to the size of q, the remaining dimensions are what remains from the reduction.

Parameters:

• input (Tensor) – the input tensor.

• q (float or Tensor) – a scalar or 1D tensor of values in the range [0, 1].

• dim (int, optional) –

  the dimension to reduce.

  keepdim (bool, optional): whether the output tensor has dim retained or not. Default: False.

Keyword Arguments:

• interpolation (str, optional) – interpolation method to use when the desired quantile lies between two data points. Can be linear, lower, higher, midpoint and nearest. Default is linear.

• out (Tensor, optional) – the output tensor.

Example:

>>> a = tensorplay.randn(2, 3)
>>> a
tensor([[ 0.0795, -1.2117,  0.9765],
        [ 1.1707,  0.6706,  0.4884]])
>>> q = tensorplay.tensor([0.25, 0.5, 0.75])
>>> tensorplay.quantile(a, q, dim=1, keepdim=True)
tensor([[[-0.5661],
        [ 0.5795]],

        [[ 0.0795],
        [ 0.6706]],

        [[ 0.5280],
        [ 0.9206]]])
>>> tensorplay.quantile(a, q, dim=1, keepdim=True).shape
tensorplay.Size([3, 2, 1])
>>> a = tensorplay.arange(4.)
>>> a
tensor([0., 1., 2., 3.])
>>> tensorplay.quantile(a, 0.6, interpolation='linear')
tensor(1.8000)
>>> tensorplay.quantile(a, 0.6, interpolation='lower')
tensor(1.)
>>> tensorplay.quantile(a, 0.6, interpolation='higher')
tensor(2.)
>>> tensorplay.quantile(a, 0.6, interpolation='midpoint')
tensor(1.5000)
>>> tensorplay.quantile(a, 0.6, interpolation='nearest')
tensor(2.)
>>> tensorplay.quantile(a, 0.4, interpolation='nearest')
tensor(1.)