batch_corr: Batch-axis correlation

batch_corr

hypercoil.loss.batch_corr(X: Tensor, N: Tensor, *, tol: float | Literal['auto'] = 0, tol_sig: float = 0.1, abs: bool = True, key: PRNGKey | None = None) → Tensor

Correlation over the batch dimension.

Parameters:

Xtensor

Tensor block containing measures to be correlated with those in N.

Ntensor

Vector of measures with which the measures in X are to be correlated.

tolnonnegative float or 'auto' (default 0)

Tolerance for correlations. Only correlation values above tol are counted. If this is set to 'auto', a tolerance is computed for the batch size given the significance level in tol_sig.

tol_sigfloat in (0, 1)

Significance level for correlation tolerance. Used only if tol is set to 'auto'.

absbool (default True)

Use the absolute value of correlations. If this is being used as a loss function, the model’s weights will thus be updated to shrink all batchwise correlations toward zero.

Returns:

tensor

Absolute correlation of each vector in X with N, after thresholding at tol. Note that, if you want the original correlations back, you will have to add tol to any nonzero correlations.

BatchCorrelationLoss

class hypercoil.loss.BatchCorrelationLoss(nu: float = 1.0, name: str | None = None, *, tol: float | Literal['auto'] = 0, tol_sig: float = 0.1, abs: bool = True, scalarisation: Callable | None = None, key: 'jax.random.PRNGKey' | None = None)

Batch correlation loss.

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.

tolnonnegative float or 'auto' (default 0)

Tolerance for correlations. Only correlation values above tol are counted. If this is set to 'auto', a tolerance is computed for the batch size given the significance level in tol_sig.

tol_sigfloat in (0, 1)

Significance level for correlation tolerance. Used only if tol is set to 'auto'.

absbool (default True)

Use the absolute value of correlations. If this is being used as a loss function, the model’s weights will thus be updated to shrink all batchwise correlations toward zero.

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, N, *[, key])

Call self as a function.