leaspy.utils.weighted_tensor ============================ .. py:module:: leaspy.utils.weighted_tensor Attributes ---------- .. autoapisummary:: leaspy.utils.weighted_tensor.TensorOrWeightedTensor Classes ------- .. autoapisummary:: leaspy.utils.weighted_tensor.WeightedTensor Functions --------- .. autoapisummary:: leaspy.utils.weighted_tensor.factory_weighted_tensor_unary_operator leaspy.utils.weighted_tensor.expand_left leaspy.utils.weighted_tensor.expand_right leaspy.utils.weighted_tensor.sum_dim leaspy.utils.weighted_tensor.unsqueeze_right leaspy.utils.weighted_tensor.wsum_dim leaspy.utils.weighted_tensor.wsum_dim_return_sum_of_weights_only leaspy.utils.weighted_tensor.wsum_dim_return_weighted_sum_only Package Contents ---------------- .. py:function:: factory_weighted_tensor_unary_operator(f, *, fill_value = None) Factory/decorator to create a weighted-tensor compatible function from the provided unary-tensor function. .. !! processed by numpydoc !! .. py:function:: expand_left(t, *, shape) Expand shape of tensor at left with provided shape. .. !! processed by numpydoc !! .. py:function:: expand_right(t, *, shape) Expand shape of tensor at right with provided shape. .. !! processed by numpydoc !! .. py:function:: sum_dim(x, *, fill_value=0, dim = None, but_dim = None, **kws) Sum dimension(s) of provided tensor (regular or weighted - filling with `fill_value` aggregates without any summed weighting if any). .. !! processed by numpydoc !! .. py:function:: unsqueeze_right(t, *, ndim) Adds `ndim` dimensions to tensor, from right-side, without copy (useful for right broadcasting which is non-standard). .. !! processed by numpydoc !! .. py:function:: wsum_dim(x, *, fill_value=0, dim = None, but_dim = None, **kws) Sum dimension(s) of provided weighted tensor. The weighted tensor is filled with `fill_value` if provided. The function returns the sum of weights as well. :Parameters: **x** : WeightedTensor The weighted tensor on which to compute the sum. **fill_value** : float The value to use for filling the weighted tensor. **dim** : int or tuple of int, optional The dimension(s) on which to sum. **but_dim** : int or tuple of int, optional The dimension(s) to omit when summing. :Returns: **weighted_sum** : torch.Tensor Weighted sum, with totally un-weighted aggregates filled with `fill_value`. **sum_weights** : torch.Tensor The sum of weights. .. !! processed by numpydoc !! .. py:function:: wsum_dim_return_sum_of_weights_only(x, *, fill_value=0, dim = None, but_dim = None, **kws) Sum dimension(s) of provided weighted tensor like `wsum_dim` but only return the sum of weights and not the weighted sum. :Parameters: **x** : WeightedTensor The weighted tensor on which to compute the sum. **fill_value** : float The value to use for filling the weighted tensor. **dim** : int or tuple of int, optional The dimension(s) on which to sum. **but_dim** : int or tuple of int, optional The dimension(s) to omit when summing. :Returns: torch.Tensor The sum of weights. .. !! processed by numpydoc !! .. py:function:: wsum_dim_return_weighted_sum_only(x, *, fill_value=0, dim = None, but_dim = None, **kws) Sum dimension(s) of provided weighted tensor like `wsum_dim` but only return the weighted sum and not the sum of weights. :Parameters: **x** : WeightedTensor The weighted tensor on which to compute the sum. **fill_value** : float The value to use for filling the weighted tensor. **dim** : int or tuple of int, optional The dimension(s) on which to sum. **but_dim** : int or tuple of int, optional The dimension(s) to omit when summing. :Returns: torch.Tensor Weighted sum, with totally un-weighted aggregates filled with `fill_value`. .. !! processed by numpydoc !! .. py:data:: TensorOrWeightedTensor .. py:class:: WeightedTensor Bases: :py:obj:`Generic`\ [\ :py:obj:`VT`\ ] A torch.tensor, with optional (non-negative) weights (0 <-> masked). :Parameters: **value** : :obj:`torch.Tensor` Raw values, without any mask. **weight** : :obj:`torch.Tensor`, optional Relative weights for values. Default: None :Attributes: **value** : :obj:`torch.Tensor` Raw values, without any mask. **weight** : :obj:`torch.Tensor` Relative weights for values. If weight is a tensor[bool], it can be seen as a mask (valid value <-> weight is True). More generally, meaningless values <-> indices where weights equal 0. Default: None .. !! processed by numpydoc !! .. py:attribute:: value :type: torch.Tensor .. py:attribute:: weight :type: Optional[torch.Tensor] :value: None .. py:property:: weighted_value :type: torch.Tensor Get the weighted value tensor. This is the value tensor multiplied by the weight tensor. :Returns: :obj:`torch.Tensor`: The weighted value tensor. If weight is None, the value tensor is returned. .. !! processed by numpydoc !! .. py:method:: filled(fill_value = None) Return the values tensor with masked zeros filled with the specified value. Return the values tensor filled with `fill_value` where the `weight` is exactly zero. :Parameters: **fill_value** : :obj:`VT`, optional The value to fill the tensor with for aggregates where weights were all zero. Default: None :Returns: :obj:`torch.Tensor`: The filled tensor. If `weight` or fill_value is None, the original tensor is returned. .. !! processed by numpydoc !! .. py:method:: valued(value) Return a new WeightedTensor with same weight as self but with new value provided. :Parameters: **value** : :obj:`torch.Tensor` The new value to be set. :Returns: :obj:`WeightedTensor`: A new WeightedTensor with the same weight as self but with the new value provided. .. !! processed by numpydoc !! .. py:method:: map(func, *args, fill_value = None, **kws) Apply a function to the values tensor while preserving weights. The function is applied only to the values tensor after optionally filling zero-weight positions. The weights remain unchanged in the returned tensor. :Parameters: **func** : Callable[[ :obj:`torch.Tensor` ], :obj:`torch.Tensor` ] The function to be applied to the values. **\*args** Positional arguments to be passed to the function. **fill_value** : :obj:`VT`, optional The value to fill the tensor with for aggregates where weights were all zero. Default: None **\*\*kws** Keyword arguments to be passed to the function. :Returns: :class:`WeightedTensor`: A new `WeightedTensor` with the result of the operation and the same weights. .. !! processed by numpydoc !! .. py:method:: map_both(func, *args, fill_value = None, **kws) Apply a function to both values and weights tensors. The same function is applied to both components of the weighted tensor. Zero-weight positions in the values tensor are filled before applying the function. :Parameters: **func** : Callable[[ :obj`torch.Tensor` ], :obj:`torch.Tensor` ] The function to be applied to both values and weights. **\*args** Positional arguments to be passed to the function. **fill_value** : :obj:`VT`, optional The value to fill the tensor with for aggregates where weights were all zero. Default: None **\*\*kws** Keyword arguments to be passed to the function. :Returns: :obj:`WeightedTensor`: A new `WeightedTensor` with the result of the operation and the appropriate weights. .. !! processed by numpydoc !! .. py:method:: index_put(indices, values, *, accumulate = False) Out-of-place :func:`torch.index_put` on values (no modification of weights). :Parameters: **indices** : :obj:`tuple` [ :obj:`torch.Tensor`, ...] The indices to put the values at. **values** : :obj:`torch.Tensor` The values to put at the specified indices. **accumulate** : :obj:`bool`, optional Whether to accumulate the values at the specified indices. Default: False :Returns: :class:`~leaspy.utils.weighted_tensor.WeightedTensor` [ :obj:`VT` ] A new :class:`~leaspy.utils.weighted_tensor.WeightedTensor` with the updated values and the same weights. .. !! processed by numpydoc !! .. py:method:: wsum(*, fill_value = 0, **kws) Get the weighted sum of tensor together with sum of weights. The result is NOT a `WeightedTensor` any more since weights are already taken into account. We always fill values with 0 prior to weighting to prevent 0 * nan = nan that would propagate nans in sums. :Parameters: **fill_value** : :obj:`VT`, optional The value to fill the sum with for aggregates where weights were all zero. Default: 0 **\*\*kws** Optional keyword-arguments for torch.sum (such as `dim=...` or `keepdim=...`) :Returns: :obj:`tuple` [ :obj:`torch.Tensor`, :obj:`torch.Tensor` ]: .. Tuple containing: - weighted_sum : :obj:`torch.Tensor` Weighted sum, with totally un-weighted aggregates filled with `fill_value`. - sum_weights : :obj:`torch.Tensor` (may be of other type than `cls.weight_dtype`) The sum of weights (useful if some average are needed). .. !! processed by numpydoc !! .. py:method:: sum(*, fill_value = 0, **kws) Compute weighted sum of values. For unweighted tensors, this is equivalent to regular :func:`torch.sum`. For weighted tensors, returns the same as the first element of wsum(). :Parameters: **fill_value** : :obj:`VT`, optional The value to fill the sum with for aggregates where weights were all zero. Default: 0 **\*\*kws** Optional keyword-arguments :Returns: :obj:`torch.Tensor`: The weighted sum, with totally un-weighted aggregates filled with `fill_value`. .. !! processed by numpydoc !! .. py:method:: view(*shape) Return a view of the weighted tensor with a different shape. :Parameters: **shape** : :obj:`tuple` [ :obj:`int`, ...] The new shape to be set. :Returns: :class:`~leaspy.utils.weighted_tensor.WeightedTensor` [ :obj:`VT` ]: A new :class:`~leaspy.utils.weighted_tensor.WeightedTensor` with the same weights but with the new shape provided. .. !! processed by numpydoc !! .. py:method:: expand(*shape) Expand the weighted tensor to a new shape. :Parameters: **shape** : :obj:`tuple` [ :obj:`int`, ...] The new shape to be set. :Returns: :class:`~leaspy.utils.weighted_tensor.WeightedTensor` [ :obj:`VT` ]: A new :class:`~leaspy.utils.weighted_tensor.WeightedTensor` with the same weights but with the new shape provided. .. !! processed by numpydoc !! .. py:method:: to(*, device) Move the weighted tensor to a different device. :Parameters: **device** : :obj:`torch.device` The device to be set. :Returns: :obj:`WeightedTensor`[:obj:`VT]: A new `WeightedTensor` with the same weights but with the new device provided. .. !! processed by numpydoc !! .. py:method:: cpu() Move the weighted tensor to CPU memory. Applies the `torch.Tensor.cpu()` operation to both the value tensor and weight tensor (if present), returning a new weighted tensor with all components on the CPU. :Returns: :class:`~leaspy.utils.weighted_tensor.WeightedTensor` [ :obj:`VT` ]: A new :class:`~leaspy.utils.weighted_tensor.WeightedTensor` with the same weights but with the new device provided. .. !! processed by numpydoc !! .. py:property:: shape :type: torch.Size Shape of the values tensor. :Returns: :obj:`torch.Size`: The shape of the values tensor. .. !! processed by numpydoc !! .. py:property:: ndim :type: int Number of dimensions of the values tensor. :Returns: :obj:`int`: The number of dimensions of the values tensor. .. !! processed by numpydoc !! .. py:property:: dtype :type: torch.dtype Type of values. :Returns: :obj:`torch.dtype`: The type of values. .. !! processed by numpydoc !! .. py:property:: device :type: torch.device Device of values. :Returns: :obj:`torch.device`: The device of values. .. !! processed by numpydoc !! .. py:property:: requires_grad :type: bool Whether the values tensor requires gradients. :Returns: :obj:`bool`: Whether the values tensor requires gradients. .. !! processed by numpydoc !! .. py:method:: abs() Compute the absolute value of the weighted tensor. :Returns: :class:`~leaspy.utils.weighted_tensor.WeightedTensor` A new `WeightedTensor` with the absolute value of the values tensor. .. !! processed by numpydoc !! .. py:method:: all() Check if all values are non-zero. :Returns: :obj:`bool`: Whether all values are non-zero. .. !! processed by numpydoc !! .. py:method:: get_filled_value_and_weight(t, *, fill_value = None) :staticmethod: Method to get tuple (value, weight) for both regular and weighted tensors. :Parameters: **t** : class:`TensorOrWeightedTensor` The tensor to be converted. **fill_value** : :obj:`VT`, optional The value to fill the tensor with for aggregates where weights were all zero. Default: None :Returns: :obj:`Tuple`[:obj:`torch.Tensor`, Optional[:obj:`torch.Tensor`]]: Tuple containing: - value : :obj:`torch.Tensor` The filled tensor. If `weight` is None, the original tensor is returned. - weight : :obj:`torch.Tensor`, optional The weight tensor. .. !! processed by numpydoc !!