Bivariate Functions

bivariateψ!(ψ::Real, p::NamedTuple)

Given a log-likelihood function (p.consistent.loglikefunction) which is bounded in parameter space and may be an ellipse approximation, this function finds the values of the nuisance parameters ω that optimise the function fixed values of the interest parameters p.ψ_x[1] and ψ and returns the log-likelihood value minus the confidence boundary target threshold. The returned function value will be zero at the locations of the approximate confidence boundary for p.ψ_x[1] and ψ. Nuisance parameter values are stored in the NamedTuple p at p.ω_opt. Used by Fix1AxisMethod.

bivariateψ_vectorsearch!(ψ::Real, p::NamedTuple)

Given a log-likelihood function (p.consistent.loglikefunction) which is bounded in parameter space and may be an ellipse approximation, this function finds the values of the nuisance parameters ω that optimise the function fixed values of the interest parameters ψxy = p.pointa + ψ*p.uhat and returns the log-likelihood value minus the confidence boundary target threshold. The returned function value will be zero at the locations of the approximate confidence boundary for ψxy. Nuisance parameter values are stored in the NamedTuple p at p.ω_opt. Used by AbstractBivariateVectorMethod.

bivariateψ_ellipse_analytical(ψ::Real, p::NamedTuple)

Returns the approximated log-likelihood value minus the confidence boundary target threshold, given an analytic ellipse approximation of a log-likelihood function (LikelihoodBasedProfileWiseAnalysis.analytic_ellipse_loglike) which is unbounded in parameter space, for values of the interest parameters p.ψ_x[1] and ψ. The returned function value will be zero at the locations of the approximate confidence boundary for p.ψ_x[1] and ψ, which correspond to locations found by LikelihoodBasedProfileWiseAnalysis.AnalyticalEllipseMethod. Used by Fix1AxisMethod.

bivariateψ_ellipse_analytical_vectorsearch(ψ::Real, p::NamedTuple)

Returns the approximated log-likelihood value minus the confidence boundary target threshold, given an analytic ellipse approximation of a log-likelihood function (LikelihoodBasedProfileWiseAnalysis.analytic_ellipse_loglike) which is unbounded in parameter space, for values of the interest parameters ψxy = p.pointa + ψ*p.uhat. The returned function value will be zero at the locations of the approximate confidence boundary for ψxy = p.pointa + ψ*p.uhat, which correspond to locations found by LikelihoodBasedProfileWiseAnalysis.AnalyticalEllipseMethod. Used by AbstractBivariateVectorMethod.

bivariateψ_ellipse_unbounded(ψ::Vector, p::NamedTuple)

Given an ellipse approximation of a log-likelihood function (LikelihoodBasedProfileWiseAnalysis.ellipse_loglike) which is unbounded in parameter space, this function finds the values of the nuisance parameters ω that optimise the function at fixed values of the two interest parameters in ψ and returns the approximated log-likelihood value minus the confidence boundary target threshold. The returned function value will be zero at the locations of the approximate confidence boundary for ψ, which correspond to the locations found by LikelihoodBasedProfileWiseAnalysis.AnalyticalEllipseMethod. Nuisance parameter values are stored in the NamedTuple p.

findpointonbounds(model::LikelihoodModel, 
    internalpoint::Vector{<:Float64}, 
    direction_πradians::Float64, 
    cosDir::Float64, 
    sinDir::Float64, 
    ind1::Int, 
    ind2::Int,
    returnboundindex::Bool=false)

Given an internalpoint and direction in radians (defined as anticlockwise rotation from the x-axis) from this point, returns the first point on the 2D bounds encountered in that direction from internalpoint. Returns which bound the point is on if returnboundindex = true.

findpointonbounds(model::LikelihoodModel, 
    internalpoint::Vector{<:Float64}, 
    direction_πradians::Float64, 
    cosDir::Float64, 
    sinDir::Float64, 
    ind1::Int, 
    ind2::Int,
    returnboundindex::Bool=false)

Alternate method for LikelihoodBasedProfileWiseAnalysis.findpointonbounds which specifies the direction from internalpoint as a vector rather than an angle in radians.

add_biv_profiles_rows!(model::LikelihoodModel, num_rows_to_add::Int)

Adds num_rows_to_add rows to model.biv_profiles_df.

set_biv_profiles_row!(model::LikelihoodModel, 
    row_ind::Int, 
    θcombination::Tuple{Int, Int},
    not_evaluated_internal_points::Bool, 
    not_evaluated_predictions::Bool,
    boundary_not_ordered::Bool,
    confidence_level::Float64, 
    dof::Int,
    profile_type::AbstractProfileType,
    method::AbstractBivariateMethod, 
    num_points::Int)

