HistoricalStormTraceSimulation

MarginalTraceScore(metrics::NTuple{N,Metric},weights=ones(length(metrics)))

Construct a scoring method for traces based on a weighted some of marginal metrics.

Arguments

• metrics: Should be a tuple of p metrics, where p is the number of variables in the trace of interest (not including time).
• weights: A vector of weights to be used (defaults to vector of ones).

Use

Given a MarginalTraceScore called mscore.

(mscore::MarginalTraceScore)(t1::StormTrace,t2::StormTrace)

will compute the marginal trace score between two traces t1 and t2.

RescaleIdentity()

A rescale type to represent the identity rescale.

RescaleMaxChangeMin()

Linear rescale to adjust the maximum of the new trace to equal the summary value.

Given a trace variable series $y_j$, and summary value $x_j$, the new trace $\tilde{y}_j$ is constructed using the following rule, $\forall t\in T_y$:

$\tilde y_j(t) &= \frac{x_j}{\max\limits_{t\in T_y}y_j(t)}y_j(t).$

RescaleMaxPreserveMin()

Linear rescale to adjust the maximum of the new trace to equal the summary value whilst preserving the minimum.

Given a trace variable series $y_j$, and summary value $x_j$, the new trace $\tilde{y}_j$ is constructed using the following rule, $\forall t\in T_y$:

$\tilde y_j(t) &= \frac{x_j-\min\limits_{t\in T_y} y_j(t)}{\max\limits_{t\in T_y}y_j(t)-\min\limits_{t\in T_y} y_j(t)} \left(y_j(t)-\min\limits_{t\in T_y} y_j(t)\right) + \min\limits_{t\in T_y} y_j(t).$

This only works if the new maximum $x_j$ satisfies $x_j>\min\limits_{t\in T_y} y_j(t)$. The formula is $\forall t\in T_y$. If this condition is not satisfied, a warning will be displayed.

RescaleMean()

Additive rescaling to match the mean of the trace to the summary value.

Given a trace variable series $y_j$, and summary value $x_j$, the new trace

$\tilde y_j(t) &= y_j(t) - \overline{y_j} + x_j$

where $\overline{y_j} = \frac{1}{|T_y|} \sum_{t\in T_y}y_j(t)$.

StormHistory(summaries,traces)

For storing historical storms.

Arguments

• summaries: Should be a vector of vectors each of length q, containing summaries of storms.
• traces: Should be a vector of StormTraces, each satisfying nvariables(t)==q.

StormTrace(value,time)

Construct a StormTrace type used for storing a storm type.

Arguments

• value: A matrix of floats which is n × p.
• time: An abstract range of length n.

TraceSampler(d,samplemethod,n::Int)

Arguments

• summarymetric: A metric for determining closeness of storm summaries (must be subtype of Metric). Default is Euclidean().
• samplemethod: Method for sampling from closest points. Passing 1:m will sample uniformly from the closest m points. Defaults to 1:50. Could also be a Distribution.
• n: The number of storms.

Note

There is an alternate constructor TraceSampler(summarymetric,samplemethod,distance_store,distance_index) this is an internal feature, distance_store and distance_index are constructed based on n in the other constructor. Their purpose is to preallocate distance storage and improve performance.

length(s::StormHistory)

Compute the length of a StormHistory, i.e. the number of storms contained in the history.

length(t::StormTrace)

Compute the length of a StormTrace, which is the number of time points (not total number of elements).

adjusttracetime(trace, summary)

Adjust the time of a trace based on a summary (just calls rescaletime and then repacks in a StormTrace).

checkcompatible(t1::StormTrace,t2::StormTrace)

Check two traces are compatible.

checkcompatible(m::MarginalTraceScore,t::StormTrace)

Check trace is compatible with MarginalTraceScore.

computedistances!(summary,history,sampler::TraceSampler)

Compute the distances for a given summary to all historical summaries.

Note: This overwrites memory in sampler and returns nothing. See samplesingletrace for argument details.

