Emulators

struct Emulator{FT<:AbstractFloat, VV<:(AbstractVector)}

Structure used to represent a general emulator, independently of the algorithm used.

Fields

• machine_learning_tool::CalibrateEmulateSample.Emulators.MachineLearningTool: Machine learning tool, defined as a struct of type MachineLearningTool.

• io_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT} where FT<:AbstractFloat: original training data

• encoded_io_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT} where FT<:AbstractFloat: encoded training data

• encoder_schedule::AbstractVector: Store of the pipeline to encode (/decode) the data

optimize_hyperparameters!(
    emulator::CalibrateEmulateSample.Emulators.Emulator{FT<:AbstractFloat},
    args...;
    kwargs...
) -> Any

Optimizes the hyperparameters in the machine learning tool. Note that some machine learning packages train hyperparameters on construction so this call is not necessary

Emulator(
    machine_learning_tool::CalibrateEmulateSample.Emulators.MachineLearningTool,
    input_output_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT<:AbstractFloat};
    encoder_schedule,
    encoder_kwargs,
    obs_noise_cov,
    mlt_kwargs...
) -> CalibrateEmulateSample.Emulators.Emulator{FT, Vector{Any}} where FT<:AbstractFloat

Constructor of the Emulator object,

Positional Arguments

• machine_learning_tool: the selected machine learning tool object (e.g. Gaussian process / Random feature interface)
• input_output_pairs: the paired input-output data points stored in a PairedDataContainer

Keyword Arguments

• encoder_schedule[=nothing]: the schedule of data encoding/decoding. This will be passed into the method create_encoder_schedule internally. nothing sets sets a default schedule [(decorrelate_sample_cov(), "in_and_out")], or [(decorrelate_sample_cov(), "in"), (decorrelate_structure_mat(), "out")] if an encoder_kwargs has a key :obs_noise_cov. Pass [] for no encoding.
• encoder_kwargs[=NamedTuple()]: a Dict or NamedTuple with keyword arguments to be passed to initialize_and_encode_with_schedule!

Other keywords are passed to the machine learning tool initialization

predict(
    gp::CalibrateEmulateSample.Emulators.GaussianProcess{CalibrateEmulateSample.Emulators.GPJL},
    new_inputs::AbstractArray{FT<:AbstractFloat, 2};
    add_obs_noise_cov,
    mlt_kwargs...
) -> Tuple{Any, Any}

Predict means and covariances in decorrelated output space using Gaussian process models. The use of stored FType and YType to control this method is deprecated, the return covariance is now determined by the predict( kwarg add_obs_noise_cov

predict(
    srfi::CalibrateEmulateSample.Emulators.ScalarRandomFeatureInterface,
    new_inputs::AbstractMatrix;
    multithread,
    add_obs_noise_cov,
    mlt_kwargs...
) -> Tuple{Any, Any}

Prediction of emulator mean at new inputs (passed in as columns in a matrix), and a prediction of the total covariance at new inputs equal to (emulator covariance + noise covariance).

predict(
    vrfi::CalibrateEmulateSample.Emulators.VectorRandomFeatureInterface,
    new_inputs::AbstractMatrix;
    add_obs_noise_cov,
    mlt_kwargs...
) -> Tuple{Any, Any}

Prediction of data observation (not latent function) at new inputs (passed in as columns in a matrix). That is, we add the observational noise into predictions.

predict(
    emulator::CalibrateEmulateSample.Emulators.Emulator{FT<:AbstractFloat},
    new_inputs::AbstractMatrix;
    encode,
    add_obs_noise_cov,
    transform_to_real,
    mlt_kwargs...
) -> Tuple{Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix{FT} where FT<:Real}, Any}

Makes a prediction using the emulator on new inputs (each new inputs given as data columns).

Keyword args

• encode [=nothing]: For the input encoder Eᵢ, and output decoder Dₒ stored in the emulator, we have learnt a predict method method G in the encoded space. Interpret the keyword as follows:
  • nothing : applies Dₒ∘G∘Eᵢ(x) (nothing is encoded) - most common for user interaction
  • "in" : applies Dₒ∘G(z) (the inputs are provided as encoded (z=Eᵢx))
  • "out" : applies G∘Eᵢ(x) (the outputs are returned as encoded)
  • "inandout": applies G(z) (inputs (z=Eᵢx) and outputs are both encoded) - internally called by Sample method
• add_obs_noise_cov[=false]: When returning the prediction covariance, whether to add the observational noise
  • false: Only return the uncertainty given by the machine learning tool - most common for user emulator validation
  • true : Return the sum of emulator and observational uncertainty - internally called by Sample method
• All other kwargs are passed into the machine learning tool.

Return type of N inputs: (in the output space)

• 1-D: mean [1 x N], cov [1 x N]
• p-D: mean [p x N], cov N x [p x p]

predict(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper,
    new_inputs::AbstractMatrix;
    encode,
    add_obs_noise_cov,
    transform_to_real
) -> Tuple{Any, Any}

Makes a prediction using the ForwardMapWrapper on new inputs (each new inputs given as data columns).

Keyword args

• encode [=nothing]: For the output encoder Eₒ, and input decoder Dᵢ stored in the ForwardMapWrapper, we have provided the forward map G in the decoded space. Interpret the keyword as follows:
  • nothing : applies G(x) (nothing is encoded) - most common for user interaction
  • "in" : applies G∘Dᵢ(z) (the inputs are provided as encoded (x=Dᵢz))
  • "out" : applies Eₒ∘G(x) (the outputs are returned as encoded)
  • "inandout": applies Eₒ∘G∘Dᵢ(z) (inputs (x=Dᵢz) and outputs are both encoded) - internally called by Sample method
