spacenet.point_patterns.weighted_pair_correlation_function#

spacenet.point_patterns.weighted_pair_correlation_function(spatial_network, node_label_name_b=None, 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=0.2, marker_kernel_n=1, marker_min=0, marker_max=1, marker_step=0.1, edge_weight_name='Distance', return_confidence_interval=False, low_memory=False, verbose=True, n_jobs=1)#

Computes the weighted pair correlation function between two populations of nodes. Computes the spatial correlation between two populations of nodes where the second population (B) has a continuous label (marker) associated with it, and the pair correlation function is weighted by the similarity in the continuous label to a target value.

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_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_bandwidthfloat, optional: The bandwidth parameter for the marker kernel function. This controls the smoothness of the weighting based on the continuous labels of objects B. Default is 0.2.
marker_kernel_nint, optional: The exponent parameter for the marker kernel function. This controls the shape of the kernel for weighting based on the continuous labels of objects B. Default is 1 (which corresponds to a Laplacian-like kernel).
marker_minfloat, optional: The minimum value of the continuous label for objects B to consider when computing the weighted pair correlation function. Default is 0.
marker_maxfloat, optional: The maximum value of the continuous label for objects B to consider when computing the weighted pair correlation function. Default is 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 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:

taunumpy.ndarray: The target marker values 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 radii and target marker values. Shape is (len(tau), len(radius)).
confidence_intervalnumpy.ndarray (if return_confidence_interval is True): If return_confidence_interval is True, this will be a numpy array (2,num_mark_targets,num_radii) containing the confidence intervals for the pair correlation function at each mark target and radii. 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

Computing the weighted pair correlation function for a spatial network with a continuous node label (marker) and plotting the results:

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
categorical_labels = sprial_df['Marker (categorical)'].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,categorical_labels,node_label_name='Marker (categorical)')
sn.utils.add_node_labels(G,continuous_labels,node_label_name='Marker (continuous)')

# get the node ids for the nodes with categorical label A
nodes_a = sn.utils.query_nodes(G,node_label_name='Marker (categorical)',relation='is',node_label_value='A')

# compute the weighted-PCF for the spatial network between nodes_a and all nodes with continuous label 'Marker (continuous)'
tau,radius,pcf_values,con_interval = sn.point_patterns.weighted_pair_correlation_function(G,
                                                                                        node_label_name_b='Marker (continuous)',
                                                                                        nodes_a=nodes_a,
                                                                                        spatial_kernel_bandwidth=80,
                                                                                        r_max=1000,
                                                                                        return_confidence_interval=True)

# plot the PCF for the weighted pair correlation function at target mark of 0 and 1
tau_index_0=np.where(tau==0)[0][0]
tau_index_1=np.where(tau==1)[0][0]

fig,ax=plt.subplots()
ax.axhline(1,linestyle='dashed',color='grey')
ax.plot(radius,pcf_values[tau_index_0,:],label='Target mark, :math:`\tau=0`',color='tab:blue')
ax.fill_between(radius,con_interval[0,tau_index_0,:],con_interval[1,tau_index_0,:],alpha=0.2,color='tab:blue')

ax.plot(radius,pcf_values[tau_index_1,:],label='Target mark, :math:`\tau=1`',color='tab:orange')
ax.fill_between(radius,con_interval[0,tau_index_1,:],con_interval[1,tau_index_1,:],alpha=0.2,color='tab:orange')

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