Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_prob_vonmises (g01er)

## Purpose

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

## Syntax

[result, ifail] = g01er(t, vk)
[result, ifail] = nag_stat_prob_vonmises(t, vk)

## Description

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 argument 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 nag_stat_prob_vonmises (g01er) 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 Accuracy) 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).

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{t}$ – double scalar
$\theta$, the observed von Mises statistic measured in radians.
2:     $\mathrm{vk}$ – double scalar
The concentration parameter $\kappa$, of the von Mises distribution.
Constraint: ${\mathbf{vk}}\ge 0.0$.

None.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{vk}}<0.0$ and nag_stat_prob_vonmises (g01er) returns $0$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

nag_stat_prob_vonmises (g01er) 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$.

Using the series expansion for small $\kappa$ the time taken by nag_stat_prob_vonmises (g01er) 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.

## Example

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

fprintf('g01er example results\n\n');

% Lower tail probabilities for Von Mises distribution
t  = [7; 2.8; 1.0; -1.4];
vk = [0; 2.4; 1.0;  1.3];

fprintf('     t         vk     probability\n');
for j = 1:numel(t)

[p, ifail] = g01er( ...
t(j), vk(j));

fprintf('%9.4f%10.4f%12.4f\n', t(j), vk(j), p);
end

```
```g01er example results

t         vk     probability
7.0000    0.0000      0.6141
2.8000    2.4000      0.9983
1.0000    1.0000      0.7944
-1.4000    1.3000      0.1016
```