struct BinnedMeasurement

Fields: * observable::Array{Observable, 1}: Observables that are measured. * values::Array{Float64, 1}: Measured values. * uncertainties::NamedTuple{<:Any, <:Tuple{Vararg{Array{Float64, 1}}}}: Uncertainties of the measurement as NamedTuple. * active::Array{Bool, 1}: Use or exclude bins in fit. Defaults to true for all bins. * bin_names::Array{Symbol, 1}: Suffixes that will be appended to the name of the measurement distribution for the individual bins. Defaults to [_bin1, _bin2, ...].

Constructors:

BinnedMeasurement(
    observable::Array{Observable, 1},
    values::Array{<:Real, 1};
    uncertainties::NamedTuple{<:Any, <:Tuple{Vararg{Union{Vector{Float64}, Vector{Int64}}}}},
    active::Union{Bool, Array{Bool, 1}} = [true for i in 1:length(vals)],
    bin_names::Array{Symbol, 1} = [Symbol("bin$i") for i in 1:length(vals)]
)

BinnedMeasurement(
    observable::Array{Function, 1},
    values::Array{<:Real, 1};
    uncertainties::NamedTuple{<:Any, <:Tuple{Vararg{Union{Vector{Float64}, Vector{Int64}}}}},
    active::Union{Bool, Array{Bool, 1}} = [true for i in 1:length(vals)],
    bin_names::Array{Symbol, 1}
)

struct Correlation

Fields:

• matrix::Array{Float64, 2}: Observables that are measured.
• active::Bool: Use this uncertainty category in fit. Defaults to true.

Constructors:

Correlation(matrix::Array{<:Real, 2}; active::Bool = true)

struct EFTfitterModel

This is the central type for using EFTfitter. It comprises all information necessary for performing an analysis. Only active Measurement and Correlation objects will be considered.

Fields:

• parameters::BAT.NamedTupleDist
• measurements::NamedTuple{<:Any, <:Tuple{Vararg{Measurement}}}
• BinnedMeasurements::NamedTuple{<:Any, <:Tuple{Vararg{BinnedMeasurement}}}
• correlations::NamedTuple{<:Any, <:Tuple{Vararg{Correlation}}}
• nuisances::Union{NamedTuple{<:Any, <:Tuple{Vararg{NuisanceCorrelation}}}, Nothing}

Constructors:

EFTfitterModel(
    parameters::BAT.NamedTupleDist,
    measurements::NamedTuple{<:Any, <:Tuple{Vararg{AbstractMeasurement}}},
    correlations::NamedTuple{<:Any, <:Tuple{Vararg{AbstractCorrelation}}},
    nuisances::Union{NamedTuple{<:Any, <:Tuple{Vararg{NuisanceCorrelation}}}, Nothing} = nothing
)

Examples:

model = EFTfitterModel(parameters, measurements, correlations) # no nuisance correlations

model = EFTfitterModel(parameters, measurements, correlations, nuisances) # with nuisance correlations
)

struct HighestDensityRegion <: AbstractRankingCriterion

Type for specifying the ranking criterion to be the area of the two-dimensional marginal posterior region containing a probability mass p for two certain parameters.

Fields:

• keys::NTuple{2, Symbol}: Names of the parameters that are used for the marginalized regions.
• p::Float64 = 0.9: Probability mass to be enclosed in the smallest interval.
• bins::T = 200: Number of bins for the histograms to calculate interval widths.

Constructors:

HighestDensityRegion(keys::NTuple{2, Symbol}, p=0.9, bins=200)

struct Measurement

Fields:

• observable::Observable: Observable that is measured.
• value::Real;: Measured value.
• uncertainties::NamedTuple{<:Any, <:Tuple{Vararg{Real}}}: Uncertainties of the measurement as NamedTuple.
• active::Bool: Use or exclude measurement in fit. Defaults to true.

Constructors:

Measurement(
    observable::Observable,
    value::Real;
    uncertainties::NamedTuple{<:Any, <:Tuple{Vararg{Real}}},
    active::Bool = true
)

