updated documentation

Author: beanumber

R/GameDay.R

@@ -2,12 +2,12 @@
 #' 
 #' @description Convenience class for dealing with MLBAM GameDay files 
 #' 
-#' @details Each gameId corresponds to one object of class 'gameday'
+#' @details Each gameId corresponds to one object of class \code{\link{gameday}}
 #' 
 #' @param gameId A valid MLBAM gameId
 #' @param ... currently ignored
 #' 
-#' @return An object of class 'gameday', which consists of a list containing
+#' @return An object of class \code{\link{gameday}}, which consists of a list containing
 #' \item{gameId}{The ID of the game (e.g. 'gid_2012_08_12_atlmlb_nynmlb_1')}
 #' \item{base}{The base URL for the game (e.g. 'http://gd2.mlb.com/components/game/mlb/year_2012/month_08/day_12/')}
 #' \item{url}{A character vector containing the names of the XML files downloaded from the GameDay server}

R/GameDayPlays.R

@@ -3,10 +3,10 @@ utils::globalVariables("event")
 #' @title GameDayPlays
 #' @aliases GameDayPlays-class
 #' 
-#' @description Contains the output from \code{\link{getData}}
+#' @description A data set that contains play-by-play information returned by \code{\link{getData}}
 #' 
-#' @format A \code{\link{GameDayPlays}} object. This is a \code{tbl_df} and 
-#' \code{data.frame} with 62 columns. The columns are as follows:
+#' @format A \code{\link{GameDayPlays}} object. This is a \code{\link{tbl_df}} and 
+#' \code{\link{data.frame}} with 62 columns. The columns are as follows:
 #'      \describe{
 #'        \item{pitcherId}{The MLBAM id of the pitcher}
 #'        \item{batterId}{The MLBAM id of the batter}
