spatial_conv#

hypercoil.functional.sphere.spatial_conv(data: Tensor, coor: Tensor, kernel: ~typing.Callable = <function kernel_gaussian>, metric: ~typing.Callable = <function spherical_geodesic>, max_bin: int = 10000, truncate: float | None = None) → Tensor[source]#

Convolve data on a manifold with an isotropic kernel.

Currently, this works by taking a dataset, a list of coordinates associated with each point in the dataset, an isotropic kernel, and a distance metric. It proceeds as follows:

  1. Using the provided metric, compute the distance between each pair of coordinates.

  2. Evaluate the isotropic kernel at each computed distance. Use this value to operationalise the loading weight of every coordinate on every other coordinate.

  3. Use the loading weights to perform a matrix product and obtain the kernel-convolved dataset.

Dimension:
data : \((*, N, C)\)

* denotes any number of intervening dimensions, C denotes the number of data channels, and N denotes the number of data observations per channel.

coor : \((*, N, D)\)

D denotes the dimension of the space in which the data are embedded.

Output : \((*, C, N)\)

Parameters:
dataTensor

Tensor containing data observations, which might be arrayed into channels.

coorTensor

Tensor containing the spatial coordinates associated with each observation in data.

kernelcallable

Function that maps a distance to a weight. Typically, shorter distances correspond to larger weights.

metriccallable

Function that takes as parameters two \((*, N_i, D)\) tensors containing coordinates and returns the pairwise distance between each pair of tensors. In Euclidean space, this could be the L2 norm; in spherical space, this could be the great-circle distance.

max_binint

Maximum number of points to include in a distance computation. If you run out of memory, try decreasing this.

truncatefloat or None (default None)

Maximum distance at which data points can be convolved together.

Returns:
data_convTensor

The input data convolved with the kernel. Each channel is convolved completely separately as of now.