simCOP: Simulate a Copula by Numerical Derivative Method

In wasquith/copBasic: General Bivariate Copula Theory and Many Utility Functions

Simulate a Copula by Numerical Derivative Method

Description

Perform a simulation and visualization of a copula using numerical partial derivatives of the copula (Nelsen, 2006, p. 32). The method is more broadly known as conditional simulation method. Because a focus of copBasic is on copula theory for pedagogic purposes, the coupling between simulation and subsequent visualization is emphasized by this function by it providing for both simulation and plotting operations by default.

The simCOP function is based on a uniformly simulating nonexceedance probability u and then conditioning the v from the inverse of the sectional derivative for V with respect to U (see derCOPinv). The function for speed will only report a warning if at least one of the requested simulations in n could not be made because of uniroot'ing problems in derCOPinv. The returned data.frame will be shortened automatically, but this can be controlled by na.rm. Failure of a simulation is purely dependent failure of the derivative inversion. In general, inversion should be quite robust for continuous or near continuous copulas and even copulas with singularities should be more or less okay. Lastly, the logical combination na.rm=FALSE and keept=TRUE could be used to isolate those combinations giving derCOPinv problems. The implemented simulation method in the copBasic package is known as the conditional distribution method (Nelsen, 2006; pp. 40–41), conditional method, or Rosenblatt transform (Joe, 2014, p. 270).

Usage

simCOP(n=100, cop=NULL, para=NULL, na.rm=TRUE, seed=NULL, keept=FALSE,
              graphics=TRUE, ploton=TRUE, points=TRUE, snv=FALSE,
              infsnv.rm=TRUE, trapinfsnv=.Machine$double.eps,
              resamv01=FALSE, showresamv01=FALSE, ...)
rCOP(n, cop=NULL, para=NULL, na.rm=TRUE, seed=NULL,
              resamv01=FALSE, showresamv01=FALSE, ...)

Arguments

n	A sample size, default is n = 100;
cop	A copula function;
para	Vector of parameters, if needed, to pass to the copula;
na.rm	A logical to toggle the removal of NA entries should they form on the returned data.frame. A well implemented copula should accommodate and not return NA but because this package relies on numerical derivation, it was decided to have a mechanism to handle this;
seed	The integer seed to pass immediately to set.seed();
keept	Keep the t uniform random variable for the simulation as the last column in the returned data.frame;
graphics	A logical that will disable graphics by setting ploton and points to FALSE and overriding whatever their settings were;
ploton	A logical to toggle on the plot (see Examples in vuongCOP);
points	A logical to actually draw the simulations by the points() function in R;
snv	A logical to convert the \{u,v\} to standard normal scores (variates) both for the optional graphics and the returned R data.frame. Curiously, Joe (2014) advocates extensively for use of normal scores, which is in contrast to Nelsen (2006) who does not;
infsnv.rm	A logical that will quietly strip out any occurrences of u = \{0,1\} or v = \{0,1\} from the simulations because these are infinity in magnitude when converted to standard normal variates has been selected. Thus, this logical only impacts logic flow when snv is TRUE. The infsnv.rm is mutually exclusive from trapinfsnv;
trapinfsnv	If TRUE and presumably small, the numerical value of this argument (\eta) is used to replace u = \{0,1\} and v = \{0,1\} with u(0) = v(0) = \eta or u(1) = v(1) = 1 - \eta as appropriate when conversion to standard normal variates has been selected. The setting of trapinfsnv only is used if snv is TRUE and infsnv.rm is FALSE;
resamv01	A logical triggering resampling for the elements of v=0 and v=1 (see Examples). This is a relatively late addition to copBasic logic and hence is disabled by default. If this is set to true, then the operations related to infsnv.rm and trapinfsnv are never to be involved later down in the functions' logic;
showresamv01	A logical providing a trigger to display a message() within the resampling loops for v <= 0, v >= 1; and
...	Additional arguments to pass to the points() function in R.

Value

An R data.frame of the simulated values is returned.

Note

Function rCOP is a light-weight implementation for bivariate copula random variates that dispatches to simCOPmicro and bypasses the graphical and other features of simCOP. Finally, an experimental parallel for the empirical copula is EMPIRsim. Note, the equivalent of a resamv01 is not implemented at the level of simCOPmicro because it is better to do such at the abstraction level of rCOP and simCOP.

Author(s)

W.H. Asquith

References

Joe, H., 2014, Dependence modeling with copulas: Boca Raton, CRC Press, 462 p.

Nelsen, R.B., 2006, An introduction to copulas: New York, Springer, 269 p.

See Also

derCOPinv, simCOPmicro

Examples

simCOP(n=5, cop=PARETOcop, para=2.4)

# We can find some unusual simulation combinations for which V == 0 or 1 and might have
# downstream operations simply not able to handle infinite quantiles (say) at the edges.
# We can readily offload the issue back to the rCOP() or simCOP() with resamv01 argument.
nsim <- 800; para <- list(cop=PLcop, para=150, alpha=0.8, beta=0.3)
JK <- rCOP(nsim, cop=composite1COP, para=para, seed=1, resamv01=FALSE)
print(JK[JK[,2] == 1,]) # 189 0.9437248 1.   So, row 189 in this example has V=1, and
UV <- rCOP(nsim, cop=composite1COP, para=para, seed=1, resamv01=TRUE ) # changing the
# resamv01 argument to TRUE, we get this message and no V=1 in the returned data frame.
# rCOP() has some v >= 1, resampling those     <---- This is the message output.

## Not run: 
# The simCOP function is oft used in other Examples sections through this package.
simCOP(n=10, cop=W)            # Frechet lower-bound copula
simCOP(n=10, cop=P)            # Independence copula
simCOP(n=10, cop=M, col=2)     # Frechet upper-bound copula
simCOP(n=10, cop=PSP)          # The PSP copula
## End(Not run)

## Not run: 
# Now simulate the PSP copula, add the level curves of the copula, and demonstrate
# the uniform distribution of marginals on the correct axes (U [top] and V [left]).
D <- simCOP(n=400, cop=PSP) # store simulated values in D
level.curvesCOP(cop=PSP, ploton=FALSE)
rug(D$U, side=3, col=2); rug(D$V, side=4, col=2)

# Now let us get more complicated and mix two Plackett copulas together using the
# composite2COP as a "compositor." The parameter argument becomes more complex, but
# is passed as shown into composite2COP.
para <- list(cop1=PLACKETTcop,cop2=PLACKETTcop, alpha=0.3,beta=0.5, para1=0.1,para2=50)
D <- simCOP(n=950, cop=composite2COP, para=para, col=grey(0, 0.2), pch=16, snv=TRUE) #
## End(Not run)

wasquith/copBasic documentation built on Dec. 13, 2024, 6:39 p.m.