Measurement(
    observable::Function,
    value::Real;
    uncertainties::NamedTuple{<:Any, <:Tuple{Vararg{Real}}},
    active::Bool = true
)

struct MeasurementRanks

Type for the results of the measurement ranking.

Fields:

• names::Vector{Symbol}: Names of the measurements.
• values::Vector{Float64}: Values of the ranking, calculated according to the criterion.
• criterion<:AbstractRankingCriterion: Criterion that was used for ranking.

Constructors:

function MeasurementRanks(
    names::Vector{Symbol}, 
    values::Vector{Float64}, 
    criterion::AbstractRankingCriterion;
    order::Symbol = :values,
    rev::Bool = false
)

Keyword arguments:

• order::Symbol = :values: Specifies how the names and values are sorted. Further options are

:names for alphabetical sorting based on the measurement names or :none for keeping the initial order of measurements.

• rev::Bool=false: Switch to invert the order.

struct NuisanceCorrelation

Fields:

• unc_key::Symbol: Name of uncertainty category.
• meas1::Symbol: Name of first measurement.
• meas2::Symbol: Name of second measurement.
• prior::Distribution: Prior distribution. Accepts the type Distribution and all other types accepted by BAT.NamedTupleDist, e.g. Interval or Real.

Constructors:

NuisanceCorrelation(unc_key::Symbol, meas1::Symbol, meas2::Symbol, prior::Any)

struct Observable

Fields:

• prediction::Function: Function returning the predicted value of the observable as a function of the parameters.
• min::Real: Minimum boundary for values of the observable. Defaults to -Inf.
• max::Real: Maximum boundary for values of the observable. Defaults to Inf.
• weight::Real: Weight of this observable in the combination. Defaults to 1.0.

Constructors:

Observable(
    prediction::Function
    min::Real = -Inf
    max::Real = Inf
    weight::Real = 1.0
)

Prediction(pred::Float64, unc::Float64)

Represents the prediction, i.e. the nominal value and the associated absolute uncertainty, of an observable for a given set of parameters.

Fields

• pred::Float64: The prediction value.
• unc::Float64: The absolute uncertainty associated with the prediction.

Constructors

• Prediction(a::Float64): Constructs a Prediction with a given value a and an uncertainty of 0.0.
• Prediction(a::Tuple{Float64, Float64}): Constructs a Prediction from a tuple where the first element is the prediction value and the second is the uncertainty.
• Prediction(a::Prediction): Identity constructor, returns the input Prediction object.

struct SmallestInterval <: AbstractRankingCriterion

Type for specifying the ranking criterion to be the total width of the one-dimensional marginalized smallest interval containing a probability mass p for a certain parameter.

Fields:

• key::Symbol: Name of the parameter that is used for the marginalized intervals.
• p::Float64 = 0.9: Probability mass to be enclosed in the smallest interval.

Constructors:

SmallestInterval(key::Symbol, p=0.9, bins=200)

struct SumOfSmallestIntervals <: AbstractRankingCriterion

Type for specifying the ranking criterion to be the summed width of all one-dimensional marginalized smallest intervals containing a probability mass p.

Fields:

• p::Float64 = 0.9: Probability mass to be enclosed in the smallest intervals.
• bins::T = 200: Number of bins for the histograms to calculate interval widths.

Constructors:

SumOfSmallestIntervals(p=0.9, bins=200)

struct UncertaintyRanks

Type for the results of the unceertainty ranking.

Fields:

• names::Vector{Symbol}: Names of the uncertainty categories.
• values::Vector{Float64}: Values of the ranking, calculated according to the criterion.
• criterion<:AbstractRankingCriterion: Criterion that was used for ranking.

Constructors:

function UncertaintyRanks(
    names::Vector{Symbol}, 
    values::Vector{Float64}, 
    criterion::AbstractRankingCriterion;
    order::Symbol = :values,
    rev::Bool = false
)

Keyword arguments:

• order::Symbol = :values: Specifies how the names and values are sorted. Further options are

:names for alphabetical sorting based on the uncertainty names or :none for keeping the initial order of uncertainty categories.

• rev::Bool=false: Switch to invert the order.

