TOML interface

path_to_ensemble_member(
    base_path::AbstractString,
    iteration::Int64,
    member::Int64;
    pad_zeros
) -> String

Return the file-system path to ensemble member member at the given iteration.

The returned path has the form <base_path>/iteration_<iter>/member_<j>/, with both indices zero-padded to pad_zeros digits.

Arguments

• base_path: root directory where EKP outputs are stored.
• iteration: iteration index of the ensemble update.
• member: one-based ensemble member index.
• pad_zeros: number of digits used for zero-padding (default 3).

get_parameter_distribution(
    param_dict::Dict,
    name::AbstractString
) -> EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution

Construct and return a ParameterDistribution for the parameter name from param_dict.

Arguments

• param_dict: nested dictionary mapping parameter names to sub-dictionaries that each contain "prior" and "constraint" keys.
• name: name of the parameter to build a distribution for.

get_parameter_values(
    param_dict::Dict,
    names;
    return_type
) -> Any

Return parameter values from param_dict, indexed by the names in names.

Arguments

• param_dict: nested dictionary mapping parameter names to sub-dictionaries that each contain a "value" key.
• names: iterable of parameter names to retrieve.
• return_type: "dict" (default) returns a Dict{name => value}; "array" returns a plain vector.

save_parameter_ensemble(
    param_array::Array{FT, 2},
    param_distribution::EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution,
    default_param_data::Dict,
    save_path::AbstractString,
    save_file::AbstractString,
    iteration::Int64;
    pad_zeros,
    apply_constraints
)

Save the parameter ensemble in param_array to TOML files organised by iteration and ensemble member.

Creates <save_path>/iteration_<iter>/member_<j>/ for each member j and writes a TOML file named save_file into each subdirectory. Parameter values are transformed from the unconstrained to the constrained space when apply_constraints is true.

Arguments

• param_array: N_param × N_ens matrix of parameter values in the unconstrained space.
• param_distribution: ParameterDistribution describing the parameters in param_array.
• default_param_data: Dict of default parameters merged with ensemble values before writing.
• save_path: root directory under which iteration and member subdirectories are created.
• save_file: filename for the TOML file written in each member directory.
• iteration: current iteration index, used to name the iteration_<iter> subdirectory.
• pad_zeros: number of digits used for zero-padding directory indices.
• apply_constraints: apply constraints in param_distribution before saving (default true).

save_parameter_samples(
    distribution::EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution,
    default_param_data,
    num_samples,
    save_path;
    save_file,
    rng,
    pad_zeros
)

Sample num_samples draws from distribution and save each as a separate TOML file under save_path.

Arguments

• distribution: ParameterDistribution to sample from.
• default_param_data: Dict of default parameters merged with the sampled values before writing.
• num_samples: number of samples to draw and save.
• save_path: directory under which per-sample TOML files are written.
• save_file: filename to use for each TOML file (default "parameters.toml").
• rng: random-number generator (default MersenneTwister(1234)).
• pad_zeros: number of digits used for zero-padding ensemble-member indices.

get_admissible_parameters(
    param_dict::Dict
) -> Vector{String}

Return the names of all parameters in param_dict that are admissible for calibration.

A parameter is admissible when its sub-dictionary contains a "prior" key whose value is not "fixed", which allows non-UQ parameters to coexist in the same TOML file.

Arguments

• param_dict: nested dictionary mapping parameter names to sub-dictionaries of parameter metadata.

get_regularization(
    param_dict::Dict,
    name::AbstractString
) -> Union{Tuple{Nothing, Nothing}, Tuple{String, Any}}

Return the regularization type and coefficient for parameter name in param_dict.

Returns a tuple (type, value) where type is "L1" or "L2" and value is the corresponding coefficient. Returns (nothing, nothing) when no regularization is specified.

Arguments

• param_dict: nested dictionary mapping parameter names to sub-dictionaries of parameter metadata.
• name: name of the parameter to query.

write_log_file(param_dict::Dict, file_path::AbstractString)

Write param_dict to a TOML file at file_path.

Arguments

• param_dict: nested dictionary mapping parameter names to sub-dictionaries of parameter metadata.
• file_path: path of the TOML file to write.