Version 1.0.3.

Update documentation: roxygenize comments, reorganize help pages.

Author: jpkerman

ChangeLog

@@ -1,3 +1,6 @@
+2017-04-05: Google <[email protected]>
+	* Version 1.0.3
+	* Update documentation: roxygenize comments, reorganize help pages.
 2017-04-04: Google <[email protected]>
 	* Version 1.0.2
 	* Update Vignette: add URL to the TBR white paper.

DESCRIPTION

@@ -15,8 +15,8 @@ Suggests:
     testthat (>= 0.10.0),
     knitr (>= 1.12.3)
 VignetteBuilder: knitr
-Date: 2017-04-04
-Version: 1.0.2
+Date: 2017-04-05
+Version: 1.0.3
 License: Apache License 2.0 | file LICENSE
 Copyright: Copyright (C) 2017 Google, Inc.
 RoxygenNote: 5.0.1

R/aggregate.R

@@ -12,28 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#' Aggregate the Metrics of a GeoTimeseries.
+#'
+#' @param x a GeoTimeseries object.
+#' @param by (character vector) name(s) of column(s) by which to group.
+#' @param FUN (function) function to apply to each metric column.
+#' @param metrics (character vector) metrics to aggregate. Default is all
+#'   metrics.
+#' @param ... optional arguments passed to FUN.
+#'
+#' @return A data.frame object.
+#'
+#' @note
+#' Uses \code{aggregate.data.frame} to do the aggregation. This function
+#' omits rows that have missing values in the '\code{by}' columns.
+#'
+#' @seealso AggregateTimeseries.
+
 aggregate.GeoTimeseries <- function(x, by=kGeo, FUN=base::sum,
                                     metrics=NULL, ...) {
-  # Aggregate the Metrics of a GeoTimeseries.
-  #
-  # Args:
-  #   x: a GeoTimeseries object.
-  #   by: (character vector) name(s) of column(s) by which to group.
-  #   FUN: (function) function to apply to each metric column.
-  #   metrics: (character vector) metrics to aggregate. Default is all metrics.
-  #   ...: optional arguments passed to FUN.
-  #
-  # Returns:
-  #   A data.frame object.
-  #
-  # Notes:
-  #
-  #   Uses 'aggregate.data.frame' to do the aggregation. This function
-  #   omits rows that have missing values in the 'by' columns.
-  #
-  # Documentation:
-  #   seealso: AggregateTimeseries.
-
   SetMessageContextString("aggregate.GeoTimeseries")
   on.exit(SetMessageContextString())
 

R/aggregatetimeseries.R

@@ -12,56 +12,37 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-AggregateTimeseries <- function(obj, freq=c("weekly", "monthly"), ...) {
-  # Aggregate the metrics of a time series object over specified time
-  # intervals.
-  #
-  # Args:
-  #   obj: an object.
-  #   freq: (string) 'weekly' or 'monthly' aggregation.
-  #   ...: further arguments passed to or from other methods.
-  #
-  # Returns:
-  #   An object of the same class as 'obj'.
-  #
-  # Notes:
-  #   A generic S3 method.
-  #
-  # Documentation:
-  #   seealso: AggregateTimeseries.GeoTimeseries.
+#' Aggregate the metrics of a time series object over specified time
+#' intervals.
+#'
+#' @param obj an object.
+#' @param freq (string) 'weekly' or 'monthly' aggregation.
+#' @param ... further arguments passed to or from other methods.
+#'
+#' @return An object of the same class as 'obj'.
+#'
+#' @note
+#' \itemize{
+#'   \item{'Weekly' frequency}: each day in the time series is mapped
+#'     to the next Sunday, then aggregated.
+#'   \item{'Monthly' frequency}: each day in the time series is mapped to
+#'     the last day of the month, then aggregated. No check is made about
+#'     the current frequency. This works best on daily data. So it is
+#'     possible to attempt to change a 'monthly' frequency back to 'weekly',
+#'     but this simply re-maps the last day of the month to the next Sunday.
+#' }
+#'
+#' @seealso \code{\link{aggregate.GeoTimeseries}}.
+#'
+#' @rdname AggregateTimeseries
 
+AggregateTimeseries <- function(obj, freq=c("weekly", "monthly"), ...) {
   UseMethod("AggregateTimeseries")
 }
 
-AggregateTimeseries.GeoTimeseries <- function(obj, freq, ...) {
-  # Convert a GeoTimeseries to a weekly or monthly
-  # GeoTimeseries. (Note: intended to transform daily data.)
-  #
-  # Args:
-  #   obj: a GeoTimeseries object.
-  #   freq: desired frequency: 'weekly' or 'monthly'.
-  #   ...: ignored.
-  #
-  # Returns:
-  #   A GeoTimeseries object with the weekly or monthly metrics
-  #   aggregated. The sums are associated with the last day of the
-  #   week (which is by our definition _Sunday_), or the last day of
-  #   the month.
-  #
-  # Notes:
-  #   'Weekly' frequency: each day in the time series is mapped to the
-  #   next Sunday, then aggregated.  'Monthly' frequency: each day in
-  #   the time series is mapped to the last day of the month, then
-  #   aggregated.
-  #
-  #   No check is made about the current frequency. This works best on
-  #   daily data.  So it is possible to attempt to change a 'monthly'
-  #   frequency back to 'weekly', but this simply re-maps the last day
-  #   of the month to the next Sunday.
-  #
-  # Documentation:
-  #   seealso: AggregateTimeseries (generic), aggregate.GeoTimeseries.
+#' @rdname AggregateTimeseries
 
+AggregateTimeseries.GeoTimeseries <- function(obj, freq, ...) {
   SetMessageContextString("AggregateTimeseries.GeoTimeseries")
   on.exit(SetMessageContextString())
 

R/as_gbrroasanalysisdata.R

@@ -12,6 +12,35 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#' Coerces an object to a GBRROASAnalysisData object.
+#'
+#' @param obj an object.
+#' @param ... further arguments to be passed to or from other methods.
+#' @return A GBRROASAnalysisData object.
+#'
+#' @seealso \code{\link{DoGBRROASAnalysis}}.
+#'
+#' @rdname as.GBRROASAnalysisData
+as.GBRROASAnalysisData <- function(obj, ...) {
+  UseMethod("as.GBRROASAnalysisData")
+}
+
+#' @param response (string) name of the response variable column.
+#' @param cost (string) name of the cost variable column.
+#' @param pretest.period (vector of non-negative integers) number(s) of the
+#'   period(s) forming the pretest period.
+#' @param intervention.period (vector of non-negative integers) number(s) of
+#'   the period(s) forming the intervention period. All must be larger
+#'   than the largest period in the pretest period.
+#' @param cooldown.period (NULL or vector of non-negative integers) number(s)
+#'   of the period(s) forming the cooldown period. All must be larger than
+#'   the largest period in the intervention period.
+#' @param control.group (NULL or a vector of positive integers) number(s) of
+#'   geo groups forming the control group.
+#' @param treatment.group (NULL or a vector of positive integers) number(s) of
+#'   geo groups forming the control group.
+#'
+#' @rdname as.GBRROASAnalysisData
 as.GBRROASAnalysisData.GeoExperimentData <- function(obj,
                                                      response=character(0),
                                                      cost=character(0),
@@ -21,32 +50,6 @@ as.GBRROASAnalysisData.GeoExperimentData <- function(obj,
                                                      control.group=1L,
                                                      treatment.group=2L,
                                                      ...) {
-  # Coerces an object to a GBRROASAnalysisData object.
-  #
-  # Args:
-  #   obj: a GeoExperimentData object.
-  #   response: (string) name of the response variable column.
-  #   cost: (string) name of the cost variable column.
-  #   pretest.period: (vector of non-negative integers) number(s) of the
-  #     period(s) forming the pretest period.
-  #   intervention.period: (vector of non-negative integers) number(s) of the
-  #     period(s) forming the intervention period. All must be larger than the
-  #     largest period in the pretest period.
-  #   cooldown.period: (NULL or vector of non-negative integers) number(s) of
-  #     the period(s) forming the cooldown period. All must be larger than the
-  #     largest period in the intervention period.
-  #   control.group: (NULL or a vector of positive integers) number(s) of geo
-  #     groups forming the control group.
-  #   treatment.group: (NULL or a vector of positive integers) number(s) of geo
-  #     groups forming the control group.
-  #   ...: ignored.
-  #
-  # Returns:
-  #   A GBRROASAnalysisData object.
-  #
-  # Documentation:
-  #   seealso: as.GBRROASAnalysisData (generic).
-
   SetMessageContextString("as.GBRROASAnalysisData.GeoExperimentData")
   on.exit(SetMessageContextString())
 

R/as_geoexperimentdata.R

@@ -12,40 +12,32 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-as.GeoExperimentData <- function(obj, ...) {
-  # Coerces an object to a GeoExperimentData object.
-  #
-  # Args:
-  #   obj: an object.
-  #   ...: further arguments passed to methods.
-  #
-  # Returns:
-  #   A GeoExperimentData object.
-  #
-  # Notes:
-  #   A generic S3 method.
+#' Coerces an object to a GeoExperimentData object.
+#'
+#' @param obj an object.
+#' @param ... further arguments passed to methods.
+#'
+#' @return A GeoExperimentData object.
+#'
+#' @rdname as.GeoExperimentData
 
+as.GeoExperimentData <- function(obj, ...) {
   UseMethod("as.GeoExperimentData")
 }
 
+#' Coerces a GeoTimeseries object to a GeoExperiment object.
+#'
+#' @param strict (flag) if FALSE, the additional columns are optional and no
+#'   error is thrown if any of them is missing;
+#'
+#' @return A GeoExperimentData object.
+#'
+#' @note The GeoTimeseries object is supposed to have the columns 'period',
+#'   'geo.group', and 'assignment'. If any of these columns are missing,
+#'   the corresponding columns in the resulting object will be 'NA'.
+#'
+#' @rdname as.GeoExperimentData
 as.GeoExperimentData.GeoTimeseries <- function(obj, strict=TRUE, ...) {
-  # Coerces a GeoTimeseries object to a GeoExperiment object.
-  #
-  # Args:
-  #   obj: a GeoTimeseries object with the additional columns 'period',
-  #     'geo.group', and 'assignment'. If any of these columns are
-  #     missing, the corresponding columns in the resulting object
-  #     will be 'NA'.
-  #   strict: (flag) if FALSE, the additional columns are optional and
-  #     no error is thrown if any of them is missing;
-  #   ...: ignored.
-  #
-  # Returns:
-  #   A GeoExperimentData object.
-  #
-  # Documentation:
-  #   seealso: as.GeoExperimentData (generic).
-
   SetMessageContextString("as.GeoExperimentData.GeoTimeseries")
   on.exit(SetMessageContextString())
 

R/as_geotimeseries.R

@@ -12,18 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-as.GeoTimeseries <- function(obj, ...) {
-  # Coerce an object to a GeoTimeseries object.
-  #
-  # Args:
-  #   obj: an object.
-  #   ...: additional arguments to be passed to or from methods.
-  #
-  # Returns:
-  #   A GeoTimeseries object.
-  #
-  # Notes:
-  #   A S3 generic method.
+#' Coerce an object to a GeoTimeseries object.
+#'
+#' @param obj an object.
+#' @param ... additional arguments to be passed to or from methods.
+#'
+#' @return A GeoTimeseries object.
 
+as.GeoTimeseries <- function(obj, ...) {
   UseMethod("as.GeoTimeseries")
 }

R/as_matrix.R

@@ -12,18 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-as.matrix.GeoTimeseries <- function(x, response, ...) {
-  # Coerces a response metric of a GeoTimeseries to a matrix representation
-  # with geos in rows, dates in columns.
-  #
-  # Args:
-  #   x: a GeoTimeseries object.
-  #   response: (string) name of the response metric to use.
-  #   ...: ignored.
-  #
-  # Returns:
-  #   A numeric matrix of the response metric, geos in rows, dates in columns.
+#' Coerces a response metric of a GeoTimeseries to a matrix representation
+#' with geos in rows, dates in columns.
+#'
+#' @param x a GeoTimeseries object.
+#' @param response (string) name of the response metric to use.
+#' @param ... ignored.
+#' @return A numeric matrix of the response metric, geos in rows, dates in
+#'   columns.
 
+as.matrix.GeoTimeseries <- function(x, response, ...) {
   SetMessageContextString("as.matrix.GeoTimeseries")
   on.exit(SetMessageContextString())
 
@@ -44,3 +42,17 @@ as.matrix.GeoTimeseries <- function(x, response, ...) {
 
   return(obj.result)
 }
+
+#' Extracts the real-valued matrix of quantiles from a TBRQuantiles object.
+#'
+#' @param x a TBRQuantiles object.
+#' @param ... ignored.
+#'
+#' @return A real-valued matrix of the quantiles. The column names are the
+#'   same as those in the TBRQuantiles object.
+
+as.matrix.TBRQuantiles <- function(x, ...) {
+  m <- as.matrix(as.data.frame(x)[!(names(x) %in% c(kDate, kPeriod))])
+  rownames(m) <- as.character(x[[kDate]])
+  return(m)
+}