cross_pair_correlation_function#
- cross_pair_correlation_function(domain, population_A, population_B, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, distance_metric='euclidean', max_R=100, annulus_step=10, annulus_width=10, exclude_zero=False, remain_within_connected_component=False, return_confidence_interval=False, return_PCF_contributions=False, visualise_output=False, visualise_spatial_statistic_kwargs={})#
Calculate the 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_Aquery-like
The first population of objects or a query to select them.
- population_Bquery-like
The second population of objects or a query to select them.
- 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.
- 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 observations separated by zero distance. Defaults to False.
- remain_within_connected_componentbool, optional
Whether to remain within the connected component. Defaults to False.
- return_confidence_intervalbool, optional
Return a 95% confidence interval around the PCF. Defaults to False.
- return_PCF_contributionsbool, optional
Return the contribution of each cell of type A to the PCF (useful for downstream batch analyses). Defaults to False.
- visualise_outputbool, optional
If True, call “visualise_spatial_statistic” to generate a plot of the PCF. Defaults to False.
- visualise_spatial_statistic_kwargsdict, optional
Arguments to pass to visualise_spatial_statistic if visualise_output is True.
- Returns:
- radii_innerndarray
The inner radii of the annuli.
- cross_PCF_A_to_Bndarray
The pair correlation function values.
- confidence_intervalsndarray (optional)
If return_confidence_interval=True, return lower and upper bounds of a 95% confidence interval around the PCF (see Loh 2008 for details on implementation https://www.doi.org/10.1086/588631)
- contributionsndarray (optional)
If return_PCF_contributions=True, return the contribution of each cell of type A to the PCF (useful for downstream batch analyses)
- 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.
- NotImplementedError
If remain_within_connected_component is True.
Notes
For more information on pair correlation function, see https://link.springer.com/content/pdf/10.1007/978-3-540-38175-4_1.pdf.