# Internal Library

Documentation for structs and functions not covered within User Interface documentation.

## Structs

EllipseSampling.EllipseType
Ellipse

Contains the information required to define an ellipse which may have been rotated and translated. See construct_ellipse.

Fields

• x_radius: radius of the ellipse in the x axis (i.e. when the rotation, α, is zero).
• y_radius: radius of the ellipse in the y axis (i.e. when the rotation, α, is zero).
• α: an angle in radians (0 to 2π) that the ellipse has been rotated by. A positive value represents an anti-clockwise rotation.
• Cx: the x coordinate of the centre of the ellipse (the translation of the ellipse in the x axis).
• Cy: the y coordinate of the centre of the ellipse (the translation of the ellipse in the y axis).
• a: the major radius of the ellipse.
• b: the minor radius of the ellipse.
• m: the eccentricity of the ellipse squared. See EllipseSampling.eccentricity_squared.
• em: complete elliptic integral of the second kind evaluated for the eccentricity squared of the ellipse: Elliptic.E(m). See: Elliptic.jl.
• circumference: the circumference of the ellipse.

## Functions

EllipseSampling.eccentricity_squaredFunction
eccentricity_squared(a::T, b::T) where T<:Float64

Computes m, the eccentricity of the ellipse squared, $m=e^2$, where $m=1-\big(\frac{b}{a}\big)^2$.

Arguments

• a: the major radius of the ellipse.
• b: the minor radius of the ellipse.

Details

This relationship between m and e is seen by considering the equation for e: $e=\frac{c}{a}$, where $c^2=\big(a^2-b^2\big)$ and $a>b$.

Replacing c in the equation for e:

$$$e=\frac{\sqrt{a^2-b^2}}{a}$$$

Substituting the equation for e into m:

$$$m = \bigg(\frac{\sqrt{a^2-b^2}}{a}\bigg)^2 = \frac{a^2-b^2}{a^2} = 1 - \frac{b^2}{a^2} = 1 - \bigg(\frac{b}{a}\bigg)^2$$$
EllipseSampling.circumferenceFunction
circumference(a::Float64, b::Float64)

Calculates the circumference of an ellipse using the elliptic integral of the second kind. Uses Elliptic.jl.

Arguments

• a: the major radius of the ellipse.
• b: the minor radius of the ellipse.
EllipseSampling.assert_parameters_are_validFunction
assert_parameters_are_valid(a::T, b::T, x_radius::T, y_radius::T) where T<:Float64

Asserts that the parameters relate to a valid ellipse. I.e. that a ≥ b and, x_radius and y_radius are positive. Note: a=max(x_radius, y_radius), b=min(x_radius, y_radius).

Arguments

• a: the major radius of the ellipse.
• b: the minor radius of the ellipse.
• x_radius: radius of the ellipse in the x axis (i.e. when the rotation, α, is zero).
• y_radius: radius of the ellipse in the y axis (i.e. when the rotation, α, is zero).
EllipseSampling.E_inverseFunction
E_inverse(em::T, z::T, m::T) where T<:Float64

Julia version of the python function t_from_length by John D. Cook.

Arguments

• em: complete elliptic integral of the second kind evaluated for the eccentricity squared of the ellipse: Elliptic.E(m). See: Elliptic.jl.
• z: Difference between em and the quotient of arc length and the major axis radius, em - arc_len/a.
• m: the eccentricity of the ellipse squared. See EllipseSampling.eccentricity_squared.
EllipseSampling.ellipse_zeroFunction
ellipse_zero(t::Float64, p::AbstractVector)

Used by EllipseSampling.E_inverse to find the location t where the function is zero. Equivalent to the anonymous function f(y) = Elliptic.E(y, m) - z.

Arguments

• x: the argument optimised over.
• p: a 2 element static array containing the values for z and m.
EllipseSampling.calculate_ellipse_parametersFunction
calculate_ellipse_parameters(Γ::Matrix{Float64}, ind1::Int, ind2::Int,
confidence_level::Float64, dof::Int)

