deepspatial.data_utils.compute_uot_coupling

deepspatial.data_utils.compute_uot_coupling#

deepspatial.data_utils.compute_uot_coupling(x0, g0, c0, x1, g1, c1, alpha_spatial=0.5, cell_type_penalty=50.0, uot_reg=0.8, uot_tau=0.05, num_itermax=50, stop_thr=0.01)[source]#

Computes the Unbalanced Optimal Transport (UOT) coupling matrix between two slices.

Parameters:

  • x0 (numpy.ndarray or torch.Tensor) – Spatial coordinates for the source slice.

  • g0 (numpy.ndarray or torch.Tensor) – Gene expression matrix for the source slice.

  • c0 (numpy.ndarray or torch.Tensor) – One-hot encoded cell types for the source slice.

  • x1 (numpy.ndarray or torch.Tensor) – Spatial coordinates for the target slice.

  • g1 (numpy.ndarray or torch.Tensor) – Gene expression matrix for the target slice.

  • c1 (numpy.ndarray or torch.Tensor) – One-hot encoded cell types for the target slice.

  • alpha_spatial (float, optional) – Weight for spatial distance in the underlying cost matrix. By default 0.5.

  • cell_type_penalty (float, optional) – Cost multiplier for cross-cell-type couplings. By default 50.0, as in the manuscript experiments.

  • uot_reg (float, optional) – Entropy regularization parameter. Higher values lead to smoother, more dispersed couplings; lower values yield sparser, more deterministic matchings. By default 0.8.

  • uot_tau (float, optional) – Marginal relaxation weight (KL divergence penalty). Controls how strictly the mass conservation is enforced. Smaller values allow more mass creation/destruction. By default 0.05.

  • num_itermax (int, optional) – Maximum Sinkhorn iterations. By default 50.

  • stop_thr (float, optional) – Sinkhorn stopping threshold. By default 1e-2.

Returns:

The calculated optimal transport coupling matrix pi of shape (N0, N1).

Return type:

numpy.ndarray

Contents