NAG Library Function Document nag_rand_copula_clayton (g05rhc)

Transcription

1 1 Purpose NAG Library Function Document nag_rand_copula_clayton () nag_rand_copula_clayton () generates pseudorandom uniform variates with joint distribution of a Clayton/Cook Johnson Archimedean copula. 2 Specification #include <nag.h> #include <nagg05.h> void nag_rand_copula_clayton (Nag_OrderType order, Integer state[], double theta, Integer n, Integer m, double x[], Integer pdx, Integer sdx, NagError *fail) 3 Description Generates n pseudorandom uniform m-variates whose joint distribution is the Clayton/Cook Johnson Archimedean copula C, given by 1=, C ¼ u 1 þ u 2 þþu 2 ð0; 1Þ, m m þ 1 u j 2 ð0; 1Š, j ¼ 1;...m; with the special case: C 1 ¼ minðu 1 ;u 2 ;...;u m Þ, the Frechet Hoeffding upper-bound. The generation method uses mixture of powers. 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_copula_clayton (). 4 References Marshall A W and Olkin I (1988) Families of Multivariate Distributions Journal of the American Statistical Association 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. On exit: contains updated information on the state of the generator..1

2 NAG Library Manual 3: theta double Input On entry:, the copula parameter. Constraint: theta 1: : n Integer Input On entry: n, the number of uniform pseudorandom variates to generate. Constraint: n 0. 5: m Integer Input On entry: m, the number of dimensions. Constraint: m 2. 6: x½pdx sdxš double Output Note: where Xði; jþ appears in this document, it refers to the array element x½ðj 1Þpdx þ i 1Š when order ¼ Nag_ColMajor; x½ði 1Þpdx þ j 1Š when order ¼ Nag_RowMajor. On exit: the uniform pseudorandom variates with joint distribution described by C, with Xði; jþ holding the ith value for the jth dimension. 7: pdx Integer Input On entry: the stride separating matrix row or column elements (depending on the value of order) in X. Constraints: if order ¼ Nag_ColMajor, pdx maxð1; nþ; if order ¼ Nag_RowMajor, pdx m. 8: sdx Integer Input On entry: the secondary dimension of X. Constraints: if order ¼ Nag_ColMajor, sdx m; if order ¼ Nag_RowMajor, sdx n. 9: 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, m ¼ hvaluei. Constraint: m > 1. On entry, n ¼ hvaluei. Constraint: n 0. On entry, pdx ¼ hvaluei. Constraint: pdx > 0. hvaluei had an illegal value..2

3 NE_INT_2 On entry, pdx must be at least On entry, sdx must be at least hvaluei: pdx ¼ hvaluei. hvaluei: sdx ¼ 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. NE_INVALID_STATE On entry, corrupt state parameter NE_REAL On entry, invalid theta: theta ¼ hvaluei. Constraint: theta 1: Accuracy Not applicable. 8 Further Comments In practice, the need for numerical stability restricts the range of such that: the function requires 1: ; if >200:0, the function returns pseudorandom uniform variates with C 1 joint distribution. 9 Example This example generates thirteen four-dimensional variates for copula C 1: Program Text /* nag_rand_copula_clayton () 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, j, lstate, pdx, sdx; Integer *state = 0; /* Double scalar and array declarations */ double *x = 0;.3

4 NAG Library Manual /* NAG structures */ NagError fail; /* Use row major order */ Nag_OrderType order = Nag_RowMajor; /* Set the number of variables and variates */ Integer n = 13, m = 4; /* Choose the base generator */ Nag_BaseRNG genid = Nag_Basic; Integer subid = 0; /* Set the seed */ Integer seed[] = ; Integer lseed = 1; /* Set the theta parameter value */ double theta = 1.3e0; /* 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_copula_clayton () 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", /* Set matrix size and principal dimension according to storage order */ pdx = (order == Nag_ColMajor)?n:m; sdx = (order == Nag_ColMajor)?m: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", /* Generate variates */ nag_rand_copula_clayton(order, state, theta, n, m, x, pdx, sdx, &fail); fprintf(fpout, "Error from nag_rand_copula_clayton ().\n%s\n",.4

5 /* Display the results */ fprintf(fpout, "Uniform variates with copula joint distrbution\n"); for (i = 1; i <= n; i++) fprintf(fpout, " "); for (j = 1; j <= m; j++) fprintf(fpout, "%9.6f%s", X(i, j), j < m?" ":"\n"); END: 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_copula_clayton () Example Program Results Uniform variates with copula joint distrbution (last)