Common Functions

convertθnames_toindices(model::LikelihoodModel, 
    θnames_to_convert::Vector{<:Symbol})

Converts a vector of symbols representing parameters in model to a vector of each symbol's corresponding index in model.core.θnames.

convertθnames_toindices(model::LikelihoodModel, 
    θnames_to_convert::Union{Vector{Vector{Symbol}}, Vector{Tuple{Symbol, Symbol}}})

Converts a vector of vectors or tuples containing symbols representing parameters in model to a vector of vectors containing each symbol's corresponding index in model.core.θnames.

ll_correction(model::LikelihoodModel, 
    profile_type::AbstractProfileType, 
    ll::Float64)

If a profile_type is LogLikelihood(), it corrects ll such that an input log-likelihood value (which has value of zero at the MLE) will now have a value of model.core.maximisedmle at the MLE. Otherwise, a copy of ll is returned, as both ellipse approximation profile types have a log-likelihood value of 0.0 at the MLE.

get_target_loglikelihood(model::LikelihoodModel, 
    confidence_level::Float64, 
    profile_type::AbstractProfileType, 
    dof::Int)

Returns the target log-likelihood / threshold at a confidence level and degrees of freedom, dof (typically the number of interest parameters OR the number of model parameters), required for a particular profile_type to be in the confidence set. Uses LikelihoodBasedProfileWiseAnalysis.ll_correction.

get_consistent_tuple(model::LikelihoodModel, 
    confidence_level::Float64, 
    profile_type::AbstractProfileType, 
    dof::Int)

Returns a tuple containing the values needed for log-likelihood evaluation and finding function zeros, including the target log-likelihood, number of model parameters, log-likelihood function to use and data tuple for evaluating the log-likelihood function.

desired_df_subset(df::DataFrame, 
    num_used_rows::Int, 
    confidence_levels::Union{Float64, Vector{<:Float64}},
    dofs::Union{Int, Vector{<:Int}}, 
    sample_types::Vector{<:AbstractSampleType}; 
    sample_dimension::Int=0, 
    regions::Union{Real, Vector{<:Real}}=Float64[],
    for_prediction_generation::Bool=false, 
    for_prediction_plots::Bool=false, 
    include_higher_confidence_levels::Bool=false)

Returns a view of df that includes only valid rows ∈ 1:num_used_rows, and rows that contain all of the values specified within function arguments. For dimensional samples.

Arguments

• df: a DataFrame - model.dim_samples_df.
• num_used_rows: the number of valid rows in df - model.num_dim_samples.
• confidence_levels: a vector of confidence levels or a Float64 of a single confidence level. If empty, all confidence levels in df are allowed. Otherwise, if include_higher_confidence_levels == true and confidence_levels is a Float64, all confidence levels greater than or equal to confidence_levels are allowed. Else, only matching confidence levels in df are allowed.
• dofs: a vector of integer degrees of freedom or a Int of a single degree of freedom. If empty, all degrees of freedom for dimensional profiles are allowed. Otherwise, only matching degrees of freedom in df are allowed.
• sample_types: a vector of AbstractSampleType structs. If empty, all sample types in df are allowed. Otherwise, only matching sample types in df are allowed.

Keyword Arguments

• sample_dimension: an integer greater than or equal to 0; if non-zero only matching dimensions of interest parameters in df are allowed, otherwise all are allowed. Default is 0.
• regions: a vector of Real numbers ∈ [0, 1] or a single Real number specifying the regions in df that are allowed. If empty, all regions are allowed. Otherwise, only matching regions in df are allowed. Default is Float64[].
• for_prediction_generation: a boolean specifying whether only rows which have not had predictions evaluated are allowed. As predictions do not need to be generated for rows which already have them evaluated.
• for_prediction_plots: a boolean specifying whether only rows which have had predictions evaluated are allowed. As prediction plots can only include rows which have evaluated predictions.
• include_higher_confidence_levels: a boolean specifying whether all confidence levels greater than or equal to confidence_levels are allowed. Useful for prediction plots as a dimensional sample can be evaluated at a high confidence level (e.g. 0.95) and then used at a lower confidence level (e.g. 0.9), extracting only the sample points that are in the 0.9 confidence set.