Sets the columns of row row_ind of model.biv_profiles_df to contain the relevant info about a just conducted profile. model.biv_profiles_dict contains the profile for row row_ind at key row_ind.

get_bivariate_opt_func(profile_type::AbstractProfileType, method::AbstractBivariateMethod)

Returns the correct bivariate optimisation function used to find the optimal values of nuisance parameters at a set of interest parameters for the profile_type log-likelihood function. The optimisation function returns the value of the profile_type log-likelihood function as well as finding the optimal nuisance parameters and saving these in one of it's inputs.

get_ωs_bivariate_ellipse_analytical!(boundary,
    num_points::Int,
    consistent::NamedTuple, 
    ind1::Int, 
    ind2::Int, 
    num_pars::Int,
    initGuess::Vector{<:Float64}, 
    θranges::Tuple{T, T, T}, 
    ωranges::Tuple{T, T, T},
    optimizationsettings::OptimizationSettings,
    samples_all_pars::Union{Missing, Matrix{Float64}}=missing) where T<:UnitRange

Determines the nuisance parameters for a EllipseApproxAnalytical boundary profile by optimising over the unbounded ellipse approximation of the log-likelihood centred at the MLE. At higher confidence levels, where the ellipse approximation is less accurate, it is likely that predictions produced by running the model with these optimised nuisance parameters will be unrealistic and/or the parameters themselves may be infeasible for the model.

bivariate_confidenceprofile(bivariate_optimiser::Function,
    model::LikelihoodModel, 
    num_points::Int,
    confidence_level::Float64,
    consistent::NamedTuple,
    ind1::Int,
    ind2::Int,
    dof::Int,
    profile_type::AbstractProfileType,
    method::AbstractBivariateMethod,
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    mle_targetll::Float64,
    save_internal_points::Bool,
    find_zero_atol::Real,
    optimizationsettings::OptimizationSettings,
    channel::RemoteChannel)

Returns a BivariateConfidenceStruct containing the num_points boundary points and internal points (if save_internal_points=true) for the specified combination of parameters ind1 and ind2, and profile_type at confidence_level using method. Calls the desired method. Called by bivariate_confidenceprofiles!.

Base.merge(a::BivariateConfidenceStruct, b::BivariateConfidenceStruct)

Specifies how to merge two variables with type BivariateConfidenceStruct.

minimum_perimeter_polygon!(points::Array{<:Real,2})

Given a set of N points that define a boundary polygon in a 2 row, N column array, solve a minimum perimeter polygon TSP problem, reorder these points in place and return the path used (vertices in order of visitation). Uses TravelingSalesmanHeuristics.jl.

findNpointpairs_radialMLE!(p::NamedTuple, 
    bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    ind1::Int, 
    ind2::Int,
    mle_targetll::Float64,
    save_internal_points::Bool,
    biv_opt_is_ellipse_analytical::Bool, 
    ellipse_confidence_level::Float64,
    dof::Int,
    ellipse_start_point_shift::Float64,
    ellipse_sqrt_distortion::Float64,
    optimizationsettings::OptimizationSettings,
    use_threads::Bool)

Implementation of finding pairs of points that bracket the bivariate confidence boundary for RadialMLEMethod.

Search directions from the MLE point are given by points placed on a ellipse approximation around the point using generate_N_clustered_points from EllipseSampling.jl.

findNpointpairs_radialMLE!(p::NamedTuple, 
    bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    ind1::Int, 
    ind2::Int,
    biv_opt_is_ellipse_analytical::Bool, 
    radial_start_point_shift::Float64,
    optimizationsettings::OptimizationSettings,
    use_threads::Bool)

Implementation of finding pairs of points that bracket the bivariate confidence boundary for IterativeBoundaryMethod, searching radially from the MLE point for points on the bounds, in search directions similar to those used by RadialRandomMethod. If a point on the bounds is inside the confidence boundary, that point will represent the boundary in that search direction.

Search directions are given by distorting uniformly spaced anticlockwise angles on a circle to angles on an ellipse representative of the relative magnitude of each parameter. If the magnitude of a parameter is a NaN value (i.e. either bound is Inf), then the relative magnitude is set to 1.0, as no information is known about its magnitude.

edge_length(boundary, inds1, inds2, relative_magnitude)

Euclidean distance between two vertices (length of an edge), scaled by the relative magnitude of parameters, so that each dimension has roughly the same weight.

internal_angle_from_pi!(vertex_internal_angle_objs, 
    indexes::UnitRange, 
    boundary, 
    adjacent_vertices)

