connectopy: Generalised connectopy

connectopy

hypercoil.loss.connectopy(Q: Tensor, A: Tensor, D: Tensor | None = None, theta: Tensor | None = None, omega: Tensor | None = None, *, dissimilarity: Callable | None = None, affinity: Callable | None = None, negative_affinity: Literal['abs', 'rectify', 'reciprocal', 'complement'] | None = 'complement', progressive_theta: bool = False, key: PRNGKey | None = None)

Generalised connectopic functional, for computing different kinds of connectopic maps.

Connectopic functional

Given an affinity matrix A, the connectopic functional is the objective

\(\mathbf{1}^\intercal \left( \mathbf{A} \circ S_\theta(\mathbf{Q}) \right) \mathbf{1}\)

for a pairwise function S. The default pairwise function is the square of the L2 distance. The columns of the Q that minimises the objective are the learned connectopic maps.

Warning

If you’re using this for a well-characterised connectopic map with a closed-form or algorithmically optimised solution, such as Laplacian eigenmaps or many forms of community detection, then in most cases you would be better off directly computing exact maps rather than using this functional to approximate them.

Because this operation attempts to learn all of the maps that jointly minimise the objective in a single shot rather than using iterative projection, it is more prone to misalignment than a projective approach for eigendecomposition-based maps.

Danger

Note that a connectopic loss is often insufficient on its own as a loss. It should be combined with appropriate projections and constraints, for instance to ensure the learned maps are zero-centred and orthogonal.

Dimension:

Q : \((D, C)\)

D denotes the number of vertices in the affinity matrix and C denotes the number of proposed maps.

A : \((D, D)\)

As above.

D : \((D, D)\)

As above.

theta : \((C)\) or \((C, C)\)

As above.

Parameters:

Qtensor

Proposed connectopies or maps.

Atensor

Affinity matrix.

Dtensor or None (default None)

If this argument is provided, then the affinity matrix is first transformed as \(D A D^\intercal\). For instance, setting D to a diagonal matrix whose entries are the reciprocal of the square root of vertex degrees corresponds to learning eigenmaps of a normalised graph Laplacian.

thetatensor, float, or None (default None)

Parameterisation of the pairwise dissimilarity function.

omegatensor, float, or None (default None)

Optional parameterisation of the affinity function, if one is provided.

dissimilaritycallable

Function to compute dissimilarity between latent coordinates induced by the proposed connectopies. By default, the square of the L2 distance is used. The callable must accept Q and theta as arguments. (theta may be unused.)

affinitycallable or None (default None)

If an affinity function is provided, then the image of argument A under this function is the affinity matrix. Otherwise, argument A is the affinity matrix.

progressive_thetabool (default False)

When this is True, a theta is generated such that the last map in Q has a weight of 1, the second-to-last has a weight of 2, and so on. This can be used to encourage the last column to correspond to the least important connectopic map and the first column to correspond to the most important connectopic map.

Returns:

Tensor

Connectopic functional value.

ConnectopyLoss

class hypercoil.loss.ConnectopyLoss(nu: float = 1.0, name: str | None = None, *, theta: Any | None = None, omega: Any | None = None, dissimilarity: Callable | None = None, affinity: Callable | None = None, negative_affinity: Literal['abs', 'rectify', 'reciprocal', 'complement'] | None = 'reciprocal', scalarisation: Callable | None = None, progressive_theta: bool = False, key: 'jax.random.PRNGKey' | None = None)

Generalised connectopic functional, for computing different kinds of connectopic maps.

Connectopic functional

Given an affinity matrix A, the connectopic functional is the objective

\(\mathbf{1}^\intercal \left( \mathbf{A} \circ S_\theta(\mathbf{Q}) \right) \mathbf{1}\)

for a pairwise function S. The default pairwise function is the square of the L2 distance. The columns of the Q that minimises the objective are the learned connectopic maps.

Warning

If you’re using this for a well-characterised connectopic map with a closed-form or algorithmically optimised solution, such as Laplacian eigenmaps or many forms of community detection, then in most cases you would be better off directly computing exact maps rather than using this functional to approximate them.

Because this operation attempts to learn all of the maps that jointly minimise the objective in a single shot rather than using iterative projection, it is more prone to misalignment than a projective approach for eigendecomposition-based maps.

Danger

Note that a connectopic loss is often insufficient on its own as a loss. It should be combined with appropriate projections and constraints, for instance to ensure the learned maps are zero-centred and orthogonal.

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.

thetatensor, float, or None (default None)

Parameterisation of the pairwise dissimilarity function.

omegatensor, float, or None (default None)

Optional parameterisation of the affinity function, if one is provided.

dissimilaritycallable

Function to compute dissimilarity between latent coordinates induced by the proposed connectopies. By default, the square of the L2 distance is used. The callable must accept Q and theta as arguments. (theta may be unused.)

affinitycallable or None (default None)

If an affinity function is provided, then the image of argument A under this function is the affinity matrix. Otherwise, argument A is the affinity matrix.

progressive_thetabool (default False)

When this is True, a theta is generated such that the last map in Q has a weight of 1, the second-to-last has a weight of 2, and so on. This can be used to encourage the last column to correspond to the least important connectopic map and the first column to correspond to the most important connectopic map.

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__(Q, A[, D, theta, omega, key])

Call self as a function.