# 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:

`CorrelationFunctions.Directional.AbstractPlane`

— Type`CorrelationFunctions.Directional.PlaneXY`

— Type`PlaneXY()`

A designator for a plane defined by vectors `[1, 0]`

and `[0, 1]`

(2D case) or `[1, 0, 0]`

and `[0, 1, 0]`

(3D case).

See also: `AbstractPlane`

.

`CorrelationFunctions.Directional.PlaneXZ`

— Type`PlaneXZ()`

A designator for a plane defined by vectors `[1, 0, 0]`

and `[0, 0, 1]`

.

See also: `AbstractPlane`

.

`CorrelationFunctions.Directional.PlaneYZ`

— Type`PlaneYZ()`

A designator for a plane defined by vectors `[0, 1, 0]`

and `[0, 0, 1]`

.

See also: `AbstractPlane`

.

## Correlation functions

This section describes higher order correlation functions.

`CorrelationFunctions.Directional.s3`

— Function`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.c3`

— Function`c3(array, phase[; planes :: Vector{AbstractPlane}, len, periodic = false])`

Calculate three-point cluster 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.

See also: `s3`

, `AbstractPlane`

.

`CorrelationFunctions.Directional.surf3`

— Function```
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`

.

See also: `s3`

, `AbstractPlane`

, `ErosionKernel`

.

`CorrelationFunctions.Directional.surf2void`

— Function```
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`

.

See also: `s3`

, `AbstractPlane`

, `ErosionKernel`

.

`CorrelationFunctions.Directional.surfvoid2`

— Function```
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`

.

See also: `s3`

, `AbstractPlane`

, `ErosionKernel`

.