Given a square matrix Γ, the inverse of the Hessian of a log-likelihood function at its maximum likelihood estimate, indexes of the two variables of interest, the confidence level and degrees of freedom used to define $\ell_c$, which constructs a 2D ellipse approximation of the log-likelihood function, return the parameters of that ellipse.

Arguments

• Γ: a square matrix which is the inverse of the Hessian of a log-likelihood function at its maximum likelihood estimate.
• ind1: index of the first parameter of interest (corresponds to the row and column index of Γ)
• ind2: index of the second parameter of interest (corresponds to the row and column index of Γ).
• confidence_level: the confidence level ∈ [0.0,1.0] at which the ellipse approximation is constructed.
• dof: integer degrees of freedom used for calculation of the asymptotic confidence threshold defining the ellipse. Default is 2.

Details

The parameters of interest are a and b, the radius of the major and minor axis respectively, x_radius and y_radius, the radius of the ellipse in the x and y axis respectively (i.e. the radius when the rotation α is zero) and α, an angle between 0 and π radians that the major axis of the ellipse has been rotated by from the positive x axis. a is equal to the maximum of x_radius and y_radius, while b is equal to the minimum of x_radius and y_radius.

Observed Fisher Information Matrix and Approximation of the Log-Likelihood Function

We can approximate a log-likelihood function from multiple parameters, $\theta$, by considering the observed Fisher information matrix (FIM). The observed FIM is a quadratic approximation of the curvature of the log-likelihood function at the maximum likelihood estimate, $\hat{\theta}$. The observed FIM is the matrix of second derivatives (the Hessian) of the log-likelihood function evaluated at the MLE with elements [1]:

$$$H_{jk}(\hat{\theta}) \equiv -\frac{\partial^2}{\partial \theta_j \partial \theta_k} \ell (\hat{\theta} \, ; \, y_{1:I}^{\textrm{o}} ).$$$

This then allows us to define the following approximation of the normalised log-likelihood function using a second-order Taylor expansion at the MLE [1]:

$$$\hat{\ell} (\theta \, ; \, y_{1:I}^{\textrm{o}} ) \approx -\frac{1}{2} (\theta-\hat{\theta})' H(\hat{\theta}) (\theta-\hat{\theta}).$$$

Similarly, for two parameters, $\psi$, from a larger number of parameters, we first invert the observed FIM, $\Gamma(\hat{\theta}) = H^{-1}(\hat{\theta})$, and then select just the rows and columns relating to the parameters of interest, before again inverting the matrix:

$$$\hat{\ell}_p (\psi \, ; \, y_{1:I}^{\textrm{o}} ) \approx -\frac{1}{2} (\psi-\hat{\psi})' ([e_j, e_k]' \, \Gamma(\hat{\theta}) \, [e_j, e_k])^{-1} (\psi-\hat{\psi}), \hspace{0.2cm} \theta_j \cup \theta_k = \psi,$$$

where $e_j$ and $e_k$ are the $j$th and $k$th canonical vectors of $\mathbb{R}^{|\theta|}$.

Obtaining Ellipse parameters

By normalising our log-likelihood approximation equation for two parameters by our target confidence threshold of interest $\ell_c$ (at confidence_level, with dof degrees of freedom, typically 2) so that one side of the equation is equal to 1 we obtain the equation of an ellipse [2]:

$$$1 = -\frac{1}{2\ell_c} (\psi-\hat{\psi})' ([e_j, e_k]' \, \Gamma(\hat{\theta}) \, [e_j, e_k])^{-1} (\psi-\hat{\psi}) = (\psi-\hat{\psi})' \mathcal{C} (\psi-\hat{\psi}),$$$

The major and minor axis radii, a and b respectively, can then be evaluated by considering the inverse of the square roots of the eigenvalues of $\mathcal{C}$ (ordered from largest to smallest) [2]. To determine the rotation, α of the major axis of the ellipse from the positive $x$ axis we calculate the inverse tangent of the division of the $y$ and $x$ components of the eigenvector corresponding to the largest eigenvalue [2].