weighted_pair_correlation_function#

weighted_pair_correlation_function(domain, population_A, population_B, mark_pop_B, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, weighting_function_pop_B=None, mark_step_pop_B=None, mark_min_pop_B=None, mark_max_pop_B=None, distance_metric='euclidean', max_R=100, annulus_step=10, annulus_width=10, exclude_zero=False, remain_within_connected_component=False, visualise_output=False, visualise_wpcf_kwargs={})#

Calculate the weighted pair correlation function between population_A and population_B. The pair correlation function (PCF) in Spatial Statistics quantifies the spatial dependence between pairs of points in a point pattern.

It is defined as the ratio of the observed density of point pairs at a given distance r to the expected density under complete spatial randomness (CSR).

If boundaries are specified, restrict analysis to those populations within the boundary and correct for edge effects. Note that if there are multiple disjoint boundary regions, the distance between points in different regions is still calculated according to the distance_metric and used in the PCF calculation.

Parameters:

domainobject: The spatial domain containing the populations.
population_Aarray-like or query-like: The first population of objects or a query to select them.
population_Barray-like or query-like: The second population of objects or a query to select them.
mark_pop_Bstr: The name of a continuous label associated with all objects in population_B
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: Buffer to exclude objects located within boundary_exclude_distance from the boundaries. Defaults to 0.
weighting_function_pop_Bfunction, optional.: Weighting function associated with mark_pop_B. If no function is passed, a triangular function whose peak is 1 and base spans 10% of the range of the mark is used.
mark_step_pop_Bfloat, optional.: Step-size dictating the resolution of the wPCF in the ‘mark’ direction. If not specified, defaults to 5% of the range of the mark.
mark_min_pop_Bfloat, optional.: Minimum value for the resolution of the wPCF in the ‘mark’ direction. If not specified, defaults to the minimum observed mark value.
mark_max_pop_Bfloat, optional.: Maximum value for the resolution of the wPCF in the ‘mark’ direction. If not specified, defaults to the maximum observed mark value.
distance_metricstr, optional: The distance metric to use. Defaults to ‘euclidean’.
max_Rfloat, optional: The maximum radius to consider. Defaults to 100.
annulus_stepfloat, optional: The step size for the annulus radii. Defaults to 10.
annulus_widthfloat, optional: The width of the annulus. Defaults to 10.
exclude_zerobool, optional: Whether to exclude zero distances. Defaults to False.
remain_within_connected_componentbool, optional: Whether to remain within the connected component. Defaults to False.
visualise_outputbool, optional: Whether to visualise the output. Defaults to False.
visualise_wpcf_kwargsdict, optional: Keyword arguments for visualisation. Defaults to {}.

Returns:

radii_innerndarray: The inner radii of the annuli.
weighted_PCF_A_to_Bndarray: The pair correlation function values.
marksndarray, optional output: The marks associated with the objects in population (if return_marks_of_B is True).

Raises:

ValueError: If the query provided for population_A is not of the correct type.
ValueError: If the query provided for population_B is not of the correct type.
ValueError: If the query provided for include_boundaries is not of the correct type.
ValueError: If the query provided for exclude_boundaries is not of the correct type.
ValueError: If the label referred to by mark_pop_B is not a continuous label.
NotImplementedError: If remain_within_connected_component is True.

Notes

For more information on the weighted pair correlation function, see https://doi.org/10.1371/journal.pcbi.1010994 or https://doi.org/10.1017/S2633903X24000011.