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_rand_copula_plackett_bivar (g05rg)

Purpose

nag_rand_copula_plackett_bivar (g05rg) generates pseudorandom uniform bivariates with joint distribution of a Plackett copula.

Syntax

[state, x, ifail] = g05rg(n, theta, sorder, state)
[state, x, ifail] = nag_rand_copula_plackett_bivar(n, theta, sorder, state)

Description

Generates pseudorandom uniform bivariates {u1,u2}[0,1]2{u1,u2}[0,1]2 whose joint distribution is the Plackett copula CθCθ with parameter θθ, given by
Cθ = ( [1 + (θ1)(u1 + u2)] sqrt( [1 + (θ1)(u1 + u2)]2 4 u1 u2 θ (θ1) ) )/(2(θ1)) ,   θ (0,) {1}
Cθ = [ 1 + (θ-1) ( u1 + u2 ) ] - [ 1 + (θ-1) ( u1 + u2 ) ] 2 - 4 u1 u2 θ (θ-1) 2(θ-1) ,   θ (0,) {1}
with the special cases:
The generation method uses conditional sampling.
One of the initialization functions nag_rand_init_repeat (g05kf) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeat (g05kg) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_copula_plackett_bivar (g05rg).

References

Nelsen R B (2006) An Introduction to Copulas (2nd Edition) Springer Series in Statistics

Parameters

Compulsory Input Parameters

1:     n – int64int32nag_int scalar
nn, the number of bivariates to generate.
Constraint: n0n0.
2:     theta – double scalar
θθ, the copula parameter.
Constraint: theta0.0theta0.0.
3:     sorder – int64int32nag_int scalar
Determines the storage order of variates; the (i,j)(i,j)th variate is stored in x(i,j)xij if sorder = 1sorder=1, and x(j,i)xji if sorder = 2sorder=2, for i = 1,2,,ni=1,2,,n and j = 1,2j=1,2.
Constraint: sorder = 1sorder=1 or 22.
4:     state( : :) – int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains information on the selected base generator and its current state.

Optional Input Parameters

None.

Input Parameters Omitted from the MATLAB Interface

ldx sdx

Output Parameters

1:     state( : :) – int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains updated information on the state of the generator.
2:     x(ldx,sdx) – double array
The nn bivariate uniforms with joint distribution described by CθCθ, with x(i,j)xij holding the iith value for the jjth dimension if sorder = 1sorder=1 and the jjth value for the iith dimension of sorder = 2sorder=2.
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = 1ifail=1
On entry, corrupt state parameter.
  ifail = 2ifail=2
Constraint: theta0.0theta0.0.
  ifail = 3ifail=3
Constraint: n0n0.
  ifail = 4ifail=4
Invalid storage option.
  ifail = 6ifail=6
On entry, ldx is too small: .
  ifail = 7ifail=7
On entry, sdx is too small: .
  ifail = 999ifail=-999
Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

In practice, the need for numerical stability restricts the range of θθ such that: where εsεs is the safe-range parameter, the value of which is returned by nag_machine_real_safe (x02am); and εε is the machine precision returned by nag_machine_precision (x02aj).

Example

function nag_rand_copula_plackett_bivar_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);
% Sample size
n = int64(13);
% Sample order
sorder = int64(1);
% Parameter
theta = 2;

% Initialize the generator to a repeatable sequence
[state, ifail] = nag_rand_init_repeat(genid, subid, seed);

% Generate variates
[state, x, ifail] = nag_rand_copula_plackett_bivar(n, theta, sorder, state)
 

state =

                   17
                 1234
                    1
                    0
                28214
                15039
                27035
                23461
                17917
                13895
                19930
                    8
                    0
                 1234
                    1
                    1
                 1234


x =

    0.6364    0.0695
    0.1065    0.4586
    0.7460    0.3586
    0.7983    0.3267
    0.1046    0.9888
    0.4925    0.8920
    0.3843    0.4903
    0.7871    0.4248
    0.4982    0.5783
    0.6717    0.4419
    0.0505    0.5802
    0.2580    0.6629
    0.6238    0.3291


ifail =

                    0


function g05rg_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);
% Sample size
n = int64(13);
% Sample order
sorder = int64(1);
% Parameter
theta = 2;

% Initialize the generator to a repeatable sequence
[state, ifail] = g05kf(genid, subid, seed);

% Generate variates
[state, x, ifail] = g05rg(n, theta, sorder, state)
 

state =

                   17
                 1234
                    1
                    0
                28214
                15039
                27035
                23461
                17917
                13895
                19930
                    8
                    0
                 1234
                    1
                    1
                 1234


x =

    0.6364    0.0695
    0.1065    0.4586
    0.7460    0.3586
    0.7983    0.3267
    0.1046    0.9888
    0.4925    0.8920
    0.3843    0.4903
    0.7871    0.4248
    0.4982    0.5783
    0.6717    0.4419
    0.0505    0.5802
    0.2580    0.6629
    0.6238    0.3291


ifail =

                    0



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–2013