The magnitude the internal angle in radians between two adjacent edges is from pi radians - i.e. how far away the two edges are from representing a straight boundary. If a boundary is straight then the objective is 0.0 radians, whereas if the boundary has an internal angle of pi/4 radians (45 deg) the objective is pi*3/4 (135 deg). Computes this by considering the angle between the two vectors that can be used to represent the edges (using AngleBetweenVectors.jl).

internal_angle_from_pi(index::Int, boundary, edge_clock, edge_anti, relative_magnitude)

Alternate method of LikelihoodBasedProfileWiseAnalysis.internal_angle_from_pi for the internal angle at only one vertex.

iterativeboundary_init(bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    p::NamedTuple, 
    ind1::Int, 
    ind2::Int,
    initial_num_points::Int,
    biv_opt_is_ellipse_analytical::Bool,
    radial_start_point_shift::Float64,
    ellipse_sqrt_distortion::Float64,
    ellipse_confidence_level::Float64,
    use_ellipse::Bool,
    save_internal_points::Bool,
    find_zero_atol::Real, 
    optimizationsettings::OptimizationSettings,
    use_threads::Bool,
    channel::RemoteChannel)

Finds the initial boundary of IterativeBoundaryMethod, containing initial_num_points, returning it and initialised parameter values.

If initial_num_points is equal to num_points then the desired number of boundary points have been found. If use_ellipse = true the boundary will be equivalent to the boundary found by RadialMLEMethod with the same parameter settings - it's value informs the method of LikelihoodBasedProfileWiseAnalysis.findNpointpairs_radialMLE! used.

newboundarypoint!(p::NamedTuple, 
    point_is_on_bounds::BitVector, 
    edge_anti_on_bounds::BitVector, 
    boundary::Matrix{Float64}, 
    boundary_all::Matrix{Float64}, 
    internal_all::Matrix{Float64}, 
    ll_values::Vector{Float64}, 
    internal_count::Int,
    bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    edge_anti::Vector{Int}, 
    num_vertices::Int, 
    ind1::Int, 
    ind2::Int,
    biv_opt_is_ellipse_analytical::Bool, 
    ve1::Int, 
    ve2::Int, 
    relative_magnitude::Float64, 
    bound_warning::Bool, 
    save_internal_points::Bool)

Method for trying to find a new boundary point for IterativeBoundaryMethod given a starting boundary polygon. Returns whether finding a new point was successful.

heapupdates_success!(edge_heap::TrackingHeap,
    angle_heap::TrackingHeap, 
    edge_clock::Vector{Int},
    edge_anti::Vector{Int},
    point_is_on_bounds::BitVector,
    edge_anti_on_bounds::BitVector,
    boundary::Matrix{Float64},
    num_vertices::Int,
    vi::Int, 
    adj_vertex::Int,
    relative_magnitude::Float64,
    clockwise_from_vi=false)

If finding a new boundary point for IterativeBoundaryMethod was successful, update the datastructures that represent the boundary as required.

heapupdates_failure!(edge_heap::TrackingHeap,
    angle_heap::TrackingHeap, 
    edge_clock::Vector{Int},
    edge_anti::Vector{Int},
    point_is_on_bounds::BitVector,
    boundary::Matrix{Float64},
    num_vertices::Int,
    ve1::Int,
    ve2::Int,
    opposite_edge_ve1::Int,
    model::LikelihoodModel,
    ind1::Int, 
    ind2::Int,
    relative_magnitude::Float64)

If finding a new boundary point for IterativeBoundaryMethod was not successful, update the datastructures that represent the boundary as required. Failure means it is likely that multiple level sets exist. If so, break the edges of the candidate point and opposite_edge_ve1 and reconnect the vertexes such that there are now multiple boundary polygons.

If there are only one or two points on one of these boundary polygons, display an info message as no additional points can be found from the method directly.

If there are three or more points on these boundary polygons, then there should be no problems finding other parts of these polygons.

If the largest polygon has less than three points the method will display a warning message and terminate, returning the boundary found up until then.

polygon_break_and_rejoin!(edge_clock::Vector{Int},
    edge_anti::Vector{Int},
    ve1::Int,
    ve2::Int,
    opposite_edge_ve1::Int,
    opposite_edge_ve2::Int,
    model::LikelihoodModel,
    ind1::Int, 
    ind2::Int)

If finding a new boundary point was not successful, breaks and rejoins the boundary polygon as required to remove the vertices from the main polygon that are likely to be on a distinct level set (boundary).

Display an info message if only one vertex was seperated, as that vertex can no longer be used to find additional points within the algorithm.