desired_df_subset(df::DataFrame, 
    num_used_rows::Int, 
    θs_of_interest::Vector{<:Int}, 
    confidence_levels::Union{Float64, Vector{<:Float64}}, 
    dofs::Union{Int, Vector{<:Int}}, 
    profile_types::Vector{<:AbstractProfileType}; 
    regions::Union{Real, Vector{<:Real}}=Float64[],
    for_points_in_interval::Tuple{Bool,Int,Real}=(false,0,0), 
    for_prediction_generation::Bool=false, 
    for_prediction_plots::Bool=false)

Returns a view of df that includes only valid rows ∈ 1:num_used_rows, and rows that contain all of the values specified within function arguments. For univariate profiles.

Arguments

• df: a DataFrame - model.uni_profiles_df.
• num_used_rows: the number of valid rows in df - model.num_uni_profiles.
• confidence_levels: a vector of confidence levels or a Float64 of a single confidence level. If empty, all confidence levels in df are allowed. Otherwise, only matching confidence levels in df are allowed.
• dofs: a vector of integer degrees of freedom or a Int of a single degree of freedom. If empty, all degrees of freedom for univariate profiles are allowed. Otherwise, only matching degrees of freedom in df are allowed.
• profile_types: a vector of AbstractProfileType structs. If empty, all profile types in df are allowed. Otherwise, only matching profile types in df are allowed.

Keyword Arguments

• regions: a vector of Real numbers ∈ [0, 1] or a single Real number specifying the regions in df that are allowed. If empty, all regions are allowed. Otherwise, only matching regions in df are allowed. Default is Float64[].
• for_points_in_interval: a tuple used for only extracting the rows that need to have points in the confidence interval evaluated by get_points_in_intervals!. Default is (false, 0, 0).
• for_prediction_generation: a boolean specifying whether only rows which have not had predictions evaluated are allowed. As predictions do not need to be generated for rows which already have them evaluated.
• for_prediction_plots: a boolean specifying whether only rows which have had predictions evaluated are allowed. As prediction plots can only include rows which have evaluated predictions.

desired_df_subset(df::DataFrame, 
    num_used_rows::Int, 
    θs_of_interest::Vector{Tuple{Int,Int}}, 
    confidence_levels::Union{Float64, Vector{<:Float64}}, 
    dofs::Union{Int, Vector{<:Int}}, 
    profile_types::Vector{<:AbstractProfileType}, 
    methods::Vector{<:AbstractBivariateMethod}=AbstractBivariateMethod[];
    regions::Union{Real, Vector{<:Real}}=Float64[], 
    for_prediction_generation::Bool=false, 
    for_prediction_plots::Bool=false, 
    include_lower_confidence_levels::Bool=false)

Returns a view of df that includes only valid rows ∈ 1:num_used_rows, and rows that contain all of the values specified within function arguments. For bivariate profiles.

Arguments

• df: a DataFrame - model.biv_profiles_df.
• num_used_rows: the number of valid rows in df - model.num_biv_profiles.
• confidence_levels: a vector of confidence levels or a Float64 of a single confidence level. If empty, all confidence levels in df are allowed. Otherwise, if include_lower_confidence_levels == true and confidence_levels is a Float64, all confidence levels less than or equal to confidence_levels are allowed. Else, only matching confidence levels in df are allowed.
• dofs: a vector of integer degrees of freedom or a Int of a integer degree of freedom. If empty, all degrees of freedom for bivariate profiles are allowed. Otherwise, only matching degrees of freedom in df are allowed.
• profile_types: a vector of AbstractProfileType structs. If empty, all profile types in df are allowed. Otherwise, only matching profile types in df are allowed.
• methods: a vector of AbstractBivariateMethod structs. If empty, all methods in df are allowed. Otherwise, only methods of the same type in df are allowed.

Keyword Arguments

