leaspy.utils.weighted_tensor

Attributes

TensorOrWeightedTensor

Classes

WeightedTensor

A torch.tensor, with optional (non-negative) weights (0 <-> masked).

Functions

factory_weighted_tensor_unary_operator(f, *[, fill_value])	Factory/decorator to create a weighted-tensor compatible function from the provided unary-tensor function.
expand_left(t, *, shape)	Expand shape of tensor at left with provided shape.
expand_right(t, *, shape)	Expand shape of tensor at right with provided shape.
sum_dim(x, *[, fill_value, dim, but_dim])	Sum dimension(s) of provided tensor (regular or weighted -
unsqueeze_right(t, *, ndim)	Adds ndim dimensions to tensor, from right-side, without
wsum_dim(x, *[, fill_value, dim, but_dim])	Sum dimension(s) of provided weighted tensor.
wsum_dim_return_sum_of_weights_only(x, *[, ...])	Sum dimension(s) of provided weighted tensor like wsum_dim but
wsum_dim_return_weighted_sum_only(x, *[, fill_value, ...])	Sum dimension(s) of provided weighted tensor like wsum_dim but

Package Contents

factory_weighted_tensor_unary_operator(f, *, fill_value=None)

Factory/decorator to create a weighted-tensor compatible function from the provided unary-tensor function.

Parameters:

• f (Callable[[Tensor], Tensor])

• fill_value (Optional[VT])

Return type:

Callable[[leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[VT]], leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[VT]]

expand_left(t, *, shape)

Expand shape of tensor at left with provided shape.

Parameters:

• t (leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[S])

• shape (Tuple[int, Ellipsis])

Return type:

leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[S]

expand_right(t, *, shape)

Expand shape of tensor at right with provided shape.

Parameters:

• t (leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[S])

• shape (Tuple[int, Ellipsis])

Return type:

leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[S]

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).

Parameters:

• x (leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor)

• dim (Union[None, int, Tuple[int, Ellipsis]])

• but_dim (Union[None, int, Tuple[int, Ellipsis]])

Return type:

Tensor

unsqueeze_right(t, *, ndim)

Adds ndim dimensions to tensor, from right-side, without copy (useful for right broadcasting which is non-standard).

Parameters:

• t (leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[S])

• ndim (int)

Return type:

leaspy.utils.weighted_tensor._weighted_tensor.TensorOrWeightedTensor[S]

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:

xWeightedTensor

The weighted tensor on which to compute the sum.

fill_valuefloat

The value to use for filling the weighted tensor.

dimint or tuple of int, optional

The dimension(s) on which to sum.

but_dimint or tuple of int, optional

The dimension(s) to omit when summing.

Returns:

weighted_sumtorch.Tensor

Weighted sum, with totally un-weighted aggregates filled with fill_value.

sum_weightstorch.Tensor

The sum of weights.

Parameters:

• x (leaspy.utils.weighted_tensor._weighted_tensor.WeightedTensor)

• dim (Union[None, int, Tuple[int, Ellipsis]])

• but_dim (Union[None, int, Tuple[int, Ellipsis]])

Return type:

Tuple[Tensor, Tensor]

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:

xWeightedTensor

The weighted tensor on which to compute the sum.

fill_valuefloat

The value to use for filling the weighted tensor.

dimint or tuple of int, optional

The dimension(s) on which to sum.

but_dimint or tuple of int, optional

The dimension(s) to omit when summing.

Returns:

torch.Tensor

The sum of weights.

Parameters:

• x (leaspy.utils.weighted_tensor._weighted_tensor.WeightedTensor)

• dim (Union[None, int, Tuple[int, Ellipsis]])

• but_dim (Union[None, int, Tuple[int, Ellipsis]])

Return type:

Tensor

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:

xWeightedTensor

The weighted tensor on which to compute the sum.

fill_valuefloat

The value to use for filling the weighted tensor.

dimint or tuple of int, optional

The dimension(s) on which to sum.

but_dimint 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.

Parameters:

• x (leaspy.utils.weighted_tensor._weighted_tensor.WeightedTensor)

• dim (Union[None, int, Tuple[int, Ellipsis]])

• but_dim (Union[None, int, Tuple[int, Ellipsis]])

Return type:

Tensor

TensorOrWeightedTensor

class WeightedTensor

Bases: Generic[VT]

A torch.tensor, with optional (non-negative) weights (0 <-> masked).

Parameters:

valuetorch.Tensor

Raw values, without any mask.

weighttorch.Tensor, optional

Relative weights for values. Default: None

Attributes:

valuetorch.Tensor

Raw values, without any mask.

weighttorch.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

value: Tensor

weight: Tensor | None = None

property weighted_value: Tensor

Get the weighted value tensor. This is the value tensor multiplied by the weight tensor.

Returns:

torch.Tensor:

The weighted value tensor. If weight is None, the value tensor is returned.

Return type:

Tensor

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_valueVT, optional

The value to fill the tensor with for aggregates where weights were all zero. Default: None

Returns:

torch.Tensor:

The filled tensor. If weight or fill_value is None, the original tensor is returned.

Parameters:

fill_value (Optional[VT])

Return type:

Tensor

valued(value)

Return a new WeightedTensor with same weight as self but with new value provided.

