spacenet.point_patterns.cross_weighted_pair_correlation_function#

spacenet.point_patterns.cross_weighted_pair_correlation_function(spatial_network, node_label_name_a, node_label_name_b, nodes_a=None, nodes_b=None, spatial_kernel_bandwidth=10, spatial_kernel_n=2, r_min=0, r_max=100, r_step=10, marker_kernel_bandwidth_A=0.2, marker_kernel_n_A=1, marker_min_A=0, marker_max_A=1, marker_step_A=0.1, marker_kernel_bandwidth_B=0.2, marker_kernel_n_B=1, marker_min_B=0, marker_max_B=1, marker_step_B=0.1, edge_weight_name='Distance', return_confidence_interval=False, low_memory=False, verbose=True, n_jobs=1)#

Compute the cross weighted pair correlation function between two populations of objects (A and B) on a spatial network, where the contributions of each object to the pair correlation function are weighted by a kernel function based on their marker levels. Polynomial kernels are used to weight contributions based on marked levels, and the pair correlation function is computed across a range of distances (r) and target marker values for both populations.

Parameters:

spatial_networknetworkx.Graph: The spatial network on which to compute the pair correlation function. Edges should have a weight attribute corresponding to the distance between nodes.
node_label_name_astr or array-like: A continuous label for each object in population A. This should be the name of labels associated with a continous label on the name. Alternatively, this can be an array of continous values of the same length as nodes_b, where each entry corresponds to the label of the respective object in population A.
node_label_name_bstr or array-like: A continuous label for each object in population B. This should be the name of labels associated with a continous label on the name. Alternatively, this can be an array of continous values of the same length as nodes_b, where each entry corresponds to the label of the respective object in population B.
nodes_aarray-like, optional: The indices of the nodes in population A. If None, all nodes in the network will be considered as part of population A. Default is None.
nodes_barray-like, optional: The indices of the nodes in population B. If None, all nodes in the network will be considered as part of population B. Default is None.
spatial_kernel_bandwidthfloat, optional: The bandwidth parameter for the spatial kernel function. This controls the smoothness of the pair correlation function. Default is 10.
spatial_kernel_nint, optional: The exponent parameter for the spatial kernel function. This controls the shape of the kernel. Default is 2 (which corresponds to a Gaussian-like kernel).
r_minfloat, optional: The minimum distance to consider when computing the pair correlation function. Default is 0.
r_maxfloat, optional: The maximum distance to consider when computing the pair correlation function. Default is 100.
r_stepfloat, optional: The step size for the distance bins when computing the pair correlation function. Default is 10.
marker_kernel_bandwidth_Afloat, optional: The bandwidth parameter for the marker kernel function for population A. This controls the smoothness of the weighting based on marker levels. Default is 0.2.
marker_kernel_n_Aint, optional: The exponent parameter for the marker kernel function for population A. This controls the shape of the kernel for marker weighting. Default is 1 (which corresponds to a triangular kernel).
marker_min_Afloat, optional: The minimum marker value to consider for population A when computing the marker kernel. Default is 0.
marker_max_Afloat, optional: The maximum marker value to consider for population A when computing the marker kernel. Default is 1.
marker_step_Afloat, optional: The step size for the marker values when computing the marker kernel for population A. Default is 0.1.
marker_kernel_bandwidth_Bfloat, optional: The bandwidth parameter for the marker kernel function for population B. This controls the smoothness of the weighting based on marker levels for population B. Default is 0.2.
marker_kernel_n_Bint, optional: The exponent parameter for the marker kernel function for population B. This controls the shape of the kernel for marker weighting for population B. Default is 1 (which corresponds to a triangular kernel).
marker_min_Bfloat, optional: The minimum marker value to consider for population B when computing the marker kernel. Default is 0.
marker_max_Bfloat, optional: The maximum marker value to consider for population B when computing the marker kernel. Default is 1.
marker_step_Bfloat, optional: The step size for the marker values when computing the marker kernel for population B. Default is 0.1.
edge_weight_namestr, optional: The name of the edge attribute in the network that corresponds to the distance between nodes. Default is ‘Distance’.
return_confidence_intervalbool, optional: Whether to compute and return 95% confidence intervals for the pair correlation function using spatial bootstrapping. Default is False.
low_memorybool, optional: Whether to use a low-memory implementation of Dijkstra’s algorithm that computes distances in batches. This can be useful for large networks that do not fit in memory. Default is False.
verbosebool, optional: Whether to print progress messages during computation. Default is True.
n_jobsint, optional: The number of parallel jobs to run when computing contributions. If n_jobs > 1, the contributions will be computed in parallel across multiple CPU cores. Default is 1 (no parallelization).

