, Xingjie Shi [ctb]
(Author of an R implementation of the FABS algorithm available
at https://github.com/shuanggema/Fabs, of which function
Lorenz.FABS is derived)| Title: | Lorenz and Penalized Lorenz Regressions |
|---|---|
| Description: | Inference for the Lorenz and penalized Lorenz regressions. More broadly, the package proposes functions to assess inequality and graphically represent it. The Lorenz Regression procedure is introduced in Heuchenne and Jacquemain (2022) <doi:10.1016/j.csda.2021.107347> and in Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024) <doi:10.1214/23-EJS2200>. |
| Authors: | Alexandre Jacquemain [aut, cre]
, Xingjie Shi [ctb]
(Author of an R implementation of the FABS algorithm available
at https://github.com/shuanggema/Fabs, of which function
Lorenz.FABS is derived) |
| Maintainer: | Alexandre Jacquemain <[email protected]> |
| License: | GPL-3 |
| Version: | 2.1.0 |
| Built: | 2025-01-10 06:53:14 UTC |
| Source: | CRAN |
autoplot generates a plot for an object of class "LR" and returns it as a ggplot object.
The plot method is a wrapper around autoplot that directly displays the plot,
providing a more familiar interface for users accustomed to base R plotting.
## S3 method for class 'LR' autoplot(object, ...) ## S3 method for class 'LR' plot(x, ...)## S3 method for class 'LR' autoplot(object, ...) ## S3 method for class 'LR' plot(x, ...)
object |
An object of class |
... |
Additional arguments passed to |
x |
An object of class |
autoplot returns a ggplot object representing the Lorenz curve of the response and the concentration curve of the response with respect to the estimated index. plot directly displays this plot.
## For examples see example(Lorenz.Reg)## For examples see example(Lorenz.Reg)
autoplot generates summary plots for an object of class "PLR" and returns them as ggplot objects.
The plot method is a wrapper around autoplot that directly displays the plot,
providing a more familiar interface for users accustomed to base R plotting.
## S3 method for class 'PLR' autoplot( object, type = c("explained", "traceplot", "diagnostic"), traceplot.which = "BIC", score.df = NULL, ... ) ## S3 method for class 'PLR' plot(x, ...)## S3 method for class 'PLR' autoplot( object, type = c("explained", "traceplot", "diagnostic"), traceplot.which = "BIC", score.df = NULL, ... ) ## S3 method for class 'PLR' plot(x, ...)
object |
An object of class |
type |
A character string indicating the type of plot. Possible values are
|
traceplot.which |
This argument indicates the value of the grid parameter for which the traceplot should be produced (see arguments |
score.df |
A data.frame providing the scores to be displayed if |
... |
Additional arguments passed to function |
x |
An object of class |
The available selection methods depend on the classes of the object: BIC is always available, bootstrap is available if object inherits from "PLR_boot", cross-validation is available if object inherits from "PLR_cv"
autoplot returns a ggplot object representing the desired graph. plot directly displays this plot.
## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)
Provides the estimated coefficients for an object of class "LR".
## S3 method for class 'LR' coef(object, ...)## S3 method for class 'LR' coef(object, ...)
object |
An object of S3 class |
... |
Additional arguments. |
a vector gathering the estimated coefficients
## For examples see example(Lorenz.Reg)## For examples see example(Lorenz.Reg)
Provides the estimated coefficients for an object of class "PLR".
## S3 method for class 'PLR' coef(object, renormalize = TRUE, pars.idx = "BIC", ...)## S3 method for class 'PLR' coef(object, renormalize = TRUE, pars.idx = "BIC", ...)
object |
An object of S3 class |
renormalize |
A logical value determining whether the coefficient vector should be re-normalized to match the representation where the first category of each categorical variable is omitted. Default value is TRUE |
pars.idx |
What grid and penalty parameters should be used for parameter selection. Either a character string specifying the selection method, where the possible values are:
Or a numeric vector of length 2, where the first element is the index of the grid parameter and the second is the index of the penalty parameter. |
... |
Additional arguments |
a vector gathering the estimated coefficients.
## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)
Provides bootstrap confidence intervals for the explained Gini coefficient, Lorenz-R2 and theta vector for an object of class "LR_boot".
## S3 method for class 'LR_boot' confint( object, parm = c("Gini", "LR2", "theta"), level = 0.95, type = c("norm", "basic", "perc"), bias.corr = TRUE, ... )## S3 method for class 'LR_boot' confint( object, parm = c("Gini", "LR2", "theta"), level = 0.95, type = c("norm", "basic", "perc"), bias.corr = TRUE, ... )
object |
An object of class |
parm |
A logical value determining whether the confidence interval is computed for the explained Gini coefficient, for the Lorenz- |
level |
A numeric giving the level of the confidence interval. Default value is 0.95. |
type |
A character string specifying the bootstrap method. Possible values are |
bias.corr |
A logical determining whether bias correction should be performed. Only used if |
... |
Additional arguments. |
The desired confidence interval.
If parm="Gini" or parm="LR2", the output is a vector.
If parm="theta", it is a matrix where each row corresponds to a different coefficient.
## For examples see example(Lorenz.boot)## For examples see example(Lorenz.boot)
Provides bootstrap confidence intervals for the explained Gini coefficient and Lorenz- for an object of class "PLR_boot".
## S3 method for class 'PLR_boot' confint( object, parm = c("Gini", "LR2"), level = 0.95, type = c("norm", "basic", "perc"), pars.idx = "BIC", bias.corr = TRUE, ... )## S3 method for class 'PLR_boot' confint( object, parm = c("Gini", "LR2"), level = 0.95, type = c("norm", "basic", "perc"), pars.idx = "BIC", bias.corr = TRUE, ... )
object |
An object of class |
parm |
A character string determining whether the confidence interval is computed for the explained Gini coefficient or for the Lorenz- |
level |
A numeric giving the level of the confidence interval. Default value is 0.95. |
type |
A character string specifying the bootstrap method. Possible values are |
pars.idx |
What grid and penalty parameters should be used for parameter selection. Either a character string specifying the selection method, where the possible values are:
Or a numeric vector of length 2, where the first element is the index of the grid parameter and the second is the index of the penalty parameter. |
bias.corr |
A logical determining whether bias correction should be performed. Only used if |
... |
Additional arguments. |
A vector providing the desired confidence interval.
## For examples see example(Lorenz.boot)## For examples see example(Lorenz.boot)
Fictitious cross-sectional dataset used to illustrate the Lorenz regression methodology. It covers 7 variables for 200 individuals aged between 25 and 30 years.
data(Data.Incomes)data(Data.Incomes)
A data frame with 200 rows and 7 columns:
Individual's labor income
Sex (0=Female, 1=Male)
Variable ranging from 0 to 10 indicating the individual health's level (0 is worst, 10 is best)
Individual's age in years, ranging from 25 to 30
Individual's weekly work hours
Individual's highest grade completed in years
Length of service in years with the individual's employer
diagnostic.PLR provides diagnostic information for an object of class "PLR"
It restricts the path of the PLR to pairs of parameters (grid, lambda) that satisfy a threshold criterion.
diagnostic.PLR( object, tol = 0.99, method = c("union", "intersect", "BIC", "Boot", "CV") )diagnostic.PLR( object, tol = 0.99, method = c("union", "intersect", "BIC", "Boot", "CV") )
object |
An object of class |
tol |
A numeric threshold value used to restrict the PLR path. More specifically, we restrict to pairs (grid,lambda) whose normalized score exceeds |
method |
A character string specifying the method used to evaluate the scores.
Options are
|
A list with two elements:
pathThe restricted model path, containing only the values of the pair (grid, lambda) that satisfy the threshold criterion.
bestThe best model. It is obtained by considering the pair (grid, lambda) in the restricted path that leads to the sparsest model. If several pairs yield the same level of sparsity, we consider the pair that maximizes the minimum score across all selection methods available.
# Continuing the Lorenz.boot(.) example: # The out-of-bag score seems to remain relatively flat when lambda is small enough plot(PLR_boot, type = "diagnostic") # What is the best pair (grid,penalty) parameter that is close enough to the highest OOB score diagnostic.PLR(PLR_boot, tol = 0.99, method = "Boot") # We want the solution to be close to the best, for both the BIC and OOB scores. diagnostic.PLR(PLR_boot, method = "intersect")# Continuing the Lorenz.boot(.) example: # The out-of-bag score seems to remain relatively flat when lambda is small enough plot(PLR_boot, type = "diagnostic") # What is the best pair (grid,penalty) parameter that is close enough to the highest OOB score diagnostic.PLR(PLR_boot, tol = 0.99, method = "Boot") # We want the solution to be close to the best, for both the BIC and OOB scores. diagnostic.PLR(PLR_boot, method = "intersect")
Gini.coef computes the concentration index of a vector y with respect to another vector x.
If y and x are identical, the obtained concentration index boils down to the Gini coefficient.
Gini.coef( y, x = y, na.rm = TRUE, ties.method = c("mean", "random"), seed = NULL, weights = NULL )Gini.coef( y, x = y, na.rm = TRUE, ties.method = c("mean", "random"), seed = NULL, weights = NULL )
y |
variable of interest. |
x |
variable to use for the ranking. By default |
na.rm |
should missing values be deleted. Default value is |
ties.method |
What method should be used to break the ties in the rank index. Possible values are "mean" (default value) or "random". If "random" is selected, the ties are broken by further ranking in terms of a uniformly distributed random variable. If "mean" is selected, the average rank method is used. |
seed |
fixes what seed is imposed for the generation of the vector of uniform random variables used to break the ties. Default is NULL, in which case no seed is imposed. |
weights |
vector of sample weights. By default, each observation is given the same weight. |
The parameter seed allows for local seed setting to control randomness in the generation of the uniform random variables.
The specified seed is applied to the respective part of the computation, and the seed is reverted to its previous state after the operation.
This ensures that the seed settings do not interfere with the global random state or other parts of the code.
The value of the concentration index (or Gini coefficient)
data(Data.Incomes) # We first compute the Gini coefficient of Income Y <- Data.Incomes$Income Gini.coef(y = Y) # Then we compute the concentration index of Income with respect to Age X <- Data.Incomes$Age Gini.coef(y = Y, x = X)data(Data.Incomes) # We first compute the Gini coefficient of Income Y <- Data.Incomes$Income Gini.coef(y = Y) # Then we compute the concentration index of Income with respect to Age X <- Data.Incomes$Age Gini.coef(y = Y, x = X)
This generic function extracts a measure of explained inequality, such as the explained Gini coefficient or the Lorenz-R2, from a fitted model object.
ineqExplained(object, type = c("Gini.explained", "Lorenz-R2"), ...)ineqExplained(object, type = c("Gini.explained", "Lorenz-R2"), ...)
object |
An object for which the inequality metrics should be extracted. |
type |
Character string specifying the type of inequality metric to retrieve. Options are |
... |
Additional arguments passed to specific methods. |
The requested inequality metric.
## For examples see example(Lorenz.Reg)## For examples see example(Lorenz.Reg)
Retrieves the explained Gini coefficient or the Lorenz- from an object of class "LR".
## S3 method for class 'LR' ineqExplained(object, type = c("Gini.explained", "Lorenz-R2"), ...)## S3 method for class 'LR' ineqExplained(object, type = c("Gini.explained", "Lorenz-R2"), ...)
object |
An object of S3 class |
type |
Character string specifying the type of inequality metric to retrieve. Options are |
... |
Additional arguments. |
A numeric value representing the requested inequality metric.
Retrieves the explained Gini coefficient or the Lorenz- from an object of class "PLR".
## S3 method for class 'PLR' ineqExplained( object, type = c("Gini.explained", "Lorenz-R2"), pars.idx = "BIC", ... )## S3 method for class 'PLR' ineqExplained( object, type = c("Gini.explained", "Lorenz-R2"), pars.idx = "BIC", ... )
object |
An object of S3 class |
type |
Character string specifying the type of inequality metric to retrieve. Options are |
pars.idx |
What grid and penalty parameters should be used for parameter selection. Either a character string specifying the selection method, where the possible values are:
Or a numeric vector of length 2, where the first element is the index of the grid parameter and the second is the index of the penalty parameter. |
... |
Additional arguments. |
A numeric value representing the requested inequality metric.
Lorenz.boot determines bootstrap estimators for the vector of coefficients of the single-index model, explained Gini coefficient and Lorenz-. In the penalized case, it also provides a selection method.
Lorenz.boot(object, R, boot_out_only = FALSE, ...)Lorenz.boot(object, R, boot_out_only = FALSE, ...)
object |
An object with S3 class |
R |
An integer indicating the number of bootstrap replicates. |
boot_out_only |
A logical determining whether the function should return raw bootstrap results. This is an advanced feature that helps save computation time in certain instances. See Details. |
... |
Additional parameters corresponding to arguments passed to the function |
Users that want to perform parallel computing have two options. The first and most obvious option is to use the facilities provided by the function boot.
Indeed, arguments such as parallel, ncpus and cl can be passed through the ....
Alternatively, users might want to run different instances of the function, each taking care of a portion of the bootstrap samples.
The argument boot_out_only can be set to TRUE to avoid unnecessary computations. If so, the returned object does not inherit from the class "LR_boot" or "PLR_boot". The function simply returns the original object, to which is added the boot_out object.
If this second option is chosen, the instances have to be combined using the function Lorenz.boot.combine.
An object of class c("LR_boot", "LR") or c("PLR_boot", "PLR"), depending on whether a non-penalized or penalized regression was fitted.
The methods confint.LR and confint.PLR are used on objects of class "LR_boot" or "PLR_boot" to construct confidence intervals for the model parameters.
For the non-penalized Lorenz regression, the returned object is a list containing the following components:
thetaThe estimated vector of parameters. In the penalized case, it is a matrix where each row corresponds to a different selection method (e.g., BIC, bootstrap, cross-validation).
Gi.explThe estimated explained Gini coefficient. In the penalized case, it is a vector, where each element corresponds to a different selection method.
LR2The Lorenz- of the regression. In the penalized case, it is a vector, where each element corresponds to a different selection method.
boot_outAn object of class "boot" containing the output of the bootstrap calculation.
For the penalized Lorenz regression, the returned object is a list containing the following components:
pathSee Lorenz.Reg for the original path. To this path is added the out-of-bag (OOB) score.
lambda.idxA vector indicating the index of the optimal lambda obtained by each selection method.
grid.idxA vector indicating the index of the optimal grid parameter obtained by each selection method.
Note: in the penalized case, the returned object may have additional classes such as "PLR_cv" if cross-validation was performed and used as a selection method.
Heuchenne, C. and A. Jacquemain (2022). Inference for monotone single-index conditional means: A Lorenz regression approach. Computational Statistics & Data Analysis 167(C).
Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024). A penalised bootstrap estimation procedure for the explained Gini coefficient. Electronic Journal of Statistics 18(1) 247-300.
Lorenz.Reg, Lorenz.GA, Lorenz.SCADFABS, Lorenz.FABS, PLR.CV, boot
# Continuing the Lorenz.Reg(.) example for the non-penalized regression: # This example is not run as it takes > 5 seconds to run. ## Not run: set.seed(123) NPLR_boot <- Lorenz.boot(NPLR, R = 30) # The method confint() is available to objects of class "LR_boot". confint(NPLR_boot) summary(NPLR_boot) ## End(Not run) # Continuing the Lorenz.Reg(.) example for the penalized regression: set.seed(123) PLR_boot <- Lorenz.boot(PLR, R = 20) # The object now inherits from the class "PLR_boot" # Hence the methods (also) display the results obtained by bootstrap. print(PLR_boot) summary(PLR_boot) coef(PLR_boot, pars.idx = "Boot") predict(PLR_boot, pars.idx = "Boot") plot(PLR_boot) # Plot of the scores for each selection method depending on the grid and penalty parameters plot(PLR_boot, type = "diagnostic") # The method confint() is available to objects of class "PLR_boot". confint(PLR_boot, pars.idx = "BIC") # Using the tuning parameters selected by BIC confint(PLR_boot, pars.idx = "Boot") # Using the tuning parameters selected by bootstrap# Continuing the Lorenz.Reg(.) example for the non-penalized regression: # This example is not run as it takes > 5 seconds to run. ## Not run: set.seed(123) NPLR_boot <- Lorenz.boot(NPLR, R = 30) # The method confint() is available to objects of class "LR_boot". confint(NPLR_boot) summary(NPLR_boot) ## End(Not run) # Continuing the Lorenz.Reg(.) example for the penalized regression: set.seed(123) PLR_boot <- Lorenz.boot(PLR, R = 20) # The object now inherits from the class "PLR_boot" # Hence the methods (also) display the results obtained by bootstrap. print(PLR_boot) summary(PLR_boot) coef(PLR_boot, pars.idx = "Boot") predict(PLR_boot, pars.idx = "Boot") plot(PLR_boot) # Plot of the scores for each selection method depending on the grid and penalty parameters plot(PLR_boot, type = "diagnostic") # The method confint() is available to objects of class "PLR_boot". confint(PLR_boot, pars.idx = "BIC") # Using the tuning parameters selected by BIC confint(PLR_boot, pars.idx = "Boot") # Using the tuning parameters selected by bootstrap
Lorenz.boot.combine combine outputs of different instances of the Lorenz.boot function.
Lorenz.boot.combine(boot_list)Lorenz.boot.combine(boot_list)
boot_list |
list of objects, each element being the output of a call to the function |
An object of class c("LR_boot", "LR") or c("PLR_boot", "PLR"), depending on whether a non-penalized or penalized regression was fitted.
The method confint is used on an object of class "LR_boot" or "PLR_boot" to obtain bootstrap inference on the model parameters.
For the non-penalized Lorenz regression, the returned object is a list containing the following components:
thetaThe estimated vector of parameters. In the penalized case, it is a matrix where each row corresponds to a different selection method (e.g., BIC, bootstrap, cross-validation).
Gi.explThe estimated explained Gini coefficient. In the penalized case, it is a vector, where each element corresponds to a different selection method.
LR2The Lorenz- of the regression. In the penalized case, it is a vector, where each element corresponds to a different selection method.
boot_outAn object of class "boot" containing the output of the bootstrap calculation.
For the penalized Lorenz regression, the returned object is a list containing the following components:
pathSee Lorenz.Reg for the original path. To this path is added the out-of-bag (OOB) score.
lambda.idxA vector indicating the index of the optimal lambda obtained by each selection method.
grid.idxA vector indicating the index of the optimal grid parameter obtained by each selection method.
Note: The returned object may have additional classes such as "PLR_cv" if cross-validation was performed and used as a selection method in the penalized case.
Heuchenne, C. and A. Jacquemain (2022). Inference for monotone single-index conditional means: A Lorenz regression approach. Computational Statistics & Data Analysis 167(C).
Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024). A penalised bootstrap estimation procedure for the explained Gini coefficient. Electronic Journal of Statistics 18(1) 247-300.
# Continuing the Lorenz.Reg(.) example for the penalized regression: boot_list <- list() set.seed(123) boot_list[[1]] <- Lorenz.boot(PLR, R = 10, boot_out_only = TRUE) set.seed(456) boot_list[[2]] <- Lorenz.boot(PLR, R = 10, boot_out_only = TRUE) PLR_boot <- Lorenz.boot.combine(boot_list) summary(PLR_boot)# Continuing the Lorenz.Reg(.) example for the penalized regression: boot_list <- list() set.seed(123) boot_list[[1]] <- Lorenz.boot(PLR, R = 10, boot_out_only = TRUE) set.seed(456) boot_list[[2]] <- Lorenz.boot(PLR, R = 10, boot_out_only = TRUE) PLR_boot <- Lorenz.boot.combine(boot_list) summary(PLR_boot)
Lorenz.curve computes the concentration curve index of a vector y with respect to another vector x.
If y and x are identical, the obtained concentration curve boils down to the Lorenz curve.
Lorenz.curve( y, x = y, graph = FALSE, na.rm = TRUE, ties.method = c("mean", "random"), seed = NULL, weights = NULL )Lorenz.curve( y, x = y, graph = FALSE, na.rm = TRUE, ties.method = c("mean", "random"), seed = NULL, weights = NULL )
y |
variable of interest. |
x |
variable to use for the ranking. By default |
graph |
whether a graph of the obtained concentration curve should be traced. Default value is FALSE. |
na.rm |
should missing values be deleted. Default value is |
ties.method |
What method should be used to break the ties in the rank index. Possible values are "mean" (default value) or "random". If "random" is selected, the ties are broken by further ranking in terms of a uniformly distributed random variable. If "mean" is selected, the average rank method is used. |
seed |
seed imposed for the generation of the vector of uniform random variables used to break the ties. Default is NULL, in which case no seed is imposed. |
weights |
vector of sample weights. By default, each observation is given the same weight. |
The parameter seed allows for local seed setting to control randomness in the generation of the uniform random variables.
The specified seed is applied to the respective part of the computation, and the seed is reverted to its previous state after the operation.
This ensures that the seed settings do not interfere with the global random state or other parts of the code.
A function corresponding to the estimated Lorenz or concentration curve. If graph is TRUE, the curve is also plotted.
data(Data.Incomes) # We first compute the Lorenz curve of Income Y <- Data.Incomes$Income Lorenz.curve(y = Y, graph = TRUE) # Then we compute the concentration curve of Income with respect to Age X <- Data.Incomes$Age Lorenz.curve(y = Y, x = X, graph = TRUE)data(Data.Incomes) # We first compute the Lorenz curve of Income Y <- Data.Incomes$Income Lorenz.curve(y = Y, graph = TRUE) # Then we compute the concentration curve of Income with respect to Age X <- Data.Incomes$Age Lorenz.curve(y = Y, x = X, graph = TRUE)
Lorenz.FABS solves the penalized Lorenz regression with (adaptive) Lasso penalty on a grid of lambda values.
For each value of lambda, the function returns estimates for the vector of parameters and for the estimated explained Gini coefficient, as well as the Lorenz- of the regression.
Lorenz.FABS( y, x, standardize = TRUE, weights = NULL, kernel = 1, h = length(y)^(-1/5.5), gamma = 0.05, lambda = "Shi", w.adaptive = NULL, eps = 0.005, iter = 10^4, lambda.min = 1e-07 )Lorenz.FABS( y, x, standardize = TRUE, weights = NULL, kernel = 1, h = length(y)^(-1/5.5), gamma = 0.05, lambda = "Shi", w.adaptive = NULL, eps = 0.005, iter = 10^4, lambda.min = 1e-07 )
y |
a vector of responses |
x |
a matrix of explanatory variables |
standardize |
Should the variables be standardized before the estimation process? Default value is TRUE. |
weights |
vector of sample weights. By default, each observation is given the same weight. |
kernel |
integer indicating what kernel function to use. The value 1 is the default and implies the use of an Epanechnikov kernel while the value of 2 implies the use of a biweight kernel. |
h |
bandwidth of the kernel, determining the smoothness of the approximation of the indicator function. Default value is n^(-1/5.5) where n is the sample size. |
gamma |
value of the Lagrange multiplier in the loss function |
lambda |
this parameter relates to the regularization parameter. Several options are available.
|
w.adaptive |
vector of size equal to the number of covariates where each entry indicates the weight in the adaptive Lasso. By default, each covariate is given the same weight (Lasso). |
eps |
step size in the FABS algorithm. Default value is 0.005. |
iter |
maximum number of iterations. Default value is 10^4. |
lambda.min |
lower bound of the penalty parameter. Only used if |
The regression is solved using the FABS algorithm developed by Shi et al (2018) and adapted to our case. For a comprehensive explanation of the Penalized Lorenz Regression, see Jacquemain et al. In order to ensure identifiability, theta is forced to have a L2-norm equal to one.
A list with several components:
lambdavector gathering the different values of the regularization parameter
thetamatrix where column i provides the vector of estimated coefficients corresponding to the value lambda[i] of the regularization parameter.
LR2vector where element i provides the Lorenz- attached to the value lambda[i] of the regularization parameter.
Gi.explvector where element i provides the estimated explained Gini coefficient related to the value lambda[i] of the regularization parameter.
Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024). A penalised bootstrap estimation procedure for the explained Gini coefficient. Electronic Journal of Statistics 18(1) 247-300.
Shi, X., Y. Huang, J. Huang, and S. Ma (2018). A Forward and Backward Stagewise Algorithm for Nonconvex Loss Function with Adaptive Lasso, Computational Statistics & Data Analysis 124, 235-251.
data(Data.Incomes) y <- Data.Incomes[,1] x <- as.matrix(Data.Incomes[,-c(1,2)]) Lorenz.FABS(y, x)data(Data.Incomes) y <- Data.Incomes[,1] x <- as.matrix(Data.Incomes[,-c(1,2)]) Lorenz.FABS(y, x)
Lorenz.GA estimates the coefficient vector of the single-index model.
It also returns the Lorenz- of the regression as well as the estimated explained Gini coefficient.
Lorenz.GA( y, x, standardize = TRUE, weights = NULL, popSize = 50, maxiter = 1500, run = 150, ties.method = c("random", "mean"), ties.Gini = c("random", "mean"), seed.random = NULL, seed.Gini = NULL, seed.GA = NULL, parallel.GA = FALSE )Lorenz.GA( y, x, standardize = TRUE, weights = NULL, popSize = 50, maxiter = 1500, run = 150, ties.method = c("random", "mean"), ties.Gini = c("random", "mean"), seed.random = NULL, seed.Gini = NULL, seed.GA = NULL, parallel.GA = FALSE )
y |
a vector of responses |
x |
a matrix of explanatory variables |
standardize |
Should the variables be standardized before the estimation process? Default value is TRUE. |
weights |
vector of sample weights. By default, each observation is given the same weight. |
popSize |
Size of the population of candidates in the genetic algorithm. Default value is 50. |
maxiter |
Maximum number ot iterations in the genetic algorithm. Default value is 1500. |
run |
Number of iterations without improvement in the best fitness necessary for the algorithm to stop. Default value is 150. |
ties.method |
What method should be used to break the ties in optimization program. Possible values are "random" (default value) or "mean". If "random" is selected, the ties are broken by further ranking in terms of a uniformly distributed random variable. If "mean" is selected, the average rank method is used. |
ties.Gini |
what method should be used to break the ties in the computation of the Gini coefficient at the end of the algorithm. Possible values and default choice are the same as above. |
seed.random |
An optional seed for generating the vector of uniform random variables used to break ties in the genetic algorithm. Defaults to |
seed.Gini |
An optional seed for generating the vector of uniform random variables used to break ties in the computation of the Gini coefficient. Defaults to |
seed.GA |
An optional seed for |
parallel.GA |
Whether parallel computing should be used to distribute the computations in the genetic algorithm. Either a logical value determining whether parallel computing is used (TRUE) or not (FALSE, the default value). Or a numerical value determining the number of cores to use. |
The genetic algorithm is solved using function ga from the GA package. The fitness function is coded in Rcpp to speed up computation time.
When discrete covariates are introduced and ties occur in the index, the default option randomly breaks them, as advised in Section 3 of Heuchenne and Jacquemain (2022)
The parameters seed.random, seed.Gini, and seed.GA allow for local seed setting to control randomness in specific parts of the function.
Each seed is applied to the respective part of the computation, and the seed is reverted to its previous state after the operation.
This ensures that the seed settings do not interfere with the global random state or other parts of the code.
A list with several components:
thetathe estimated vector of parameters.
LR2the Lorenz- of the regression.
Gi.explthe estimated explained Gini coefficient.
niternumber of iterations attained by the genetic algorithm.
fitvalue attained by the fitness function at the optimum.
Heuchenne, C. and A. Jacquemain (2022). Inference for monotone single-index conditional means: A Lorenz regression approach. Computational Statistics & Data Analysis 167(C).
data(Data.Incomes) y <- Data.Incomes$Income x <- cbind(Data.Incomes$Age, Data.Incomes$Work.Hours) Lorenz.GA(y, x, popSize = 40)data(Data.Incomes) y <- Data.Incomes$Income x <- cbind(Data.Incomes$Age, Data.Incomes$Work.Hours) Lorenz.GA(y, x, popSize = 40)
Lorenz.graphs traces the Lorenz curve of a response and the concentration curve of the response and each of a series of covariates.
Lorenz.graphs(formula, data, difference = FALSE, ...)Lorenz.graphs(formula, data, difference = FALSE, ...)
formula |
A formula object of the form response ~ other_variables. |
data |
A dataframe containing the variables of interest |
difference |
A logical determining whether the vertical axis should be expressed in terms of deviation from perfect equality. Default is |
... |
Further arguments (see Section 'Arguments' in |
A plot comprising
The Lorenz curve of response
The concentration curves of response with respect to each element of other_variables
data(Data.Incomes) Lorenz.graphs(Income ~ Age + Work.Hours, data = Data.Incomes) # Expressing now the vertical axis as the deviation from perfect equality Lorenz.graphs(Income ~ Age + Work.Hours, data = Data.Incomes, difference = TRUE)data(Data.Incomes) Lorenz.graphs(Income ~ Age + Work.Hours, data = Data.Incomes) # Expressing now the vertical axis as the deviation from perfect equality Lorenz.graphs(Income ~ Age + Work.Hours, data = Data.Incomes, difference = TRUE)
Lorenz.Reg fits the Lorenz regression of a response with respect to several covariates.
Lorenz.Reg( formula, data, weights, na.action, penalty = c("none", "SCAD", "LASSO"), grid.arg = c("h", "SCAD.nfwd", "eps", "kernel", "a", "gamma"), grid.value = NULL, lambda.list = NULL, ... )Lorenz.Reg( formula, data, weights, na.action, penalty = c("none", "SCAD", "LASSO"), grid.arg = c("h", "SCAD.nfwd", "eps", "kernel", "a", "gamma"), grid.value = NULL, lambda.list = NULL, ... )
formula |
An object of class " |
data |
An optional data frame, list or environment (or object coercible by |
weights |
An optional vector of sample weights to be used in the fitting process. Should be |
na.action |
A function which indicates what should happen when the data contain |
penalty |
A character string specifying the type of penalty on the size of the estimated coefficients of the single-index model.
The default value is |
grid.arg |
A character string specifying the tuning parameter for which a grid is to be constructed, see Details. |
grid.value |
A numeric vector specifying the grid values, see Details. |
lambda.list |
Technical argument used inside the function |
... |
Additional parameters corresponding to arguments passed in |
In the penalized case, the model is fitted for a grid of values of two parameters : the penalty parameter (lambda) and one tuning parameter specified by the arguments grid.arg and grid.value.
The possibles values for grid.arg are tuning parameters of the functions Lorenz.FABS and Lorenz.SCADFABS : ''h'' (the default), ''SCAD.nfwd'',''eps'', ''kernel'', ''a'' and ''gamma''.
The values for the grid are specified with grid.value. The default is NULL, in which case no grid is constructed
An object of class "LR" for the non-penalized Lorenz regression or of class "PLR" for a penalized Lorenz regression.
Several methods are available for both classes to facilitate model analysis.
Use summary.LR or summary.PLR to summarize the model fits.
Extract the coefficients of the single-index model using coef.LR or coef.PLR.
Measures of explained inequality (Gini coefficient and Lorenz-) are retrieved using ineqExplained.LR or ineqExplained.PLR.
Obtain predictions with predict.LR or predict.PLR, and fitted values with fitted.LR or fitted.PLR.
For visual representations of explained inequality, use autoplot.LR and plot.LR, or autoplot.PLR and plot.PLR.
The object of class "LR" is a list containing the following components:
thetaThe estimated vector of parameters.
Gi.explThe estimated explained Gini coefficient.
LR2The Lorenz- of the regression.
The object of class "PLR" is a list containing the following components:
pathA list where the different elements correspond to the values of the grid parameter. Each element is a matrix where the first line displays the vector of lambda values. The second and third lines display the evolution of the Lorenz- and explained Gini coefficient along that vector. The next lines display the evolution of the BIC score. The remaining lines display the evolution of the estimated coefficients of the single-index model.
lambda.idxthe index of the optimal lambda obtained by the BIC method
grid.idxthe index of the optimal grid parameter obtained by the BIC method.
In both cases, the list also provides technical information, such as the specified formula, weights and call, as well as the design matrix x and the response vector y.
Heuchenne, C. and A. Jacquemain (2022). Inference for monotone single-index conditional means: A Lorenz regression approach. Computational Statistics & Data Analysis 167(C).
Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024). A penalised bootstrap estimation procedure for the explained Gini coefficient. Electronic Journal of Statistics 18(1) 247-300.
Lorenz.GA, Lorenz.SCADFABS, Lorenz.FABS, Lorenz.boot
data(Data.Incomes) set.seed(123) data <- Data.Incomes[sample(1:200,40),] # 1. Non-penalized regression NPLR <- Lorenz.Reg(Income ~ ., data = Data.Incomes, penalty = "none", popSize = 15) # 2. Penalized regression PLR <- Lorenz.Reg(Income ~ ., data = Data.Incomes, penalty = "SCAD", eps = 0.06, grid.arg = "h", grid.value=c(0.5,1,2)*nrow(Data.Incomes)^(-1/5.5)) # Print method print(NPLR) print(PLR) # Summary method summary(NPLR) summary(PLR) # Coef method coef(NPLR) coef(PLR) # ineqExplained method ineqExplained(NPLR) ineqExplained(PLR) # Predict method ## One can predict either the index or the response predict(NPLR,type="response") predict(PLR,type="response") # Plot method plot(NPLR) plot(PLR) ## Traceplot of the penalized coefficients plot(PLR,type="traceplot")data(Data.Incomes) set.seed(123) data <- Data.Incomes[sample(1:200,40),] # 1. Non-penalized regression NPLR <- Lorenz.Reg(Income ~ ., data = Data.Incomes, penalty = "none", popSize = 15) # 2. Penalized regression PLR <- Lorenz.Reg(Income ~ ., data = Data.Incomes, penalty = "SCAD", eps = 0.06, grid.arg = "h", grid.value=c(0.5,1,2)*nrow(Data.Incomes)^(-1/5.5)) # Print method print(NPLR) print(PLR) # Summary method summary(NPLR) summary(PLR) # Coef method coef(NPLR) coef(PLR) # ineqExplained method ineqExplained(NPLR) ineqExplained(PLR) # Predict method ## One can predict either the index or the response predict(NPLR,type="response") predict(PLR,type="response") # Plot method plot(NPLR) plot(PLR) ## Traceplot of the penalized coefficients plot(PLR,type="traceplot")
Lorenz.SCADFABS solves the penalized Lorenz regression with SCAD penalty on a grid of lambda values.
For each value of lambda, the function returns estimates for the vector of parameters and for the estimated explained Gini coefficient, as well as the Lorenz- of the regression.
Lorenz.SCADFABS( y, x, standardize = TRUE, weights = NULL, kernel = 1, h = length(y)^(-1/5.5), gamma = 0.05, a = 3.7, lambda = "Shi", eps = 0.005, SCAD.nfwd = NULL, iter = 10^4, lambda.min = 1e-07 )Lorenz.SCADFABS( y, x, standardize = TRUE, weights = NULL, kernel = 1, h = length(y)^(-1/5.5), gamma = 0.05, a = 3.7, lambda = "Shi", eps = 0.005, SCAD.nfwd = NULL, iter = 10^4, lambda.min = 1e-07 )
y |
a vector of responses |
x |
a matrix of explanatory variables |
standardize |
Should the variables be standardized before the estimation process? Default value is TRUE. |
weights |
vector of sample weights. By default, each observation is given the same weight. |
kernel |
integer indicating what kernel function to use. The value 1 is the default and implies the use of an Epanechnikov kernel while the value of 2 implies the use of a biweight kernel. |
h |
bandwidth of the kernel, determining the smoothness of the approximation of the indicator function. Default value is n^(-1/5.5) where n is the sample size. |
gamma |
value of the Lagrange multiplier in the loss function |
a |
parameter of the SCAD penalty. Default value is 3.7. |
lambda |
this parameter relates to the regularization parameter. Several options are available.
|
eps |
step size in the FABS algorithm. Default value is 0.005. |
SCAD.nfwd |
optional tuning parameter used if penalty="SCAD". Default value is NULL. The larger the value of this parameter, the sooner the path produced by the SCAD will differ from the path produced by the LASSO. |
iter |
maximum number of iterations. Default value is 10^4. |
lambda.min |
lower bound of the penalty parameter. Only used if lambda="Shi". |
The regression is solved using the SCAD-FABS algorithm developed by Jacquemain et al and adapted to our case. For a comprehensive explanation of the Penalized Lorenz Regression, see Heuchenne et al. In order to ensure identifiability, theta is forced to have a L2-norm equal to one.
A list with several components:
lambdavector gathering the different values of the regularization parameter
thetamatrix where column i provides the vector of estimated coefficients corresponding to the value lambda[i] of the regularization parameter.
LR2vector where element i provides the Lorenz- attached to the value lambda[i] of the regularization parameter.
Gi.explvector where element i provides the estimated explained Gini coefficient related to the value lambda[i] of the regularization parameter.
Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024). A penalised bootstrap estimation procedure for the explained Gini coefficient. Electronic Journal of Statistics 18(1) 247-300.
data(Data.Incomes) y <- Data.Incomes[,1] x <- as.matrix(Data.Incomes[,-c(1,2)]) Lorenz.SCADFABS(y, x)data(Data.Incomes) y <- Data.Incomes[,1] x <- as.matrix(Data.Incomes[,-c(1,2)]) Lorenz.SCADFABS(y, x)
PLR.CV selects the grid and penalization parameters of the penalized Lorenz regression by cross-validation.
PLR.CV(object, k, seed.CV = NULL, parallel = FALSE, ...)PLR.CV(object, k, seed.CV = NULL, parallel = FALSE, ...)
object |
An object with S3 class |
k |
An integer indicating the number of folds in the k-fold cross-validation |
seed.CV |
An optional seed that is used internally for the creation of the folds. Default is |
parallel |
Whether parallel computing should be used to distribute the cross-validation computations. Either a logical value determining whether parallel computing is used (TRUE) or not (FALSE, the default value). Or a numerical value determining the number of cores to use. |
... |
Additional parameters corresponding to arguments passed to the function |
The parameter seed.CV allows for local seed setting to control randomness in the generation of the folds.
The specified seed is applied to the respective part of the computation, and the seed is reverted to its previous state after the operation.
This ensures that the seed settings do not interfere with the global random state or other parts of the code.
An object of class c("PLR_cv", "PLR"). The object is a list containing the following components:
pathSee the Lorenz.Reg function for the documentation of the original path. To this path is added the CV-score.
lambda.idxA vector indicating the index of the optimal lambda obtained by each selection method.
grid.idxA vector indicating the index of the optimal grid parameter obtained by each selection method.
Note: The returned object may have additional classes such as "PLR_boot" if bootstrap was performed.
Jacquemain, A., C. Heuchenne, and E. Pircalabelu (2024). A penalised bootstrap estimation procedure for the explained Gini coefficient. Electronic Journal of Statistics 18(1) 247-300.
Lorenz.Reg, Lorenz.SCADFABS, Lorenz.FABS, Lorenz.boot
# Continuing the Lorenz.Reg(.) example: PLR_CV <- PLR.CV(PLR, k = 5, seed.CV = 123) # The object now inherits from the class "PLR_CV". # Hence the methods (also) display the results obtained by cross-validation. print(PLR_CV) summary(PLR_CV) coef(PLR_CV, pars.idx = "CV") predict(PLR_CV, pars.idx = "CV") plot(PLR_CV) plot(PLR_CV, type = "diagnostic") # Plot of the scores depending on the grid and penalty parameters# Continuing the Lorenz.Reg(.) example: PLR_CV <- PLR.CV(PLR, k = 5, seed.CV = 123) # The object now inherits from the class "PLR_CV". # Hence the methods (also) display the results obtained by cross-validation. print(PLR_CV) summary(PLR_CV) coef(PLR_CV, pars.idx = "CV") predict(PLR_CV, pars.idx = "CV") plot(PLR_CV) plot(PLR_CV, type = "diagnostic") # Plot of the scores depending on the grid and penalty parameters
prediction provides predictions for an object of class "LR",
while fitted extracts the fitted values.
## S3 method for class 'LR' predict(object, newdata, type = c("index", "response"), ...) ## S3 method for class 'LR' fitted(object, type = c("index", "response"), ...)## S3 method for class 'LR' predict(object, newdata, type = c("index", "response"), ...) ## S3 method for class 'LR' fitted(object, type = c("index", "response"), ...)
object |
An object of class |
newdata |
An optional data frame in which to look for variables with which to predict. If omitted, the original data are used. |
type |
A character string indicating the type of prediction or fitted values. Possible values are |
... |
Additional arguments passed to the function |
If type="response", the link function of the single-index model must be estimated. This is done via the function Rearrangement.estimation.
A vector of predictions for predict, or a vector of fitted values for fitted.
Lorenz.Reg, Rearrangement.estimation
## For examples see example(Lorenz.Reg) and example(Lorenz.boot)## For examples see example(Lorenz.Reg) and example(Lorenz.boot)
prediction provides predictions for an object of class "PLR",
while fitted extracts the fitted values.
## S3 method for class 'PLR' predict(object, newdata, type = c("index", "response"), pars.idx = "BIC", ...) ## S3 method for class 'PLR' fitted(object, type = c("index", "response"), pars.idx = "BIC", ...)## S3 method for class 'PLR' predict(object, newdata, type = c("index", "response"), pars.idx = "BIC", ...) ## S3 method for class 'PLR' fitted(object, type = c("index", "response"), pars.idx = "BIC", ...)
object |
An object of S3 class |
newdata |
An optional data frame in which to look for variables with which to predict. If omitted, the original data are used. |
type |
A character string indicating the type of prediction or fitted values. Possible values are |
pars.idx |
What grid and penalty parameters should be used for parameter selection. Either a character string specifying the selection method, where the possible values are:
Or a numeric vector of length 2, where the first element is the index of the grid parameter and the second is the index of the penalty parameter. |
... |
Additional arguments passed to the function |
If type="response", the link function of the single-index model must be estimated. This is done via the function Rearrangement.estimation.
A vector of predictions for predict, or a vector of fitted values for fitted.
Lorenz.Reg, Rearrangement.estimation
## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)
Prints the arguments, explained Gini coefficient and estimated coefficients of an object of class "LR".
## S3 method for class 'LR' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'LR' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
The number of significant digits to be passed. |
... |
Additional arguments. |
No return value, called for printing an object of class "LR" to the console.
## For examples see example(Lorenz.Reg)## For examples see example(Lorenz.Reg)
Prints the arguments, explained Gini coefficient and estimated coefficients of an object of class "PLR".
## S3 method for class 'PLR' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'PLR' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of S3 class |
digits |
The number of significant digits to be passed. |
... |
Additional arguments. |
The explained Gini coefficient and estimated coefficients are returned for each available selection method, depending on the class of x.
No return value, called for printing an object of class "PLR" to the console.
## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)
Provides a printing method for an object of class "summary.LR".
## S3 method for class 'summary.LR' print(x, digits = max(3L, getOption("digits") - 3L), ...) ## S3 method for class 'summary.LR_boot' print( x, digits = max(3L, getOption("digits") - 3L), signif.stars = getOption("show.signif.stars"), ... )## S3 method for class 'summary.LR' print(x, digits = max(3L, getOption("digits") - 3L), ...) ## S3 method for class 'summary.LR_boot' print( x, digits = max(3L, getOption("digits") - 3L), signif.stars = getOption("show.signif.stars"), ... )
x |
An object of class |
digits |
Number of significant digits to be passed. |
... |
Additional arguments passed to the function |
signif.stars |
Logical determining whether p-values should be also encoded visually. See the help of the function |
No return value, called for printing an object of class "LR" to the console.
## For examples see example(Lorenz.Reg) and example(Lorenz.boot)## For examples see example(Lorenz.Reg) and example(Lorenz.boot)
Provides a printing method for an object of class "summary.PLR".
## S3 method for class 'summary.PLR' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.PLR' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
Number of significant digits to be passed. |
... |
Additional arguments passed to the function |
No return value, called for printing an object of class "summary.PLR" to the console.
## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)
Rearrangement.estimation estimates the increasing link function of a single index model via the methodology proposed in Chernozhukov et al (2009).
Rearrangement.estimation(Y, Index, t = Index, weights = NULL, degree.pol = 1)Rearrangement.estimation(Y, Index, t = Index, weights = NULL, degree.pol = 1)
Y |
The response variable. |
Index |
The estimated index. The user may obtain it using function |
t |
A vector of points over which the link function |
weights |
vector of sample weights. By default, each observation is given the same weight. |
degree.pol |
degree of the polynomial used in the local polynomial regression. Default value is 1. |
A first estimator of the link function, neglecting the assumption of monotonicity, is obtained with function locpol from the locpol package.
The final estimator is obtained through the rearrangement operation explained in Chernozhukov et al (2009). This operation is carried out with function rearrangement from package Rearrangement.
A list with the following components
tthe points over which the estimation has been undertaken.
Hthe estimated link function evaluated at t.
Chernozhukov, V., I. Fernández-Val, and A. Galichon (2009). Improving Point and Interval Estimators of Monotone Functions by Rearrangement. Biometrika 96 (3). 559–75.
Lorenz.Reg, locpol, rearrangement
data(Data.Incomes) PLR <- Lorenz.Reg(Income ~ ., data = Data.Incomes, penalty = "SCAD", eps = 0.01) Y <- PLR$y Index <- predict(PLR) Rearrangement.estimation(Y = Y, Index = Index)data(Data.Incomes) PLR <- Lorenz.Reg(Income ~ ., data = Data.Incomes, penalty = "SCAD", eps = 0.01) Y <- PLR$y Index <- predict(PLR) Rearrangement.estimation(Y = Y, Index = Index)
Provides a summary for an object of class "LR".
## S3 method for class 'LR' summary(object, ...)## S3 method for class 'LR' summary(object, ...)
object |
An object of class |
... |
Additional arguments. |
The inference provided in the coefficients matrix is obtained by using the asymptotic normality and estimating the asymptotic variance via bootstrap.
An object of class "summary.LR", containing the following elements:
callThe matched call.
ineqA matrix with one row and three columns providing information on explained inequality. The first column gives the explained Gini coefficient, the second column gives the Gini coefficient of the response. The third column gives the Lorenz-.
coefficientsA matrix providing information on the estimated coefficients. The first column gives the estimates.
If object inherits from "LR_boot", bootstrap inference was performed and the matrix contains further information. The second column is the boostrap standard error. The third column is the z-value. Finally, the last column is the p-value.
In this case, the class "summary.LR_boot" is added to the output.
## For examples see example(Lorenz.Reg) and example(Lorenz.boot)## For examples see example(Lorenz.Reg) and example(Lorenz.boot)
Provides a summary for an object of class "PLR".
## S3 method for class 'PLR' summary(object, renormalize = TRUE, ...)## S3 method for class 'PLR' summary(object, renormalize = TRUE, ...)
object |
An object of class |
renormalize |
A logical value determining whether the coefficient vector should be re-normalized to match the representation where the first category of each categorical variable is omitted. Default value is TRUE |
... |
Additional arguments |
An object of class "summary.PLR", which contains:
callThe matched call.
ineqA table of explained inequality metrics. The columns display the explained Gini coefficient, the Gini coefficient of the response, and the Lorenz-R2. The first row contains the results obtained by BIC.
coefficientsA matrix with estimated coefficients, each row corresponding to a specific coefficient. The first column contains the results obtained by BIC.
If the object inherits from "PLR_boot", ineq and coefficients also include results from bootstrap, and the class "summary.PLR_boot" is added to the output.
Similarly, if the object inherits from "PLR_cv", ineq and coefficients also include results from cross-validation, and the class "summary.PLR_cv" is added to the output.
Lorenz.Reg, Lorenz.boot, PLR.CV
## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)## For examples see example(Lorenz.Reg), example(Lorenz.boot) and example(PLR.CV)