Example: Dansgaard-Oescher events with NGRIP and CLIMBER-X data

[JanJereczek]

This PR mainly provides an example (docs/src/examples/do-events.jl) of Critical Slowing Down applied on the $\delta^{18}O$ record from NGRIP. This time series displays DO-events and therefore many abrupt transitions in real-world, paleoclimatic data. Furthtermore, the same analysis is performed on simulation data from CLIMBER-X (less noisy and even time sampling), an Earth Model of Intermediate Complexity able to reproduce DO-like events.

Two things are mildly ugly in this example and are subject to future changes:

• The preprocessing is quite long. Maybe upload preprocessed time series to cut down code of example? On the other hand, maybe nice for people to see how preprocessing can be done.
• The transition times of the DO are eye-balled + hand-coded. This should be replaced by an automated procedure like those provided by ChangePoints.jl, which however did not give good results so far on the NGRIP data.

This PR additionally comes with minor suggestions:

• Created docs/src/examples folder for literate examples.
• Renamed examples.jl to permutation_entropy.jl and moved to docs/src/examples.
• Replaced docs/src/tutorial.md by docs/src/examples/tutorial.jl such that the tutorial is built by Literate.jl.
• estimate_transitions is renamed to transition_metrics as it describes more accurately what the function does, namely computing the indicators and their change metric (I suggest we generally refer to them as transition metrics). So far, no transition is estimated since it is done in the later step of significance analysis.
• significant_transitions was renamed to estimate_significance. For more details, c.f. next comment.
• The significance analysis has now an option detrend_surro to detrend the surrogate. This is sometimes done in the literature and might therefore be wishful (although, I agree, not of utmost importance).
• precompute_ridgematrix was renamed to ridgematrix since it simply computes the matrix.

[JanJereczek]

Commit d430b09 separates the config of the significance analysis, now defined in e.g. SurrogastesConfig<:SignificanceConfig, from its results, now stored in e.g. SurrogatesSignificance<:TransitionsSignificance. Now we would run:

sigconfig = SurrogatesConfig()
signif = estimate_significance(sigconfig, wir::WindowedIndicatorResults)

The p-values, their flags and the config used are accessible by calling the fields .pvalues, .flags, .config. This separation is more coherent with the choices we've made so far for the API, for instance separating WindowedIndicatorConfig from WindowedIndicatorResults.

Furthermore, if one wants to analyse many time series with the same config, no need to initialise it every time within the loop.

An additional change has been made in the initialisation of the p-values (c.f. estimate_significance). It was formerly done with similar() which however led to some nonsense p-values in some cases (outside of [0,1]). It is now corrected by simply using zeros instead.

[Datseris]

please use this : JuliaDynamics/ComplexityMeasures.jl#302

[Datseris]

[Li2019](@cite)

[Datseris]

closing in favor of #48 (which I will review soon). Don't worry Jan I am not deleting the branch yet.