dispersion: Vector dispersion

dispersion

hypercoil.loss.dispersion(X: Tensor, *, metric: ~typing.Callable = <function linear_distance>, key: ~jax._src.random.PRNGKey | None = None)

Dispersion of the centres of mass of objects in a tensor block.

Note

This operates on precomputed centres of mass.

Parameters:

XTensor

Tensor block containing the data to be evaluated. Each row contains the centre of mass of a single object or parcel.

metricCallable

Function to calculate the distance between centres of mass. This should take either one or two arguments, and should return the distance between each pair of observations.

Returns:

Tensor

Dispersion of the centres of mass of objects in a tensor block.

DispersionLoss

class hypercoil.loss.DispersionLoss(nu: float = 1.0, name: Optional[str] = None, *, metric: Callable = <function linear_distance>, scalarisation: Optional[Callable] = None, key: Optional['jax.random.PRNGKey'] = None)

Loss function penalising proximity between vectors.

Mutual separation among a set of vectors.

Vector dispersion

The dispersion among a set of vectors \(v \in \mathcal{V}\) is defined as

\(\sum_{i, j} \mathrm{d}\left(v_i - v_j\right)\)

for some measure of separation \(\mathrm{d}\). (It is also valid to use a reduction other than the sum.)

This can be used as one half of a clustering loss. Such a clustering loss would promote mutual separation among centroids (between-cluster separation, imposed by the VectorDispersion loss) while also promoting proximity between observations and their closest centroids (within-cluster closeness, for instance using a norm loss or compactness if the clusters are associated with spatial coordinates).

Parameters:

name: str

Designated name of the loss function. It is not required that this be specified, but it is recommended to ensure that the loss function can be identified in the context of a reporting utilities. If not explicitly specified, the name will be inferred from the class name and the name of the scoring function.

nu: float

Loss strength multiplier. This is a scalar multiplier that is applied to the loss value before it is returned. This can be used to modulate the relative contributions of different loss functions to the overall loss value. It can also be used to implement a schedule for the loss function, by dynamically adjusting the multiplier over the course of training.

metricCallable

Function to calculate the distance between centres of mass. This should take either one or two arguments, and should return the distance between each pair of observations.

scalarisation: Callable

The scalarisation function to be used to aggregate the values returned by the scoring function. This function should take a single argument, which is a tensor of arbitrary shape, and return a single scalar value. By default, the mean scalarisation is used.

Methods

__call__(X, *[, key])

Call self as a function.