conditional_expected_score(summary,trace,history,sampler,rescalemethod,interpolation_method,tracescore)

Compute the conditional expected score of a given historical trace. A different method will be used if the trace sampler uses a uniform over the closest m points method (i.e. if the sampler has a UnitRange for its samplemethod).

Arguments

• summary: The summary of a historical trace.
• trace: The corresponding trace.
• sampler: A TraceSampler.
• history, rescalemethod, interpolation_method: see sampletraces
• tracescore: Score for comparing traces.

dataframes2storms(event_data, event_start_end, input_data, simulated_data)

Convert dataframes containing storm parameters and data to traces and summaries for use in package.

Will reorder variables to match up names of variables. Pass outputs to sampletraces function.

Arguments:

• event_data - DataFrame containing summaries of historical storms.
• event_start_end - DataFrame containing start and end indices of events in input_data.
• input_data - DataFrame containing historical time series.
• simulated_data - DataFrame containing simulated storm summaries.

Outputs:

• new_summaries - Vector of summary vectors.
• history - StormHistory object.
• summary_names - Names of summary variables in order (traces are the same but one less variable (time is separate)).

expected_score(history::StormHistory; samplemethod=1:50, rescalemethod, summarymetric::Metric=Euclidean(), interpolation_method=LinearInterpolation, tracescore::TraceScore)

Compute the expected score.

Arguments:

• history, samplemethod, rescalemethod, summarymetric, interpolation_method: see sampletraces.
• tracescore: Score for comparing traces.

find_best_distance(D::Type{<:Metric},x₀,history; lowerbounds, upperbounds, optim_kwargs=(), kwargs...)

Use optim to find the best distance based on score_method scoring.

Arguments:

• D the type of distance (e.g. WeightedEuclidean). Note this is the type, not an instance!
• x₀ initial parameters for the distance to start optimisation.
• history the storm history.
• lowerbounds the lower bounds for the optimisation, defaults to fill(-Inf,length(x₀)).
• upperbounds the upper bounds for the optimisation, defaults to fill(Inf,length(x₀)).
• optim_kwargs: Key word arguments to be passed to Optim.
• kwargs additional key word arguments, similar to score_method, but not including summarymetric, as this is specified by the optimisation.

interpolatetrace(trace,Δ,interpolation_method=LinearInterpolation)

Interpolate a trace to a new resolution Δ.

Arguments

• trace: The trace to be interpolated.
• Δ: The new time resolution.
• interpolation_method: see docstring for sampletraces.

nvariables(t::StormTrace)

Compute the number of variable contained by a storm trace, including time.

This is size(t.value,2)+1.

rescaletime(time,duration)

Rescale the time to match the duration $(d)$ and start at 0. The formula is, $\forall t \in T_y$

$\tilde{t}_t &= (t-\min T_y) \frac{d}{\max T_y - \min T_y}.$

Then the time vector of $\tilde y$ is $T_{\tilde{y}} = \{\tilde{t}_t \mid t \in T_y\}$.

rescaletrace!(trace::StormTrace,summary,rescalemethod::NTuple{N,RescaleMethod}) where {N}

Rescale a trace to match a summary.

Arguments

• trace: The StormTrace to be adjusted.
• summary: The summary to simulate a trace for.
• rescalemethod: see docstring for sampletraces.

samplehistoricaltrace(summary,history,sampler::TraceSampler)

Sample a historical trace from a history given a summary.

See samplesingletrace for argument details.

samplesingletrace(summary,history,sampler,rescalemethod,interpolation_method=LinearInterpolation)

Function to sample a trace given a summary and history.

Arguments

• summary: The summary to simulate a trace for.
• history: The StormHistory to match to.
• sampler: Sampler of type TraceSampler.
• rescalemethod: see docstring for sampletraces.
• interpolation_method: see docstring for sampletraces.

simulatesinglefixedtrace()

Method to simulate a fixed trace based on rescaling the ith historical trace.