Documentation and plots as a requires implementation

JoelTrent · Jun 12, 2023 · 6125385 · 6125385
1 parent 6e4dce5
commit 6125385
Show file tree

Hide file tree

Showing 19 changed files with 412 additions and 111 deletions.
diff --git a/Project.toml b/Project.toml
@@ -13,15 +13,18 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 EllipseSampling = "7d220c50-6298-48cd-9710-1d1a8ef13806"
 FLoops = "cc61a311-1640-44b5-9fba-1b764f453329"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 LatinHypercubeSampling = "a5e1c1ea-c99a-51d3-a14d-a9a37257b02d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Meshes = "eacbb407-ea5a-433e-ab97-5258b1ca43fa"
 NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 SnoopPrecompile = "66db9d55-30c0-4569-8b51-7e840670fc0c"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

diff --git a/docs/make.jl b/docs/make.jl
@@ -1,4 +1,6 @@
+using Revise
 using PlaceholderLikelihood
+using Plots
 using Documenter
 
 DocMeta.setdocmeta!(PlaceholderLikelihood, :DocTestSetup, :(using PlaceholderLikelihood); recursive=true)
@@ -16,7 +18,10 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
-    ],
+        "Quick Start" => "quick_start.md",
+        "User Interface" => "user_interface.md",
+        "Internal Library" => "internal_library.md"
+    ]
 )
 
 deploydocs(;

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -6,9 +6,3 @@ CurrentModule = PlaceholderLikelihood
 
 Documentation for [PlaceholderLikelihood](https://github.com/JoelTrent/PlaceholderLikelihood.jl).
 
-```@index
-```
-
-```@autodocs
-Modules = [PlaceholderLikelihood]
-```
diff --git a/docs/src/internal_library.md b/docs/src/internal_library.md
@@ -0,0 +1 @@
+# Internal Library
diff --git a/docs/src/quick_start.md b/docs/src/quick_start.md
@@ -0,0 +1 @@
+# Quick Start
diff --git a/docs/src/user_interface.md b/docs/src/user_interface.md
@@ -0,0 +1,151 @@
+```@index
+Pages = ["user_interface.md"]
+```
+
+# User Interface
+
+
+## Main Model Structs and Initialisation
+
+```@docs
+LikelihoodModel
+CoreLikelihoodModel
+EllipseMLEApprox
+initialiseLikelihoodModel
+```
+
+## Parameter Transformations
+
+```@docs
+transformbounds
+transformbounds_NLopt
+```
+
+## Optimisation of Nuisance Parameters
+
+This is presently done using a predefined NLopt optimiser. 
+```@docs
+optimise
+optimise_unbounded
+```
+
+## Parameter Profiles and Samples
+
+### Structs
+
+```@docs
+PointsAndLogLikelihood
+AbstractConfidenceStruct
+UnivariateConfidenceStruct
+BivariateConfidenceStruct
+SampledConfidenceStruct
+```
+
+### Profile Types
+
+Profile type is a Struct that specifies whether the profile to be taken uses the true loglikelihood function or an ellipse approximation of the loglikelihood function centred at the MLE (with optional use of parameter bounds).
+
+```@docs
+AbstractProfileType
+AbstractEllipseProfileType
+LogLikelihood
+EllipseApprox
+EllipseApproxAnalytical
+```
+
+### Univariate Profiles
+
+```@docs
+univariate_confidenceintervals!
+get_points_in_interval!
+```
+
+### Bivariate Profiles
+
+```
+bivariate_confidenceprofiles!
+```
+
+#### Methods
+
+```@docs
+AbstractBivariateMethod
+AbstractBivariateVectorMethod
+bivariate_methods
+IterativeBoundaryMethod
+RadialMLEMethod
+RadialRandomMethod
+SimultaneousMethod
+Fix1AxisMethod
+AnalyticalEllipseMethod
+ContinuationMethod, 
+```
+
+### Dimensional Samples
+
+We can generate samples within the loglikelihood boundary at any dimension of model interest parameters.
+
+#### Sample Types
+
+```@docs
+AbstractSampleType
+UniformGridSamples
+UniformRandomSamples
+LatinHypercubeSamples
+```
+
+#### Full Likelihood Sampling
+
+
+```@docs
+full_likelihood_sample!
+```
+
+#### Dimensional Likelihood Sampling
+
+Note: dimensional likelihood samples can be 'full' likelihood samples as well.
+
+```@docs
+dimensional_likelihood_sample!
+bivariate_concave_hull
+```
+
+## Predictions From Profiles and Samples
+
+In the event that a prediction function has not been added to the [`LikelihoodModel`](@ref) struct yet, we can add one using [`add_prediction_function!`](@ref)
+```@docs
+add_prediction_function!
+check_prediction_function_exists
+```
+
+Then to generate predictions we can use one of three functions, depending on whether we want to generate predictions from univariate or bivariate profiles, or dimensional samples.
+
+```@docs
+generate_predictions_univariate!
+generate_predictions_bivariate! 
+generate_predictions_dim_samples!
+```
+
+## Plots
+
+### Univariate Profiles
+
+```@docs
+plot_univariate_profiles
+plot_univariate_profiles_comparison
+```
+
+### Bivariate Profiles and Samples
+
+```@docs
+plot_bivariate_profiles
+plot_bivariate_profiles_comparison
+plot_bivariate_profiles_iterativeboundary_gif
+```
+
+### Predictions
+
+```@docs
+plot_predictions_individual
+plot_predictions_union
+```
diff --git a/src/NLopt_optimiser.jl b/src/NLopt_optimiser.jl
@@ -1,4 +1,9 @@
-# Numerical optimisation 
+"""
+    optimise(fun, θ₀, lb, ub;
+        dv = false, method = dv ? :LD_LBFGS : :LN_BOBYQA)
+
+NLopt optimiser used for calculating the values of nuisance parameters.
+"""
 function optimise(fun, θ₀, lb, ub;
     dv = false,
     method = dv ? :LD_LBFGS : :LN_BOBYQA,
@@ -19,6 +24,12 @@ function optimise(fun, θ₀, lb, ub;
     return res[[2,1]]
 end
 
+"""
+    optimise_unbounded(fun, θ₀;
+        dv = false, method = dv ? :LD_LBFGS : :LN_BOBYQA)
+
+Alternative version of [`optimise`](@ref) without nuisance parameter bounds. Used for computing the nuisance parameters of [`EllipseApproxAnalytical`](@ref) profiles.
+"""
 function optimise_unbounded(fun, θ₀;
     dv = false,
     method = dv ? :LD_LBFGS : :LN_BOBYQA,

diff --git a/src/PlaceholderLikelihood.jl b/src/PlaceholderLikelihood.jl
@@ -1,78 +1,80 @@
 module PlaceholderLikelihood
 
+using DataStructures, DataFrames, Accessors, StaticArrays, TrackingHeaps
 using NLopt, Roots
 using ForwardDiff, LinearAlgebra
-using Random, StatsBase, Combinatorics
-using DataStructures, DataFrames, Accessors, StaticArrays
 using EllipseSampling
 using LatinHypercubeSampling
-using Distributed, FLoops
-using ConcaveHull
+using Random, StatsBase, Combinatorics, Distributions
 using Distances, TravelingSalesmanHeuristics
-using Clustering, Meshes
+using Clustering, Meshes, ConcaveHull
 using AngleBetweenVectors
-using TrackingHeaps
+using Distributed, FLoops
+using Requires
 
 using ProgressMeter
 const global PROGRESS__METER__DT = 1.0
 
+# TYPES ###################################################################################
+export EllipseMLEApprox, CoreLikelihoodModel, LikelihoodModel, 
 
-export AbstractEllipseMLEApprox, AbstractCoreLikelihoodModel, AbstractLikelihoodModel,
-    EllipseMLEApprox, CoreLikelihoodModel, LikelihoodModel, 
-
-    AbstractProfileType, AbstractEllipseProfileType, LogLikelihood, EllipseApprox, EllipseApproxAnalytical
-    AbstractSampleType, UniformGridSamples, UniformRandomSamples, LatinHypercubeSamples
-
+    AbstractProfileType, AbstractEllipseProfileType, LogLikelihood, EllipseApprox, EllipseApproxAnalytical,
+
     AbstractConfidenceStruct, PointsAndLogLikelihood, 
-    SampledConfidenceStruct, UnivariateConfidenceStruct, BivariateConfidenceStruct,
-
+    UnivariateConfidenceStruct, BivariateConfidenceStruct, SampledConfidenceStruct,
+    
     AbstractBivariateMethod, AbstractBivariateVectorMethod, bivariate_methods,
     IterativeBoundaryMethod, RadialMLEMethod, RadialRandomMethod, SimultaneousMethod, Fix1AxisMethod,
     AnalyticalEllipseMethod, ContinuationMethod, 
+
+    AbstractSampleType, UniformGridSamples, UniformRandomSamples, LatinHypercubeSamples,
+
+    AbstractPredictionStruct, PredictionStruct
 
-    AbstractPredictionStruct, PredictionStruct,
 
-    initialiseLikelihoodModel,
-    getMLE_ellipse_approximation!, check_ellipse_approx_exists!
+# FUNCTIONS ###############################################################################
+export initialiseLikelihoodModel,
+    getMLE_ellipse_approximation!, check_ellipse_approx_exists!,
     setθmagnitudes!, setbounds!,
 
+    optimise, optimise_unbounded,
+
     transformbounds, transformbounds_NLopt,
 
     univariate_confidenceintervals!, get_points_in_interval!,
-    bivariate_confidenceprofiles!, minimum_perimeter_polygon!,
+    bivariate_confidenceprofiles!,
     dimensional_likelihood_sample!, bivariate_concave_hull,
     full_likelihood_sample!,
 
     add_prediction_function!, check_prediction_function_exists,
-    generate_predictions_bivariate!, generate_predictions_univariate!, generate_predictions_dim_samples!
+    generate_predictions_univariate!, generate_predictions_bivariate!, generate_predictions_dim_samples!
 
+# OPTIMISER ###############################################################################
 include("NLopt_optimiser.jl")
 
-# TYPES ##############################################################
+# TYPES ###################################################################################
 include("types/bivariate_methods.jl")
 include("types/levelsets.jl")
 include("types/predictions.jl")
-include("types/profiletype.jl")
+include("types/profiletypes.jl")
+include("types/sampletypes.jl")
 include("types/likelihoodmodel.jl")
 
-
+# CORE FUNCTIONS ##########################################################################
 include("model_initialiser.jl")
 # include("combination_relationships.jl")
 include("transform_bounds.jl")
 include("common_profile_likelihood.jl")
 include("ellipse_likelihood.jl")
 include("predictions.jl")
-include("plotting_functions.jl")
-
 
-# UNIVARIATE METHODS #################################################
+# UNIVARIATE METHODS ######################################################################
 include("univariate_methods/init_and_array_mapping.jl")
 include("univariate_methods/loglikelihood_functions.jl")
 include("univariate_methods/univariate_profile_likelihood.jl")
 include("univariate_methods/points_in_interval.jl")
 
-
-# BIVARIATE METHODS ##################################################
+# BIVARIATE METHODS #######################################################################
 include("bivariate_methods/init_and_array_mapping.jl")
 include("bivariate_methods/findpointon2Dbounds.jl")
 include("bivariate_methods/loglikelihood_functions.jl")
@@ -84,12 +86,31 @@ include("bivariate_methods/iterativeboundary.jl")
 include("bivariate_methods/bivariate_profile_likelihood.jl")
 include("bivariate_methods/MPP_TSP.jl")
 
-
-# SAMPLING METHODS ###################################################
+# SAMPLING METHODS ########################################################################
 include("dimensional_methods/full_likelihood_sampling.jl")
 include("dimensional_methods/dimensional_likelihood_sampling.jl")
 include("dimensional_methods/bivariate_concave_hull.jl")
 
+# PLOT FUNCTIONS ##########################################################################
+function plot_univariate_profiles end
+function plot_univariate_profiles_comparison end
+function plot_bivariate_profiles end
+function plot_bivariate_profiles_comparison end
+function plot_bivariate_profiles_iterativeboundary_gif end
+function plot_predictions_individual end
+function plot_predictions_union end
+
+export plot_univariate_profiles, plot_univariate_profiles_comparison,
+    plot_bivariate_profiles, plot_bivariate_profiles_comparison,
+    plot_bivariate_profiles_iterativeboundary_gif,
+    plot_predictions_individual, plot_predictions_union
+
+function __init__()
+    @require Plots="91a5bcdd-55d7-5caf-9e0b-520d859cae80" begin 
+        using Plots
+        include("plotting_functions.jl") 
+    end
+end
 
 import SnoopPrecompile
 

diff --git a/src/bivariate_methods/continuation_polygon_manipulation.jl b/src/bivariate_methods/continuation_polygon_manipulation.jl
@@ -13,7 +13,7 @@ function star_obj(centers, points)
         for vi in 1:n
             intersects_polygon=false
 
-            internal_segment = Segment(Point(c_point), Point(points[:,vi]))
+            internal_segment = Segment(Point(c_point...), Point(points[:,vi]...))
             # println()
             # println("Vi=", vi)
             # println(internal_segment)
@@ -25,7 +25,7 @@ function star_obj(centers, points)
             # println("v2s:", v2s)
 
             for ei in eachindex(v1s)
-                edge_segment = Segment(Point(points[:,v1s[ei]]), Point(points[:,v2s[ei]])) 
+                edge_segment = Segment(Point(points[:,v1s[ei]]...), Point(points[:,v2s[ei]]...)) 
                 # println(edge_segment)
                 # segment_plot(internal_segment, edge_segment, xlim=[-0.1,4.1], ylim=[-0.1, 6.1])
                 if intersection(internal_segment, edge_segment).type != IntersectionType(0)