interhemispheric_tether: Inter-hemispheric tethering loss

interhemispheric_tether

hypercoil.loss.interhemispheric_tether(lh: Tensor, rh: Tensor, lh_coor: Tensor, rh_coor: Tensor, *, radius: float = 100.0, key: PRNGKey | None = None) → Tensor

Distance of centres of mass of left-hemisphere parcels from corresponding right-hemisphere parcels. This can be used to promote a symmetric atlas.

Note

It is assumed that the first coordinate in lh_coor and rh_coor is the x-coordinate, and that the left hemisphere is on the opposite side of the x-axis from the right hemisphere.

Parameters:

lhTensor

Tensor block containing the data for the left hemisphere. 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.

rhTensor

Tensor block containing the data for the right hemisphere.

lh_coorTensor

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

rh_coorTensor

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

radiusfloat (default 100)

Radius of the spherical manifold on which the coordinates are located.

Returns:

Tensor

Distance of the centres of mass of the objects in lh from the corresponding objects in rh.

InterhemisphericTetherLoss

class hypercoil.loss.InterhemisphericTetherLoss(nu: float = 1.0, name: str | None = None, *, lh_coor: Tensor | None = None, rh_coor: Tensor | None = None, radius: float | None = 100.0, scalarisation: Callable | None = None, key: 'jax.random.PRNGKey' | None = None)

Loss function penalising distance between matched parcels or objects on opposite hemispheres.

Displacement of centres of mass in one cortical hemisphere from corresponding centres of mass in the other cortical hemisphere.

Hemispheric Tether

The hemispheric tether is defined as

:math:`sum_{ell} left| ell_{LH, centre} - ell_{RH, centre}

ight|`

where \(\ell\) denotes a pair of regions, one in each cortical hemisphere.

The symmetry of this spatial null model is enforced through a moderately strong hemispheric tether.

When an atlas is initialised with the same number of parcels in each cortical hemisphere compartment, the hemispheric tether can be used to approximately enforce symmetry and to enforce analogy between a pair of parcels in the two cortical hemispheres.

Warning

Currently, this loss only works in spherical surface space.

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.

lh_coorTensor

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

rh_coorTensor

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

radiusfloat (default 100)

Radius of the spherical manifold on which the coordinates are located.

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__(lh, rh[, lh_coor, rh_coor, key])

Call self as a function.