Generalize TransferOperator

Project.toml

@@ -9,6 +9,7 @@ Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 DelayEmbeddings = "5732040d-69e3-5649-938a-b6b4f237613f"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+KrylovKit = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Neighborhood = "645ca80c-8b79-4109-87ea-e1f58159d116"
 QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
@@ -28,6 +29,7 @@ Combinatorics = "1"
 DelayEmbeddings = "2.6"
 Distances = "0.9, 0.10"
 FFTW = "1"
+KrylovKit = "0.10.2"
 Neighborhood = "0.2.4"
 QuadGK = "2.9"
 Reexport = "1"

docs/make.jl

@@ -42,5 +42,5 @@ bib = CitationBibliography(
 )
 
 build_docs_with_style(pages, ComplexityMeasures, StateSpaceSets;
-    expandfirst = ["index.md"], bib,
+    expandfirst = ["index.md"], bib,linkcheck=false
 )

docs/src/examples.md

@@ -66,6 +66,62 @@ kldivergence(py, px)
 
 (`Inf` because there are events with 0 probability in `px`)
 
+
+## Transition probabilitites: Transfer operator
+
+What are the most probable outcomes the system can transition to, given its current state?
+Transition probabilities capture dynamic information and can also be relevant in cases 
+where one needs more than just the probabilities of outcomes. 
+The [`TransferOperator`](@ref) or (Perron-Frobenius operator) is also implemented as a 
+subtype of `ProbabilitiesEstimator`, giving access to transition probabilities as well as 
+the probabilities of outcomes themselves.
+
+As a first example, let's look at transition probabilities between bins of
+the coarse-grained phase space (partitioning) of the Henon map:
+
+````@example MAIN
+using ComplexityMeasures
+using DynamicalSystemsBase
+
+henon_rule(x, p, n) = SVector{2}(1.0 - p[1]*x[1]^2 + x[2], p[2]*x[1])
+ds = DeterministicIteratedMap(henon_rule, [0.0,0.0], [1.4,0.3])
+timeseries, t = trajectory(ds, 10_000; Ttr = 500)
+
+
+b = ValueBinning(RectangularBinning(3,true)) #3x3 grid in 2D
+to = transferoperator(b, timeseries)
+P = transfermatrix(to)
+````
+
+Estimate probabilities from the transition matrix: 
+````@example MAIN
+outs = outcomes(to) #bins
+probs = probabilities(TransferOperator(), b, timeseries)
+````
+
+The transfer operator is generalized to work with many more outcomes. Let's look at 
+transition probabilities between ordinal patterns using time series  of the logistic map:
+````@example MAIN
+using ComplexityMeasures
+using DynamicalSystemsBase
+
+logistic_rule(u, r, t) = SVector(r*u[1]*(1 - u[1]))
+ds = DeterministicIteratedMap(logistic_rule, [0.4], 4.0)
+X, t = trajectory(ds, 10_000; Ttr = 100)
+x = x[:, 1]
+
+o = OrdinalPatterns{3}()
+to = transferoperator(o, x)
+P = transfermatrix(to)
+````
+
+Estimate probabilities from the transition matrix iteratively or by calculating eigenvectors: 
+````@example MAIN
+outs = outcomes(to) #show observed ordinal patterns
+p_it = probabilities(TransferOperator(ApproximationIterative()), o, x)
+p_eig = probabilities(TransferOperator(ApproximationEigen()), o, x)
+````
+
 ## Differential entropy: estimator comparison
 
 ### Shannon entropy

docs/src/probabilities.md

@@ -52,21 +52,6 @@ AmplitudeAwareOrdinalPatterns
 Dispersion
 ```
 
-### Transfer operator
-
-```@docs
-TransferOperator
-```
-
-#### Utility methods/types
-
-```@docs
-InvariantMeasure
-invariantmeasure
-transfermatrix
-transferoperator
-```
-
 ### Kernel density
 
 ```@docs
@@ -136,6 +121,7 @@ RelativeAmount
 BayesianRegularization
 Shrinkage
 AddConstant
