hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_stat_prob_students_t (g01eb)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_stat_prob_students_t (g01eb) returns the lower tail, upper tail or two tail probability for the Student's t-distribution with real degrees of freedom.

Syntax

[result, ifail] = g01eb(t, df, 'tail', tail)
[result, ifail] = nag_stat_prob_students_t(t, df, 'tail', tail)
Note: the interface to this routine has changed since earlier releases of the toolbox:
At Mark 23: tail was made optional (default 'L')

Description

The lower tail probability for the Student's t-distribution with ν degrees of freedom, PTt:ν is defined by:
P Tt:ν = Γ ν+1 / 2 πν Γν/2 - t 1+ T2ν -ν+1 / 2 dT ,   ν1 .  
Computationally, there are two situations:
(i) when ν<20, a transformation of the beta distribution, PβBβ:a,b is used
P Tt:ν = 12 Pβ B ν ν+t2 : ν/2, 12   when ​ t<0.0  
or
P Tt:ν = 12 + 12 Pβ B ν ν+t2 : ν/2, 12   when ​ t>0.0 ;  
(ii) when ν20, an asymptotic normalizing expansion of the Cornish–Fisher type is used to evaluate the probability, see Hill (1970).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Hill G W (1970) Student's t-distribution Comm. ACM 13(10) 617–619

Parameters

Compulsory Input Parameters

1:     t – double scalar
t, the value of the Student's t variate.
2:     df – double scalar
ν, the degrees of freedom of the Student's t-distribution.
Constraint: df1.0.

Optional Input Parameters

1:     tail – string (length ≥ 1)
Default: 'L'
Indicates which tail the returned probability should represent.
tail='U'
The upper tail probability is returned, i.e., PTt:ν.
tail='S'
The two tail (significance level) probability is returned,
i.e., PTt:ν+PT-t:ν.
tail='C'
The two tail (confidence interval) probability is returned,
i.e., PTt:ν-PT-t:ν.
tail='L'
The lower tail probability is returned, i.e., PTt:ν.
Constraint: tail='U', 'S', 'C' or 'L'.

Output Parameters

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

Error Indicators and Warnings

Errors or warnings detected by the function:
If ifail0, then nag_stat_prob_students_t (g01eb) returns 0.0.
   ifail=1
On entry,tail'U', 'S', 'C' or 'L'.
   ifail=2
On entry,df<1.0.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

The computed probability should be accurate to five significant places for reasonable probabilities but there will be some loss of accuracy for very low probabilities (less than 10-10), see Hastings and Peacock (1975).

Further Comments

The probabilities could also be obtained by using the appropriate transformation to a beta distribution (see Abramowitz and Stegun (1972)) and using nag_stat_prob_beta (g01ee). This function allows you to set the required accuracy.

Example

This example reads values from, and degrees of freedom for Student's t-distributions along with the required tail. The probabilities are calculated and printed until the end of data is reached.
function g01eb_example


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

% Probability for Students' t distribution
t    = 0.85;
df   = 20;
tail = {'Lower'; 'Significance'; 'Confidence'; 'Upper'};

fprintf('  Tail    t      df    probability\n');
for j = 1:size(tail,1);

  [p, ifail] = g01eb( ...
                      t, df, 'tail', tail{j});

  fprintf('%4s%8.3f%8.1f%12.4f\n', tail{j}(1), t, df, p);
end


g01eb example results

  Tail    t      df    probability
   L   0.850    20.0      0.7973
   S   0.850    20.0      0.4054
   C   0.850    20.0      0.5946
   U   0.850    20.0      0.2027

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015