bivariate_confidenceprofile_iterativeboundary(bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    consistent::NamedTuple, 
    ind1::Int, 
    ind2::Int,
    dof::Int,
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    initial_num_points::Int,
    angle_points_per_iter::Int,
    edge_points_per_iter::Int,
    radial_start_point_shift::Float64,
    ellipse_sqrt_distortion::Float64,
    ellipse_confidence_level::Float64,
    use_ellipse::Bool,
    mle_targetll::Float64,
    save_internal_points::Bool,
    find_zero_atol::Real, 
    optimizationsettings::OptimizationSettings,
    use_threads::Bool,
    channel::RemoteChannel)

Implementation of IterativeBoundaryMethod.

generatepoint(model::LikelihoodModel, ind1::Int, ind2::Int)

Generates a uniform random x and y value between the lower and upper bounds for the parameters at ind1 and ind2.

findNpointpairs_simultaneous!(p::NamedTuple, 
    bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    ind1::Int, 
    ind2::Int,
    mle_targetll::Float64,
    save_internal_points::Bool,
    biv_opt_is_ellipse_analytical::Bool,
    min_proportion_unique::Real,
    use_MLE_point::Bool,
    optimizationsettings::OptimizationSettings)

Implementation of finding pairs of points that bracket the bivariate confidence boundary for SimultaneousMethod.

find_m_spaced_radialdirections(num_directions::Int; start_point_shift::Float64=rand())

Returns num_directions equally spaced anticlockwise angles between 0 and 2pi which are shifted by start_point_shift * 2.0 / convert(Float64, num_directions).

findNpointpairs_radialrandom!(p::NamedTuple, 
    bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    num_directions::Int, 
    ind1::Int, 
    ind2::Int,
    mle_targetll::Float64,
    save_internal_points::Bool,
    biv_opt_is_ellipse_analytical::Bool, 
    use_MLE_point::Bool,
    optimizationsettings::OptimizationSettings)

Implementation of finding pairs of points that bracket the bivariate confidence boundary for RadialRandomMethod.

Distorts uniformly spaced anticlockwise angles on a circle using LikelihoodBasedProfileWiseAnalysis.find_m_spaced_radialdirections to angles on an ellipse representative of the relative magnitude of each parameter. If the magnitude of a parameter is a NaN value (i.e. either bound is Inf), then the relative magnitude is set to 1.0, as no information is known about its magnitude.

bivariate_confidenceprofile_vectorsearch(bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    consistent::NamedTuple, 
    ind1::Int, 
    ind2::Int,
    dof::Int,
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    mle_targetll::Float64,
    save_internal_points::Bool,
    find_zero_atol::Real, 
    optimizationsettings::OptimizationSettings,
    use_threads::Bool,
    channel::RemoteChannel;
    num_radial_directions::Int=0,
    min_proportion_unique::Real=1.0,
    use_MLE_point::Bool=false,
    ellipse_confidence_level::Float64=-1.0,
    ellipse_start_point_shift::Float64=0.0,
    ellipse_sqrt_distortion::Float64=0.0)

Implementation of [AbstractBivariateVectorMethod] boundary search methods SimultaneousMethod, RadialMLEMethod and RadialRandomMethod.

findNpointpairs_fix1axis!(p::NamedTuple, 
    bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    i::Int, 
    j::Int,
    mle_targetll::Float64,
    save_internal_points::Bool,
    biv_opt_is_ellipse_analytical::Bool,
    channel::RemoteChannel)

Implementation of finding pairs of points that bracket the bivariate confidence boundary for Fix1AxisMethod.

bivariate_confidenceprofile_fix1axis(bivariate_optimiser::Function, 
    model::LikelihoodModel, 
    num_points::Int, 
    consistent::NamedTuple, 
    ind1::Int, 
    ind2::Int,
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    mle_targetll::Float64,
    save_internal_points::Bool, 
    find_zero_atol::Real, 
    optimizationsettings::OptimizationSettings,
    use_threads::Bool,
    channel::RemoteChannel)

Implementation of Fix1AxisMethod.

construct_polygon_hull(model::LikelihoodModel,
    θindices::Vector{<:Int},
    conf_struct::BivariateConfidenceStruct,
    confidence_level::Float64,
    dof::Int,
    boundary_not_ordered::Bool,
    hullmethod::AbstractBivariateHullMethod,
    return_boundary_not_mesh::Bool)