Returns:

tau_Anumpy.ndarray: The target marker values for label A at which the pair correlation function was computed.
tau_Bnumpy.ndarray: The target marker values for label B at which the pair correlation function was computed.
radiinumpy.ndarray: The radii at which the pair correlation function was computed.
gnumpy.ndarray: The values of the pair correlation function at the corresponding target marker values and radii. This will be a 3D array with dimensions corresponding to (number of target marker values for A, number of target marker values for B, number of radii).
confidence_intervalnumpy.ndarray (if return_confidence_interval is True): If return_confidence_interval is True, this will be a numpy array (2, number of target marker values for A, number of target marker values for B, number of radii) containing the confidence intervals for the pair correlation function at each combination of target marker values and radius. The CI[0,:,:,:] corresponds to the lower bounds of the confidence intervals, and CI[1,:,:,:] corresponds to the upper bounds. If return_confidence_interval is False, this will not be returned.

Notes

For more information, see the reference paper:

Moore et al. (2026). netPCF: Geometry-aware Pair Correlation Functions for Spatial Biology. DOI: https://doi.org/10.64898/2026.07.02.736020

Examples

Compute the cross weighted pair correlation function for the Spiral dataset, where the contributions of each point to the pair correlation function are weighted by a kernel function based on their continuous marker levels. The example computes the pair correlation function across a range of distances and target marker values, and plots the results for specific target marker combinations.

import spacenet as sn
import numpy as np
import matplotlib.pyplot as plt 

# get data from the Spiral dataset
sprial_df = sn.datasets.load_dataset('spiral')
points = sprial_df[['x','y']].values
continuous_labels = sprial_df['Marker (continuous)'].values

# generate a spatial network using the delaunay method and add labels
G = sn.utils.spatial_network_from_points(points,network_type='delaunay',max_edge_distance=75)
sn.utils.add_node_labels(G,continuous_labels,node_label_name='Marker (continuous)')

# compute the cross weighted-PCF for the spatial network continuous label 'Marker (continuous)'
tau_a,tau_b,radius,pcf_values,con_interval = sn.point_patterns.cross_weighted_pair_correlation_function(G,
                                                                                                        node_label_name_a='Marker (continuous)',
                                                                                                        node_label_name_b='Marker (continuous)',
                                                                                                        spatial_kernel_bandwidth=80,
                                                                                                        r_max=1000,
                                                                                                        return_confidence_interval=True)

# plot the PCF for the cross weighted pair correlation function at target mark of 0 and 1
tau_a_index_0=np.where(tau_a==0)[0][0]
tau_a_index_1=np.where(tau_a==1)[0][0]

tau_b_index_0=np.where(tau_b==0)[0][0]

fig,ax=plt.subplots()
ax.axhline(1,linestyle='dashed',color='grey')
ax.plot(radius,pcf_values[tau_a_index_0,tau_b_index_0,:],label='Target marks, :math:`\tau_{a}=0, \, \tau_{b}=0`',color='tab:blue')
ax.fill_between(radius,con_interval[0,tau_a_index_0,tau_b_index_0,:],con_interval[1,tau_a_index_0,tau_b_index_0,:],alpha=0.2,color='tab:blue')

ax.plot(radius,pcf_values[tau_a_index_1,tau_b_index_0,:],label='Target marks, :math:`\tau_{a}=1, \, \tau_{b}=0`',color='tab:orange')
ax.fill_between(radius,con_interval[0,tau_a_index_1,tau_b_index_0,:],con_interval[1,tau_a_index_1,tau_b_index_0,:],alpha=0.2,color='tab:orange')

ax.set_xlabel('Radius')
ax.set_ylabel('Cross Weighted Pair Correlation')
ax.set_ylim(0,2.5)
ax.set_xlim(0,1000)   
ax.legend()