# Internal Library

Documentation for `structs`

and functions not covered within User Interface documentation.

## Structs

`EllipseSampling.Ellipse`

— Type`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_squared`

— Function`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.circumference`

— Function`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_valid`

— Function`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_inverse`

— Function`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_zero`

— Function`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_parameters`

— Function```
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].