topographical_correlation_map

topographical_correlation_map(domain, population_A, population_B, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, radius_of_interest=50, kernel_radius=150, kernel_sigma=50, kernel_function=None, mesh_step=10, max_correlation_threshold=5, remain_within_connected_component=False, add_contribution_as_labels=False, contribution_label_name='TCM contributions', visualise_output=False, visualise_tcm_kwargs={})

Compute the topographical correlation map (TCM) between two populations within a given domain. The TCM is a measure of spatial heterogeneity in the correlation between pairs of points across an ROI. The TCM provides a quantitative summary of colocalization between the points which is spatially resolved across the ROI. Local maxima and minima of the TCM identify areas where points with different labels are (positively or negatively) correlated, relative to a baseline of CSR.

Parameters:

domainDomain

A muspan domain.

population_Alist or np.ndarray or query-like

The first population of objects or a query to select objects.

population_Blist or np.ndarray or query-like

The second population of objects or a query to select objects.

include_boundariesarray-like, query-like, or None, optional

Boundaries to include in the analysis. Defaults to None.

exclude_boundariesarray-like, query-like, or None, optional

Boundaries to exclude from the analysis. Defaults to None.

boundary_exclude_distancefloat, optional

Distance from the boundary to exclude objects, by default 0.

radius_of_interestfloat, optional

The radius within which to consider objects for correlation. Default is 50.

kernel_radiusfloat, optional

The radius of the kernel used for smoothing. Default is 150.

kernel_sigmafloat, optional

The standard deviation of the default Gaussian kernel used for smoothing. Default is 50.

kernel_functioncallable, optional

Custom kernel function. If None, a Gaussian kernel is used. Defaults to None.

mesh_stepfloat, optional

The step size for the mesh grid. Default is 10.

max_correlation_thresholdfloat, optional

The maximum correlation threshold for normalization. Default is 5.

remain_within_connected_componentbool, optional

Whether to remain within the connected component of the boundary. Default is False.

visualise_outputbool, optional

Whether to visualize the output TCM. Default is False.

visualise_tcm_kwargsdict, optional

Additional keyword arguments for visualise.visualise_topographical_correlation_map.

Returns:

topographicalCorrelationMapnp.ndarray

The computed topographical correlation map.

Raises:

ValueError

If the provided queries are not of the correct type.

Notes

For more information on the topographical correlation map, see the following reference: https://doi.org/10.1017/S2633903X24000011