• add_obs_noise_cov[=false]: When returning the prediction covariance, whether to add the observational noise
  • false: Only return the uncertainty given by the machine learning tool - most common for user emulator validation
  • true : Return the sum of emulator and observational uncertainty - internally called by Sample method
• All other kwargs are passed into the machine learning tool.

Return type of N inputs: (in the output space)

• 1-D: mean [1 x N], cov [1 x N]
• p-D: mean [p x N], cov N x [p x p]

encode_data(
    cc::CalibrateEmulateSample.Utilities.CanonicalCorrelation,
    data::AbstractMatrix
) -> Any

Apply the CanonicalCorrelation encoder, on a columns-are-data matrix

encode_data(
    dd::CalibrateEmulateSample.Utilities.Decorrelator,
    data::AbstractMatrix
) -> Any

Apply the Decorrelator encoder, on a columns-are-data matrix

encode_data(
    es::CalibrateEmulateSample.Utilities.ElementwiseScaler,
    data::AbstractMatrix
) -> Any

Apply the ElementwiseScaler encoder, on a columns-are-data matrix

encode_data(
    encoder_schedule::AbstractVector,
    data::Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix},
    in_or_out::AbstractString
) -> Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix{FT} where FT<:Real}

Encode the new data (a DataContainer, or matrix where data are columns) representing inputs ("in") or outputs ("out"). with the stored and initialized encoder schedule.

decode_data(
    cc::CalibrateEmulateSample.Utilities.CanonicalCorrelation,
    data::AbstractMatrix
) -> Any

Apply the CanonicalCorrelation decoder, on a columns-are-data matrix

decode_data(
    dd::CalibrateEmulateSample.Utilities.Decorrelator,
    data::AbstractMatrix
) -> Any

Apply the Decorrelator decoder, on a columns-are-data matrix

decode_data(
    es::CalibrateEmulateSample.Utilities.ElementwiseScaler,
    data::AbstractMatrix
) -> Any

Apply the ElementwiseScaler decoder, on a columns-are-data matrix

decode_data(
    encoder_schedule::AbstractVector,
    data::Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix},
    in_or_out::AbstractString
) -> Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix{FT} where FT<:Real}

Decode the new data (a DataContainer, or matrix where data are columns) representing inputs ("in") or outputs ("out"). with the stored and initialized encoder schedule.

encode_structure_matrix(
    cc::CalibrateEmulateSample.Utilities.CanonicalCorrelation,
    structure_matrix::Union{LinearAlgebra.UniformScaling, LinearMaps.LinearMap, AbstractMatrix, AbstractVector}
) -> Any

Apply the CanonicalCorrelation encoder to a provided structure matrix

encode_structure_matrix(
    dd::CalibrateEmulateSample.Utilities.Decorrelator,
    structure_matrix::Union{LinearAlgebra.UniformScaling, LinearMaps.LinearMap, AbstractMatrix, AbstractVector}
) -> Any

Apply the Decorrelator encoder to a provided structure matrix. If the structure matrix is a LinearMap, then the encoded structure matrix remains a LinearMap.

encode_structure_matrix(
    es::CalibrateEmulateSample.Utilities.ElementwiseScaler,
    structure_matrix::Union{LinearAlgebra.UniformScaling, LinearMaps.LinearMap, AbstractMatrix, AbstractVector}
) -> Any

Apply the ElementwiseScaler encoder to a provided structure matrix. If the structure matrix is a LinearMap, then the encoded structure matrix remains a LinearMap.

encode_structure_matrix(
    encoder_schedule::AbstractVector,
    structure_mat,
    in_or_out::AbstractString
) -> Any

Encode a new structure matrix in the input space ("in") or output space ("out"). with the stored and initialized encoder schedule.

decode_structure_matrix(
    cc::CalibrateEmulateSample.Utilities.CanonicalCorrelation,
    enc_structure_matrix::Union{LinearAlgebra.UniformScaling, LinearMaps.LinearMap, AbstractMatrix, AbstractVector}
) -> Any

Apply the CanonicalCorrelation decoder to a provided structure matrix

decode_structure_matrix(
    dd::CalibrateEmulateSample.Utilities.Decorrelator,
    enc_structure_matrix::Union{LinearAlgebra.UniformScaling, LinearMaps.LinearMap, AbstractMatrix, AbstractVector}
) -> Any

Apply the Decorrelator decoder to a provided structure matrix. If the structure matrix is a LinearMap, then the encoded structure matrix remains a LinearMap.

decode_structure_matrix(
    es::CalibrateEmulateSample.Utilities.ElementwiseScaler,
    enc_structure_matrix::Union{LinearAlgebra.UniformScaling, LinearMaps.LinearMap, AbstractMatrix, AbstractVector}
) -> Any

Apply the ElementwiseScaler decoder to a provided structure matrix. If the structure matrix is a LinearMap, then the encoded structure matrix remains a LinearMap.

decode_structure_matrix(
    encoder_schedule::AbstractVector,
    structure_mat,
    in_or_out::AbstractString
) -> Any

Decode a new structure matrix in the input space ("in") or output space ("out"). with the stored and initialized encoder schedule.