@@ -202,9 +202,9 @@ plot.GameDayPlays = function(x, batterName = NULL, pitcherName = NULL, events =
 #' 
 #' @description Summarize MLBAM data
 #' 
-#' @details Prints information about the contents of an object of class 'GameDayPlays' 
+#' @details Prints information about the contents of an object of class \code{\link{GameDayPlays}} 
 #' 
-#' @param object A 'GameDayPlays' data set
+#' @param object A \code{\link{GameDayPlays}} data set
 #' @param ... currently ignored
 #' 
 #' @return NULL
@@ -225,9 +225,9 @@ summary.GameDayPlays = function(object, ...) {
 #' 
 #' @description Summarize MLBAM data
 #' 
-#' @details Tabulates Lahman-style statistics by team for the contents of a 'GameDayPlays' data set.
+#' @details Tabulates Lahman-style statistics by team for the contents of a \code{\link{GameDayPlays}} data set.
 #' 
-#' @param data An object of class 'GameDayPlays'
+#' @param data An object of class \code{\link{GameDayPlays}}
 #' 
 #' @return A data.frame of seasonal totals for each team
 #' 

R/GameDayPlaysExt.R

@@ -1,6 +1,6 @@
 #' @title GameDayPlaysExt
 #' 
-#' @description Contains the output from makeWAR()
+#' @description Contains the output from \code{\link{makeWAR}}
 #' 
 #' @exportClass GameDayPlaysExt
 #' @examples showClass('GameDayPlaysExt')

R/fieldingplot.R

@@ -13,7 +13,7 @@
 #'  \code{\link{contourplot}}.
 #' @param y y-coordinate for default method passed to \code{\link{contourplot}}.
 #' @param z z-coordinate for default method passed to \code{\link{contourplot}}.
-#' @param data a GameDayPlays dataset
+#' @param data a \code{\link{GameDayPlays}} dataset
 #' @param label a string to be used in the resulting filename
 #' @param write.pdf a \code{logical} indicating whether to write the contourplot
 #'  to a file

R/getData.R

@@ -1,17 +1,18 @@
 #' @title getData
 #' 
-#' @description Retrieves MLBAM GameDay files for a specified time interval using multiple calls of the gameday function.  
+#' @description Retrieves MLBAM GameDay files for a specified time interval using
+#'  multiple calls of the \code{\link{gameday}} function.  
 #' 
-#' @details Given a beginning and end date, this function will retrieve all data from the MLABM
-#' GameDay server in the specified interval and process them into a single data.frame. 
+#' @details Given a beginning and end date, this function will retrieve all data from the MLBAM
+#' GameDay server in the specified interval and process them into a single data frame. 
 #' 
-#' @param start A valid date in yyyy-mm-dd format (default is \code{Sys.Date() - 1} (i.e. yesterday))
+#' @param start A valid date in yyyy-mm-dd format (default is \code{\link{Sys.Date}() - 1} (i.e. yesterday))
 #' @param end A valid date in yyyy-mm-dd format (default is \code{NULL}, which then uses the same value as \code{start} (i.e. yesterday))
 #' @param gameIds a vector of specific gameIds that you want to retrieve. If 
 #' NULL (the default), then the dates are used to fetch the relevant gameIds
 #' @param drop.suspended Logical indicating whether games with fewer than 5 innings should be excluded.  Default is \code{TRUE}.
 #' 
-#' @return A data.frame of class 'GameDayPlays' consisting of play-by-play data 
+#' @return A \code{\link{tbl_df}} of class \code{\link{GameDayPlays}} consisting of play-by-play data 
 #' 
 #' @import dplyr
 #'
@@ -61,23 +62,13 @@ getData <- function(start = Sys.Date() - 1, end = NULL, gameIds = NULL, drop.sus
 }
 
 
-#' @title getDataMonthly
-#' 
-#' @description Retrieves MLBAM GameDay files for a single month 
-#' 
-#' @details Given a year and month, this function will retrieve data from the 
-#' GameDay server from the specified month and process them into a single data.frame.
-#' 
+#' @rdname getData
 #' @param yyyy A year
 #' @param m A numeric value corresponding to a month
-#' 
-#' @return A data.frame of class 'GameDayPlays' consisting of play-by-play data 
-#' 
 #' @export
-#' @export getDataMonthly
 #' @examples
 #' 
-#' #Retrieve all of the MLBAM data from May 2013
+#' # Retrieve all of the MLBAM data from May 2013
 #' \dontrun{
 #' # ds = getDataMonthly(2013, 5)
 #' }
@@ -88,22 +79,11 @@ getDataMonthly <- function(yyyy = 2013, m = 5) {
     return(getData(start, end))
 }
 
-#' @title getDataWeekly
-#' 
-#' @description Retrieves MLBAM GameDay files for a single week
-#' 
-#' @details Given a date, this function will retrieve data from the week starting on the specified date from the 
-#' GameDay server and process them into a single data.frame.
-#' 
-#' @param start A valid date in yyyy-mm-dd format (default Sys.Date()-8)
-#' 
-#' @return A data.frame of class 'GameDayPlays' consisting of play-by-play data 
-#' 
+#' @rdname getData
 #' @export
-#' @export getDataWeekly
 #' @examples
 #' 
-#' #Retrieve all the data from the first week of the 2013 season
+#' # Retrieve all the data from the first week of the 2013 season
 #' \dontrun{
 #' ds = getDataWeekly('2013-03-31')
 #' }
@@ -160,7 +140,7 @@ getGameIds <- function(date = Sys.Date()) {
 #' @param data a data.frame returned by \code{\link{getData}}
 #' @param ... currently ignored
 #'  
-#' @return A data.frame of class 'GameDayPlays' consisting of play-by-play data 
+#' @return A data.frame of class \code{\link{GameDayPlays}} consisting of play-by-play data 
 #' 
 #' @export
 #' @examples

R/makeWAR.R

@@ -1,9 +1,9 @@
 #' @title makeWAR
 #' @aliases makeWAR.GameDayPlays
 #' 
-#' @description Computes runs above average (RAA) for each player involved in each play of the 'GameDayPlays' object. 
+#' @description Computes runs above average (RAA) for each player involved in each play of the \code{\link{GameDayPlays}} object. 
 #' 
-#' @details Within a 'GameDayPlays' object, each row consists of a single plate appearance and contains information about the batter, all of the baserunners,
+#' @details Within a \code{\link{GameDayPlays}} object, each row consists of a single plate appearance and contains information about the batter, all of the baserunners,
 #'  the pitcher, and all of the fielders on the field during the plate appearance. The total value of the play as determined by the change in the run expectancy 
 #'  matrix from the beginning of the plate appearence to the end of the plate appearance is partitioned across all players involved in the play on offense, 
 #'  and that same value (with the opposite sign) is partitioned across the pitcher and all of the fielders.  Thus for every single plate appearance a runs above average (RAA) value is assigned
@@ -28,20 +28,20 @@
 #' must be 'batterPos' (the defensive position of the batter)}
 #' }
 #' 
-#' @param data An object of class 'GameDayPlays'
+#' @param data An object of class \code{\link{GameDayPlays}}
 #' @param models A named list of models, each with a predict() method. See Details.
 #' @param verbose A \code{logical} indicating whether you want various messages 
 #' and information to be displayed during the computation
 #' @param low.memory A \code{logical} indicating whether to conserve memory by 
 #' not storing the model objects. 
 #' @param ... currently ignored
 #' 
-#' @return An object of class 'openWARPlays' which is a list of length 4 containing the following: 
+#' @return An object of class \code{\link{openWARPlays}} which is a list of length 4 containing the following: 
 #' \itemize{
-#' \item{plays}{A data.frame of class 'GameDayPlays' that is the same as the input to the function.}
-#' \item{data}{A data.frame of class 'GameDayPlaysExt' containing the original data along with appended rows containing the RAA values for each player involved in a plate appearance}
+#' \item{plays}{A data.frame of class \code{\link{GameDayPlays}} that is the same as the input to the function.}
+#' \item{data}{A data.frame of class \code{\link{GameDayPlaysExt}} containing the original data along with appended rows containing the RAA values for each player involved in a plate appearance}
 #'  \item{models.used}{A list containing all of the model information for each of the models used in computing RAA.}
-#'   \item{openWAR}{A data.frame of class 'openWARPlays' containing only the columns necessry for input into the getWAR function.  }
+#'   \item{openWAR}{A data.frame of class \code{\link{openWARPlays}} containing only the columns necessry for input into the getWAR function.  }
 #' }
 #' 
 #' @import dplyr

R/openWARPlays.R

@@ -11,12 +11,12 @@ setClass("openWARPlays", contains = "data.frame")
 #' 
 #' @description Tabulates runs above average (RAA) values per player
 #' 
-#' @details Takes an object of class 'openWARPlays' and consolidates the RAA values by player
+#' @details Takes an object of class \code{\link{openWARPlays}} and consolidates the RAA values by player
 #' 
-#' @param data An object of class 'openWARPlays' 
+#' @param data An object of class \code{\link{openWARPlays}} 
 #' @param ... currently ignored
 #' 
-#' @return A data.frame of class 'openWARPlayers'
+#' @return A data.frame of class \code{\link{openWARPlayers}}
 #' 
 #' @import dplyr
 #' 

R/replacement.R

@@ -12,7 +12,7 @@
 #' of a replacement-level player for use in converting runs above average (RAA) 
 #' into runs above replacement (RAR) and ultimately wins above replacement (WAR).  
 #' 
-#' @param data An object of class 'openWARPlays'
+#' @param data An object of class \code{\link{openWARPlays}}
 #' @param nteams the number of teams used to calculate the number of non-replacement
 #' players. The default is 30 since that is the number of MLB teams. (Note: Using 27.5
 #' seems to result in a total WAR that is close to 1000.)
@@ -75,7 +75,7 @@ getReplacementPlayers.openWARPlays = function(data, nteams = 30, ...) {
 #' 
 #' @details Returns only the RAA values involving replacement-level players
 #' 
-#' @param data A data.frame of class 'openWARPlays'
+#' @param data A data.frame of class \code{\link{openWARPlays}}
 #' @param replacementIds A vector of playerIds for replacement-level players
 #' 
 #' @return A list of RAA values for each type of activity that generates RAA values
@@ -126,7 +126,7 @@ getReplacementActivity.openWARPlays = function(data, replacementIds) {
 #' 
 #' @details Identifies replacement level players and then computes their mean contribution
 #' 
-#' @param data A data.frame of class 'openWARPlays'
+#' @param data A data.frame of class \code{\link{openWARPlays}}
 #' @param replIds MLBAM IDs of specific players that you want to designate as replacement-level
 #' 
 #' @return A numeric vector of mean contributions per activity for replacement-level players

R/shakeWAR.R

@@ -1,17 +1,33 @@
 #' @title shakeWAR
 #' 
-#' @description resample a data.frame to obtain variance estimates for WAR
+#' @description Resample to obtain variance estimates for WAR
 #' 
-#' @details Resamples the rows of an MLBAM data set and calculates WAR values on the re-sampled data set.  
-#' This process is repeated many times to yield variance estimates of WAR.
+#' @details The general idea is to use resampling techniques to compute
+#' variance estimates for openWAR. The \code{resample} argument controls 
+#' how that resampling is done. 
+#' 
+#' For \code{resample = 'plays'}, \code{\link{makeWAR}} is run on the actual
+#' plays passed in the \code{data} argument, if it hasn't been computed already.
+#' The resulting RAA values (for each play) are an estimate of what actually happened. 
+#' These RAA values are resampled \code{N} times. 
+#' 
+#' \code{resample = 'models'} is not currently implemented, but in future versions,
+#' this option would allow you to resample the rows of the original data, run 
+#' \code{\link{makeWAR}} on each resampled data set, collect all of the models
+#' generated during that process, and then evaluate the original data using each
+#' of the resampled models. This would allow you isolate the modeling error. 
+#' 
+#' For \code{resample = 'both'}, the plays are resampled, and \code{\link{makeWAR}}
+#' is computed on each resampled data set. Note that this is both computationally
+#' and memory intensive. 
 #' 
 #' @param data An object that contains \code{\link{GameDayPlays}} data or data that has already been processed by \code{\link{makeWAR}}.  
 #' @param N the number of resamples (default 10)
 #' @param resample An element of \code{c('plays', 'models', 'both')}. Currently only \code{plays}
-#' and \code{both} are implemented. Only works with \code{shakeWAR.GameDayPlays} method.
-#' @param ... additional arguments passed to \code{shakeWAR} methods
+#' and \code{both} are implemented. Only works with \code{\link{shakeWAR.GameDayPlays}} method.
+#' @param ... additional arguments passed to \code{\link{shakeWAR}} methods
 #' 
-#' @return a data.frame with RAA values 
+#' @return a \code{do.\link{openWARPlayers}} data frame with RAA values 
 #' 
 #' @export 
 #' 
@@ -20,7 +36,7 @@
 #' @examples
 #' 
 #' \dontrun{
-#' res = shakeWAR(May, resample='plays', N=5)
+#' res <- shakeWAR(May, resample='plays', N=5)
 #' summary(res)
 #' }
 #' 

man/GameDayPlays-class.Rd

@@ -4,8 +4,8 @@
 \name{GameDayPlays-class}
 \alias{GameDayPlays-class}
 \title{GameDayPlays}
-\format{A \code{\link{GameDayPlays}} object. This is a \code{tbl_df} and
-\code{data.frame} with 62 columns. The columns are as follows:
+\format{A \code{\link{GameDayPlays}} object. This is a \code{\link{tbl_df}} and
+\code{\link{data.frame}} with 62 columns. The columns are as follows:
      \describe{
        \item{pitcherId}{The MLBAM id of the pitcher}
        \item{batterId}{The MLBAM id of the batter}
@@ -73,7 +73,7 @@
         Home plate has \code{theta} of 0.}
      }}
 \description{
-Contains the output from \code{\link{getData}}
+A data set that contains play-by-play information returned by \code{\link{getData}}
 }
 \examples{
 showClass('GameDayPlays')