# NAG FL Interfaceg01erf (prob_​vonmises)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g01erf returns the probability associated with the lower tail of the von Mises distribution between $-\pi$ and $\pi$ through the function name.

## 2Specification

Fortran Interface
 Function g01erf ( t, vk,
 Real (Kind=nag_wp) :: g01erf Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: t, vk
#include <nag.h>
 double g01erf_ (const double *t, const double *vk, Integer *ifail)
The routine may be called by the names g01erf or nagf_stat_prob_vonmises.

## 3Description

The von Mises distribution is a symmetric distribution used in the analysis of circular data. The lower tail area of this distribution on the circle with mean direction ${\mu }_{0}=0$ and concentration parameter kappa, $\kappa$, can be written as
 $Pr(Θ≤θ:κ)=12πI0(κ) ∫-πθeκcos⁡ΘdΘ,$
where $\theta$ is reduced modulo $2\pi$ so that $-\pi \le \theta <\pi$ and $\kappa \ge 0$. Note that if $\theta =\pi$ then g01erf returns a probability of $1$. For very small $\kappa$ the distribution is almost the uniform distribution, whereas for $\kappa \to \infty$ all the probability is concentrated at one point.
The method of calculation for small $\kappa$ involves backwards recursion through a series expansion in terms of modified Bessel functions, while for large $\kappa$ an asymptotic Normal approximation is used.
In the case of small $\kappa$ the series expansion of Pr($\Theta \le \theta$: $\kappa$) can be expressed as
 $Pr(Θ≤θ:κ)=12+θ (2π) +1πI0(κ) ∑n=1∞n-1In(κ)sin⁡nθ,$
where ${I}_{n}\left(\kappa \right)$ is the modified Bessel function. This series expansion can be represented as a nested expression of terms involving the modified Bessel function ratio ${R}_{n}$,
 $Rn(κ)=In(κ) In-1(κ) , n=1,2,3,…,$
which is calculated using backwards recursion.
For large values of $\kappa$ (see Section 7) an asymptotic Normal approximation is used. The angle $\Theta$ is transformed to the nearly Normally distributed variate $Z$,
 $Z=b(κ)sin⁡Θ2,$
where
 $b(κ)=2π eκ I0(κ)$
and $b\left(\kappa \right)$ is computed from a continued fraction approximation. An approximation to order ${\kappa }^{-4}$ of the asymptotic normalizing series for $z$ is then used. Finally the Normal probability integral is evaluated.
For a more detailed analysis of the methods used see Hill (1977).

## 4References

Hill G W (1977) Algorithm 518: Incomplete Bessel function ${I}_{0}$: The Von Mises distribution ACM Trans. Math. Software 3 279–284
Mardia K V (1972) Statistics of Directional Data Academic Press

## 5Arguments

1: $\mathbf{t}$Real (Kind=nag_wp) Input
On entry: $\theta$, the observed von Mises statistic measured in radians.
2: $\mathbf{vk}$Real (Kind=nag_wp) Input
On entry: the concentration parameter $\kappa$, of the von Mises distribution.
Constraint: ${\mathbf{vk}}\ge 0.0$.
3: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{vk}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{vk}}\ge 0.0$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

g01erf uses one of two sets of constants depending on the value of machine precision. One set gives an accuracy of six digits and uses the Normal approximation when ${\mathbf{vk}}\ge 6.5$, the other gives an accuracy of $12$ digits and uses the Normal approximation when ${\mathbf{vk}}\ge 50.0$.

## 8Parallelism and Performance

g01erf is not threaded in any implementation.

Using the series expansion for small $\kappa$ the time taken by g01erf increases linearly with $\kappa$; for larger $\kappa$, for which the asymptotic Normal approximation is used, the time taken is much less.
If angles outside the region $-\pi \le \theta <\pi$ are used care has to be taken in evaluating the probability of being in a region ${\theta }_{1}\le \theta \le {\theta }_{2}$ if the region contains an odd multiple of $\pi$, $\left(2n+1\right)\pi$. The value of $F\left({\theta }_{2}\text{;}\kappa \right)-F\left({\theta }_{1}\text{;}\kappa \right)$ will be negative and the correct probability should then be obtained by adding one to the value.

## 10Example

This example inputs four values from the von Mises distribution along with the values of the parameter $\kappa$. The probabilities are computed and printed.

### 10.1Program Text

Program Text (g01erfe.f90)

### 10.2Program Data

Program Data (g01erfe.d)

### 10.3Program Results

Program Results (g01erfe.r)