reference_tether: Spatial tether to reference points#

reference_tether#

hypercoil.loss.reference_tether(X: Tensor, ref: Tensor, coor: Tensor, *, radius: float | None = 100.0, key: PRNGKey | None = None) → Tensor[source]#

Distance of centres of mass from tethered reference points.

This can potentially be used, for instance, to adapt an existing atlas to a new dataset.

Parameters:
XTensor

Tensor block containing the data to be tethered. Each row is a collection of masses assigned to the single object or parcel, and each column denotes the distribution of masses across objects or parcels at a single spatial location.

refTensor

Coordinates of the reference points to which the centres of mass of the objects in X should be tethered. Each object or parcel should have a single corresponding reference point.

coorTensor

Coordinates of the spatial locations in each of the columns of X.

radiusfloat or None (default 100)

Radius of the spherical manifold on which the coordinates are located. If this is specified as None, it is assumed that the coordinates are in Euclidean space.

Returns:
Tensor

Distance of the centres of mass of the objects in X from the corresponding reference points in ref.

ReferenceTetherLoss#

class hypercoil.loss.ReferenceTetherLoss(nu: float = 1.0, name: str | None = None, *, ref: Tensor | None = None, coor: Tensor | None = None, radius: float | None = 100.0, scalarisation: Callable | None = None, key: 'jax.random.PRNGKey' | None = None)[source]#

Loss function penalising distance from a tethered reference point.

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. {spatial_loss_spec}

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[, ref, coor, key])

Call self as a function.