Constructs a 2D polygon hull that represents an approximation of a true bivariate log-likelihood confidence boundary, given boundary points and saved internal points in conf_struct, using hullmethod. Optionally returns the boundary as an ordered 2*n array or as a SimpleMesh. For a description of the algorithms used for each AbstractBivariateHullMethod see their docstrings: ConvexHullMethod, ConcaveHullMethod and MPPHullMethod.

bivariate_concave_hull(points::AbstractArray{Float64}, 
    ll::Vector{<:Float64},
    min_proportion_to_keep::Real, 
    min_scaling_from_desired_ll::Real, 
    target_ll::Float64,
    sample_type::AbstractSampleType=LatinHypercubeSamples())

The implementation of ConcaveHullMethod(), largely intended for use with dimensional sampling point clouds, but available for use with other methods as well. Uses a heuristic defined number of neighbours with the concave hull algorithm from ConcaveHull.jl on the collection of points given by both boundary and saved internal points, returning the approximate boundary polygon hull as a 2*n array.

bivariate_concave_hull(sampled_struct::SampledConfidenceStruct, 
    θindices::Vector{Int},
    min_proportion_to_keep::Real, 
    min_scaling_from_desired_ll::Real, 
    target_ll::Float64, 
    sample_type::AbstractSampleType)

Method which unpacks a sampled_struct into the format required to call the other method of LikelihoodBasedProfileWiseAnalysis.bivariate_concave_hull.

update_biv_dict_internal!(model::LikelihoodModel,
    biv_row_number::Int,
    points::PointsAndLogLikelihood)

Updates the internal_points field of a BivariateConfidenceStruct, for the profile related to biv_row_number stored at model.biv_profiles_dict[biv_row_number], with the internal points stored in points.

sample_internal_points_LHC(model::LikelihoodModel, 
    target_num_points::Int, 
    θindices::Tuple{Int,Int}, 
    profile_type::AbstractProfileType,
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    conf_struct::BivariateConfidenceStruct, 
    confidence_level::Float64,
    dof::Int,
    boundary_not_ordered::Bool,
    hullmethod::AbstractBivariateHullMethod,
    use_threads::Bool)

Given a hullmethod of type AbstractBivariateHullMethod which creates a 2D polygon hull from a set of boundary and internal points (method dependent) in conf_struct as a representation of the true confidence boundary, sample points from the bounding box, with edges parallel to x and y axes, of a 2D polygon hull using a heuristically optimised Latin Hypercube sampling plan to find approximately target_num_points within the polygon, rejecting any that are not inside the log-likelihood threshold at that confidence_level, dof and profile_type.

sample_internal_points_uniform_random(model::LikelihoodModel, 
    num_points::Int, 
    θindices::Tuple{Int,Int}, 
    profile_type::AbstractProfileType,
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    conf_struct::BivariateConfidenceStruct, 
    confidence_level::Float64,
    dof::Int,
    boundary_not_ordered::Bool,
    hullmethod::AbstractBivariateHullMethod,
    optimizationsettings::OptimizationSettings,
    use_threads::Bool)

Given a hullmethod of type AbstractBivariateHullMethod which creates a 2D polygon hull from a set of boundary and internal points (method dependent) in conf_struct as a representation of the true confidence boundary, sample points from the polygon hull homogeneously until num_points are found, rejecting any that are not inside the log-likelihood threshold at that confidence_level, dof and profile_type.

sample_internal_points_single_row(model::LikelihoodModel,
    sub_df::Union{DataFrame, SubDataFrame},
    i::Int,
    biv_row_number::Int, 
    num_points::Int, 
    sample_type::AbstractSampleType,
    hullmethod::AbstractBivariateHullMethod, 
    θlb_nuisance::AbstractVector{<:Real},
    θub_nuisance::AbstractVector{<:Real},
    t::Union{AbstractVector,Missing},
    evaluate_predictions_for_samples::Bool,
    proportion_of_predictions_to_keep::Real,
    optimizationsettings::OptimizationSettings,
    use_threads::Bool,
    channel::RemoteChannel)

Sample internal points from the bivariate profile given by a valid row number in model.biv_profiles_df using either homogeneous sampling (UniformRandomSamples()) to find exactly num_points or a Latin Hypercube sampling plan (LatinHypercubeSamples()) to find approximately num_points.

predictions_can_be_merged(model::LikelihoodModel, rows::AbstractVector{<:Int})

Returns true if all the prediction struct arrays have the same size in the 1st (and 3rd if relevant) dimensions. Return false otherwise.

rebuild_bivariate_datastructures!(model::LikelihoodModel)

Rebuilds all the bivariate datastructures so that the :rowind of rows in `model.bivprofiles_df` begins at 1 and increases in increments of 1, updating dictionary keys with the new row indexes.