• regions: a vector of Real numbers ∈ [0, 1] or a single Real number specifying the regions in df that are allowed. If empty, all regions are allowed. Otherwise, only matching regions in df are allowed. Default is Float64[].
• for_prediction_generation: a boolean specifying whether only rows which have not had predictions evaluated are allowed. As predictions do not need to be generated for rows which already have them evaluated.
• for_prediction_plots: a boolean specifying whether only rows which have had predictions evaluated are allowed. As prediction plots can only include rows which have evaluated predictions.
• remove_combined_method: a boolean specifiying whether rows with method of type CombinedBivariateMethod should be removed. Needed by combine_bivariate_boundaries! to ensure that combined boundaries are not removed from df.
• include_lower_confidence_levels: a boolean specifying whether all confidence levels less than or equal to confidence_levels are allowed. Useful for prediction plots if a given set of bivariate profiles has few internal points evaluated, meaning some information about predictions may be missing. Bivariate profiles at lower confidence levels are by definition inside the desired confidence profile and may provide additional information on predictions.

variablemappingranges(num_pars::T, index::T) where T <: Int

Returns two tuples of ranges that map variables in nuisance parameter space (ω) to their corresponding indexes in parameter space (θ) given an interest parameter ψ at index.

variablemappingranges(num_pars::T, index1::T, index2::T) where T <: Int

Returns two tuples of ranges that map variables in nuisance parameter space (ω) to their corresponding indexes in parameter space (θ), given interest parameters ψ at index1 and index2 and index1 < index2.

variablemapping!(θ::Union{Vector, SubArray}, ω::Union{Vector, SubArray}, θranges::Tuple{T, T}, ωranges::Tuple{T, T}) where T <: UnitRange

Modifies the array θ in place, mapping the variable values in the nuisance parameter array ω to their corresponding indexes in the parameter array θ, where the ranges are determined by LikelihoodBasedProfileWiseAnalysis.variablemappingranges. For one interest parameter.

variablemapping!(θ::Union{Vector, SubArray}, ω::Union{Vector, SubArray}, θranges::Tuple{T,T,T}, ωranges::Tuple{T,T,T})) where T <: UnitRange

Modifies the array θ in place, mapping the variable values in the nuisance parameter array ω to their corresponding indexes in the parameter array θ, where the ranges are determined by LikelihoodBasedProfileWiseAnalysis.variablemappingranges. For two interest parameters.

boundsmapping!(newbounds::Vector, bounds::AbstractVector, index::Int)

Modifies newbounds in place, mapping all the values in bounds in order into newbounds with the exception of the value at index, which is the interest parameter.

boundsmapping!(newbounds::Vector, bounds::AbstractVector, index1::Int, index2::Int)

Modifies newbounds in place, mapping all the values in bounds in order into newbounds with the exception of the values at index1 and index2, which are the interest parameters and index1 < index2.

init_nuisance_parameters(model::LikelihoodModel, index::Int)

Initialises the lower and upper bounds, and initial guess for nuisance parameters using LikelihoodBasedProfileWiseAnalysis.boundsmapping! and ranges that map variables between nuisance parameter and parameter space using LikelihoodBasedProfileWiseAnalysis.variablemappingranges, given an interest parameter at index. The initial guess for nuisance parameters is their corresponding value at the maximum likelihood estimate (model.core.θmle).

init_nuisance_parameters(model::LikelihoodModel, index::Int)

Initialises the lower and upper bounds, and initial guess for nuisance parameters using LikelihoodBasedProfileWiseAnalysis.boundsmapping! and ranges that map variables between nuisance parameter and parameter space using LikelihoodBasedProfileWiseAnalysis.variablemappingranges, given interest parameters at index1 and index2 where index1 < index2. The initial guess for nuisance parameters is their corresponding value at the maximum likelihood estimate (model.core.θmle).

init_nuisance_parameters(model::LikelihoodModel, index::Int)

Initialises the lower and upper bounds, and initial guess for nuisance parameters and indices that map variables between parameter and nuisance parameter space, given interest parameters in θindices. The initial guess for nuisance parameters is their corresponding value at the maximum likelihood estimate (model.core.θmle).

correct_θbounds_nuisance(m::LikelihoodModel,
    θlb_nuisance::AbstractVector{<:Float64},
    θub_nuisance::AbstractVector{<:Float64})

Makes sure that nuisance parameter bounds contain the MLE parameter values - if not, set that part of the nuisance parameter bound to the bounds in model.core.