NAG Library Function Document nag_rand_bivariate_copula_frank (g05rfc)

Transcription

1 1 Purpose NAG Library Function Document nag_rand_bivariate_copula_frank () nag_rand_bivariate_copula_frank () generates pseudorandom uniform bivariates with joint distribution of a Frank Archimedean copula. 2 Specification #include <nag.h> #include <nagg05.h> void nag_rand_bivariate_copula_frank (Nag_OrderType order, Integer state[], double theta, Integer n, double x[], Integer ldx, Integer tdx, NagError *fail) 3 Description Generates pseudorandom uniform bivariates fu 1 ;u 2 g 2 ½0; 1Š 2 whose joint distribution is the Frank Archimedean copula C with parameter, given by 2 3 C ¼ 1 e u 1 1 e u 2 1 ln 4 1 þ 5, e 2 ð 1; 1Þnfg 0 1 with the special cases: C 1 ¼ maxðu 1 þ u 2 1; 0Þ, the Frechet Hoeffding lower-bound; C 0 ¼ u 1 u 2, the product copula; C 1 ¼ minðu 1 ;u 2 Þ, the Frechet Hoeffding upper-bound. The generation method uses conditional sampling. One of the initialization routines nag_rand_init_repeatable (g05kfc) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeatable (g05kgc) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_bivariate_copula_frank (). 4 References Nelsen R B (2006) An Introduction to Copulas (2nd Edition) Springer Series in Statistics 5 Arguments 1: order Nag_OrderType Input On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., rowmajor ordering or column-major ordering. C language defined storage is specified by order ¼ Nag_RowMajor. See Section in the Essential Introduction for a more detailed explanation of the use of this argument. Constraint: order ¼ Nag_RowMajor or Nag_ColMajor. 2: state½lstateš Integer Communication Array Note: lstate ¼ lstate, the dimension of state as supplied to the initialization function nag_rand_init_repeatable (g05kfc) or nag_rand_init_nonrepeatable (g05kgc). On entry: contains information on the selected base generator and its current state..1

2 NAG Library Manual On exit: contains updated information on the state of the generator. 3: theta double Input On entry:, the copula parameter. 4: n Integer Input On entry: n, the number of bivariates to generate. Constraint: n 0. 5: x½ldx tdxš double Output Note: where Xði; jþ appears in this document, it refers to the array element x½ðj 1Þldx þ i 1Š when order ¼ Nag_ColMajor; x½ði 1Þtdx þ j 1Š when order ¼ Nag_RowMajor. On exit: the n bivariate uniforms with joint distribution described by C, with Xði; jþ holding the ith value for the jth dimension. 6: ldx Integer Input On entry: the first dimension of the array x as declared in the function from which nag_rand_bivariate_copula_frank () is called. Constraints: if order ¼ Nag_ColMajor, ldx n; if order ¼ Nag_RowMajor, ldx 2. 7: tdx Integer Input On entry: the second dimension of the array x as declared in the function from which nag_rand_bivariate_copula_frank () is called. Constraints: if order ¼ Nag_ColMajor, tdx 2; if order ¼ Nag_RowMajor, tdx n. 8: fail NagError * Input/Output The NAG error argument (see Section 3.6 in the Essential Introduction). 6 Error Indicators and Warnings NE_BAD_PARAM On entry, argument NE_INT On entry, n ¼ hvaluei. Constraint: n 0. NE_INT_2 On entry, ldx must be at least On entry, tdx must be at least hvaluei had an illegal value. hvaluei: ldx ¼ hvaluei. hvaluei: tdx ¼ hvaluei. NE_INTERNAL_ERROR An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance..2

3 NE_INVALID_STATE On entry, corrupt state parameter. 7 Accuracy Not applicable. 8 Further Comments In practice, the need for numerical stability restricts the range of such that: if <ln s, the function returns pseudorandom uniform variates with C 1 joint distribution; if jj< 1:0 10 6, the function returns pseudorandom uniform variates with C 0 joint distribution; if >ln, the function returns pseudorandom uniform variates with C 1 joint distribution; where s is the implementation-specific safe-range parameter, the value of which is returned by nag_real_safe_small_number (X02AMC); and is the machine precision returned by nag_machine_precision (X02AJC). 9 Example This example generates thirteen variates for copula C 12: Program Text /* nag_rand_bivariate_copula_frank () Example Program. * * Copyright 2009, Numerical Algorithms Group. * * Mark 9, */ /* Pre-processor includes */ #include <stdio.h> #include <math.h> #include <nag.h> #include <nagx04.h> #include <nag_stdlib.h> #include <nagg05.h> #define X(I, J) x[order == Nag_ColMajor?((J-1)*pdx + I-1):((I-1)*pdx + J-1)] int main(int argc, char *argv[]) FILE *fpout = 0; /* Integer scalar and array declarations */ Integer exit_status = 0; Integer i, lstate, pdx, sdx; Integer *state = 0; /* Double scalar and array declarations */ double *x = 0; /* NAG structures */ NagError fail; /* Use row major order */ Nag_OrderType order = Nag_RowMajor; /* Set the number of variates */ Integer n = 13; /* Choose the base generator */ Nag_BaseRNG genid = Nag_Basic;.3

4 NAG Library Manual Integer subid = 0; /* Set the seed */ Integer seed[] = ; Integer lseed = 1; /* Set the theta parameter value */ double theta = -12.0e0; /* Initialise the error structure */ INIT_FAIL(fail); /* Check for command-line IO options */ fpout = nag_example_file_io(argc, argv, "-results", NULL); fprintf(fpout, "nag_rand_bivariate_copula_frank () " "Example Program Results\n\n"); /* Get the length of the state array */ lstate = -1; nag_rand_init_repeatable(genid, subid, seed, lseed, state, &lstate, &fail); fprintf(fpout, "Error from nag_rand_init_repeatable (g05kfc).\n%s\n", fail.message); /* Set matrix size and principal dimension according to storage order */ pdx = (order == Nag_ColMajor)?n:2; sdx = (order == Nag_ColMajor)?2:n; /* Allocate arrays */ if (!(x = NAG_ALLOC((pdx*sdx), double))!(state = NAG_ALLOC(lstate, Integer))) fprintf(fpout, "Allocation failure\n"); exit_status = -1; /* Initialise the generator to a repeatable sequence */ nag_rand_init_repeatable(genid, subid, seed, lseed, state, &lstate, &fail); fprintf(fpout, "Error from nag_rand_init_repeatable (g05kfc).\n%s\n", fail.message); /* Generate variates */ nag_rand_bivariate_copula_frank(order, state, theta, n, x, pdx, sdx, &fail); fprintf(fpout, "Error from nag_rand_bivariate_copula_frank ().\n" "%s\n", fail.message); /* Display the results */ fprintf(fpout, "Uniform variates with copula joint distrbution\n"); for (i = 1; i <= n; i++) fprintf(fpout, " %9.6f %9.6f\n", X(i, 1), X(i, 2)); END:.4

5 if (fpout!= stdout) fclose(fpout); if (x) NAG_FREE(x); if (state) NAG_FREE(state); return exit_status; 9.2 Program Data None. 9.3 Program Results nag_rand_bivariate_copula_frank () Example Program Results Uniform variates with copula joint distrbution (last)