+TransferOperator
 ```
 
 ## [Encodings/Symbolizations API](@id encodings)

docs/src/tutorial.jl

@@ -190,7 +190,7 @@ probsy_bayes .- probsy
 
 # While the corrections of [`BayesianRegularization`](@ref) are small in this case, they are
 # nevertheless measurable.
-#
+
 # When calling [`probabilities`](@ref) only with an outcome space instance and some input
 # data (skipping the [`ProbabilitiesEstimator`](@ref)), then by default, the
 # [`RelativeAmount`](@ref) probabilities estimator is used to extract the probabilities.

src/core/outcome_spaces.jl

@@ -35,7 +35,6 @@ discretize/encode the data directly.
 | [`CosineSimilarityBinning`](@ref)       | Cosine similarity                 | `Vector`                  | ✔                  |
 | [`BubbleSortSwaps`](@ref)               | Swap counts when sorting          | `Vector`                  | ✔                  |
 | [`SequentialPairDistances`](@ref)       | Sequential state vector distances | `Vector`, `StateSpaceSet` | ✔                  |
-| [`TransferOperator`](@ref)              | Binning (transfer operator)       | `Vector`, `StateSpaceSet` | ✖                  |
 | [`NaiveKernel`](@ref)                   | Kernel density estimation         | `StateSpaceSet`           | ✖                  |
 | [`WeightedOrdinalPatterns`](@ref)       | Ordinal patterns                  | `Vector`, `StateSpaceSet` | ✖                  |
 | [`AmplitudeAwareOrdinalPatterns`](@ref) | Ordinal patterns                  | `Vector`, `StateSpaceSet` | ✖                  |

src/core/probabilities.jl

@@ -167,6 +167,7 @@ The default probabilities estimator is [`RelativeAmount`](@ref), which is compat
 - [`Shrinkage`](@ref).
 - [`BayesianRegularization`](@ref).
 - [`AddConstant`](@ref).
+- [`TransferOperator`](@ref).
 
 ## Description
 

src/deprecations.jl

@@ -124,3 +124,43 @@ function allcounts(args...)
     @warn "`allcounts` is deprecated. Use `allcounts_and_outcomes` instead."
     return first(allcounts_and_outcomes(args...))
 end
+
+function TransferOperator(b :: AbstractBinning)
+    @warn "`TransferOperator(b <: AbstractBinning)` is deprecated. Use `TransferOperator(approximation_method::ApproximationMethod,boundary_condition)` instead."
+    return TransferOperator()
+end
+
+function transferoperator(pts::Array_or_SSSet,
+        binning::Union{FixedRectangularBinning, RectangularBinning};
+        boundary_condition = :none, 
+        warn_precise = true) 
+
+    @warn "`transferoperator(pts, binning::Union{FixedRectangularBinning, RectangularBinning)` is deprecated. Use `transferoperator(o::OutcomeSpace,x)` instead."
+
+    return transferoperator(ValueBinning(binning), pts)
+
+end
+
+function invariantmeasure(x::Array_or_SSSet,binning::Union{FixedRectangularBinning, RectangularBinning})
+
+    @warn "`invariantmeasure(x, binning::Union{FixedRectangularBinning, RectangularBinning)` is deprecated. Use `invariantmeasure(o::OutcomeSpace,x)` instead."
+
+    o = ValueBinning(binning)
+    invariantmeasure(o, x)
+
+end
+
+function probabilities(x::Array_or_SSSet,est::TransferOperator)
+    @warn "`probabilities(est::TransferOperator, x` is deprecated. Since `TransferOperator` is no longer limited to binnings, you have to explicitly provide an `OutcomeSpace` as well. Use `probabilities(probest::TransferOperator, o::OutcomeSpace, x::Array_or_SSSet)` instead. Defaulting to `RectangularBinning(3,true)`."
+    b = RectangularBinning(3,true)
+    o = ValueBinning(b)
+    probabilities(est, o, x)
+end
+
+
+function probabilities_and_outcomes(x::Array_or_SSSet,est::TransferOperator)
+    @warn "`probabilities_and_outcomes(est::TransferOperator, x` is deprecated. Since `TransferOperator` is no longer limited to binnings, you have to explicitly provide an `OutcomeSpace` as well. Use `probabilities_and_outcomes(probest::TransferOperator, o::OutcomeSpace, x::Array_or_SSSet)` instead. Defaulting to `RectangularBinning(3,true)."
+    b = RectangularBinning(3, true)
+    o = ValueBinning(b)
+    probabilities_and_outcomes(est, o, x)
+end

src/outcome_spaces/outcome_spaces.jl

@@ -4,7 +4,6 @@ include("ordinal_patterns.jl")
 include("kernel_density.jl")
 include("power_spectrum.jl")
 include("wavelet_overlap.jl")
-include("transfer_operator/transfer_operator.jl")
 include("dispersion.jl")
 include("cosine_similarity_binning.jl")
 include("sequential_pair_distances.jl")