PairCorrelationFunction

Constants(xlims::Tuple{Float64, Float64}, ylims::Tuple{Float64, Float64}[, zlims::Tuple{Float64, Float64}], dr::Real)

A struct to hold the constants needed for the pair correlation function calculation.

The vector of radii that define the concentric annuli must have constant spacing. You may either pass in the spacing dr or a range of radii in the form r0:dr:rf.

Fields

• grid_size::NTuple{N, Float64}: The size of the grid in each dimension.
• base_point::NTuple{N, Float64}: The base point of the grid to be used to calculate distance to the boundary.
• domain_volume::Float64: The volume of the domain.
• radii::AbstractRange{<:Real}: The range of radii to be used for the pair correlation function.
• radii2::AbstractVector{<:Real}: The squared values of the radii.

Examples

using PairCorrelationFunction
xlims = (-450.0, 450.0)
ylims = (-450.0, 450.0)
radii = 0:20.0:1300.0
constants = Constants(xlims, ylims, radii)
# output
Constants for 2D pair correlation function:
  grid_size: (900.0, 900.0)
  base_point: (-450.0, -450.0)
  domain_volume: 810000.0
  radii: 0.0 - 1300.0
  #annuli: 65

using PairCorrelationFunction
xlims = (-450.0, 450.0)
ylims = (-450.0, 450.0)
zlims = (-450.0, 450.0)
dr = 100.0
constants = Constants(xlims, ylims, zlims, dr)
# output
Constants for 3D pair correlation function:
  grid_size: (900.0, 900.0, 900.0)
  base_point: (-450.0, -450.0, -450.0)
  domain_volume: 7.29e8
  radii: 0.0 - 1600.0
  #annuli: 16

PCFResult

A struct to hold the results of the pair correlation function calculation.

For a single sample/timepoint, the g field will be a vector of pair correlation function values. For multiple samples/timepoints, the g field will be a matrix where each column corresponds to a sample/timepoint.

The hcat function is overloaded to allow for easy concatenation of multiple PCFResult objects. See example below.

Fields

• radii::AbstractVector{<:Real}: The range of radii used for the pair correlation function.
• g::AbstractArray{Float64}: The pair correlation function values for each radius, possibly over many samples/timepoints.

Example

using PairCorrelationFunction
radii = [0.0, 1.0, 2.0]
g = [0.5, 1.2]
PairCorrelationFunction.PCFResult(radii, g)
# output
PCFResult:
  Radii: 0.0 - 2.0 with 2 annuli
  g: 0.5 - 1.2 (min - max)

using PairCorrelationFunction
radii = 0.0:1.0:2.0
result_1 = PairCorrelationFunction.PCFResult(radii, [0.5, 1.2])
result_2 = PairCorrelationFunction.PCFResult(radii, [0.6, 1.3])
result_3 = PairCorrelationFunction.PCFResult(radii, [0.8, 1.4])
hcat(result_1, result_2, result_3)
# output
PCFResult:
  #timepoints: 3
  Radii: 0.0 - 2.0 with 2 annuli
  g: 0.5 - 1.4 (min - max)

_histcounts_include_min!(N::Vector{Int}, x::Vector{Float64}, xedges::AbstractRange{<:Real})

Like histcounts!, but includes the minimum edge of the histogram in the first bin.

This function relies on xedges[1]==0.0 and the input x being all distances to guarantee no value is less than 0. Users can pass in radii with any upper bound and nothing stops the targets from being outside the domain, so we cannot guarantee that the maximum value of x is less than or equal to the maximum value of xedges.

pcf(centers::AbstractMatrix{<:Real}, targets::AbstractMatrix{<:Real}, constants::Constants)

Calculate the pair correlation function for a set of centers and targets.

For each point in the centers matrix, compute the distance to each point in the targets matrix. Bin these distances by the radii defined in the constants object. If targets is not provided, the function will use centers as both centers and targets. Technically, this is the traditional pcf. The version with centers and targets is the cross-PCF.

Arguments

• centers::AbstractMatrix{<:Real}: A matrix of centers, where each row is a center.
• targets::AbstractMatrix{<:Real}: A matrix of targets, where each row is a target.
• constants::Constants: A Constants object containing the grid size, base point, domain volume, and radii.

Returns

• PCFResult: A struct with the radii and the pair correlation function values.

pcfplot

Plot the pair correlation function.

Arguments

The function accepts 1, 2, or 3 arguments. In all three cases, the objects containing the PCF values are in the final of these arguments either as single instances or as vectors of instances.

Vectors

If the PCF values are all vectors, this will assume that these are independent realizations of the same process and will plot a mean and standard deviation. In this case, an optional first argument can be passed to specify the radii. If omitted, then the radii will be inferred from the PCFResult objects or, in the case Vector{<:Real} are passed in, the radii will be the vector indices, i.e. 1:length(g).

Matrices

If the PCF values are all matrices, this will assume that each column is a different timepoint and will plot a heatmap of the mean across all samples (each matrix representing a timeseries sample). In this case, two optional first arguments can be passed to specify the timepoints and radii, respectively. If providing these arguments, the radii argument can be omitted ONLY IF the PCF values are passed in as PCFResult objects, i.e., they have the radii stored in the radii field. This ordering is because we assume that the time will be displayed on the x-axis. To swap the axes, transpose the matrices; then, pass in the timepoints as the second argument and the radii as the first argument. If neither are passed in, the radii will be inferred as for the vectors; timepoints will be the indices of the columns of the matrices, i.e. 1:size(g, 2).

Optional arguments

When plotting a heatmap, i.e., matrices, pcfplot will use the :tofino colorscheme by default. This can be changed by passing in a keyword argument colorscheme with the desired colorscheme. See the Plots-supported color schemes for more options. So long as color is not user-defined, then pcfplot use this scheme and will further set the color scheme to transition at the pcf value 1 to highlight the transition from depletion to enrichment.

Examples

using PairCorrelationFunction
using Plots
g = [0.5; 1.2; 0.8; 0.7; 0.6; 1.6]
pcfplot(g)

using PairCorrelationFunction
using Plots
g1 = [0.5; 1.2; 0.8; 0.7; 0.6; 1.6]
g2 = [0.9; 1.0; 1.1; 1.2; 1.3; 1.4]
pcfplot([g1, g2])

using PairCorrelationFunction
using Plots
g = [0.5 1.2 0.8;
     0.7 0.6 1.6;
     0.9 1.0 1.1;
     1.2 1.3 1.4;
     1.5 1.6 1.7]
pcfplot(g; colorscheme=:cork)

using PairCorrelationFunction
using Plots
result = PairCorrelationFunction.PCFResult(0:20.0:100.0, [0.1; 0.2; 0.3; 0.4; 0.5])
pcfplot(result)

using PairCorrelationFunction
using Plots
result1 = PairCorrelationFunction.PCFResult(0:20.0:100.0, [0.1; 0.2; 0.3; 0.4; 0.5])
result2 = PairCorrelationFunction.PCFResult(0:20.0:100.0, [0.6; 0.7; 0.8; 0.9; 1.0])
RESULT = hcat(result1, result2)
pcfplot([100.0, 200.0], RESULT) # use radii in RESULT for y-axis
pcfplot([100.0, 200.0], 0:20.0:100.0, RESULT) # explicitly pass in radii