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.