NAG Toolbox: nag_stat_inv_cdf_students_t_vector (g01tb)

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{ldf}\right)$:

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

The lower tail probability, i.e., $p_i=P\left(T_i\le t_{p_i}:{\nu }_i\right)$.

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

The upper tail probability, i.e., $p_i=P\left(T_i\ge t_{p_i}:{\nu }_i\right)$.

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

The two tail (confidence interval) probability,
i.e., $p_i=P\left(T_i\le \left|t_{p_i}\right|:{\nu }_i\right)-P\left(T_i\le -\left|t_{p_i}\right|:{\nu }_i\right)$.

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

The two tail (significance level) probability,
i.e., $p_i=P\left(T_i\ge \left|t_{p_i}\right|:{\nu }_i\right)+P\left(T_i\le -\left|t_{p_i}\right|:{\nu }_i\right)$.

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

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

$p_i$, the probability of the required Student's $t$-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<\mathbf{p}\left(\mathit{j}\right)<1.0$, for $\mathit{j}=1,2,\dots ,\mathbf{lp}$.

3:     $\mathrm{df}\left(\mathbf{ldf}\right)$ – double array

${\nu }_i$, the degrees of freedom of the Student's $t$-distribution with ${\nu }_i=\mathbf{df}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{ldf}\right)+1$.

Constraint: $\mathbf{df}\left(\mathit{j}\right)\ge 1.0$, for $\mathit{j}=1,2,\dots ,\mathbf{ldf}$.

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{ldf}$ – int64int32nag_int scalar

Default: the dimension of the array df.

The length of the array df.

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

Output Parameters

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

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

$t_{p_i}$, the deviates for the Student's $t$-distribution.

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

The dimension of the array ivalid will be $\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{ldf}\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 $t_{p_i}$.

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

On entry,	$p_i\le 0.0$,
or	$p_i\ge 1.0$.

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

On entry,

${\nu }_i<1.0$.

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

The solution has failed to converge. The result returned should represent an approximation to the 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 or df 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{ldf}>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: g01tb_example

function g01tb_example


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

p    = [0.01; 0.01; 0.99];
df   = [20;   7.5;  45];
tail = {'S';  'L';  'C'};
[x, ivalid, ifail] = g01tb( ...
                            tail, p, df);

fprintf('     p      df    tail      x\n');
lp    = numel(p);
ldf   = numel(df);
ltail = numel(tail);
len   = max ([lp, ldf, ltail]);
for i=0:len-1
 fprintf('%8.3f%8.3f   %c   %8.3f\n', p(mod(i,lp)+1), df(mod(i,ldf)+1), ...
         tail{mod(i,ltail)+1}, x(i+1));
end

g01tb example results

     p      df    tail      x
   0.010  20.000   S      2.845
   0.010   7.500   L     -2.943
   0.990  45.000   C      2.690