# Higher order statistics

Since version 0.9 CorrelationFunctions.jl has a support for higher order correlation functions. These functions are placed in the CorrelationFunctions.Directional module. There is no support for higher order correlation maps because such maps consume a large amount of memory.

## Patterns and planes

Currently these functions sample an input array with a pattern in the form of a right triangle parallel to one of coordinate planes. Here is a description of the planes:

## Correlation functions

This section describes higher order correlation functions.

CorrelationFunctions.Directional.s3Function
s3(array[; planes :: Vector{AbstractPlane}, len, periodic = false])

Calculate the three-point correlation function using a right triangle pattern.

This function takes an array and a vector of planes parallel to axes of the array. For each plane all possible right triangles with length of a side ≤ len and parallel to that plane are generated and tested against the array. A dictionary of type Dict{AbstractPlane, Matrix{Float64}} is returned as a result. Indices of arrays equal to lengths of catheti of a right triangle. Periodic or zero-padding boundary conditions are selected with the choose of periodic argument.

The following invariants hold:

julia> array = rand(Bool, (100, 100));
julia> vals2 = s2(array, 1);
julia> vals3 = s3(array);
julia> vals2[DirX()] == vals3[PlaneXY][:, 1]
true
julia> vals2[DirY()] == vals3[PlaneXY][1, :]
true

The same is true for other planes.

See also: AbstractPlane, s2.

s3(array, phase[; planes :: Vector{AbstractPlane}, len, periodic = false])

The same as s3(array .== phase; ...). Kept for consistency with other parts of the API.

CorrelationFunctions.Directional.surf3Function
surf3(array, phase[; planes :: Vector{AbstractPlane},
len, periodic = false, filter :: AbstractKernel])

Calculate surface-surface-surface ($F_{sss}$) correlation function.

This function is is internally calculated using s3 and hence uses the same sampling pattern and returns a result in the same format.

You can chose how an edge between phases is selected by passing filter argument of type Utilities.ErosionKernel.

CorrelationFunctions.Directional.surf2voidFunction
surf2void(array, phase[; void_phase = 0,
planes :: Vector{AbstractPlane}, len, periodic = false, filter :: AbstractKernel])

Calculate surface-surface-void ($F_{ssv}$) correlation function.

This function is is internally calculated using s3 and hence uses the same sampling pattern and returns a result in the same format. The first index in the resulting arrays is responsible for the "void part" of the functions and the second is responsible for the "surface part".

You can chose how an edge between phases is selected by passing filter argument of type Utilities.ErosionKernel.

CorrelationFunctions.Directional.surfvoid2Function
surfvoid2(array, phase[; void_phase = 0,
planes :: Vector{AbstractPlane}, len, periodic = false, filter :: AbstractKernel])

Calculate surface-void-void ($F_{svv}$) correlation function.

This function is is internally calculated using s3 and hence uses the same sampling pattern and returns a result in the same format.

You can chose how an edge between phases is selected by passing filter argument of type Utilities.ErosionKernel.