BLUE(model::EFTfitterModel)

Calculates the best linear unbiased estimator (BLUE) for multiple measurements of the same observable, according to https://www.sciencedirect.com/science/article/pii/0168900288900186.

Note: Works only for an EFTfitterModel where all measurements have the same observable. If this is not the case, an error is thrown.

Returns a NamedTuple with the fields:

• :value: BLUE value
• :unc: BLUE uncertainty
• :weights: Array with the weights for each measurement

Example:

blue = BLUE(model)
println(blue.value, blue.unc, blue.weights)

apply_criterion(criterion<:AbstractRankingCriterion, samples::DensitySampleVector)

Applies the criterion to the samples and returns the corresponding value.

Available ranking criteria:

• SumOfSmallestIntervals(p=0.9): summed width of all one-dimensional marginalized smallest intervals containing p=90% of the posterior probability
• SmallestInterval(key=:C1, p=0.9): width of the one-dimensional marginalized smallest interval of parameter :C1 containing p=90% of the posterior probability.
• `HighestDensityRegion(keys::NTuple{2, Symbol}, p=0.9, bins=200): volume of the highest density regione

cov_to_cor(cov::Array{<:Real, 2})

Convert a covariance matrix cov to a correlation matrix and a vector of uncertainty values.

Returns a matrix and a vector. Throws a warning when the covariance matrix is not positive definite.

Example:

cor, unc = cov_to_cor(cov)

function criterion_value(
    criterion::AbstractRankingCriterion,
    model::EFTfitterModel;
    sampling_algorithm::BAT.AbstractSamplingAlgorithm=MCMCSampling()
)

Computes the value of the criterion for the model using the sampling_algorithm.

Available ranking criteria:

• SmallestIntervalsSum(p=0.9): summed width of all one-dimensional marginalized smallest intervals containing p=90% of the posterior probability
• SmallestInterval(key=:C1, p=0.9): width of the one-dimensional marginalized smallest interval of parameter key=:C1 containing p=90% of the posterior probability

get_correlations(m::EFTfitterModel)

Returns a NamedTuple with the Correlationss in the EFTfitterModel.

get_crossmatrix(mus::ModelUncertaintiesIndicator, ncs::NuisanceCorrelationsIndicator, m::EFTfitterModel, weights)

For all other models (i.e., covariance matrix is changed during sampling), this function computes the cross matrix without including observable weights in the matrix.

get_crossmatrix(mus::NoModelUncertainties, ncs::NoNuissanceCorrelations, m::EFTfitterModel, weights)

For models without model uncertainties and without nuisance correlations, this function computes the cross matrix using the observable weights included in the matrix.

get_measurement_distributions(m::EFTfitterModel)

Returns a NamedTuple with the BinnedMeasurements in the EFTfitterModel.

get_measurements(m::EFTfitterModel)

Returns a NamedTuple with the Measurements in the EFTfitterModel.

get_nuisance_correlations(m::EFTfitterModel)

Returns a NamedTuple with the NuisanceCorrelations in the EFTfitterModel.

get_observables(m::EFTfitterModel)

Returns a NamedTuple with the Observables in the EFTfitterModel. Note: The upper and lower limits are ignored and for each unique Functions only one Observable is returned.

get_parameters(m::EFTfitterModel)

Returns model parameters.

get_smallest_interval_edges(
    samples::DensitySampleVector, 
    key::Union{Symbol, Real}, 
    p::Real; 
    bins=200,
    atol=0.0)

Calculates the edges of the smallest intervals containing the fraction p of the probability of the marginal distribution of parameter key.

Returns a NamedTuple with the keys lower and upper which both contain Vectors with the corresponding bin edges. Keywords:

• bins=200: The number of bins used fpr calculating the intervals and edges.
• atol=0.0: Intervals are joined together when they are seperated by less than this value.

function measurement_models(model::EFTfitterModel)

Creates a Vector of EFTfitterModel where always one of the initially active measurements is deactivated at a time. Returns a Vector of EFTfitterModel and a Vector of Symbol with the names of the currently deactivated measurement.

rank_measurements(
    model::EFTfitterModel;
    sampling_algorithm::BAT.AbstractSamplingAlgorithm = MCMCSampling(),
    criterion = SmallestIntervalsSum(p=0.9),
    order = :values,
    rev = true
)

Computes a ranking of the individual measurement in the EFTfitterModel based on a certain ranking criterion by performing the sampling according to the specified sampling_algorithm. Returns a MeasurementRank object.

By default, the summed width of all one-dimensional marginalized smallest intervals containing 90% of the posterior probability is used as the ranking criterion. The measurements are ranked by the relative increase of this value.

Available ranking criteria:

• SmallestIntervalsSum(p=0.9): summed width of all one-dimensional marginalized smallest intervals containing p=90% of the posterior probability
• SmallestInterval(key=:C1, p=0.9): width of the one-dimensional marginalized smallest interval of parameter :C1 containing p=90% of the posterior probability.

rank_uncertainties(
    model::EFTfitterModel;
    sampling_algorithm::BAT.AbstractSamplingAlgorithm = MCMCSampling(),
    criterion = SmallestIntervalsSum(p=0.9),
    order = :values,
    rev = true
)

Computes a ranking of the types of uncertainty in the EFTfitterModel based on a certain ranking criterion by performing the sampling according to the specified sampling_algorithm. Returns a MeasurementRank object.

By default, the summed width of all one-dimensional marginalized smallest intervals containing 90% of the posterior probability is used as the ranking criterion. The uncertainty types are ranked by the relative decrease of this value.

Available ranking criteria:

• SmallestIntervalsSum(p=0.9): summed width of all one-dimensional marginalized smallest intervals containing p=90% of the posterior probability
• SmallestInterval(key=:C1, p=0.9): width of the one-dimensional marginalized smallest interval of parameter key=:C1 containing p=90% of the posterior probability

run_speed_test(m::EFTfitterModel; matrix_types=[Matrix, sparse, Symmetric], vs=rand(m.parameters, 10), verbose=true)

Test different data types for the (inverse) covariance matrix to find the optimal one in terms of speed.

Arguments

• m::EFTfitterModel: The model for which the speed test is performed.

Keyword Arguments

• matrix_types::Vector{DataType}=[Matrix, sparse, Symmetric]: The types of matrices to be tested.
• vs: Sample values to test. Default is 10 random samples from m.parameters.
• verbose::Bool=true: If true, informative messages and results are displayed during the test.

Returns

• A table summarizing the test results, showing minimum computation times, memory allocations, etc., for each matrix type.
• A list of benchmark results for each matrix type.

Notes

The function benchmarks the provided matrix types using the given sample values and returns recommendations based on minimum computation times. The recommended matrix type is the one with the shortest minimum time.

Example

julia> tbl, benchmarks = run_speed_test(model)

to_correlation_matrix(
    measurements::NamedTuple{<:Any, <:Tuple{Vararg{AbstractMeasurement}}},
    correlations::Tuple{Symbol,Symbol, Union{<:Real, Array{<:Real, 2}}}...
)

Returns a `Matrix{Float64}` as the correlation matrix for the measurements with all diagonal-elements being unity.
The correlations are specified by passing tuples of two `Symbols` (the keys of the `Measurements`) with a value or matrix for the correlation coefficients.
If the matrix is not positive-definite, a warning is shown but the matrix is still returned.

Example:
```julia
dist_corr = [1.0 0.5 0.0;
             0.5 1.0 0.0;
             0.0 0.0 1.0]

another_corr_matrix = to_correlation_matrix(
    measurements,
    (:Meas1, :Meas2, 0.4), 
    (:Meas1, :MeasDist, 0.1), 
    (:MeasDist, :MeasDist, dist_corr), 
    (:MeasDist_bin2, :MeasDist_bin3, 0.3),
)
```

function uncertainty_models(model::EFTfitterModel)

Creates a Vector of EFTfitterModel where always one of the initially active uncertainty types is deactivated at a time. Returns a Vector of EFTfitterModel and a Vector of Symbol with the names of the currently deactivated uncertainty types.