Parameters:

valuetorch.Tensor

The new value to be set.

Returns:

WeightedTensor:

A new WeightedTensor with the same weight as self but with the new value provided.

Parameters:

value (Tensor)

Return type:

WeightedTensor

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:

funcCallable[[ torch.Tensor ], torch.Tensor ]

The function to be applied to the values.

*args

Positional arguments to be passed to the function.

fill_valueVT, 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:

WeightedTensor:

A new WeightedTensor with the result of the operation and the same weights.

Parameters:

• func (Callable[[Tensor], Tensor])

• fill_value (Optional[VT])

Return type:

WeightedTensor

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:

funcCallable[[ :obj`torch.Tensor` ], torch.Tensor ]

The function to be applied to both values and weights.

*args

Positional arguments to be passed to the function.

fill_valueVT, 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:

WeightedTensor:

A new WeightedTensor with the result of the operation and the appropriate weights.

Parameters:

• func (Callable[[Tensor], Tensor])

• fill_value (Optional[VT])

Return type:

WeightedTensor

index_put(indices, values, *, accumulate=False)

Out-of-place torch.index_put() on values (no modification of weights).

Parameters:

indicestuple [ torch.Tensor, …]

The indices to put the values at.

valuestorch.Tensor

The values to put at the specified indices.

accumulatebool, optional

Whether to accumulate the values at the specified indices. Default: False

Returns:

WeightedTensor [ VT ]

A new WeightedTensor with the updated values and the same weights.

Parameters:

• indices (Tuple[Tensor, Ellipsis])

• values (Tensor)

• accumulate (bool)

Return type:

WeightedTensor[VT]

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_valueVT, 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:

tuple [ torch.Tensor, torch.Tensor ]:

Tuple containing:

• weighted_sumtorch.Tensor

  Weighted sum, with totally un-weighted aggregates filled with fill_value.

• sum_weightstorch.Tensor (may be of other type than cls.weight_dtype)

  The sum of weights (useful if some average are needed).

Parameters:

fill_value (VT)

Return type:

Tuple[Tensor, Tensor]

sum(*, fill_value=0, **kws)

Compute weighted sum of values.

For unweighted tensors, this is equivalent to regular torch.sum(). For weighted tensors, returns the same as the first element of wsum().

Parameters:

fill_valueVT, optional

The value to fill the sum with for aggregates where weights were all zero. Default: 0

**kws

Optional keyword-arguments

Returns:

torch.Tensor:

The weighted sum, with totally un-weighted aggregates filled with fill_value.

Parameters:

fill_value (VT)

Return type:

Tensor

view(*shape)

Return a view of the weighted tensor with a different shape.

Parameters:

shapetuple [ int, …]

The new shape to be set.

Returns:

WeightedTensor [ VT ]:

A new WeightedTensor with the same weights but with the new shape provided.

Return type:

WeightedTensor[VT]

expand(*shape)

Expand the weighted tensor to a new shape.

Parameters:

shapetuple [ int, …]

The new shape to be set.

Returns:

WeightedTensor [ VT ]:

A new WeightedTensor with the same weights but with the new shape provided.

Return type:

WeightedTensor[VT]

to(*, device)

Move the weighted tensor to a different device.

Parameters:

devicetorch.device

The device to be set.

Returns:

:obj:`WeightedTensor`[:obj:`VT]:

A new WeightedTensor with the same weights but with the new device provided.

Parameters:

device (device)

Return type:

WeightedTensor[VT]

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:

WeightedTensor [ VT ]:

A new WeightedTensor with the same weights but with the new device provided.

Return type:

WeightedTensor[VT]

property shape: Size

Shape of the values tensor.

Returns:

torch.Size:

The shape of the values tensor.

Return type:

Size

property ndim: int

Number of dimensions of the values tensor.

Returns:

int:

The number of dimensions of the values tensor.

Return type:

int

property dtype: dtype

Type of values.

Returns:

torch.dtype:

The type of values.

Return type:

dtype

property device: device

Device of values.

Returns:

torch.device:

The device of values.

Return type:

device

property requires_grad: bool

Whether the values tensor requires gradients.

Returns:

bool:

Whether the values tensor requires gradients.

Return type:

bool

abs()

Compute the absolute value of the weighted tensor.

Returns:

WeightedTensor

A new WeightedTensor with the absolute value of the values tensor.

Return type:

WeightedTensor

all()

Check if all values are non-zero.

Returns:

bool:

Whether all values are non-zero.

Return type:

bool

static get_filled_value_and_weight(t, *, fill_value=None)

Method to get tuple (value, weight) for both regular and weighted tensors.

Parameters:

tclass:TensorOrWeightedTensor

The tensor to be converted.

fill_valueVT, optional

The value to fill the tensor with for aggregates where weights were all zero. Default: None

Returns:

Tuple`[:obj:`torch.Tensor, Optional[torch.Tensor]]:

Tuple containing: - value : torch.Tensor

The filled tensor. If weight is None, the original tensor is returned.

• weighttorch.Tensor, optional

  The weight tensor.

Parameters:

• t (TensorOrWeightedTensor[VT])

• fill_value (Optional[VT])

Return type:

Tuple[Tensor, Optional[Tensor]]