# Control function for BTLLasso Control parameters for different penalty terms and for tuning the fitting algorithm. ```r ctrl.BTLLasso( l.lambda = 30, log.lambda = TRUE, lambda.min = 0.05, adaptive = TRUE, scale = TRUE, norm = c("L1", "L2"), epsilon = 1e-04, lambda2 = 1e-04, c = 1e-09, precision = 3, weight.penalties = TRUE, include.intercepts = TRUE, order.effect = FALSE, object.order.effect = FALSE, order.center = FALSE, name.order = "Order", penalize.intercepts = FALSE, penalize.X = TRUE, penalize.Z2 = FALSE, penalize.Z1.absolute = TRUE, penalize.Z1.diffs = TRUE, penalize.order.effect.absolute = TRUE, penalize.order.effect.diffs = FALSE ) ``` ## Arguments - `l.lambda`: Number of tuning parameters. Applies only if `lambda = NULL` in the main function. - `log.lambda`: Should the grid of tuning parameters be created on a logarithmic scale rather than equidistant. Applies only if `lambda = NULL` in the main function. - `lambda.min`: Minimal value for tuning parameter. Applies only if `lambda = NULL` in the main function. - `adaptive`: Should adaptive lasso be used? Default is TRUE. - `scale`: Should the covariates be scaled so that they are on comparable scales? Default is TRUE. Variables will be properly scaled AND centered. Please note that results will refer to scaled covariates. If `adaptive = TRUE` scaling is not necessary to keep penalties comparable. - `norm`: Specifies the norm used in the penalty term. Currently, only 'L1' and 'L2' are possible. Default is to 'L1', only 'L1' allows for clustering and variable selection. - `epsilon`: Threshold value for convergence of the algorithm. - `lambda2`: Tuning parameter for ridge penalty on all coefficients. Should be small, only used to stabilize results. - `c`: Internal parameter for the quadratic approximation of the L1 penalty. Should be sufficiently small. - `precision`: Precision for final parameter estimates, specifies number of decimals. - `weight.penalties`: Should the penalties across the different model components (i.e. intercepts, order effects, X, Z1, Z2) be weighted according to the number of penalties included? Default is `TRUE` to minimize the risk of selection bias across different model components. - `include.intercepts`: Should intercepts be included in the model? - `order.effect`: Should a global order effect (corresponding to home effect in sports applications) be included in the model? - `object.order.effect`: Should object-specific order effects (corresponding to home effects in sports applications) be included in the model? - `order.center`: Should (in case of object-specific order effects) the order effects be centered in the design matrix? Centering is equivalent to the coding scheme of effect coding instead of dummy coding. - `name.order`: How should the order effect(s) be called in plots or prints. - `penalize.intercepts`: Should intercepts be penalized? If `TRUE`, all pairwise differences between intercepts are penalized. - `penalize.X`: Should effects from X matrix be penalized? If `TRUE`, all pairwise differences corresponding to one covariate are penalized. Can also be used with a character vector as input. Then, the character vector contains the names of the variables from X whose parameters should be penalized. - `penalize.Z2`: Should absolute values of effects from Z2 matrix be penalized? Can also be used with a character vector as input. Then, the character vector contains the names of the variables from Z2 whose parameters should be penalized. - `penalize.Z1.absolute`: Should absolute values of effects from Z1 matrix be penalized? Can also be used with a character vector as input. Then, the character vector contains the names of the variables from Z1 whose parameters should be penalized. - `penalize.Z1.diffs`: Should differences of effects from Z1 matrix be penalized? If `TRUE`, all pairwise differences corresponding to one covariate are penalized. Can also be used with a character vector as input. Then, the character vector contains the names of the variables from Z1 whose parameters should be penalized. - `penalize.order.effect.absolute`: Should absolute values of order effect(s) be penalized? Only relevant if either `object.order.effect = TRUE` or `order.effect = TRUE`. - `penalize.order.effect.diffs`: Should differences of order effects be penalized? If `TRUE`, all pairwise differences are penalized. Only relevant if `object.order.effect = TRUE` ## Examples ```r ## Not run: op <- par(no.readonly = TRUE) ############################## ##### Example with simulated data set containing X, Z1 and Z2 ############################## data(SimData) ## Specify control argument ## -> allow for object-specific order effects and penalize intercepts ctrl <- ctrl.BTLLasso(penalize.intercepts = TRUE, object.order.effect = TRUE, penalize.order.effect.diffs = TRUE) ## Simple BTLLasso model for tuning parameters lambda m.sim <- BTLLasso(Y = SimData$Y, X = SimData$X, Z1 = SimData$Z1, Z2 = SimData$Z2, control = ctrl) m.sim par(xpd = TRUE) plot(m.sim) ## Cross-validate BTLLasso model for tuning parameters lambda set.seed(1860) m.sim.cv <- cv.BTLLasso(Y = SimData$Y, X = SimData$X, Z1 = SimData$Z1, Z2 = SimData$Z2, control = ctrl) m.sim.cv coef(m.sim.cv) logLik(m.sim.cv) head(predict(m.sim.cv, type="response")) head(predict(m.sim.cv, type="trait")) plot(m.sim.cv, plots_per_page = 4) ## Example for bootstrap intervals for illustration only ## Don't calculate bootstrap intervals with B = 20!!!! set.seed(1860) m.sim.boot <- boot.BTLLasso(m.sim.cv, B = 20, cores = 20) m.sim.boot plot(m.sim.boot, plots_per_page = 4) ############################## ##### Example with small version from GLES data set ############################## data(GLESsmall) ## extract data and center covariates for better interpretability Y <- GLESsmall$Y X <- scale(GLESsmall$X, scale = FALSE) Z1 <- scale(GLESsmall$Z1, scale = FALSE) ## vector of subtitles, containing the coding of the X covariates subs.X <- c('', 'female (1); male (0)') ## Cross-validate BTLLasso model m.gles.cv <- cv.BTLLasso(Y = Y, X = X, Z1 = Z1) m.gles.cv coef(m.gles.cv) logLik(m.gles.cv) head(predict(m.gles.cv, type="response")) head(predict(m.gles.cv, type="trait")) par(xpd = TRUE, mar = c(5,4,4,6)) plot(m.gles.cv, subs.X = subs.X, plots_per_page = 4, which = 2:5) paths(m.gles.cv, y.axis = 'L2') ############################## ##### Example with Bundesliga data set ############################## data(Buli1516) Y <- Buli1516$Y5 Z1 <- scale(Buli1516$Z1, scale = FALSE) ctrl.buli <- ctrl.BTLLasso(object.order.effect = TRUE, name.order = "Home", penalize.order.effect.diffs = TRUE, penalize.order.effect.absolute = FALSE, order.center = TRUE, lambda2 = 1e-2) set.seed(1860) m.buli <- cv.BTLLasso(Y = Y, Z1 = Z1, control = ctrl.buli) m.buli par(xpd = TRUE, mar = c(5,4,4,6)) plot(m.buli) ############################## ##### Example with Topmodel data set ############################## data("Topmodel2007", package = "psychotree") Y.models <- response.BTLLasso(Topmodel2007$preference) X.models <- scale(model.matrix(preference~., data = Topmodel2007)[,-1]) rownames(X.models) <- paste0("Subject",1:nrow(X.models)) colnames(X.models) <- c("Gender","Age","KnowShow","WatchShow","WatchFinal") set.seed(5) m.models <- cv.BTLLasso(Y = Y.models, X = X.models) plot(m.models, plots_per_page = 6) par(op) ## End(Not run) ``` ## References Schauberger, Gunther and Tutz, Gerhard (2019): BTLLasso - A Common Framework and Software Package for the Inclusion and Selection of Covariates in Bradley-Terry Models, **Journal of Statistical Software**, 88(9), 1-29, tools:::Rd_expr_doi("10.18637/jss.v088.i09") Schauberger, Gunther and Tutz, Gerhard (2017): Subject-specific modelling of paired comparison data: A lasso-type penalty approach, **Statistical Modelling**, 17(3), 223 - 243 Schauberger, Gunther, Groll Andreas and Tutz, Gerhard (2018): Analysis of the importance of on-field covariates in the German Bundesliga, **Journal of Applied Statistics**, 45(9), 1561 - 1578 ## See Also `BTLLasso`, `cv.BTLLasso` ## Author(s) Gunther Schauberger gunther.schauberger@tum.de

ctrl.BTLLasso function