NAG Toolbox: nag_stat_inv_cdf_beta_vector (g01te)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{tail}\left(\mathbf{ltail}\right)$ – cell array of strings

Indicates which tail the supplied probabilities represent. For $j=\left(\left(\mathit{i}-1\right)\mathrm{ mod }\mathbf{ltail}\right)+1$, for $\mathit{i}=1,2,\dots ,\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{la},\mathbf{lb}\right)$:

$\mathbf{tail}\left(j\right)=\text{'L'}$

The lower tail probability, i.e., $p_i=P\left(B_i\le {\beta }_{p_i}:a_i,b_i\right)$.

$\mathbf{tail}\left(j\right)=\text{'U'}$

The upper tail probability, i.e., $p_i=P\left(B_i\ge {\beta }_{p_i}:a_i,b_i\right)$.

Constraint: $\mathbf{tail}\left(\mathit{j}\right)=\text{'L'}$ or $\text{'U'}$, for $\mathit{j}=1,2,\dots ,\mathbf{ltail}$.

2:     $\mathrm{p}\left(\mathbf{lp}\right)$ – double array

$p_i$, the probability of the required beta distribution as defined by tail with $p_i=\mathbf{p}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{lp}\right)+1$.

Constraint: $0.0\le \mathbf{p}\left(\mathit{j}\right)\le 1.0$, for $\mathit{j}=1,2,\dots ,\mathbf{lp}$.

3:     $\mathrm{a}\left(\mathbf{la}\right)$ – double array

$a_i$, the first parameter of the required beta distribution with $a_i=\mathbf{a}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{la}\right)+1$.

Constraint: $0.0<\mathbf{a}\left(\mathit{j}\right)\le {10}^6$, for $\mathit{j}=1,2,\dots ,\mathbf{la}$.

4:     $\mathrm{b}\left(\mathbf{lb}\right)$ – double array

$b_i$, the second parameter of the required beta distribution with $b_i=\mathbf{b}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{lb}\right)+1$.

Constraint: $0.0<\mathbf{b}\left(\mathit{j}\right)\le {10}^6$, for $\mathit{j}=1,2,\dots ,\mathbf{lb}$.

Optional Input Parameters

1:     $\mathrm{ltail}$ – int64int32nag_int scalar

Default: the dimension of the array tail.

The length of the array tail.

Constraint: $\mathbf{ltail}>0$.

2:     $\mathrm{lp}$ – int64int32nag_int scalar

Default: the dimension of the array p.

The length of the array p.

Constraint: $\mathbf{lp}>0$.

3:     $\mathrm{la}$ – int64int32nag_int scalar

Default: the dimension of the array a.

The length of the array a.

Constraint: $\mathbf{la}>0$.

4:     $\mathrm{lb}$ – int64int32nag_int scalar

Default: the dimension of the array b.

The length of the array b.

Constraint: $\mathbf{lb}>0$.

5:     $\mathrm{tol}$ – double scalar

Default: $0.0$

The relative accuracy required by you in the results. If nag_stat_inv_cdf_beta_vector (g01te) is entered with tol greater than or equal to $1.0$ or less than $10\times \mathit{machine precision}$ (see nag_machine_precision (x02aj)), then the value of $10\times \mathit{machine precision}$ is used instead.

Output Parameters

1:     $\mathrm{beta}\left(:\right)$ – double array

The dimension of the array beta will be $\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{la},\mathbf{lb}\right)$

${\beta }_{p_i}$, the deviates for the beta distribution.

2:     $\mathrm{ivalid}\left(:\right)$ – int64int32nag_int array

The dimension of the array ivalid will be $\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{la},\mathbf{lb}\right)$

$\mathbf{ivalid}\left(i\right)$ indicates any errors with the input arguments, with

$\mathbf{ivalid}\left(i\right)=0$

No error.

$\mathbf{ivalid}\left(i\right)=1$

On entry,

invalid value supplied in tail when calculating ${\beta }_{p_i}$.

$\mathbf{ivalid}\left(i\right)=2$

On entry,	$p_i<0.0$,
or	$p_i>1.0$.

$\mathbf{ivalid}\left(i\right)=3$

On entry,	$a_i\le 0.0$,
or	$a_i>{10}^6$,
or	$b_i\le 0.0$,
or	$b_i>{10}^6$.

$\mathbf{ivalid}\left(i\right)=4$

The solution has not converged but the result should be a reasonable approximation to the solution.

$\mathbf{ivalid}\left(i\right)=5$

Requested accuracy not achieved when calculating the beta probability. The result should be a reasonable approximation to the correct solution.

3:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  $\mathbf{ifail}=1$

On entry, at least one value of tail, p, a, or b was invalid, or the solution failed to converge.
Check ivalid for more information.

   $\mathbf{ifail}=2$

Constraint: $\mathbf{ltail}>0$.

   $\mathbf{ifail}=3$

Constraint: $\mathbf{lp}>0$.

   $\mathbf{ifail}=4$

Constraint: $\mathbf{la}>0$.

   $\mathbf{ifail}=5$

Constraint: $\mathbf{lb}>0$.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g01te_example

function g01te_example


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

tail = {'L'};
p = [0.5; 0.99; 0.25];
a = [1.0; 1.5; 20.0];
b = [2.0; 1.5; 10.0];

[x, ivalid, ifail] = g01te( ...
                            tail, p, a, b);

fprintf('  tail  probability    a         b    deviate    ivalid\n');
ltail = numel(tail);
lp    = numel(p);
la    = numel(a);
lb    = numel(b);
len   = max ([ltail, lp, la, lb]);
for i=0:len-1
  fprintf('%5s%9.4f%10.3f%10.3f%10.4f%8d\n', tail{mod(i, ltail)+1}, ...
          p(mod(i,lp)+1), a(mod(i,la)+1), b(mod(i,lb)+1), x(i+1), ivalid(i+1));
end

g01te example results

  tail  probability    a         b    deviate    ivalid
    L   0.5000     1.000     2.000    0.2929       0
    L   0.9900     1.500     1.500    0.9672       0
    L   0.2500    20.000    10.000    0.6105       0