Utils

This section describes utility functionalities provided by RecurrenceMicrostatesAnalysis.jl, including parameter optimization and operations on recurrence microstates.

Optimizing a parameter

When working with recurrence plots (RPs), a well-known challenge is selecting an appropriate recurrence threshold. Within the RMA framework, this issue is addressed by optimizing an information-theoretic or complexity-based measure with respect to the threshold parameter.

In practice, it is common to determine the threshold that maximizes either the RecurrenceEntropy or the Disorder quantifier (Lima Prado et al., 2023).

This optimization procedure is implemented via the optimize function, which computes the optimal value of a given Parameter.

Parameter

optimize(param::Parameter, qm::QuantificationMeasure, args...)

Parameters

Threshold <: Parameter

optimize(::Threshold, qm::RecurrenceEntropy, [x], n::int; kwargs...)
optimize(::Threshold, qm::Disorder{N}, [x]; kwargs...)

using Distributions, RecurrenceMicrostatesAnalysis
data = StateSpaceSet(rand(Uniform(0, 1), 1000))
th, s = optimize(Threshold(), RecurrenceEntropy(), data, 3)

Operations on microstates

The package also provides a set of operations that can be applied to recurrence microstates or to their decimal representations.

Operation

operate(op::Operation, [...])

Permutations and Transposition

When working with square microstates, it is natural to consider symmetry operations such as row and column permutations, as well as transposition. These operations are particularly important for defining equivalence classes used in the computation of the Disorder quantifier.

To illustrate these operations, we consider a square microstate of size $3 \times 3$:

\[\mathbf{M} = \begin{pmatrix} a & b & c \\ d & e & f \\ g & h & i \end{pmatrix}.\]

Permutations of Rows

Let $\sigma \in S_N$ be a permutation, where $S_N$ is the symmetric group, and let $\mathcal{L}_\sigma$ denote the operator that permutes the rows of a microstate $\mathbf{M}$ according to $\sigma$.

For example, for $\sigma = 132$, the third and second rows are exchanged, while the first row remains unchanged:

\[\mathcal{L}_{132}\mathbf{M} = \begin{pmatrix} a & b & c \\ g & h & i \\ d & e & f \end{pmatrix}.\]

For a given microstate size $n$, all possible row (or column) permutations can be generated using the Combinatorics.jl package:

using Combinatorics

n = 3
Sn = collect(permutations(1:n))

6-element Vector{Vector{Int64}}:
 [1, 2, 3]
 [1, 3, 2]
 [2, 1, 3]
 [2, 3, 1]
 [3, 1, 2]
 [3, 2, 1]

σ = Sn[2]

3-element Vector{Int64}:
 1
 3
 2

The permutation is applied using PermuteRows operation. For example, consider the square $3\times 3$ microstate with decimal index $I = 237$:

\[\mathbf{M} = \begin{pmatrix} 0 & 0 & 1 \\ 1 & 0 & 1 \\ 1 & 1 & 0 \end{pmatrix}.\]

using RecurrenceMicrostatesAnalysis

shape = Rect(n, n)
row_permutation = PermuteRows(shape)

operate(row_permutation, 237, σ)

349

The result is the microstate with decimal identifier $I = 239$, corresponding to:

\[\mathcal{L}_{132}\mathbf{M} = \begin{pmatrix} 0 & 0 & 1 \\ 1 & 1 & 0 \\ 1 & 0 & 1 \end{pmatrix}.\]

PermuteRows{R, C} <: Operation

PermuteRows(::Rect2{R, C, B, E})

PermuteRows(Rect(3, 3))     #   Microstate 3 x 3
PermuteRows(Rest(3, 1))     #   Microstate 3 x 1 (it is a column)

operate(::PermuteRows, I::Int, σ::Vector{Int})

Permutations of Columns

Column permutations follow the same logic as row permutations, but are applied to the columns of the microstate.

Let $\mathcal{C}_\sigma$ denote the operator that permutes the columns of $\mathbf{M}$ according to $\sigma \in S_N$. For $\sigma = 132$, the transformation is given by:

\[\mathcal{C}_{132}\mathbf{M} = \begin{pmatrix} a & c & b \\ d & f & e \\ g & i & h \end{pmatrix}.\]

Using the same example of $I = 237$, column permutation is performed using the PermuteColumns operation:

col_permutation = PermuteColumns(shape; S = Sn)

PermuteColumns{3, 3}(Vector{UInt32}[[0x00000000, 0x00000001, 0x00000002, 0x00000003, 0x00000004, 0x00000005, 0x00000006, 0x00000007], [0x00000000, 0x00000001, 0x00000004, 0x00000005, 0x00000002, 0x00000003, 0x00000006, 0x00000007], [0x00000000, 0x00000002, 0x00000001, 0x00000003, 0x00000004, 0x00000006, 0x00000005, 0x00000007], [0x00000000, 0x00000002, 0x00000004, 0x00000006, 0x00000001, 0x00000003, 0x00000005, 0x00000007], [0x00000000, 0x00000004, 0x00000001, 0x00000005, 0x00000002, 0x00000006, 0x00000003, 0x00000007], [0x00000000, 0x00000004, 0x00000002, 0x00000006, 0x00000001, 0x00000005, 0x00000003, 0x00000007]])

operate(col_permutation, 237, 2)

347

The resulting microstate has decimal identifier $I = 347$, corresponding to:

\[\mathcal{C}_{132}\mathbf{M} = \begin{pmatrix} 0 & 1 & 0 \\ 1 & 1 & 0 \\ 1 & 0 & 1 \end{pmatrix}.\]

PermuteColumns{R, C} <: Operation

PermuteColumns(::Rect2{R, C, B, E}; S::Vector{Vector{Int}} = collect(permutations(1:C))

PermuteColumns(Rect(3, 3))     #   Microstate 3 x 3
PermuteColumns(Rest(1, 3))     #   Microstate 1 x 3 (it is a line)

operate(op::PermuteColumns, I::Int, Qi::Int)

Transposition

Transposition exchanges rows and columns of a microstate. Let $\mathcal{T}$ denote the transposition operator:

\[\mathcal{T}\mathbf{M} = \begin{pmatrix} a & d & g \\ b & e & f \\ c & f & i \end{pmatrix}.\]

Using the same example microstate with identifier $I = 237$, transposition is performed via the Transpose operator:

transposition = Transpose(shape)
operate(transposition, 237)

231

The resulting microstate has decimal identifier $I = 231$ corresponding to:

\[\mathcal{T}\mathbf{M} = \begin{pmatrix} 0 & 1 & 1 \\ 0 & 0 & 1 \\ 1 & 1 & 0 \end{pmatrix}.\]

Transpose{R, C} <: Operation

Transpose(::Rect2{R, C, B, E})

Transpose(Rect(3, 3))     # 3 x 3 microstate

operate(::Transpose, I::Int)