[Mboost-commits] r856 - in pkg/mboostPatch: R inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Jul 30 17:32:48 CEST 2015
Author: hofner
Date: 2015-07-30 17:32:47 +0200 (Thu, 30 Jul 2015)
New Revision: 856
Added:
pkg/mboostPatch/man/plot.Rd
Modified:
pkg/mboostPatch/R/methods.R
pkg/mboostPatch/inst/CITATION
pkg/mboostPatch/inst/NEWS.Rd
pkg/mboostPatch/man/Family.Rd
pkg/mboostPatch/man/glmboost.Rd
pkg/mboostPatch/man/methods.Rd
Log:
- plot.Rd: Added documentation for plot.mboost function
and moved documentation of plot.glmboost to the same help page.
- Family.Rd: Updated manual for multinomial logit model.
Predictions for new data are now possible
- inst/CITATION: Added subheadings and tutorial paper.
- print.mboost/print.glmboost: Truncate output of
complete data structure when model is printed.
Modified: pkg/mboostPatch/R/methods.R
===================================================================
--- pkg/mboostPatch/R/methods.R 2015-07-03 11:07:37 UTC (rev 855)
+++ pkg/mboostPatch/R/methods.R 2015-07-30 15:32:47 UTC (rev 856)
@@ -369,8 +369,11 @@
cat("\n")
cat("\t Model-based Boosting\n")
cat("\n")
- if (!is.null(x$call))
- cat("Call:\n", deparse(x$call), "\n\n", sep = "")
+ if (!is.null(x$call)) {
+ if(length(deparse(x$call$data)) > 20)
+ x$call$data <- deparse(x$call$data, nlines = 1)
+ cat("Call:\n", deparse(x$call), "\n\n", sep = "")
+ }
show(x$family)
cat("\n")
cat("Number of boosting iterations: mstop =", mstop(x), "\n")
@@ -387,8 +390,11 @@
cat("\n")
cat("\t Generalized Linear Models Fitted via Gradient Boosting\n")
cat("\n")
- if (!is.null(x$call))
- cat("Call:\n", deparse(x$call), "\n\n", sep = "")
+ if (!is.null(x$call)) {
+ if(length(deparse(x$call$data)) > 20)
+ x$call$data <- deparse(x$call$data, nlines = 1)
+ cat("Call:\n", deparse(x$call), "\n\n", sep = "")
+ }
show(x$family)
cat("\n")
cat("Number of boosting iterations: mstop =", mstop(x), "\n")
Modified: pkg/mboostPatch/inst/CITATION
===================================================================
--- pkg/mboostPatch/inst/CITATION 2015-07-03 11:07:37 UTC (rev 855)
+++ pkg/mboostPatch/inst/CITATION 2015-07-30 15:32:47 UTC (rev 856)
@@ -1,6 +1,4 @@
-citHeader("To cite package 'mboost' in publications use:")
-
year <- sub(".*(2[[:digit:]]{3})-.*", "\\1", meta$Date)
vers <- paste("R package version", meta$Version)
@@ -14,27 +12,32 @@
year = year,
note = paste("{R} package version", vers),
url = "http://CRAN.R-project.org/package=mboost",
- textVersion =
- paste("T. Hothorn, P. Buehlmann, T. Kneib, M. Schmid, and B. Hofner (",
- year,
- "). mboost: Model-Based Boosting, ",
- paste("R package version", vers),
- ", http://CRAN.R-project.org/package=mboost", ".",
- sep=""))
+ header = "To cite the package 'mboost' itself use:",
+ textVersion = paste(
+ "T. Hothorn, P. Buehlmann, T. Kneib, M. Schmid, and B. Hofner (",
+ year, "). mboost: Model-Based Boosting, ",
+ paste("R package version", vers),
+ ", http://CRAN.R-project.org/package=mboost", ".", sep = ""
+ )
+ )
citEntry(entry="Article",
- title = "Boosting Algorithms: Regularization, Prediction and Model Fitting (with Discussion)",
- author = personList(as.person("Peter Buehlmann"), as.person("Torsten Hothorn")),
- journal = "Statistical Science",
- year = "2007",
- volume = "22",
- number = "4",
- pages = "477--505",
-
- textVersion =
- paste("Peter Buehlmann and Torsten Hothorn (2007).",
- "Boosting Algorithms: Regularization, Prediction and Model Fitting (with Discussion).",
- "Statistical Science, 22(4), 477-505."),
+ title = "Model-based Boosting in {R}: A Hands-on Tutorial Using the {R} Package mboost",
+ author = personList(as.person("Benjamin Hofner"),
+ as.person("Andreas Mayr"),
+ as.person("Nikolay Robinzonov"),
+ as.person("Matthias Schmid")),
+ journal = "Computational Statistics",
+ year = "2014",
+ volume = "29",
+ pages = "3--35",
+ header = "A comprehensive tutorial is given in:",
+ textVersion = paste(
+ "Benjamin Hofner, Andreas Mayr, Nikolay Robinzonov,",
+ "Matthias Schmid (2014).",
+ "Model-based Boosting in R: A Hands-on Tutorial Using the R Package mboost.",
+ "Computational Statistics, 29, 3-35."
+ )
)
citEntry(entry="Article",
@@ -48,14 +51,29 @@
year = "2010",
volume = "11",
pages = "2109--2113",
+ header = "An overview of the implementation is given in:",
+ textVersion = paste(
+ "Torsten Hothorn, Peter Buehlmann, Thomas Kneib,",
+ "Matthias Schmid and Benjamin Hofner (2010).",
+ "Model-based Boosting 2.0.",
+ "Journal of Machine Learning Research, 11, 2109-2113."
+ )
+ )
- textVersion =
- paste("Torsten Hothorn, Peter Buehlmann, Thomas Kneib,",
- "Matthias Schmid and Benjamin Hofner (2010).",
- "Model-based Boosting 2.0.",
- "Journal of Machine Learning Research, 11, 2109-2113."
- ),
+citEntry(entry="Article",
+ title = "Boosting Algorithms: Regularization, Prediction and Model Fitting (with Discussion)",
+ author = personList(as.person("Peter Buehlmann"), as.person("Torsten Hothorn")),
+ journal = "Statistical Science",
+ year = "2007",
+ volume = "22",
+ number = "4",
+ pages = "477--505",
+ header = "The theory and the package (until version 2.0) are described in:",
+ textVersion = paste(
+ "Peter Buehlmann and Torsten Hothorn (2007).",
+ "Boosting Algorithms: Regularization, Prediction and Model Fitting (with Discussion).",
+ "Statistical Science, 22(4), 477-505."
+ )
)
-
-citFooter('Use ', sQuote('toBibtex(citation("mboost"))'), ' to extract BibTeX references.')
+citFooter('\nUse ', sQuote('toBibtex(citation("mboost"))'), ' to extract BibTeX references.')
Modified: pkg/mboostPatch/inst/NEWS.Rd
===================================================================
--- pkg/mboostPatch/inst/NEWS.Rd 2015-07-03 11:07:37 UTC (rev 855)
+++ pkg/mboostPatch/inst/NEWS.Rd 2015-07-30 15:32:47 UTC (rev 856)
@@ -2,9 +2,23 @@
\title{News for Package 'mboost'}
\section{Changes in mboost version 2.4-3 (2015-03-20)}{
+ \subsection{User-visible changes}{
+ \itemize{
+ \item Added documentation for \code{plot.mboost} function and moved
+ documentation of \code{plot.glmboost} to the same help page.
+ Resolves issue \href{https://github.com/hofnerb/mboost/issues/11}{#11}.
+ }
+ }
\subsection{Miscellaneous}{
\itemize{
- \item Updated manual for \code{PropOdds()}.
+ \item \code{PropOdds()}: Updated manual for proportional odds model.
+ \item \code{Multinomial()}: Updated manual for multinomial logit
+ model. Predictions for new data are now
+ possible (resolves issue
+ \href{https://github.com/hofnerb/mboost/issues/13}{#13}, thanks to
+ Sarah Brockhaus).
+ \item \file{inst/CITATION}: Added subheadings and
+ tutorial paper.
}
}
\subsection{Bug-fixes}{
@@ -12,6 +26,9 @@
\item Fixed bug in \code{PropOdds()} which occured if
\code{offset} was specified: nuisance parameters \code{delta}
and \code{sigma} were not properly initialized.
+ \item Truncate output of complete data structure when model is
+ printed. Resolves issue
+ \href{https://github.com/hofnerb/mboost/issues/11}{#11}.
}
}
}
Modified: pkg/mboostPatch/man/Family.Rd
===================================================================
--- pkg/mboostPatch/man/Family.Rd 2015-07-03 11:07:37 UTC (rev 855)
+++ pkg/mboostPatch/man/Family.Rd 2015-07-30 15:32:47 UTC (rev 856)
@@ -206,8 +206,8 @@
model specification (see example). More specifically, the predictor must
be in the form of a linear array model (see \code{\link{\%O\%}}). Note
that this family does not work with tree-based base-learners at the
- moment. The class corresponding to the last level of the factor coding
- the response is uses as reference class.
+ moment. The class corresponding to the last level of the factor coding
+ of the response is used as reference class.
}
\section{Warning}{
@@ -278,8 +278,7 @@
\code{AUC()} was donated by Fabian Scheipl.
}
\examples{
-Laplace()
-
+### Define a new family
MyGaussian <- function(){
Family(ngradient = function(y, f, w = 1) y - f,
loss = function(y, f) (y - f)^2,
@@ -287,7 +286,7 @@
}
\donttest{
-### fitting a proportional odds model
+### Proportional odds model
data(iris)
iris$Species <- factor(iris$Species, ordered = TRUE)
if (require("MASS")) {
@@ -298,27 +297,38 @@
mstop(mod.PropOdds) <- 1000
## thresholds are treated as nuisance parameters, to extract these use
nuisance(mod.PropOdds)
-## effect estimate:
+## effect estimate
coef(mod.PropOdds)["Sepal.Length"]
-
-## effect
-coef(mod.PropOdds)["Sepal.Length"]
## make thresholds comparable to a model without intercept
nuisance(mod.PropOdds) - coef(mod.PropOdds)["(Intercept)"] -
attr(coef(mod.PropOdds), "offset")
}
-### fitting multinomial logit model via a linear array model
-X0 <- K0 <- diag(nlevels(iris$Species) - 1)
-colnames(X0) <- levels(iris$Species)[-nlevels(iris$Species)]
+### Multinomial logit model via a linear array model
+## One needs to convert the data to a list
+myiris <- as.list(iris)
+## ... and define a dummy vector with one factor level less
+## than the outcome, which is used as reference category.
+myiris$class <- factor(levels(iris$Species)[-nlevels(iris$Species)])
+## Now fit the linear array model
mlm <- mboost(Species ~ bols(Sepal.Length, df = 2) \%O\%
- buser(X0, K0, df = 2), data = iris,
+ bols(class, df = 2, contrasts.arg = "contr.dummy"),
+ data = myiris,
family = Multinomial())
-head(round(predict(mlm, type = "response"), 2))
+coef(mlm) ## one should use more boosting iterations.
+head(round(pred <- predict(mlm, type = "response"), 2))
+## Prediction with new data:
+newdata <- as.list(iris[1,])
+## One always needs to keep the dummy vector class as above!
+newdata$class <- factor(levels(iris$Species)[-nlevels(iris$Species)])
+pred2 <- predict(mlm, type = "response", newdata = newdata)
+## check results
+pred[1, ]
+pred2
\donttest{
+## Compare results with nnet::multinom
if (require("nnet")) {
- ### compare results with nnet::multinom
mlmn <- multinom(Species ~ Sepal.Length, data = iris)
max(abs(fitted(mlm[1000], type = "response") -
fitted(mlmn, type = "prob")))
Modified: pkg/mboostPatch/man/glmboost.Rd
===================================================================
--- pkg/mboostPatch/man/glmboost.Rd 2015-07-03 11:07:37 UTC (rev 855)
+++ pkg/mboostPatch/man/glmboost.Rd 2015-07-30 15:32:47 UTC (rev 856)
@@ -3,7 +3,7 @@
\alias{glmboost.formula}
\alias{glmboost.matrix}
\alias{glmboost.default}
-\alias{plot.glmboost}
+
\title{ Gradient Boosting with Component-wise Linear Models }
\description{
Gradient boosting for optimizing arbitrary loss functions where component-wise
@@ -15,8 +15,6 @@
center = TRUE, control = boost_control(), ...)
\method{glmboost}{matrix}(x, y, center = TRUE, control = boost_control(), ...)
\method{glmboost}{default}(x, ...)
-\method{plot}{glmboost}(x, main = deparse(x$call), col = NULL,
- off2int = FALSE, ...)
}
\arguments{
\item{formula}{ a symbolic description of the model to be fit. }
@@ -31,15 +29,8 @@
contain \code{NA}s.}
\item{center}{logical indicating of the predictor variables are centered before fitting.}
\item{control}{ a list of parameters controlling the algorithm.}
- \item{x}{ design matrix or an object of class \code{glmboost} for plotting.
- Sparse matrices of class \code{Matrix} can be used as well.}
+ \item{x}{ design matrix. Sparse matrices of class \code{Matrix} can be used as well.}
\item{y}{ vector of responses. }
- \item{main}{ a title for the plot.}
- \item{col}{ (a vector of) colors for plotting the lines representing
- the coefficient paths.}
- \item{off2int}{ logical indicating whether the offset should be
- added to the intercept (if there is any) or if the offset is
- neglected for plotting (default).}
\item{\dots}{ additional arguments passed to \code{\link{mboost_fit}},
including \code{weights}, \code{offset}, \code{family} and
\code{control}. For default values see \code{\link{mboost_fit}}.}
@@ -110,10 +101,10 @@
control = boost_control(mstop = 2000),
center = TRUE)
- ## plot coefficient paths oth glmboost
+ ## plot coefficient paths of glmboost
par(mfrow=c(1,2), mai = par("mai") * c(1, 1, 1, 2.5))
- plot(cars.gb, main="without centering")
- plot(cars.gb_centered, main="with centering")
+ plot(cars.gb, main = "without centering")
+ plot(cars.gb_centered, main = "with centering")
### alternative loss function: absolute loss
cars.gbl <- glmboost(dist ~ speed, data = cars,
Modified: pkg/mboostPatch/man/methods.Rd
===================================================================
--- pkg/mboostPatch/man/methods.Rd 2015-07-03 11:07:37 UTC (rev 855)
+++ pkg/mboostPatch/man/methods.Rd 2015-07-30 15:32:47 UTC (rev 856)
@@ -316,6 +316,11 @@
}
\references{
+ Benjamin Hofner, Andreas Mayr, Nikolay Robinzonov and Matthias Schmid
+ (2014). Model-based Boosting in R: A Hands-on Tutorial Using the R
+ Package mboost. \emph{Computational Statistics}, \bold{29}, 3--35.\cr
+ \url{http://dx.doi.org/10.1007/s00180-012-0382-5}
+
Clifford M. Hurvich, Jeffrey S. Simonoff and Chih-Ling Tsai (1998),
Smoothing parameter selection in nonparametric regression using
an improved Akaike information criterion.
@@ -340,9 +345,14 @@
DOI: \url{http://dx.doi.org/10.3414/ME11-02-0030}
}
-\seealso{ \code{\link{gamboost}}, \code{\link{glmboost}} and
- \code{\link{blackboost}} for model fitting. See \code{\link{cvrisk}} for
- cross-validated stopping iteration.}
+\seealso{
+ \code{\link{gamboost}}, \code{\link{glmboost}} and
+ \code{\link{blackboost}} for model fitting.
+
+ \code{\link{plot.mboost}} for plotting methods.
+
+ \code{\link{cvrisk}} for cross-validated stopping iteration.
+}
\examples{
### a simple two-dimensional example: cars data
Added: pkg/mboostPatch/man/plot.Rd
===================================================================
--- pkg/mboostPatch/man/plot.Rd (rev 0)
+++ pkg/mboostPatch/man/plot.Rd 2015-07-30 15:32:47 UTC (rev 856)
@@ -0,0 +1,206 @@
+\name{plot}
+\alias{plot}
+
+\alias{plot.glmboost}
+\alias{plot.mboost}
+\alias{lines.mboost}
+
+\title{
+ Plot effect estimates of boosting models
+}
+\description{
+ Plot coefficient plots for \code{glmboost} models and partial effect
+ plots for all other \code{mboost} models.
+}
+\usage{
+
+\method{plot}{glmboost}(x, main = deparse(x$call), col = NULL,
+ off2int = FALSE, ...)
+
+\method{plot}{mboost}(x, which = NULL, newdata = NULL,
+ type = "b", rug = TRUE, rugcol = "black",
+ ylim = NULL, xlab = NULL, ylab = expression(f[partial]),
+ add = FALSE, ...)
+
+\method{lines}{mboost}(x, which = NULL, type = "l", rug = FALSE, ...)
+
+}
+
+\arguments{
+ \item{x}{
+ object of class \code{glmboost} or an object inheriting from
+ \code{mboost} for plotting.
+ }
+ \item{main}{
+ a title for the plot.
+ }
+ \item{col}{
+ (a vector of) colors for plotting the lines representing the
+ coefficient paths.
+ }
+ \item{off2int}{
+ logical indicating whether the offset should be added to the
+ intercept (if there is any) or if the offset is neglected for
+ plotting (default).
+ }
+ \item{which}{
+ a subset of base-learners used for plotting. If \code{which} is
+ given (as an integer vector or characters corresponding
+ to base-learners) only the corresponding partial effect plots are
+ depicted. Per default all selected base-learners are plotted.
+ }
+ \item{newdata}{
+ optionally, a data frame in which to look for variables with
+ which to make predictions that are then plotted. This is especially
+ useful if the data that was used to fit the model shows some larger
+ gaps as effect plots are linearly interpolated between observations.
+ For an example using \code{newdata} see below.
+ }
+ \item{type}{
+ character string giving the type of plot desired. Per default,
+ points and lines are plotted (\code{"b"}). Other useful options are
+ points (\code{"p"}) or lines (\code{"l"}). See
+ \code{\link{plot.default}} for details.
+ }
+ \item{rug}{
+ logical. Should a rug be added to the x-axis?
+ }
+ \item{rugcol}{
+ color for the rug.
+ }
+ \item{ylim}{
+ the y limits of the plot.
+ }
+ \item{xlab}{
+ a label for the x axis.
+ }
+ \item{ylab}{
+ a label for the y axis.
+ }
+ \item{add}{
+ logical. Should the plot be added to the previous plot?
+ }
+ \item{\dots}{
+ Additional arguments to the \code{plot} functions. E.g. one can
+ specify the x limits \code{xlim} or the color of the plot using
+ \code{col}.
+ }
+
+}
+\details{
+ The coefficient paths for \code{glmboost} models show how the
+ coefficient estimates evolve with increasing \code{mstop}. Each line
+ represents one parameter estimate. Parameter estimates are only
+ depicted when they they are selected at any time in the boosting
+ model. Parameters that are not selected are droped from the figure
+ (see example).
+
+ Models specified with \code{gamboost} or \code{mboost} are plotted as
+ partial effects. Only the effect of the current bossting iteration is
+ depicted instead of the coefficient paths as for linear models. The
+ function \code{lines} is just a wrapper to \code{plot(\ldots , add =
+ TRUE)} where per default the effect is plotted as line and the
+ \code{rug} is set to \code{FALSE}.
+
+ Spatial effects can be also plotted using the function \code{plot}
+ for mboost models (using \code{lattice} graphics). More complex
+ effects reuquire manual plotting: One needs to predict the effects on
+ a disired grid and plot the effect estimates.
+}
+\value{
+ A plot of the fitted model.
+}
+\references{
+ Benjamin Hofner, Andreas Mayr, Nikolay Robinzonov and Matthias Schmid
+ (2014). Model-based Boosting in R: A Hands-on Tutorial Using the R
+ Package mboost. \emph{Computational Statistics}, \bold{29}, 3--35.\cr
+ \url{http://dx.doi.org/10.1007/s00180-012-0382-5}
+}
+\seealso{
+ \code{\link{mboost_methods}} for further methods.
+}
+\examples{
+
+### a simple example: cars data with one random variable
+set.seed(1234)
+cars$z <- rnorm(50)
+
+########################################
+## Plot linear models
+########################################
+
+## fit a linear model
+cars.lm <- glmboost(dist ~ speed + z, data = cars)
+
+## plot coefficient paths of glmboost
+par(mfrow = c(3, 1), mar = c(4, 4, 4, 8))
+plot(cars.lm,
+ main = "Coefficient paths (offset not included)")
+plot(cars.lm, off2int = TRUE,
+ main = "Coefficient paths (offset included in intercept)")
+
+## plot coefficient paths only for the first 15 steps,
+## i.e., bevore z is selected
+mstop(cars.lm) <- 15
+plot(cars.lm, off2int = TRUE, main = "z is not yet selected")
+
+
+########################################
+## Plot additive models; basics
+########################################
+
+## fit an additive model
+cars.gam <- gamboost(dist ~ speed + z, data = cars)
+
+## plot effects
+par(mfrow = c(1, 2), mar = c(4, 4, 0.1, 0.1))
+plot(cars.gam)
+
+## use same y-lims
+plot(cars.gam, ylim = c(-50, 50))
+
+## plot only the effect of speed
+plot(cars.gam, which = "speed")
+## as partial matching is used we could also use
+plot(cars.gam, which = "sp")
+
+
+########################################
+## More complex plots
+########################################
+
+## Let us use more boosting iterations and compare the effects.
+
+## We change the plot type and plot both effects in one figure:
+par(mfrow = c(1, 1), mar = c(4, 4, 4, 0.1))
+mstop(cars.gam) <- 100
+plot(cars.gam, which = 1, col = "red", type = "l", rug = FALSE,
+ main = "Compare effect for various models")
+
+## Now the same model with 1000 iterations
+mstop(cars.gam) <- 1000
+lines(cars.gam, which = 1, col = "grey", lty = "dotted")
+
+## There are some gaps in the data. Use newdata to get a smoother curve:
+newdata <- data.frame(speed = seq(min(cars$speed), max(cars$speed),
+ length = 200))
+lines(cars.gam, which = 1, col = "grey", lty = "dashed",
+ newdata = newdata)
+
+## The model with 1000 steps seems to overfit the data.
+## Usually one should use e.g. cross-validation to tune the model.
+
+## Finally we refit the model using linear effects as comparison
+cars.glm <- gamboost(dist ~ speed + z, baselearner = bols, data = cars)
+lines(cars.glm, which = 1, col = "black")
+## We see that all effects are more or less linear.
+
+## Add a legend
+legend("topleft", title = "Model",
+ legend = c("... with mstop = 100", "... with mstop = 1000",
+ "... with linear effects"),
+ lty = c("solid", "dashed", "solid"),
+ col = c("red", "grey", "black"))
+
+}
+\keyword{ methods }
More information about the Mboost-commits
mailing list