spacenet.point_patterns.cross_pair_correlation_function#

spacenet.point_patterns.cross_pair_correlation_function(spatial_network, nodes_a=None, nodes_b=None, spatial_kernel_bandwidth=10, spatial_kernel_n=2, r_min=0, r_max=100, r_step=10, edge_weight_name='Distance', return_confidence_interval=False, low_memory=False, verbose=True, n_jobs=1)#

Computes the pair correlation function (PCF) or cross-pair correlation function (cross-PCF) for nodes in a spatial network.

The PCF is computed when nodes_a and nodes_b refer to the same set of nodes, and quantifies spatial dependence within a single node population.

The cross-PCF is computed when nodes_a and nodes_b refer to different node populations, and quantifies spatial dependence between those 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.
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 Epanechnikov).
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.
edge_weight_namestr, optional: The name of the edge attribute in the network that corresponds to the distance between nodes. Default is ‘Distance’.
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:

radiinumpy.ndarray: The radii at which the pair correlation function was computed.
gnumpy.ndarray: The values of the pair correlation function at the corresponding radii.
confidence_intervalnumpy.ndarray (if return_confidence_interval is True): If return_confidence_interval is True, this will be a numpy array (2,n) containing the confidence intervals for the pair correlation function at each radius. The first row corresponds to the lower bounds of the confidence intervals, and the second row 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

Computing the pair correlation function for a single population of nodes:

import spacenet as sn
import matplotlib.pyplot as plt 

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

# generate a spatial network using the delaunay method
G = sn.utils.spatial_network_from_points(points,network_type='delaunay',max_edge_distance=75)

# compute the PCF for the spatial network over all nodes
radius,pcf_values,con_interval = sn.point_patterns.cross_pair_correlation_function(G,spatial_kernel_bandwidth=80,r_max=1000,return_confidence_interval=True)

# plot the PCF
fig,ax=plt.subplots()
ax.axhline(1,linestyle='dashed',color='grey')
ax.plot(radius,pcf_values)
ax.fill_between(radius,con_interval[0],con_interval[1],alpha=0.2)
ax.set_xlabel('Radius')
ax.set_ylabel('Pair Correlation')
ax.set_ylim(0,2)  

Computing the cross pair correlation function for a two populations of nodes:

import spacenet as sn
import matplotlib.pyplot as plt 

# get data from the Spiral dataset
sprial_df = sn.datasets.load_dataset('spiral')
points = sprial_df[['x','y']].values
categorical_labels = sprial_df['Marker (categorical)'].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,categorical_labels,node_label_name='Marker (categorical)')

# get the node ids for the two categories
nodes_a = sn.utils.query_nodes(G,node_label_name='Marker (categorical)',relation='is',node_label_value='A')
nodes_b = sn.utils.query_nodes(G,node_label_name='Marker (categorical)',relation='is',node_label_value='B') 

# compute the cross-PCF for the spatial network between nodes_a and nodes_b
radius,pcf_values,con_interval = sn.point_patterns.cross_pair_correlation_function(G,nodes_a=nodes_a,nodes_b=nodes_b,spatial_kernel_bandwidth=80,r_max=1000,return_confidence_interval=True)

# plot the PCF
fig,ax=plt.subplots()
ax.axhline(1,linestyle='dashed',color='grey')
ax.plot(radius,pcf_values)
ax.fill_between(radius,con_interval[0],con_interval[1],alpha=0.2)
ax.set_xlabel('Radius')
ax.set_ylabel('Pair Correlation')
ax.set_ylim(0,3)    