HIGHLY EXPERIMENTAL AND SUBJECT TO OVERHAUL OR REMOVAL---Compute an analog to the line of organic correlation (reduced major axis) using the diagonal of a copula.
$$\mathrm{Pr}[U \le u, V \le v] = \mathbf{C}(u,v) = f\mbox{.}$$
The primary diagonal is defined as $$\mathbf{\delta}_\mathbf{C}(t) = \mathbf{C}(t,t) = f\mbox{.}$$
Two diagnostic plots can be plotted by the arguments available for this function. The plot for \((U,V)\) coordinate nonexceedance probability domain along with the analyses involving the copula diagonal inversion comes first, which is followed by that for \((X,Y)\) coordinate domain along with the well-known line of organic correlation by the method of L-moments and such a “line” (could be a curve) by copula diagonal inversion.
This much infrastructure written for flexibility in how a copula would interact for the purpose of estimation with moment preservation. The simple \(u = v\) might be sufficient but let us have some flexibility.
bicoploc(xp, yp=NULL, xout=NA, xpara=NULL, ypara=NULL, dtypex="nor", dtypey="nor",
ctype=c("weibull", "hazen", "bernstein", "checkerboard"), kumaraswamy=TRUE,
plotuv=TRUE, plotxy=TRUE, adduv=FALSE, addxy=FALSE, snv=FALSE, limout=TRUE,
autoleg=TRUE, xleg="topleft", yleg=NULL, rugxy=TRUE, ruglwd=0.5,
xlim=NULL, ylim=NULL, titleuv="", titlexy="", titlecex=1,
a=0, ff=pnorm(seq(-5, +5, by=0.1)), locdigits=6,
paracop=TRUE, verbose=TRUE, x=NULL, y=NULL, ...)Lists, vectors, and data frames for the computations and predictions are returned.
A list containing a data frame of the predictions for xout by the conventional LOC (locpair) (see also locsols$lmrloc), the estimates by the L-moments of the parameters of the marginal distributions (locpara), the estimates by copula diagonal with Kumaraswamy smoothing (if requested) (bicoploc), and the predictions based solely on the empirical copula approximation for the diagonal (bicoploc_emp). The bicoploc and bicoploc_emp are equal to each other if Kumaraswamy was not used. The bicoploc is intended to be the official output from the bicoploc() function. The furthest right column is bicoploc_cop and represents the predicting values using a parametric copula as fit to the \((U,V)\) domain mapped into the \((X,Y)\) domain as explained elsewhere in this documentation or sources;
A list of solutions to the LOC based (1) (locpair) on the conventional definition on the paired data (xp and yp) with the finiteness check previously described by lmomco::lmrloc() and (2) (locpara) the LOC solution not on the paired data but extractable from the L-moments of the parameters for the marginal distributions. Certain permutations of available features will either have the two L-moment solutions equal, or just the slopes equal, or differing in both intercept and slope. The lmrloc list contains both L-moment and product moment estimation of the LOC to adhere precisely to lmomco::lmrloc() output;
The parameters of the marginal distribution in \(X\) either as given in xpara, as estimated from xp, or estimated from x by the method of L-moments through the lmomco package;
The parameters of the marginal distribution in \(Y\) either as given in ypara, as estimated from yp, or estimated from y by the method of L-moments through the lmomco package;
A named vector containing some numerical facts about the operations and principally the requisite sample sizes involved are reported here;
A named vector containing some numerical facts about the operations involving the fitting of the parametric asymmetric copula (Plackett by default) to the \((U,V)\) domain; and
A data frame containing information on the copula diagonal including the joint probability column jtprob (the ff as stand in for \(C(t,t) = f\)), the \(u=v=t\) in column uv by the Kumaraswamy smooth (if requested), and the solely empirical copula version in column uv_emp. If the Kumaraswamy smooth is not used, then uv and uv_emp will be equal to each other. The furthest right column is uv_cop and represents the values using a parametric copula as fit to the \((U,V)\) domain as explained elsewhere in this documentation or sources.
Numeric vector giving paired data points of \(X\). If this is a matrix or data frame, then the first and second columns are extracted for the xp and yp internall;
Optional numeric vector giving paired data points of \(Y\) depending on the composition of x;
An optional set of numeric values specifying where interpolation through the diagonal inversion is to take place;
An lmomco package parameter object for the \(X\) variable, which if not provided will trigger an method of L-moment parameter estimation for the distribution dtypex;
An lmomco package parameter object for the \(Y\) variable, which if not provided will trigger an method of L-moment parameter estimation for the distribution dtypey;
The lmomco package distribution abbreviations (see lmomco::dist.list()) for the \(X\) variable. If this argument is set NULL and xpara is given with an element of type, then that distribution type is assigned internally to dtypex;
The lmomco package distribution abbreviations (see lmomco::dist.list()) for the \(Y\) variable; If this argument is set NULL and xpara is given with an element of type, then that distribution type is assigned internally to dtypex;
Argument of the same name for the empirical copula for dispatch to EMPIRcop. The 1/n form is disabled for bicoploc operations based on limited experiments. The first letter of the argument's value is extracted, converted to upper case, and used as the plotting character in the two diagnostic plots;
A logical to trigger Kumaraswamy distribution smoothing of the copula diagonal inversion from the empricial copula. The Kumaraswamy distribution is a distribution having support \([0,1]\) with an explicit quantile function and takes the place of a Beta distribution (see lmomco function quakur() for more details). The smoothing by Kumaraswamy will provide a continuous real number on the interval, which should insure no flat-lining as one rolls on to or off off the discrete interval provided by the empirical copula for expected sample sizes of the operations anticipated for the bicoploc function;
A logical to trigger plotting of the analyses in the \((U,V)\) coordinate nonexceedance probability domain along with the analyses involving the copula diagonal inversion. If set true, then adduv is set false internally;
A logical to trigger plotting of the analyses in the \((X,Y)\) coordinate domain along with the well-known line of organic correlation by the method of L-moments and such a “line” (could be a curve) by copula diagonal inversion. If set true, then addxy is set false internally;
A logical when set true will not call the plot() function for \((U,V)\) coordinate nonexceedance probability domain but the other graphical operations of lines and points will be called;
A logical when set true will not call the plot() function for \((X,Y)\) coordinate domain but the other graphical operations of lines and points will be called;
A logical when set true will plot the \((U,V)\) coordinate nonexceedance probability domain in units of standard normal variates;
A logical when set true will plot the \((X,Y)\) coordinate domain with horizontal and vertical axis limits inflated to the xout and \(Y\) predictions;
A logical when set will draw a legend for the plots if the plots are requested;
The value to become the argument x in the legend() call. The default setting is based on general assumption that this bicoploc() function is to be more commonly used in positive assocation circumstances between \(X\) and \(Y\) (positive Spearman Rho);
The value to become the argument y in the legend() call;
Call rug() plotting operations on the \(X\) and \(Y\) values used in the parameter estimation of the parametric marginal distributions using the xp and yp, unless either or both have been overridden for the contents in x and (or) y arguments;
The line wide passed into rug(). Because plotting of small and large sample sizes can make it difficult in the smaller samples to see the line, it is judged useful to explicitly have this setting as an declared argument;
A numeric vector that if precisely of length 2 and no missing values therein, will override the horizontal limits of the plotxy plot of the \((X,Y)\) domain. Otherwise, the contents of xlim, if not null, are inserted into a range computation for the limits to apply;
A numeric vector that if precisely of length 2 and no missing values therein, will override the vertical limits of the plotxy plot of the \((X,Y)\) domain. Otherwise, the contents of ylim, if not null, are inserted into a range computation for the limits to apply;
An optional title for the \((U,V)\) domain plot;
An optional title for the \((X,Y)\) domain plot;
The character expansion factor for the titles;
Value for the plotting-position formula for lmomco::pp(), default is a=0, which specifies Weibull plotting positions;
The nonexceedance joint probability of of the copula diagonal from which inversion computes the marginal nonexceedance probability values for \(u=v=t\) as \(\mathbf{C}(t,t) = f\) where ff is the variable notation for the joint probability \(f\);
Number of digits for rounding exclusive to the loc data frame produced in the returned list. The reasoning for this setting is that the expected application in practical circumstances will have discipline knowledge of the rounding depth suitable;
A logical trigging the use of the parametric asymmetric copula fit by numerical optimization to the \((U,V)\) domain of the data (see Details);
Show messages of incremental progress with a incremental counter on the message;
Numeric vector of \(X\) values to be used in parameter estimation of the marginal parametric distribution if xpara=NULL and these values are internally replaced with xp (paired \(X\)) if not otherwise specified. This provides the ability to insert an alternative and presumably longer vector of the entire \(X\) sample without the restriction of individual values paired to the \(Y\). A feature unique to providing the x is that missing values can be and are removed on the fly prior to parameter estimation of the marginal distribution. The x can be specific independent of y or even at all for either. Absolutely no provision is made that x can be a matrix or data frame holding the y;
Numeric vector of \(Y\) values to be used in parameter estimation of the marginal parametric distribution if ypara=NULL and these values are internally replaced with yp (paired \(Y\)) if not otherwise specified. This provides the ability to insert an alternative and presumably longer vector of the entire \(Y\) sample without the restriction of individual values paired to the \(X\). A feature unique to providing the y is that missing values can be and are removed on the fly prior to parameter estimation of the marginal distribution. The x can be specific independent of y or even at all for either; and
Additional arguments to pass.
W.H. Asquith
ON THE USE OF AN PARAMETRIC ASYMMETRIC COPULA---
Kruskal, W.H., 1953, On the uniqueness of the line of organic correlation: Biometrics, vol. 9, no. 1, pp. 47--58, tools:::Rd_expr_doi("10.2307/3001632").
diagCOPatf