├── CONTRIBUTING ├── ChangeLog ├── DESCRIPTION ├── LICENSE ├── NAMESPACE ├── R ├── aggregate.R ├── aggregatetimeseries.R ├── as_gbrroasanalysisdata.R ├── as_geoexperimentdata.R ├── as_geotimeseries.R ├── as_matrix.R ├── as_tbranalysisdata.R ├── as_tbrplotdata.R ├── constants.R ├── dogbrroasanalysis.R ├── doroasanalysis.R ├── doroaspreanalysis.R ├── dotbranalysis.R ├── dotbranalysis_tbr1.R ├── dotbrroasanalysis.R ├── estimateincremental.R ├── experimentperiods.R ├── extractexperimentperiods.R ├── extractgeoassignment.R ├── extractgeos.R ├── extractgeostrata.R ├── extracttreatmentassignment.R ├── gbrroasanalysisdata.R ├── gbrroasanalysisfit_gbr1.R ├── geoassignment.R ├── geoexperimentdata.R ├── geos.R ├── geostrata.R ├── geotimeseries.R ├── geoxpreanalysisdata.R ├── getgeogroup.R ├── getgeonames.R ├── getweeklyaverages.R ├── isinperiod.R ├── mapgeogroups.R ├── merge_methods.R ├── plot_methods.R ├── plot_tbrplotdata.R ├── quantile.R ├── randomize.R ├── roasanalysisresults.R ├── setexperimentperiods.R ├── setgeoassignment.R ├── setgeogroup.R ├── setincrementalresponse.R ├── setspendchange.R ├── settreatmentassignment.R ├── simulategeoxdataset.R ├── simulateposterior.R ├── simulateroasanalysis.R ├── startup_message.R ├── subset.R ├── summary_tbranalysisfit_tbr1.R ├── tbranalysisdata.R ├── treatmentassignment.R ├── utils_analysis.R ├── utils_assert.R ├── utils_check_objects.R ├── utils_check_vectors.R ├── utils_class.R ├── utils_general.R ├── utils_messaging.R ├── utils_strings.R └── utils_time.R ├── README.md ├── data ├── geoassignment.rda └── salesandcost.rda ├── inst └── doc │ ├── GeoexperimentsResearch-manual.pdf │ └── GeoexperimentsResearch-vignette.pdf ├── man ├── AggregateTimeseries.Rd ├── CheckForAllTrue.Rd ├── CheckForBadValues.Rd ├── CheckForDuplicateRows.Rd ├── CheckForMapping.Rd ├── CheckForMissingColumns.Rd ├── CheckForTypes.Rd ├── CheckGeoGroupNumber.Rd ├── CheckPeriodNumbers.Rd ├── CheckThat.Rd ├── ComputeLinearModelWeights.Rd ├── ConcatItems.Rd ├── CountRandomizations.Rd ├── CountRandomizationsInAStratum.Rd ├── DoGBRROASAnalysis.Rd ├── DoROASPreanalysis.Rd ├── DoTBRAnalysis.Rd ├── DoTBRAnalysisTbr1.Rd ├── DoTBRROASAnalysis.Rd ├── EstimateIncremental.Rd ├── ExperimentPeriods.Rd ├── ExtractExperimentPeriods.Rd ├── ExtractGeoAssignment.Rd ├── ExtractGeoStrata.Rd ├── ExtractGeos.Rd ├── ExtractTreatmentAssignment.Rd ├── FormatText.Rd ├── GenerateStrata.Rd ├── GeoAssignment.Rd ├── GeoExperimentData.Rd ├── GeoExperimentPreanalysisData.Rd ├── GeoStrata.Rd ├── GeoTimeseries.Rd ├── Geos.Rd ├── GetGeoNames.GeoStrata.Rd ├── GetGeoNames.Rd ├── GetInfo.Rd ├── GetMessageContextString.Rd ├── GetModelIds.Rd ├── GetOneTBRDataFrameForGgplot.Rd ├── GetPreanalysisSummary.Rd ├── GetTBRDataFrameForGgplot.Rd ├── GetTBRPlotPanelNames.Rd ├── GetWeeklyAverages.Rd ├── GetWeeklyShadedBackgroundDataFrameForGgplot.Rd ├── IsFixedRandomization.Rd ├── IsInPeriod.Rd ├── IsStratumCompatibleWithRatios.Rd ├── Message.Rd ├── Messagef.Rd ├── ROASAnalysisResults.Rd ├── ROASPreanalysisFitRow.Rd ├── Randomize.Rd ├── RenameColumns.Rd ├── SetExperimentPeriods.Rd ├── SetGeoAssignment.Rd ├── SetIncrementalResponse.Rd ├── SetInfo.Rd ├── SetMessageContextString.Rd ├── SetSpendChange.Rd ├── SetTreatmentAssignment.Rd ├── SimulateGeoExperimentData.Rd ├── SimulatePosterior.Rd ├── SimulateROASAnalysis.Rd ├── Subset.Rd ├── TBRAnalysisData.Rd ├── TreatmentAssignment.Rd ├── aggregate.GeoTimeseries.Rd ├── as.GBRROASAnalysisData.Rd ├── as.GeoExperimentData.Rd ├── as.GeoTimeseries.Rd ├── as.TBRAnalysisData.Rd ├── as.TBRPlotData.Rd ├── as.matrix.GeoTimeseries.Rd ├── as.matrix.TBRQuantiles.Rd ├── coef.GBRROASAnalysisFitGbr1.Rd ├── confint.GBRROASAnalysisFitGbr1.Rd ├── cumsum.PosteriorSimulations.Rd ├── doroasanalysis.Rd ├── gbrroasanalysisdata.Rd ├── geoassignment-data.Rd ├── getgeogroup.Rd ├── mapgeogroups.Rd ├── merge.GeoExperimentData.Rd ├── merge.GeoTimeseries.Rd ├── plot.GeoTimeseries.Rd ├── plot.Geos.Rd ├── plot.TBRAnalysisFitTbr1.Rd ├── plot.TBRPlotData.Rd ├── plot.TBRROASAnalysisFit.Rd ├── print.GBRROASAnalysisFitGbr1.Rd ├── print.ROASPreanalysisFit.Rd ├── print.TBRROASAnalysisFit.Rd ├── quantile.PosteriorSimulations.Rd ├── quantile.TBRAnalysisFitTbr1.Rd ├── quantile.TBRROASAnalysisFit.Rd ├── round.ROASAnalysisResults.Rd ├── salesandcost-data.Rd ├── setgeogroup.Rd ├── signif.ROASAnalysisResults.Rd ├── summary.GBRROASAnalysisFitGbr1.Rd ├── summary.ROASPreanalysisFit.Rd ├── summary.TBRAnalysisFitTbr1.Rd ├── summary.TBRROASAnalysisFit.Rd ├── utils_check_objects.Rd ├── utils_check_vectors.Rd └── utils_time.Rd ├── tests ├── testthat.R └── testthat │ ├── helper_01_data.R │ ├── helper_02_data.R │ ├── test_001_utils_check_objects.R │ ├── test_001_utils_check_vectors.R │ ├── test_002_utils_messaging.R │ ├── test_003_utils_strings.R │ ├── test_004_utils_class.R │ ├── test_005_utils_time.R │ ├── test_006_utils_assert.R │ ├── test_007_utils_general.R │ ├── test_010_class_GeoTimeseries.R │ ├── test_020a_geoassignment.R │ ├── test_020b_experimentperiods.R │ ├── test_020c_trtassignment.R │ ├── test_022_geoexperimentdata.R │ ├── test_024_set.R │ ├── test_025_setspendchange.R │ ├── test_026_setincrementalresponse.R │ ├── test_030_methods_aggregate.R │ ├── test_030_methods_subset.R │ ├── test_040_as_gbranalysisdata.R │ ├── test_040_gbrpostanalysisdata.R │ ├── test_041_gbranalysis.R │ ├── test_042_roaspostanalysisresults.R │ ├── test_043_aggregatetimeseries.R │ ├── test_044_plot.R │ ├── test_045_merge.R │ ├── test_060_tbranalysisdata.R │ ├── test_061_as_tbranalysisdata.R │ ├── test_062_isinperiod.R │ ├── test_070_tbranalysismodel1.R │ ├── test_072_getgeonames.R │ ├── test_075_getweeklyaverages.R │ ├── test_080_geos.R │ ├── test_085_geostrata.R │ ├── test_086_setgeogroups.R │ ├── test_087_getgeogroup.R │ ├── test_088_mapgeogroups.R │ ├── test_090_randomize.R │ ├── test_100_geoxpreanalysisdata.R │ ├── test_110_simulateposterior.R │ ├── test_120_dotbrroasanalysis.R │ ├── test_125_quantile.R │ ├── test_130_doroasanalysis.R │ ├── test_140_dopreanalysis.R │ ├── test_160_as_tbrplotdata.R │ └── test_170_tbrplot.R └── vignettes └── GeoexperimentsResearch-vignette.Rmd /CONTRIBUTING: -------------------------------------------------------------------------------- 1 | Please send any reports to geoexperiments-opensource@google.com. 2 | -------------------------------------------------------------------------------- /ChangeLog: -------------------------------------------------------------------------------- 1 | 2017-04-05: Google 2 | * Version 1.0.3 3 | * Update documentation: roxygenize comments, reorganize help pages. 4 | 2017-04-04: Google 5 | * Version 1.0.2 6 | * Update Vignette: add URL to the TBR white paper. 7 | * Update Vignette: include details on experiment periods. 8 | 2017-03-22: Google 9 | * Version 1.0.1 10 | * Update GBR weighting scheme. 11 | 2017-03-06: Google 12 | * Version 1.0.0 13 | * Initial commit. 14 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: GeoexperimentsResearch 2 | Title: Geo Experiments 3 | Author: Google Inc. 4 | Maintainer: Google Inc. 5 | Description: Functions for manipulating and analyzing geo experiment data. 6 | Depends: 7 | R (>= 3.2.2), 8 | stats 9 | Imports: 10 | assertthat (>= 0.1.0.99), 11 | ggplot2 (>= 2.0.0), 12 | reshape2 (>= 1.2.1), 13 | MASS (>= 7.3) 14 | Suggests: 15 | testthat (>= 0.10.0), 16 | knitr (>= 1.12.3) 17 | VignetteBuilder: knitr 18 | Date: 2017-04-05 19 | Version: 1.0.3 20 | License: Apache License 2.0 | file LICENSE 21 | Copyright: Copyright (C) 2017 Google, Inc. 22 | RoxygenNote: 5.0.1 23 | -------------------------------------------------------------------------------- /R/aggregate.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Aggregate the Metrics of a GeoTimeseries. 16 | #' 17 | #' @param x a GeoTimeseries object. 18 | #' @param by (character vector) name(s) of column(s) by which to group. 19 | #' @param FUN (function) function to apply to each metric column. 20 | #' @param metrics (character vector) metrics to aggregate. Default is all 21 | #' metrics. 22 | #' @param ... optional arguments passed to FUN. 23 | #' 24 | #' @return A data.frame object. 25 | #' 26 | #' @note 27 | #' Uses \code{aggregate.data.frame} to do the aggregation. This function 28 | #' omits rows that have missing values in the '\code{by}' columns. 29 | #' 30 | #' @seealso AggregateTimeseries. 31 | 32 | aggregate.GeoTimeseries <- function(x, by=kGeo, FUN=base::sum, 33 | metrics=NULL, ...) { 34 | SetMessageContextString("aggregate.GeoTimeseries") 35 | on.exit(SetMessageContextString()) 36 | 37 | assert_that(is.function(FUN)) 38 | all.metrics <- GetInfo(x, "metrics") 39 | if (is.null(metrics)) { 40 | metrics <- all.metrics 41 | } 42 | # Ensure that all 'metrics' are there. 43 | CheckForMissingColumns(metrics, dataframe=x) 44 | # Ensure that all 'by' columns are there. 45 | CheckForMissingColumns(by, dataframe=x) 46 | # 'metrics' and 'by' cannot intersect. 47 | assert_that(length(intersect(metrics, by)) == 0L, 48 | msg=Message("'metrics' and 'by' cannot intersect")) 49 | dfx <- as.data.frame(x)[metrics] 50 | dfb <- as.data.frame(x)[by] 51 | dfa <- aggregate(dfx, by=dfb, FUN=FUN, ...) 52 | return(dfa) 53 | } 54 | -------------------------------------------------------------------------------- /R/aggregatetimeseries.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Aggregate the metrics of a time series object over specified time 16 | #' intervals. 17 | #' 18 | #' @param obj an object. 19 | #' @param freq (string) 'weekly' or 'monthly' aggregation. 20 | #' @param ... further arguments passed to or from other methods. 21 | #' 22 | #' @return An object of the same class as 'obj'. 23 | #' 24 | #' @note 25 | #' \itemize{ 26 | #' \item{'Weekly' frequency}: each day in the time series is mapped 27 | #' to the next Sunday, then aggregated. 28 | #' \item{'Monthly' frequency}: each day in the time series is mapped to 29 | #' the last day of the month, then aggregated. No check is made about 30 | #' the current frequency. This works best on daily data. So it is 31 | #' possible to attempt to change a 'monthly' frequency back to 'weekly', 32 | #' but this simply re-maps the last day of the month to the next Sunday. 33 | #' } 34 | #' 35 | #' @seealso \code{\link{aggregate.GeoTimeseries}}. 36 | #' 37 | #' @rdname AggregateTimeseries 38 | 39 | AggregateTimeseries <- function(obj, freq=c("weekly", "monthly"), ...) { 40 | UseMethod("AggregateTimeseries") 41 | } 42 | 43 | #' @rdname AggregateTimeseries 44 | 45 | AggregateTimeseries.GeoTimeseries <- function(obj, freq, ...) { 46 | SetMessageContextString("AggregateTimeseries.GeoTimeseries") 47 | on.exit(SetMessageContextString()) 48 | 49 | dates <- obj[[kDate]] 50 | # Last day of week is Sunday (=7). 51 | new.dates <- switch(freq, 52 | weekly=.GetLastDayOfWeek(dates, last.day=7L), 53 | monthly=.GetLastDayOfMonth(dates), 54 | stop(Message(paste0("Possible values for 'freq' are ", 55 | "'weekly' and 'monthly'")))) 56 | obj[[kDate]] <- new.dates 57 | internal <- intersect(c(kDate, kGeo, kPeriod, kGeoGroup, kAssignment), 58 | names(obj)) 59 | df.agg <- aggregate(obj, by=internal) 60 | metrics <- GetInfo(obj, "metrics") 61 | obj.gts <- GeoTimeseries(df.agg, metrics=metrics) 62 | return(obj.gts) 63 | } 64 | -------------------------------------------------------------------------------- /R/as_geoexperimentdata.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Coerces an object to a GeoExperimentData object. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... further arguments passed to methods. 19 | #' 20 | #' @return A GeoExperimentData object. 21 | #' 22 | #' @rdname as.GeoExperimentData 23 | 24 | as.GeoExperimentData <- function(obj, ...) { 25 | UseMethod("as.GeoExperimentData") 26 | } 27 | 28 | #' Coerces a GeoTimeseries object to a GeoExperiment object. 29 | #' 30 | #' @param strict (flag) if FALSE, the additional columns are optional and no 31 | #' error is thrown if any of them is missing; 32 | #' 33 | #' @return A GeoExperimentData object. 34 | #' 35 | #' @note The GeoTimeseries object is supposed to have the columns 'period', 36 | #' 'geo.group', and 'assignment'. If any of these columns are missing, 37 | #' the corresponding columns in the resulting object will be 'NA'. 38 | #' 39 | #' @rdname as.GeoExperimentData 40 | as.GeoExperimentData.GeoTimeseries <- function(obj, strict=TRUE, ...) { 41 | SetMessageContextString("as.GeoExperimentData.GeoTimeseries") 42 | on.exit(SetMessageContextString()) 43 | 44 | obj.ga <- ExtractGeoAssignment(obj, strict=strict) 45 | obj.periods <- ExtractExperimentPeriods(obj, strict=strict) 46 | obj.trt <- ExtractTreatmentAssignment(obj, strict=strict) 47 | obj.ged <- GeoExperimentData(obj, 48 | periods=obj.periods, 49 | geo.assignment=obj.ga, 50 | treat.assignment=obj.trt) 51 | return(obj.ged) 52 | } 53 | -------------------------------------------------------------------------------- /R/as_geotimeseries.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Coerce an object to a GeoTimeseries object. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... additional arguments to be passed to or from methods. 19 | #' 20 | #' @return A GeoTimeseries object. 21 | 22 | as.GeoTimeseries <- function(obj, ...) { 23 | UseMethod("as.GeoTimeseries") 24 | } 25 | -------------------------------------------------------------------------------- /R/as_matrix.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Coerces a response metric of a GeoTimeseries to a matrix representation 16 | #' with geos in rows, dates in columns. 17 | #' 18 | #' @param x a GeoTimeseries object. 19 | #' @param response (string) name of the response metric to use. 20 | #' @param ... ignored. 21 | #' @return A numeric matrix of the response metric, geos in rows, dates in 22 | #' columns. 23 | 24 | as.matrix.GeoTimeseries <- function(x, response, ...) { 25 | SetMessageContextString("as.matrix.GeoTimeseries") 26 | on.exit(SetMessageContextString()) 27 | 28 | obj <- x 29 | metrics <- GetInfo(obj, "metrics") 30 | assert_that(is.string(response), 31 | response %in% GetInfo(obj, "metrics"), 32 | msg=paste0("The specified response variable '", 33 | response, "' is not available")) 34 | 35 | # Create a matrix with geos in rows and date numbers in columns. 36 | form <- as.formula(sprintf("%s ~ %s + %s", response, kGeo, kDate)) 37 | x <- xtabs(form, data=obj) 38 | 39 | # As for R 3.2.2, as.matrix(x) does not yet produce a plain matrix, 40 | # so we must do unclass first. 41 | obj.result <- as.matrix(unclass(x)) 42 | 43 | return(obj.result) 44 | } 45 | 46 | #' Extracts the real-valued matrix of quantiles from a TBRQuantiles object. 47 | #' 48 | #' @param x a TBRQuantiles object. 49 | #' @param ... ignored. 50 | #' 51 | #' @return A real-valued matrix of the quantiles. The column names are the 52 | #' same as those in the TBRQuantiles object. 53 | 54 | as.matrix.TBRQuantiles <- function(x, ...) { 55 | m <- as.matrix(as.data.frame(x)[!(names(x) %in% c(kDate, kPeriod))]) 56 | rownames(m) <- as.character(x[[kDate]]) 57 | return(m) 58 | } 59 | -------------------------------------------------------------------------------- /R/doroasanalysis.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Performs a ROAS analysis using the given model. 16 | #' 17 | #' @param obj an object. 18 | #' @param model (string) id of the model to use. Available models are 'gbr1', 19 | #' 'tbr1'. 20 | #' @param ... further arguments passed to or from other models. 21 | #' @return A GBRROASAnalysisFit (for 'gbr1') or a TBRROASAnalysisFit object 22 | #' (for 'tbr1'). 23 | #' 24 | #' @note 25 | #' Dispatches the right method for the given model type. 26 | #' @seealso \code{\link{DoGBRROASAnalysis}}, \code{\link{DoTBRROASAnalysis}}. 27 | #' @rdname doroasanalysis 28 | DoROASAnalysis <- function(obj, model, ...) { 29 | SetMessageContextString("DoROASAnalysis") 30 | on.exit(SetMessageContextString()) 31 | 32 | assert_that(is.nonempty.string(model)) 33 | assert_that(model %in% GetModelIds(), 34 | msg=Messagef("Unknown model: '%s'", model)) 35 | 36 | method <- kModelToMethod[model] 37 | obj.result <- switch(method, 38 | gbr=DoGBRROASAnalysis(obj, ...), 39 | tbr=DoTBRROASAnalysis(obj, model=model, ...)) 40 | return(obj.result) 41 | } 42 | -------------------------------------------------------------------------------- /R/dotbranalysis.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Executes a TBR Causal Effect Analysis. 16 | #' 17 | #' @param obj an object. 18 | #' @param model (string) model to use. 19 | #' @param ... further arguments passed to or from other methods. 20 | #' 21 | #' @return A TBRAnalysisFit object. 22 | #' 23 | #' @note 24 | #' Dispatcher of methods. 25 | #' The actual method to execute the 'tbr1' method is \code{DoTBRAnalysisTbr1}. 26 | #' @seealso \code{\link{DoTBRAnalysisTbr1}}, \code{\link{DoROASAnalysis}}, 27 | #' \code{\link{DoGBRROASAnalysis}}. 28 | #' @rdname DoTBRAnalysis 29 | DoTBRAnalysis <- function(obj, model, ...) { 30 | assert_that(is.nonempty.string(model)) 31 | if (model %in% kDefault) { 32 | model <- getOption("geoexperiments.default.tbr.model", 33 | default=kTBRModel1) 34 | } 35 | UseMethod("DoTBRAnalysis") 36 | } 37 | 38 | #' @rdname DoTBRAnalysis 39 | DoTBRAnalysis.GeoExperimentData <- function(obj, model, ...) { 40 | obj <- as.TBRAnalysisData(obj, ...) 41 | obj.result <- DoTBRAnalysis(obj, model=model, ...) 42 | return(obj.result) 43 | } 44 | 45 | #' @rdname DoTBRAnalysis 46 | DoTBRAnalysis.TBRAnalysisData <- function(obj, model, ...) { 47 | SetMessageContextString("DoTBRAnalysis.TBRAnalysisData") 48 | on.exit(SetMessageContextString()) 49 | 50 | if (model %in% kTBRModel1) { 51 | obj.result <- DoTBRAnalysisTbr1(obj, ...) 52 | } else { 53 | stop(Messagef("Unknown model '%s'", model)) 54 | } 55 | return(obj.result) 56 | } 57 | -------------------------------------------------------------------------------- /R/extractexperimentperiods.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Extracts an ExperimentPeriods object. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... further arguments passed on to methods. 19 | #' 20 | #' @return An ExperimentPeriods object. 21 | #' 22 | #' @rdname ExtractExperimentPeriods 23 | ExtractExperimentPeriods <- function(obj, ...) { 24 | UseMethod("ExtractExperimentPeriods") 25 | } 26 | 27 | #' Extracts a ExperimentPeriods object from a GeoTimeseries. 28 | #' 29 | #' @param strict (flag) if FALSE, the function returns NULL if the column 30 | #' 'period' does not exist. Otherwise, throws an error. 31 | #' 32 | #' @return An ExperimentPeriods object. 33 | #' 34 | #' @rdname ExtractExperimentPeriods 35 | ExtractExperimentPeriods.GeoTimeseries <- function(obj, strict=TRUE, ...) { 36 | SetMessageContextString("ExtractExperimentPeriods.GeoTimeseries") 37 | on.exit(SetMessageContextString()) 38 | 39 | assert_that(is.flag(strict)) 40 | if (!strict && !(kPeriod %in% names(obj))) { 41 | return(NULL) 42 | } 43 | # Ensure that the required column 'period' is in the given data frame. 44 | CheckForMissingColumns(kPeriod, dataframe=obj, what="required") 45 | # Find the dates that mark the limits of the periods. 46 | keys <- c(date=kDate, group=kPeriod) 47 | df.agg <- unique(obj[keys]) 48 | # R drops the Date class attribute when unlisting, so keep the dates 49 | # temporarily as character. 50 | date.ranges <- tapply(df.agg[[kDate]], df.agg[[kPeriod]], 51 | FUN=function(x) as.character(range(x))) 52 | start.dates <- as.Date(sapply(date.ranges, "[", 1L)) 53 | end.date <- max(as.Date(unlist(date.ranges))) 54 | period.dates <- c(start.dates, end.date) 55 | obj.ga <- ExperimentPeriods(period.dates) 56 | return(obj.ga) 57 | } 58 | -------------------------------------------------------------------------------- /R/extractgeoassignment.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Extracts a GeoAssignment object. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... further arguments passed on to methods. 19 | #' @return A GeoAssignment object. Or \code{NULL} if not available. 20 | #' 21 | #' @rdname ExtractGeoAssignment 22 | 23 | ExtractGeoAssignment <- function(obj, ...) { 24 | UseMethod("ExtractGeoAssignment") 25 | } 26 | 27 | #' Attempts to extract a GeoAssignment object from a GeoTimeseries. 28 | #' 29 | #' @param strict (flag) if FALSE, the function returns NULL if the column 30 | #' 'geo.group' does not exist. Otherwise, throws an error. 31 | #' 32 | #' @return A GeoAssignment object. 33 | #' 34 | #' @note 35 | #' Finds all unique pairs of ('geo', 'geo.group') in the GeoTimeseries. 36 | #' 'geo.group' can have missing values. 37 | #' 38 | #' @rdname ExtractGeoAssignment 39 | ExtractGeoAssignment.GeoTimeseries <- function(obj, strict=TRUE, ...) { 40 | SetMessageContextString("ExtractGeoAssignment.GeoTimeseries") 41 | on.exit(SetMessageContextString()) 42 | 43 | assert_that(is.flag(strict)) 44 | if (!strict && !(kGeoGroup %in% names(obj))) { 45 | return(NULL) 46 | } 47 | # Ensure that all required columns are in the given data frame. 48 | CheckForMissingColumns(kGeoGroup, dataframe=obj, what="required") 49 | # Aggregate all metrics by geo and geo group; keep them in the 50 | # data frame for reference. By default sort by the 1st metric. 51 | metrics <- GetInfo(obj, "metrics") 52 | keys <- c(kGeo, kGeoGroup) 53 | df.agg <- as.data.frame(unique(obj[keys])) 54 | df.agg <- df.agg[order(df.agg[[kGeo]]), , drop=FALSE] 55 | obj.ga <- GeoAssignment(df.agg) 56 | return(obj.ga) 57 | } 58 | 59 | #' @rdname ExtractGeoAssignment 60 | ExtractGeoAssignment.GeoExperimentData <- function(obj, ...) { 61 | geo.assignment <- GetInfo(obj, "geo.assignment") 62 | return(geo.assignment) 63 | } 64 | -------------------------------------------------------------------------------- /R/extractgeos.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Extract a Geos object from an object. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... other arguments passed to the methods. 19 | #' 20 | #' @return A 'Geos' object. 21 | #' 22 | #' @rdname ExtractGeos 23 | ExtractGeos <- function(obj, ...) { 24 | UseMethod("ExtractGeos") 25 | } 26 | 27 | #' @param volume (string) name of a metric in the GeoTimeseries over which to 28 | #' generate the 'volume' column. If omitted, the first metric is used. 29 | #' The volumes have to be non-negative. 30 | #' 31 | #' @return A Geos object, with the average weekly volume of all metrics in 32 | #' 'obj'. 33 | #' 34 | #' @rdname ExtractGeos 35 | ExtractGeos.GeoTimeseries <- function(obj, volume=NULL, ...) { 36 | SetMessageContextString("ExtractGeos.GeoTimeseries") 37 | on.exit(SetMessageContextString()) 38 | 39 | metrics <- GetInfo(obj, "metrics") 40 | if (length(volume) == 0) { 41 | volume <- metrics[1] 42 | } 43 | assert_that(is.nonempty.string(volume), 44 | volume %in% metrics) 45 | CheckForBadValues(obj, columns=volume, 46 | CHECK=function(z) { z < 0 }, good=FALSE, what="negative") 47 | geos <- GetWeeklyAverages(obj) 48 | obj.result <- Geos(geos, volume=volume) 49 | return(obj.result) 50 | } 51 | -------------------------------------------------------------------------------- /R/extractgeostrata.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Extract a GeoStrata object from an object. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... further arguments passed to or from other methods. 19 | #' 20 | #' @return A GeoStrata object. 21 | #' 22 | #' @rdname ExtractGeoStrata 23 | 24 | ExtractGeoStrata <- function(obj, ...) { 25 | UseMethod("ExtractGeoStrata") 26 | } 27 | 28 | #' Extract a GeoStrata object from a GeoTimeseries. 29 | #' 30 | #' @param volume (string) name of a metric from which to generate the 31 | #' \code{volume} column. 32 | #' 33 | #' @rdname ExtractGeoStrata 34 | ExtractGeoStrata.GeoTimeseries <- function(obj, volume=NULL, ...) { 35 | SetMessageContextString("ExtractGeoStrata.GeoTimeseries") 36 | on.exit(SetMessageContextString()) 37 | 38 | obj.geos <- ExtractGeos(obj, volume=volume) 39 | obj <- GeoStrata(obj.geos, ...) 40 | return(obj) 41 | } 42 | 43 | #' @rdname ExtractGeoStrata 44 | ExtractGeoStrata.GeoExperimentData <- function(obj, volume=NULL, ...) { 45 | SetMessageContextString("ExtractGeoStrata.GeoExperimentData") 46 | on.exit(SetMessageContextString()) 47 | 48 | obj.geos <- ExtractGeos(obj, volume=volume) 49 | obj.ga <- GetInfo(obj, "geo.assignment") 50 | 51 | excluded.geos.ga <- obj.ga[obj.ga[[kGeoGroup]] == kExcludeGeoGroup, , 52 | drop=FALSE] 53 | obj <- GeoStrata(obj.geos, ...) 54 | if (nrow(excluded.geos.ga) > 0) { 55 | SetGeoGroup(obj) <- excluded.geos.ga 56 | } 57 | return(obj) 58 | } 59 | -------------------------------------------------------------------------------- /R/geoassignment.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Constructs a GeoAssignment object. 16 | #' 17 | #' @param x a data frame with columns 'geo' (character) and 'geo.group' 18 | #' (integer-valued, positive). 'geo.group' indicates the group (1, 2, 19 | #' ...) the corresponding geo belongs to. Other columns are allowed but 20 | #' not checked. If 'geo' is an integer-valued numeric or factor, it is 21 | #' coerced to character 22 | #' 23 | #' @return An object of class 'GeoAssignment'. 24 | #' 25 | #' @details 26 | #' The group numbers must be integers (integer-valued numeric are 27 | #' allowed as input), starting with 1. The column 'geo.group' *can* have 28 | #' missing values (NA), unlike 'geo', which must have no missing values, 29 | #' and no duplicates. A missing value in geo.group simply indicates that 30 | #' the mapping from a geo is not available. When associating the geo 31 | #' assignment with a GeoExperimentData object, the effect will be the same 32 | #' as if the geo with 'geo.group'==NA was not in the mapping in the first 33 | #' place. 34 | 35 | GeoAssignment <- function(x) { 36 | kClassName <- "GeoAssignment" 37 | SetMessageContextString(kClassName) 38 | on.exit(SetMessageContextString()) 39 | 40 | # Make sure 'x' is a plain data frame. 41 | assert_that(is.data.frame(x), 42 | msg=Message("'x' must be a data.frame")) 43 | # Required columns. 44 | required <- c(geo=kGeo, group=kGeoGroup) 45 | # Ensure that all required columns are in the given data frame. 46 | CheckForMissingColumns(required, dataframe=x, what="required") 47 | # Coerce 'geo' to character. 48 | if (is.factor(x[[kGeo]]) || is.integer.valued(x[[kGeo]])) { 49 | x[[kGeo]] <- as.character(x[[kGeo]]) 50 | } 51 | # Ensure that the required columns are of the specified type. 52 | checklist <- list(geo=is.character.vector, 53 | group=is.integer.valued) 54 | names(checklist) <- required[names(checklist)] 55 | CheckForTypes(x, checklist=checklist) 56 | # Do not allow missing values in 'geo'. 57 | CheckForBadValues(x, columns=kGeo, CHECK=is.na, good=FALSE, 58 | what="missing") 59 | # Check for specific bad values in 'geo.group'. Note: NAs are OK. 60 | CheckForBadValues(x, columns=kGeoGroup, CHECK=is.geo.group.number, 61 | good=c(TRUE, NA), what="bad") 62 | x[[kGeoGroup]] <- as.integer(x[[kGeoGroup]]) 63 | 64 | # Check for duplicate 'geo' columns. 65 | CheckForDuplicateRows(x, columns=kGeo) 66 | obj <- x 67 | obj <- SetInfo(obj, info=list()) 68 | class(obj) <- c(kClassName, oldClass(obj)) 69 | return(obj) 70 | } 71 | -------------------------------------------------------------------------------- /R/geos.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Constructor for Geos objects. 16 | #' 17 | #' @param x a data frame with column 'geo' and optionally other columns. Each 18 | #' 'geo' must be unique. 19 | #' @param volume name of the column that represents the 'volume' of the geo. 20 | #' The proportion of volume is computed. If omitted, the assumed volumes 21 | #' will be 1 for each geo. The volumes have to be non-negative and sum 22 | #' up to a positive value. 23 | #' 24 | #' @return An object of class 'Geos', which is a data frame with the column 25 | #' 'geo', the column 'proportion' and 'volume', and other optional 26 | #' columns. The rows are sorted by the descending order of 'volume'. 27 | 28 | Geos <- function(x, volume=NULL) { 29 | kClassName <- "Geos" 30 | SetMessageContextString(kClassName) 31 | on.exit(SetMessageContextString()) 32 | 33 | CheckForMissingColumns(kGeo, dataframe=x, what="required") 34 | 35 | if (is.factor(x[[kGeo]])) { 36 | x[[kGeo]] <- as.character(x[[kGeo]]) 37 | } 38 | checklist <- structure(list(is.character.vector), names=kGeo) 39 | CheckForTypes(x, checklist=checklist) 40 | 41 | # Ensure all geos are unique. 42 | CheckForDuplicateRows(x, columns=kGeo) 43 | 44 | # Disallow any missing values. 45 | CheckForBadValues(x, columns=names(x), 46 | CHECK=is.na, good=FALSE, what="missing") 47 | 48 | if (length(volume) > 0) { 49 | assert_that(is.nonempty.string(volume)) 50 | CheckForMissingColumns(volume, dataframe=x, what="specified") 51 | CheckForBadValues(x, columns=volume, 52 | CHECK=function(z) { z < 0 }, good=FALSE, what="negative") 53 | vol <- x[[volume]] 54 | assert_that(sum(vol) > 0, 55 | msg=sprintf(paste("To be defined as a volume, column '%s'", 56 | "needs to sum up to a positive value"), 57 | volume)) 58 | } else { 59 | vol <- rep(1, length.out=nrow(x)) 60 | } 61 | 62 | x[[kVolume]] <- vol 63 | proportion <- (vol / sum(vol)) 64 | x[[kProportion]] <- proportion 65 | first.cols <- c(kGeo, kProportion, kVolume) 66 | x <- x[union(first.cols, names(x))] 67 | obj <- x[rev(order(vol)), , drop=FALSE] 68 | rownames(obj) <- NULL 69 | 70 | class(obj) <- c(kClassName, class(obj)) 71 | return(obj) 72 | } 73 | -------------------------------------------------------------------------------- /R/getgeogroup.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Returns the geo-to-geo group mapping. 16 | #' 17 | #' @param obj an object with the columns 'geo' and 'geo.group'. 18 | #' @param geo (character vector or NULL) names of geos for which to obtain the 19 | #' geo group ids. 20 | #' @param ... other arguments passed on to the methods. 21 | #' @return A named integer-valued vector, with the geo names in the names 22 | #' attribute, mapping geos to geo group ids. 23 | #' @rdname getgeogroup 24 | GetGeoGroup <- function(obj, geo=NULL, ...) { 25 | UseMethod("GetGeoGroup") 26 | } 27 | 28 | #' @note 29 | #' If a specified 'geo' does not exist in the GeoAssignment object, the 30 | #' corresponding geo group will be an NA. 31 | #' @rdname getgeogroup 32 | GetGeoGroup.GeoAssignment <- function(obj, geo=NULL, ...) { 33 | SetMessageContextString("GetGeoGroup.GeoAssignment") 34 | on.exit(SetMessageContextString()) 35 | 36 | assert_that(is.null(geo) || is.character(geo)) 37 | 38 | map <- structure(as.integer(obj[[kGeoGroup]]), names=obj[[kGeo]]) 39 | 40 | if (length(geo) == 0) { 41 | return(map) 42 | } 43 | return(map[geo]) 44 | } 45 | 46 | #' @rdname getgeogroup 47 | GetGeoGroup.GeoExperimentData <- function(obj, geo=NULL, ...) { 48 | SetMessageContextString("GetGeoGroup.GeoExperimentData") 49 | on.exit(SetMessageContextString()) 50 | 51 | ga <- GetInfo(obj, "geo.assignment") 52 | assert_that(!is.null(ga), msg="No geo.assignment found") 53 | 54 | map <- GetGeoGroup.GeoAssignment(ga, geo=geo) 55 | return(map) 56 | } 57 | 58 | #' @rdname getgeogroup 59 | GetGeoGroup.GeoStrata <- function(obj, geo=NULL, ...) { 60 | SetMessageContextString("GetGeoGroup.GeoStrata") 61 | on.exit(SetMessageContextString()) 62 | 63 | map <- GetGeoGroup.GeoAssignment(obj, geo=geo) 64 | return(map) 65 | } 66 | -------------------------------------------------------------------------------- /R/getweeklyaverages.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Calculates the weekly averages of the metrics per geo. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... further arguments passed to or from other methods. 19 | #' 20 | #' @return A data frame with one row per 'geo', and the weekly averages of 21 | #' each metric in the columns. 22 | #' 23 | #' @rdname GetWeeklyAverages 24 | 25 | GetWeeklyAverages <- function(obj, ...) { 26 | UseMethod("GetWeeklyAverages") 27 | } 28 | 29 | #' @param na.rm (flag) remove NAs? 30 | #' 31 | #' @note 32 | #' Does not handle incomplete weeks. Each week is supposed to have the 33 | #' complete total sales of the week. If for example the first and last 34 | #' weeks of a daily data set are incomplete, the weekly average will be 35 | #' underestimated. Works for both weekly and daily data. The averages are 36 | #' calculated by first calculating the weekly sums for each geo, and then 37 | #' taking the averages over the weeks. \code{NA}s are removed by default. 38 | 39 | #' @rdname GetWeeklyAverages 40 | GetWeeklyAverages.GeoTimeseries <- function(obj, na.rm=TRUE, ...) { 41 | assert_that(is.flag(na.rm) && !is.na(na.rm)) 42 | 43 | metrics <- GetInfo(obj, "metrics") 44 | df.agg <- aggregate(obj, by=c(kGeo, kWeekindex), FUN=base::sum, na.rm=na.rm) 45 | df.result <- aggregate(df.agg[metrics], by=df.agg[kGeo], FUN=base::mean) 46 | df.result <- df.result[order(df.result[[kGeo]]), ] 47 | return(df.result) 48 | } 49 | -------------------------------------------------------------------------------- /R/isinperiod.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' [internal] Returns a logical vector indicating which of the rows are in 16 | #' the specified period(s). 17 | #' 18 | #' @param obj some object. 19 | #' @param periods names of the periods. 20 | #' 21 | #' @return A logical vector of length \code{nrow(obj)}, \code{TRUE} for a row 22 | #' that is within the given period(s), \code{FALSE} otherwise. No \code{NA}s. 23 | #' 24 | #' @rdname IsInPeriod 25 | IsInPeriod <- function(obj, periods) { 26 | assert_that(is.vector.of.nonempty.strings(periods)) 27 | there <- structure(periods %in% names(kStandardPeriods), names=periods) 28 | assert_that(all(there), 29 | msg=Message(FormatText(!there, "Unknown periods: $X"))) 30 | 31 | UseMethod("IsInPeriod") 32 | } 33 | 34 | #' @rdname IsInPeriod 35 | IsInPeriod.TBRAnalysisData <- function(obj, periods) { 36 | SetMessageContextString("IsInPeriod.TBRAnalysisData") 37 | on.exit(SetMessageContextString()) 38 | 39 | period <- obj[[kPeriod]] 40 | period.numbers <- unlist(kStandardPeriods[periods]) 41 | in.period <- (period %in% period.numbers) 42 | 43 | return(in.period) 44 | } 45 | 46 | #' @rdname IsInPeriod 47 | IsInPeriod.TBRAnalysisFitTbr1 <- function(obj, periods) { 48 | x <- IsInPeriod.TBRAnalysisData(obj, periods=periods) 49 | return(x) 50 | } 51 | 52 | #' @note \code{TBRROASAnalysisFit} consists of simulations with rows only for 53 | #' the prediction period, not for the preanalysis period. 54 | #' 55 | #' @rdname IsInPeriod 56 | IsInPeriod.TBRROASAnalysisFit <- function(obj, periods) { 57 | tbr.fit <- GetInfo(obj, "tbr.resp") 58 | in.prediction <- IsInPeriod(tbr.fit, periods="prediction") 59 | rows.in.periods <- IsInPeriod(tbr.fit, periods=periods)[in.prediction] 60 | return(rows.in.periods) 61 | } 62 | 63 | #' @note \code{TBRQuantiles} consists of simulations with rows only for the 64 | #' prediction period, not for the preanalysis period. 65 | #' 66 | #' @rdname IsInPeriod 67 | IsInPeriod.TBRQuantiles <- function(obj, periods) { 68 | rows.in.periods <- IsInPeriod.TBRAnalysisData(obj, periods=periods) 69 | return(rows.in.periods) 70 | } 71 | -------------------------------------------------------------------------------- /R/setexperimentperiods.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Associates the object with an ExperimentPeriods object. 16 | #' 17 | #' @param obj the object to change. 18 | #' @param ... further arguments passed to methods. 19 | #' @param value a ExperimentPeriods object. 20 | #' 21 | #' @return The object that has been modified in place. 22 | #' 23 | #' @rdname SetExperimentPeriods 24 | 25 | "SetExperimentPeriods<-" <- function(obj, ..., value) { 26 | UseMethod("SetExperimentPeriods<-") 27 | } 28 | 29 | #' @param strict (flag) insist that data has all specified experiment periods? 30 | #' 31 | #' @note The 'date' column is mapped to the 'period' column. The 'period' slot 32 | #' is assigned with the new value and the columns 'period' and 'assignment' are 33 | #' changed to reflect the new date ranges. 34 | #' 35 | #' @rdname SetExperimentPeriods 36 | "SetExperimentPeriods<-.GeoExperimentData" <- function(obj, strict=TRUE, ..., 37 | value) { 38 | SetMessageContextString("SetExperimentPeriods<-.GeoExperimentData") 39 | on.exit(SetMessageContextString()) 40 | 41 | assert_that(is.flag(strict)) 42 | assert_that(is.null(value) || inherits(value, "ExperimentPeriods"), 43 | msg=Message("An ExperimentPeriods object or NULL is required")) 44 | 45 | obj.periods <- value 46 | if (is.null(obj.periods)) { 47 | period.numbers <- NA_integer_ 48 | } else { 49 | column.order <- names(obj) 50 | dates <- obj[[kDate]] 51 | period.numbers <- rep(NA_integer_, length.out=nrow(obj)) 52 | for (i in seq_len(nrow(obj.periods))) { 53 | period.number <- obj.periods[i, "Period"] 54 | start.period <- obj.periods[i, "Start"] 55 | end.period <- obj.periods[i, "End"] 56 | dates.in.range <- (dates >= start.period & dates <= end.period) 57 | if (strict) { 58 | assert_that(any(dates.in.range), 59 | msg=paste0("No data available for period ", period.number)) 60 | } 61 | period.numbers[dates.in.range] <- period.number 62 | } 63 | } 64 | obj[[kPeriod]] <- period.numbers 65 | obj <- SetInfo(obj, periods=obj.periods) 66 | # Re-generate the treatment assignment vector, as 'geo.groups' may 67 | # have changed. 68 | SetTreatmentAssignment(obj) <- GetInfo(obj, "treat.assignment") 69 | return(obj) 70 | } 71 | -------------------------------------------------------------------------------- /R/settreatmentassignment.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Associates the object with an TreatmentAssignment object. 16 | #' 17 | #' @param obj the object to change. 18 | #' @param ... further arguments passed to methods. 19 | #' @param value a TreatmentAssignment object. 20 | #' 21 | #' @return The object (that has been modified in place). 22 | #' 23 | #' @rdname SetTreatmentAssignment 24 | 25 | "SetTreatmentAssignment<-" <- function(obj, ..., value) { 26 | UseMethod("SetTreatmentAssignment<-") 27 | } 28 | 29 | #' @param strict (flag) insist that data has all treatment combinations? 30 | #' 31 | #' @note The value pairs ('period', 'geo.group') are mapped to a (treatment) 32 | #' 'assignment' column. 33 | #' 34 | #' If 'strict' is TRUE, throws an error if some treatment assignments 35 | #' are not found in the data. If 'strict' is FALSE, no warnings or errors 36 | #' are thrown. 37 | #' 38 | #' @rdname SetTreatmentAssignment 39 | "SetTreatmentAssignment<-.GeoExperimentData" <- function(obj, strict=TRUE, ..., 40 | value) { 41 | SetMessageContextString("SetTreatmentAssignment<-.GeoExperimentData") 42 | on.exit(SetMessageContextString()) 43 | 44 | assert_that(is.flag(strict)) 45 | assert_that(inherits(value, "TreatmentAssignment") || is.null(value), 46 | msg=Message( 47 | "A TreatmentAssignment object or 'NULL' was expected")) 48 | 49 | obj.treat.assignment <- value 50 | info <- GetInfo(obj) 51 | if (is.null(obj.treat.assignment) || 52 | is.null(GetInfo(obj, "periods")) || 53 | is.null(GetInfo(obj, "geo.assignment"))) { 54 | # Not enough information: assignment will remain undefined. 55 | assignment <- NA_integer_ 56 | } else { 57 | key <- c(kPeriod, kGeoGroup) 58 | df.period.group <- as.data.frame(obj[key]) 59 | df.period.group[[kTmpi]] <- seq_len(nrow(obj)) 60 | df.trt <- as.data.frame(obj.treat.assignment) 61 | df.trt[[kTmpj]] <- seq_len(nrow(df.trt)) 62 | df.m <- merge(df.period.group, df.trt, by=key, all.x=TRUE, all.y=FALSE) 63 | # Restore original order. 64 | df.m <- df.m[order(df.m[[kTmpi]]), , drop=FALSE] 65 | assignment <- df.m[[kAssignment]] 66 | # Find out which ('period', 'geo.group') combinations were not 67 | # mapped. 68 | specified <- (!is.na(df.m)) # A matrix. 69 | key.specified <- (specified[, kPeriod] & specified[, kGeoGroup]) 70 | assigned <- specified[, kAssignment] 71 | needs.default <- (key.specified & !assigned) 72 | if (any(needs.default)) { 73 | assignment[needs.default] <- kTreatmentAssignment["none"] 74 | } 75 | excluded <- (obj[[kGeoGroup]] %in% kExcludeGeoGroup) 76 | assignment[excluded] <- kTreatmentAssignment["exclude"] 77 | } 78 | obj[[kAssignment]] <- assignment 79 | obj <- SetInfo(obj, treat.assignment=obj.treat.assignment) 80 | return(obj) 81 | } 82 | -------------------------------------------------------------------------------- /R/simulategeoxdataset.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Returns a geo experiment data set. 16 | #' 17 | #' @param obj an object. 18 | #' @param ... further arguments passed to or from other methods. 19 | #' 20 | #' @return A GeoExperimentData object with the experiment periods, geo 21 | #' assignment, and the treatment assignment set. 22 | #' 23 | #' @rdname SimulateGeoExperimentData 24 | SimulateGeoExperimentData <- function(obj, ...) { 25 | UseMethod("SimulateGeoExperimentData") 26 | } 27 | 28 | #' Returns a set number i from the GeoExperimentPreanalysisData object. 29 | #' 30 | #' @param i (positive integer or NA) number of the pseudo data set; if NA, the 31 | #' number will be drawn from a uniform discrete distribution. 32 | #' 33 | #' @note If the embedded 'geos' object is GeoStrata, a randomization is done 34 | #' and the geo assignment applied. 35 | #' 36 | #' @rdname SimulateGeoExperimentData 37 | SimulateGeoExperimentData.GeoExperimentPreanalysisData <- function(obj, 38 | i=NA_integer_, ...) { 39 | 40 | SetMessageContextString( 41 | "SimulateGeoExperimentData.GeoExperimentPreanalysisData") 42 | on.exit(SetMessageContextString()) 43 | 44 | i.max <- GetInfo(obj, "i.max") 45 | assert_that((is.count(i) && !isTRUE(is.na(i)) && i <= i.max) || 46 | isTRUE(is.na(i)), 47 | msg=Messagef("i must be >=1 and <= %d", i.max)) 48 | 49 | if (is.na(i)) { 50 | i <- sample.int(i.max, size=1) 51 | } 52 | 53 | period.lengths <- GetInfo(obj, "period.lengths") 54 | # There may be 2 or 3 periods. 55 | n.periods <- length(period.lengths) 56 | cum.pl <- cumsum(period.lengths) 57 | period.offset <- c(0L, cum.pl[-n.periods], cum.pl[n.periods] - 1L) 58 | 59 | dates <- GetInfo(obj, "dates") 60 | date.start <- dates[i] 61 | 62 | period.names <- c("Pretest", "Test", "Cooldown")[seq_len(n.periods)] 63 | period.dates <- (date.start + period.offset) 64 | obj.periods <- ExperimentPeriods(period.dates, 65 | period.names=period.names) 66 | geos <- GetInfo(obj, "geos") 67 | if (inherits(geos, "GeoAssignment")) { 68 | geo.assignment <- GetInfo(obj, "geo.assignment") # GeoAssignment. 69 | } else { 70 | geo.assignment <- Randomize(geos) # GeoStrata. 71 | } 72 | 73 | treatment.assignment <- GetInfo(obj, "treat.assignment") 74 | 75 | kClassName <- "GeoExperimentPreanalysisData" 76 | class(obj) <- setdiff(class(obj), kClassName) 77 | 78 | obj.result <- GeoExperimentData(obj, 79 | periods=obj.periods, 80 | geo.assignment=geo.assignment, 81 | treat.assignment=treatment.assignment) 82 | return(obj.result) 83 | } 84 | -------------------------------------------------------------------------------- /R/startup_message.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | .onAttach <- function(libname, pkgname) { 16 | packageStartupMessage("This software is not an official Google product.", 17 | " For research purposes only.", 18 | " Copyright 2017 Google, Inc.") 19 | } 20 | -------------------------------------------------------------------------------- /R/summary_tbranalysisfit_tbr1.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Returns a concise summary of the incremental response estimate and its 16 | #' confidence interval for the model 'tbr1'. 17 | #' 18 | #' @param object a \code{TBRAnalysisFit} object. 19 | #' @param level (number between 0 and 1) confidence level. 20 | #' @param interval.type (string) 'one-sided', 'two-sided' (interval). 21 | #' @param threshold (numeric vector) threshold(s) for the right-tail posterior. 22 | #' @param ... ignored. 23 | #' 24 | #' @return A \code{TBRAnalysisResults} object. 25 | 26 | summary.TBRAnalysisFitTbr1 <- function(object, 27 | level=0.90, 28 | interval.type=c("one-sided", 29 | "two-sided"), 30 | threshold=0, ...) { 31 | kClassName <- "TBRAnalysisResults" 32 | SetMessageContextString("summary.TBRAnalysisFitTbr1") 33 | on.exit(SetMessageContextString()) 34 | 35 | assert_that(is.real.number(level), 36 | level > 0 && level < 1) 37 | interval.type <- match.arg(interval.type) 38 | assert_that(is.real.number(threshold)) 39 | 40 | day.in.analysis <- IsInPeriod(object, periods="analysis") 41 | last.day.of.test <- tail(which(day.in.analysis), 1) 42 | x <- object[last.day.of.test, , drop=TRUE] 43 | incr.estimate <- x[[kYpredCumdif]] 44 | df.residual <- GetInfo(object, "fit")[["df.residual"]] 45 | sd.estimate <- x[[kYpredCumdifSd]] 46 | if (interval.type %in% "two-sided") { 47 | p.left <- (0.5 * (1 - level)) 48 | p <- c(p.left, 1 - p.left) 49 | } else { 50 | p <- c(1 - level, 1) # Upper bound will be Inf. 51 | } 52 | t.alpha <- qt(p, df=df.residual) # Vector of length 2. 53 | margins.of.error <- (t.alpha * sd.estimate) 54 | precision <- abs(margins.of.error[1]) 55 | conf.int <- (incr.estimate + margins.of.error) 56 | model <- GetInfo(object, "model") 57 | 58 | post.prob <- GetInfo(object, "tailprob")(threshold) 59 | 60 | obj <- data.frame(estimate=incr.estimate, 61 | precision=precision, 62 | lower=conf.int[1], 63 | upper=conf.int[2], 64 | se=sd.estimate, 65 | level=level, 66 | thres=threshold, 67 | prob=round(post.prob, digits=3), 68 | model=model) 69 | rownames(obj) <- "incremental" 70 | obj <- SetInfo(obj, estimate.columns=c("estimate", 71 | "precision", "lower", "upper", "se")) 72 | class(obj) <- c(kClassName, oldClass(obj)) 73 | return(obj) 74 | } 75 | -------------------------------------------------------------------------------- /R/utils_analysis.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Computes the weights to be used in the weighted linear model used to 16 | #' estimate ROAS. 17 | #' 18 | #' @param response a vector of the response in the pre period. Length equal to 19 | #' the number of geos. Must be all nonnegative. 20 | #' @param power default power to which 'response' is raised to. Can be 21 | #' overridden by setting the global option 22 | #' 'geoexperiments.gbr1.weight.power'. Must be nonnegative. 23 | #' @return A vector of weights of the same length as 'response'. Data points 24 | #' with response == 0 have weight NA (indicating these need to be taken 25 | #' special care of). There is an attribute 'power' corresponding to the 26 | #' exponent used. 27 | #' 28 | #' @note 29 | #' If a component of 'response' tends to infinity, the corresponding 30 | #' weight tends to 0 (i.e., the corresponding data point is ignored). 31 | 32 | ComputeLinearModelWeights <- function(response, power=2.0) { 33 | assert_that(is.numeric(response), !anyNA(response), all(response >= 0)) 34 | power <- getOption("geoexperiments.gbr1.weight.power", default=power) 35 | assert_that(is.numeric(power), !is.na(power), power >= 0) 36 | weights <- 1 / (response^power) 37 | weights[response == 0] <- NA_real_ 38 | attr(weights, "power") <- power 39 | return(weights) 40 | } 41 | -------------------------------------------------------------------------------- /R/utils_check_vectors.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Tests each component of the vector 'x' for valid values. 16 | #' 17 | #' @param x object to test. 18 | #' 19 | #' @return A logical vector of the same length as 'x', with 'TRUE' if and only 20 | #' if the string is a valid value, NA if the string is NA, otherwise FALSE. If 21 | #' 'x' is not character, throws an error. 22 | #' 23 | #' @note 24 | #' NA in a component returns NA. These are supposed to be tested 25 | #' separately. 26 | #' 27 | #' \itemize{ 28 | #' \item{\code{is.treatment.assignment}} The valid treatment assignment 29 | #' symbols can be found in the constant \code{kTreatmentAssignment}. 30 | #' Note however that the treatment assignment symbols are not used 31 | #' in the current version of the package (included for possible future 32 | #' use). 33 | #' \item{\code{is.geo.group.number}} The value '0' has a special meaning: 34 | #' it indicates a geo that has been omitted from the experiment. 35 | #' \item{\code{is.period.number}} Negative period numbers are allowed. 36 | #' } 37 | #' 38 | #' @rdname utils_check_vectors 39 | is.treatment.assignment <- function(x) { 40 | assert_that((is.logical(x) && all(is.na(x))) || is.integer.valued(x)) 41 | pass <- ifelse(is.na(x), yes=NA, no=x %in% kTreatmentAssignment) 42 | return(pass) 43 | } 44 | 45 | #' @rdname utils_check_vectors 46 | is.geo.group.number <- function(x) { 47 | assert_that((is.logical(x) && all(is.na(x))) || is.integer.valued(x)) 48 | pass <- ifelse(is.na(x), yes=NA, no=(x >= 0L)) 49 | return(pass) 50 | } 51 | 52 | #' @rdname utils_check_vectors 53 | is.period.number <- function(x) { 54 | assert_that((is.logical(x) && all(is.na(x))) || is.integer.valued(x)) 55 | pass <- ifelse(is.na(x), yes=NA, no=TRUE) 56 | return(pass) 57 | } 58 | -------------------------------------------------------------------------------- /R/utils_class.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Get a value of the 'info' attribute of an object. 16 | #' 17 | #' @param obj any R object. 18 | #' @param field (string) name of the field the value of which to retrieve. 19 | #' @return The requested value (object). 20 | GetInfo <- function (obj, field) { 21 | info <- attr(obj, "info") 22 | if (missing(field)) { 23 | return(info) 24 | } else if (!(field %in% names(info))) { 25 | stop(sprintf("Field '%s' does not exist in this object of class '%s'", 26 | field, class(obj)[1])) 27 | } 28 | return(info[[field]]) 29 | } 30 | 31 | #' Set the values of the 'info' attribute of an object. 32 | #' 33 | #' @param obj some object. 34 | #' @param ... name-value pairs to set in the list-valued attribute 'info'. 35 | #' @param info the initial value of the 'info' attribute; if specified, will 36 | #' re-set the value before changing the individual name-value pairs. 37 | #' 38 | #' @note 39 | #' Used only internally in this package. Do not use for data tables. 40 | #' @return The object ('obj') that was changed. 41 | SetInfo <- function (obj, ..., info=NULL) { 42 | assert_that(is.object(obj)) 43 | if (is.null(info)) { 44 | info <- GetInfo(obj) 45 | if (is.null(info)) { 46 | info <- list() 47 | } 48 | } 49 | assert_that(is.plain.list(info) && 50 | (length(info) == 0L || is.named.list(info)), 51 | msg="'info' is not a named list or an empty list") 52 | dots <- list(...) 53 | for (i in seq_along(dots)) { 54 | name <- names(dots)[i] 55 | info[name] <- dots[i] 56 | } 57 | attr(obj, "info") <- info 58 | return(obj) 59 | } 60 | -------------------------------------------------------------------------------- /R/utils_general.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Renames columns of a data frame. 16 | #' 17 | #' @param x a data frame. 18 | #' @param map a named character vector, mapping old column names to new ones 19 | #' such that the new ones are in 'names' and the values are the old 20 | #' ones. For example, \code{c(geo='GMA', date='Week Ending')}. If 'map' 21 | #' has length 0, the original data frame is returned. 22 | #' 23 | #' @return The data frame, with the column names renamed. 24 | 25 | RenameColumns <- function(x, map=character(0)) { 26 | SetMessageContextString("RenameColumns") 27 | on.exit(SetMessageContextString()) 28 | 29 | assert_that(is.data.frame(x)) 30 | assert_that(is.character(map) || is.null(map)) 31 | if (length(map) == 0) { 32 | return(x) 33 | } 34 | assert_that(length(map) > 0, 35 | length(names(map)) == length(map), 36 | is.vector.of.nonempty.strings(names(map)), 37 | msg="'map' must be a named character vector") 38 | x.names <- names(x) 39 | there <- structure(map %in% x.names, names=map) 40 | assert_that(all(there), 41 | msg=Message(FormatText(!there, 42 | "The following specified columns are not ", 43 | "in the data frame: $X"))) 44 | i.names <- which(x.names %in% map) 45 | inv.map <- structure(names(map), names=map) 46 | x.names[i.names] <- inv.map[x.names[i.names]] 47 | dups <- structure(duplicated(x.names), names=x.names) 48 | assert_that(!any(dups), 49 | msg=Message(FormatText(dups, 50 | "Duplicated column names: $X"))) 51 | names(x) <- x.names 52 | return(x) 53 | } 54 | -------------------------------------------------------------------------------- /R/utils_messaging.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | #' Save a string representing the current context of the program flow. 16 | #' 17 | #' @param context (a string) context of the message; to be displayed in (error) 18 | #' messages. 19 | #' @return The previous message context strings (a character vector). 20 | 21 | SetMessageContextString <- function(context) { 22 | opt <- getOption("geoexperiments", default=list()) 23 | context.old <- opt[["context"]] 24 | if (is.null(context.old)) { 25 | opt.context <- character(0) 26 | } else { 27 | opt.context <- context.old 28 | } 29 | if (missing(context)) { 30 | opt.context <- opt.context[-1L] 31 | } else { 32 | assert_that(is.nonempty.string(context), 33 | msg="'context' must be a nonempty string") 34 | opt.context <- c(context, opt.context) 35 | } 36 | opt["context"] <- list(opt.context) 37 | options(geoexperiments=opt) 38 | invisible(context.old) 39 | } 40 | 41 | #' Get the current message context string. 42 | #' 43 | #' @return The current message context string. If not available, returns an 44 | #' empty string (""). 45 | #' 46 | #' @note 47 | #' Pastes the strings together with '>' 48 | 49 | GetMessageContextString <- function() { 50 | kSeparator <- ">" 51 | context.strings <- getOption("geoexperiments", default=list())[["context"]] 52 | if (length(context.strings) == 0L) { 53 | context.string <- "" 54 | } else { 55 | context.string <- paste(rev(context.strings), collapse=kSeparator) 56 | } 57 | return(context.string) 58 | } 59 | 60 | #' Form a message, prefixed with the message context string. 61 | #' 62 | #' @param ... R vectors, usually character, to be collapsed using 'paste0'. 63 | #' @return A string. 64 | 65 | Message <- function(...) { 66 | prefix <- GetMessageContextString() 67 | if (nchar(prefix) > 0L) { 68 | prefix <- paste0(prefix, ": ") 69 | } 70 | paste0(prefix, ..., collapse="") 71 | } 72 | 73 | #' Form a message, using sprintf. 74 | #' 75 | #' @param fmt a character vector of format strings (see 'sprintf' for details). 76 | #' @param ... values to be passed to 'fmt'. 77 | #' @return A string. 78 | 79 | Messagef <- function(fmt, ...) { 80 | assert_that(is.nonempty.string(fmt)) 81 | Message(sprintf(fmt, ...)) 82 | } 83 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # R package GeoexperimentsResearch version 1.0.3 2 | 3 | Copyright (C) 2017 Google, Inc. 4 | License: Apache 2.0 5 | 6 | ## Disclaimer 7 | 8 | This is not an official Google product. For research purposes only. 9 | 10 | ## What is this R package for? 11 | 12 | This R package ('GeoexperimentsResearch') is an open-source implementation of the geo 13 | experiment analysis methodology developed at Google [1, 2]. 14 | 15 | This package provides object classes and methods and functions for handling, 16 | verifying, and analyzing data from geo experiments. Version 1.0 implements the 17 | geo experiment methodology presented in [1], also called the geo-based 18 | regression (GBR), and also the follow-up methodology 'time-based regression' 19 | (TBR), introduced in [2]. 20 | 21 | ## Documentation 22 | 23 | See the vignette and the manual in this package (in the subdirectory inst/doc/ 24 | in the source package). 25 | 26 | ## References 27 | 28 | [1] Vaver, J. and Koehler, J. (2011) 29 | [Measuring Ad Effectiveness Using Geo Experiments](http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/38355.pdf). 30 | 31 | [2] Kerman, J., Wang, P. and Vaver, J. (2017) 32 | [Estimating Ad Effectiveness Using Geo Experiments in a Time-Based Regression Framework](https://research.google.com/pubs/pub45950.html). 33 | 34 | -------------------------------------------------------------------------------- /data/geoassignment.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/GeoexperimentsResearch/abf2eac956072e55ad6a39b5fc5db5066b163858/data/geoassignment.rda -------------------------------------------------------------------------------- /data/salesandcost.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/GeoexperimentsResearch/abf2eac956072e55ad6a39b5fc5db5066b163858/data/salesandcost.rda -------------------------------------------------------------------------------- /inst/doc/GeoexperimentsResearch-manual.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/GeoexperimentsResearch/abf2eac956072e55ad6a39b5fc5db5066b163858/inst/doc/GeoexperimentsResearch-manual.pdf -------------------------------------------------------------------------------- /inst/doc/GeoexperimentsResearch-vignette.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/GeoexperimentsResearch/abf2eac956072e55ad6a39b5fc5db5066b163858/inst/doc/GeoexperimentsResearch-vignette.pdf -------------------------------------------------------------------------------- /man/AggregateTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/aggregatetimeseries.R 5 | \name{AggregateTimeseries} 6 | \alias{AggregateTimeseries} 7 | \alias{AggregateTimeseries.GeoTimeseries} 8 | \title{Aggregate the metrics of a time series object over specified time 9 | intervals.} 10 | \usage{ 11 | AggregateTimeseries(obj, freq = c("weekly", "monthly"), ...) 12 | 13 | \method{AggregateTimeseries}{GeoTimeseries}(obj, freq, ...) 14 | } 15 | \arguments{ 16 | \item{obj}{an object.} 17 | 18 | \item{freq}{(string) 'weekly' or 'monthly' aggregation.} 19 | 20 | \item{...}{further arguments passed to or from other methods.} 21 | } 22 | \value{ 23 | An object of the same class as 'obj'. 24 | } 25 | \description{ 26 | Aggregate the metrics of a time series object over specified time 27 | intervals. 28 | } 29 | \note{ 30 | \itemize{ 31 | \item{'Weekly' frequency}: each day in the time series is mapped 32 | to the next Sunday, then aggregated. 33 | \item{'Monthly' frequency}: each day in the time series is mapped to 34 | the last day of the month, then aggregated. No check is made about 35 | the current frequency. This works best on daily data. So it is 36 | possible to attempt to change a 'monthly' frequency back to 'weekly', 37 | but this simply re-maps the last day of the month to the next Sunday. 38 | } 39 | } 40 | \seealso{ 41 | \code{\link{aggregate.GeoTimeseries}}. 42 | } 43 | 44 | -------------------------------------------------------------------------------- /man/CheckForAllTrue.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckForAllTrue} 6 | \alias{CheckForAllTrue} 7 | \title{Checks whether all components are TRUE.} 8 | \usage{ 9 | CheckForAllTrue(x, ...) 10 | } 11 | \arguments{ 12 | \item{x}{(logical) vector. A 'TRUE' denotes a success, and 'FALSE' and 'NA' 13 | a failure. The names attribute must be set, with nonempty, non-NA, 14 | non-duplicated names.} 15 | 16 | \item{...}{one or more character vectors, passed on to \code{FormatText}.} 17 | } 18 | \value{ 19 | If all tests pass, returns TRUE invisibly. Otherwise, an 20 | 'assertError' is thrown. 21 | } 22 | \description{ 23 | Checks whether all components are TRUE. 24 | } 25 | 26 | -------------------------------------------------------------------------------- /man/CheckForBadValues.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckForBadValues} 6 | \alias{CheckForBadValues} 7 | \title{Checks for bad values in given columns.} 8 | \usage{ 9 | CheckForBadValues(x, columns, CHECK, good = TRUE, what = "invalid", ...) 10 | } 11 | \arguments{ 12 | \item{x}{(data frame) any data frame.} 13 | 14 | \item{columns}{(character) columns to check.} 15 | 16 | \item{CHECK}{(function) function that returns a logical vector (of length 17 | \code{nrow(x)}).} 18 | 19 | \item{good}{(logical) the value or values that indicate a 'good' value. 20 | Other values returned by 'CHECK' will be 'bad' and throw an error.} 21 | 22 | \item{what}{(string) a string to display in the informative message.} 23 | 24 | \item{...}{further arguments passed on to function 'CHECK'.} 25 | } 26 | \value{ 27 | If all tests pass, returns NULL invisibly. Otherwise, an 28 | 'assertError' is thrown. 29 | } 30 | \description{ 31 | Checks for bad values in given columns. 32 | } 33 | 34 | -------------------------------------------------------------------------------- /man/CheckForDuplicateRows.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckForDuplicateRows} 6 | \alias{CheckForDuplicateRows} 7 | \title{Checks whether the values in rows of given columns are not duplicated.} 8 | \usage{ 9 | CheckForDuplicateRows(x, columns) 10 | } 11 | \arguments{ 12 | \item{x}{a data frame.} 13 | 14 | \item{columns}{(character) vector.} 15 | } 16 | \value{ 17 | If all tests pass, returns TRUE invisibly. Otherwise, an 18 | 'assertError' is thrown. 19 | } 20 | \description{ 21 | Checks whether the values in rows of given columns are not duplicated. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/CheckForMapping.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckForMapping} 6 | \alias{CheckForMapping} 7 | \title{Checks whether the mapping is consistent within a data frame.} 8 | \usage{ 9 | CheckForMapping(x, from, to) 10 | } 11 | \arguments{ 12 | \item{x}{a data frame.} 13 | 14 | \item{from}{(character) vector of column names.} 15 | 16 | \item{to}{(character) vector of column names. Typically these are different 17 | from those in 'from'.} 18 | } 19 | \value{ 20 | If all tests pass, returns TRUE invisibly. Otherwise, an 21 | 'assertError' is thrown. 22 | } 23 | \description{ 24 | Checks whether the mapping is consistent within a data frame. 25 | } 26 | \note{ 27 | Checks that no rows in 'x[from]' map to two different values of 28 | 'x[to]'. 29 | } 30 | 31 | -------------------------------------------------------------------------------- /man/CheckForMissingColumns.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckForMissingColumns} 6 | \alias{CheckForMissingColumns} 7 | \title{Checks whether specified column names exist in a data frame.} 8 | \usage{ 9 | CheckForMissingColumns(x, dataframe, what = "specified") 10 | } 11 | \arguments{ 12 | \item{x}{(character) names of the columns.} 13 | 14 | \item{dataframe}{(data frame) data frame.} 15 | 16 | \item{what}{(string) string to use in the error message.} 17 | } 18 | \value{ 19 | If all tests pass, returns TRUE invisibly. Otherwise, an 20 | 'assertError' is thrown. 21 | } 22 | \description{ 23 | Checks whether specified column names exist in a data frame. 24 | } 25 | \note{ 26 | Convenient for checking function arguments. Quotes the name of the 27 | variable 'x'. 28 | } 29 | 30 | -------------------------------------------------------------------------------- /man/CheckForTypes.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckForTypes} 6 | \alias{CheckForTypes} 7 | \title{Checks whether the vector values in the given list satisfies the specified 8 | types.} 9 | \usage{ 10 | CheckForTypes(x, checklist) 11 | } 12 | \arguments{ 13 | \item{x}{a named list or a data frame.} 14 | 15 | \item{checklist}{(named list) mapping from names to functions that check 16 | whether the functions are correct or not.} 17 | } 18 | \value{ 19 | invisible NULL. 20 | } 21 | \description{ 22 | Checks whether the vector values in the given list satisfies the specified 23 | types. 24 | } 25 | 26 | -------------------------------------------------------------------------------- /man/CheckGeoGroupNumber.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckGeoGroupNumber} 6 | \alias{CheckGeoGroupNumber} 7 | \title{Check that the specified geo group number is present in the data.} 8 | \usage{ 9 | CheckGeoGroupNumber(geo.group, values) 10 | } 11 | \arguments{ 12 | \item{geo.group}{(an integer) geo group number (>= 1). (NA throws an error).} 13 | 14 | \item{values}{(vector) values to check against.} 15 | } 16 | \value{ 17 | TRUE, invisibly; as a side effect may throw an assertion error. 18 | } 19 | \description{ 20 | Check that the specified geo group number is present in the data. 21 | } 22 | \note{ 23 | For checking arguments within a function. Outputs the name of the 24 | variable in error messages. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/CheckPeriodNumbers.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckPeriodNumbers} 6 | \alias{CheckPeriodNumbers} 7 | \title{Check that the specified period numbers are present in the data.} 8 | \usage{ 9 | CheckPeriodNumbers(period, values) 10 | } 11 | \arguments{ 12 | \item{period}{(integer vector): one or more period numbers. (NA throws an 13 | error).} 14 | 15 | \item{values}{(vector) values to check against.} 16 | } 17 | \value{ 18 | TRUE invisibly if the checks pass. As a side effect will terminate 19 | with an error if the checks fail. 20 | } 21 | \description{ 22 | Check that the specified period numbers are present in the data. 23 | } 24 | \note{ 25 | For checking arguments within a function. Outputs the name of the 26 | variable in error messages. 27 | } 28 | 29 | -------------------------------------------------------------------------------- /man/CheckThat.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_assert.R 5 | \name{CheckThat} 6 | \alias{CheckThat} 7 | \title{An alternative version of assert_that, outputting a modified error 8 | message.} 9 | \usage{ 10 | CheckThat(..., env = parent.frame(), name = NULL) 11 | } 12 | \arguments{ 13 | \item{...}{see 'assert_that'.} 14 | 15 | \item{env}{see 'assert_that'.} 16 | 17 | \item{name}{(string) name of the object to output in the error message.} 18 | } 19 | \value{ 20 | 'TRUE' if tests pass; otherwise throws an error. 21 | } 22 | \description{ 23 | An alternative version of assert_that, outputting a modified error 24 | message. 25 | } 26 | \note{ 27 | Replaces anything up to ' is not ' in the error message with the 28 | value of 'name'. 29 | } 30 | \examples{ 31 | # Outputs "Column 'foo' is not an integer-valued numeric vector" 32 | # if 'x' fails the test. 33 | \dontrun{ 34 | CheckThat(is.integer.valued(x), name="Column 'foo'")} 35 | } 36 | 37 | -------------------------------------------------------------------------------- /man/ComputeLinearModelWeights.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_analysis.R 5 | \name{ComputeLinearModelWeights} 6 | \alias{ComputeLinearModelWeights} 7 | \title{Computes the weights to be used in the weighted linear model used to 8 | estimate ROAS.} 9 | \usage{ 10 | ComputeLinearModelWeights(response, power = 2) 11 | } 12 | \arguments{ 13 | \item{response}{a vector of the response in the pre period. Length equal to 14 | the number of geos. Must be all nonnegative.} 15 | 16 | \item{power}{default power to which 'response' is raised to. Can be 17 | overridden by setting the global option 18 | 'geoexperiments.gbr1.weight.power'. Must be nonnegative.} 19 | } 20 | \value{ 21 | A vector of weights of the same length as 'response'. Data points 22 | with response == 0 have weight NA (indicating these need to be taken 23 | special care of). There is an attribute 'power' corresponding to the 24 | exponent used. 25 | } 26 | \description{ 27 | Computes the weights to be used in the weighted linear model used to 28 | estimate ROAS. 29 | } 30 | \note{ 31 | If a component of 'response' tends to infinity, the corresponding 32 | weight tends to 0 (i.e., the corresponding data point is ignored). 33 | } 34 | 35 | -------------------------------------------------------------------------------- /man/ConcatItems.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_strings.R 5 | \name{ConcatItems} 6 | \alias{ConcatItems} 7 | \title{Concatenate items of a vector, optionally quoting each.} 8 | \usage{ 9 | ConcatItems(x, quote = "'", collapse = ", ", max.output = Inf) 10 | } 11 | \arguments{ 12 | \item{x}{(atomic vector) an atomic vector, coerced to character.} 13 | 14 | \item{quote}{(string) a quote character to use.} 15 | 16 | \item{collapse}{(string) string to use for collapsing the components of 'x'.} 17 | 18 | \item{max.output}{(integer) maximum number of items of 'x' to output.} 19 | } 20 | \value{ 21 | A string. 22 | } 23 | \description{ 24 | Concatenate items of a vector, optionally quoting each. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/CountRandomizations.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geostrata.R 5 | \name{CountRandomizations} 6 | \alias{CountRandomizations} 7 | \title{Counts the total numbers of randomizations in a GeoStrata object.} 8 | \usage{ 9 | CountRandomizations(geostrata, show.warnings = TRUE, log.scale = FALSE) 10 | } 11 | \arguments{ 12 | \item{geostrata}{a GeoStrata object.} 13 | 14 | \item{show.warnings}{(flag) if \code{TRUE}, shows a warning when a stratum 15 | is not compatible with the group.ratios.} 16 | 17 | \item{log.scale}{(flag) if \code{TRUE}, returns the result on the log.scale.} 18 | } 19 | \value{ 20 | An integer vector of the same length as the number of strata in 21 | geostrata (excluding stratum 0, if it exists). The i-th coordinate 22 | corresponds to the total number of possible randomizations for the i-th 23 | stratum. 24 | } 25 | \description{ 26 | Counts the total numbers of randomizations in a GeoStrata object. 27 | } 28 | \note{ 29 | A warning is issued if one or more of the stratas are not compatible 30 | with the group.ratios. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/CountRandomizationsInAStratum.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geostrata.R 5 | \name{CountRandomizationsInAStratum} 6 | \alias{CountRandomizationsInAStratum} 7 | \title{Counts the total numbers of randomization in a single stratum.} 8 | \usage{ 9 | CountRandomizationsInAStratum(geo.group, group.ratios, log.scale = TRUE) 10 | } 11 | \arguments{ 12 | \item{geo.group}{(integer vector of length equal to number of geos) a vector 13 | of geo group numbers (may be NAs, but zeros are not allowed).} 14 | 15 | \item{group.ratios}{(integer vector of length equal to number of geo groups) 16 | vector of ratios of the sizes of each group.} 17 | 18 | \item{log.scale}{(flag) if TRUE, returns the result on the log.scale.} 19 | } 20 | \value{ 21 | An integer value that corresponds to the total number of possible 22 | randomizations for the stratum represented by geo.group. 23 | } 24 | \description{ 25 | Counts the total numbers of randomization in a single stratum. 26 | } 27 | 28 | -------------------------------------------------------------------------------- /man/DoGBRROASAnalysis.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/dogbrroasanalysis.R 5 | \name{DoGBRROASAnalysis} 6 | \alias{DoGBRROASAnalysis} 7 | \alias{DoGBRROASAnalysis.GBRROASAnalysisData} 8 | \alias{DoGBRROASAnalysis.GeoExperimentData} 9 | \title{Performs a GBR ROAS Analysis.} 10 | \usage{ 11 | DoGBRROASAnalysis(obj, ...) 12 | 13 | \method{DoGBRROASAnalysis}{GBRROASAnalysisData}(obj, ...) 14 | 15 | \method{DoGBRROASAnalysis}{GeoExperimentData}(obj, response = character(0), 16 | cost = character(0), pretest.period = 0L, intervention.period = 1L, 17 | cooldown.period = NULL, control.group = 1L, treatment.group = 2L, ...) 18 | } 19 | \arguments{ 20 | \item{obj}{an object.} 21 | 22 | \item{...}{further arguments passed to or from other methods.} 23 | 24 | \item{response}{(string) name of the response variable column.} 25 | 26 | \item{cost}{(string) name of the cost variable column.} 27 | 28 | \item{pretest.period}{(non-negative integer) number of the pretest period, 29 | typically 0.} 30 | 31 | \item{intervention.period}{(vector of non-negative integers) number(s) of 32 | the period(s) forming the intervention period. All must be larger 33 | than the largest period in the pretest period.} 34 | 35 | \item{cooldown.period}{(vector of non-negative integers or NULL) number(s) 36 | of the period(s) forming the cooldown period. All must be larger than 37 | the largest period in the intervention period.} 38 | 39 | \item{control.group}{(a vector of positive integers) number(s) of geo groups 40 | forming the control group.} 41 | 42 | \item{treatment.group}{(a vector of positive integers) number(s) of geo 43 | groups forming the treatment group.} 44 | } 45 | \value{ 46 | A GBRROASAnalysisFit object. 47 | } 48 | \description{ 49 | Performs a GBR ROAS Analysis. 50 | } 51 | \seealso{ 52 | \code{\link{as.GBRROASAnalysisData}}, \code{\link{DoROASAnalysis}}. 53 | } 54 | 55 | -------------------------------------------------------------------------------- /man/DoTBRAnalysis.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/dotbranalysis.R 5 | \name{DoTBRAnalysis} 6 | \alias{DoTBRAnalysis} 7 | \alias{DoTBRAnalysis.GeoExperimentData} 8 | \alias{DoTBRAnalysis.TBRAnalysisData} 9 | \title{Executes a TBR Causal Effect Analysis.} 10 | \usage{ 11 | DoTBRAnalysis(obj, model, ...) 12 | 13 | \method{DoTBRAnalysis}{GeoExperimentData}(obj, model, ...) 14 | 15 | \method{DoTBRAnalysis}{TBRAnalysisData}(obj, model, ...) 16 | } 17 | \arguments{ 18 | \item{obj}{an object.} 19 | 20 | \item{model}{(string) model to use.} 21 | 22 | \item{...}{further arguments passed to or from other methods.} 23 | } 24 | \value{ 25 | A TBRAnalysisFit object. 26 | } 27 | \description{ 28 | Executes a TBR Causal Effect Analysis. 29 | } 30 | \note{ 31 | Dispatcher of methods. 32 | The actual method to execute the 'tbr1' method is \code{DoTBRAnalysisTbr1}. 33 | } 34 | \seealso{ 35 | \code{\link{DoTBRAnalysisTbr1}}, \code{\link{DoROASAnalysis}}, 36 | \code{\link{DoGBRROASAnalysis}}. 37 | } 38 | 39 | -------------------------------------------------------------------------------- /man/DoTBRAnalysisTbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/dotbranalysis_tbr1.R 5 | \name{DoTBRAnalysisTbr1} 6 | \alias{DoTBRAnalysisTbr1} 7 | \alias{DoTBRAnalysisTbr1.TBRAnalysisData} 8 | \title{Performs a TBR Analysis using the 2-parameter linear model 'tbr1'.} 9 | \usage{ 10 | DoTBRAnalysisTbr1(obj, ...) 11 | 12 | \method{DoTBRAnalysisTbr1}{TBRAnalysisData}(obj, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{an object.} 16 | 17 | \item{...}{further arguments passed to or from other methods.} 18 | } 19 | \value{ 20 | A TBRAnalysisFit object. 21 | } 22 | \description{ 23 | Performs a TBR Analysis using the 2-parameter linear model 'tbr1'. 24 | } 25 | 26 | -------------------------------------------------------------------------------- /man/DoTBRROASAnalysis.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/dotbrroasanalysis.R 5 | \name{DoTBRROASAnalysis} 6 | \alias{DoTBRROASAnalysis} 7 | \alias{DoTBRROASAnalysis.GeoExperimentData} 8 | \title{Performs a TBR ROAS Analysis.} 9 | \usage{ 10 | DoTBRROASAnalysis(obj, model, response, cost, n.sims = 1e+05, ...) 11 | 12 | \method{DoTBRROASAnalysis}{GeoExperimentData}(obj, model, response, cost, 13 | n.sims = 1e+05, ...) 14 | } 15 | \arguments{ 16 | \item{obj}{an object.} 17 | 18 | \item{model}{(string) id of the TBR to use.} 19 | 20 | \item{response}{(string) name of the column of the response variable.} 21 | 22 | \item{cost}{(string) name of the column of the cost variable, or 23 | alternatively a real number specifying the exact incremental cost 24 | (spend change).} 25 | 26 | \item{n.sims}{(integer) number of simulations to draw.} 27 | 28 | \item{...}{arguments passed to function 'DoTBRAnalysis'.} 29 | } 30 | \value{ 31 | A TBRROASAnalysisFit object. 32 | } 33 | \description{ 34 | Performs a TBR ROAS Analysis. 35 | } 36 | \seealso{ 37 | DoTBRAnalysis, DoGBRROASAnalysis 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/EstimateIncremental.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/estimateincremental.R 5 | \name{EstimateIncremental} 6 | \alias{EstimateIncremental} 7 | \alias{EstimateIncremental.GBRROASAnalysisData} 8 | \title{Estimates the difference of a metric between the test and counterfactual 9 | between the pre and the post periods.} 10 | \usage{ 11 | EstimateIncremental(obj, ...) 12 | 13 | \method{EstimateIncremental}{GBRROASAnalysisData}(obj, 14 | variable = c("response", "cost"), ...) 15 | } 16 | \arguments{ 17 | \item{obj}{an object.} 18 | 19 | \item{...}{further arguments passed to or from other methods.} 20 | 21 | \item{variable}{(string) 'response' or 'cost'.} 22 | } 23 | \value{ 24 | A vector of (adjusted) incremental values, of length 25 | \code{nrow(obj)}. 26 | } 27 | \description{ 28 | Estimates the difference of a metric between the test and counterfactual 29 | between the pre and the post periods. 30 | } 31 | \note{ 32 | The incremental metric (response or cost) is calculated as the 33 | difference between the actual observed metric and the counterfactual 34 | during the test period. The counterfactual is defined as the prediction 35 | of the metric, using a model that uses only the control geos as the 36 | training data set. The incremental cost is defined to be zero for the 37 | control geos. In case there is not enough data to model the 38 | counterfactual (happens when all pre-test data are constant, usually 39 | zero), the counterfactual is defined to be simply the metric during the 40 | pre-test period. 41 | } 42 | 43 | -------------------------------------------------------------------------------- /man/ExperimentPeriods.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/experimentperiods.R 5 | \name{ExperimentPeriods} 6 | \alias{ExperimentPeriods} 7 | \title{Constructs an ExperimentPeriods object.} 8 | \usage{ 9 | ExperimentPeriods(period.dates, period.names = NULL, 10 | date.format = "\%Y-\%m-\%d") 11 | } 12 | \arguments{ 13 | \item{period.dates}{(a character or Date vector); start dates of each 14 | period, plus the last date of the experiment. The first period is the 15 | pretest period, after which there must be at least one test period 16 | (there can be more than one test period); the length must be at least 17 | 3.} 18 | 19 | \item{period.names}{(character or NULL or a vector of nonempty strings) 20 | optional names of the periods. By default, names 'Pretest' and 'Test' 21 | (or 'Test1', 'Test2', ...) are used.} 22 | 23 | \item{date.format}{(string) format for the dates if provided in character 24 | format.} 25 | } 26 | \value{ 27 | An ExperimentPeriods object. 28 | } 29 | \description{ 30 | Constructs an ExperimentPeriods object. 31 | } 32 | \note{ 33 | The periods must be consecutive and each period must be at least of 34 | length 1 (day). No gaps can be specified. It is however possible to 35 | define a ('dummy') test period that is not included in the analyses. 36 | } 37 | 38 | -------------------------------------------------------------------------------- /man/ExtractExperimentPeriods.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/extractexperimentperiods.R 5 | \name{ExtractExperimentPeriods} 6 | \alias{ExtractExperimentPeriods} 7 | \alias{ExtractExperimentPeriods.GeoTimeseries} 8 | \title{Extracts an ExperimentPeriods object.} 9 | \usage{ 10 | ExtractExperimentPeriods(obj, ...) 11 | 12 | \method{ExtractExperimentPeriods}{GeoTimeseries}(obj, strict = TRUE, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{an object.} 16 | 17 | \item{...}{further arguments passed on to methods.} 18 | 19 | \item{strict}{(flag) if FALSE, the function returns NULL if the column 20 | 'period' does not exist. Otherwise, throws an error.} 21 | } 22 | \value{ 23 | An ExperimentPeriods object. 24 | 25 | An ExperimentPeriods object. 26 | } 27 | \description{ 28 | Extracts an ExperimentPeriods object. 29 | 30 | Extracts a ExperimentPeriods object from a GeoTimeseries. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/ExtractGeoAssignment.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/extractgeoassignment.R 5 | \name{ExtractGeoAssignment} 6 | \alias{ExtractGeoAssignment} 7 | \alias{ExtractGeoAssignment.GeoExperimentData} 8 | \alias{ExtractGeoAssignment.GeoTimeseries} 9 | \title{Extracts a GeoAssignment object.} 10 | \usage{ 11 | ExtractGeoAssignment(obj, ...) 12 | 13 | \method{ExtractGeoAssignment}{GeoTimeseries}(obj, strict = TRUE, ...) 14 | 15 | \method{ExtractGeoAssignment}{GeoExperimentData}(obj, ...) 16 | } 17 | \arguments{ 18 | \item{obj}{an object.} 19 | 20 | \item{...}{further arguments passed on to methods.} 21 | 22 | \item{strict}{(flag) if FALSE, the function returns NULL if the column 23 | 'geo.group' does not exist. Otherwise, throws an error.} 24 | } 25 | \value{ 26 | A GeoAssignment object. Or \code{NULL} if not available. 27 | 28 | A GeoAssignment object. 29 | } 30 | \description{ 31 | Extracts a GeoAssignment object. 32 | 33 | Attempts to extract a GeoAssignment object from a GeoTimeseries. 34 | } 35 | \note{ 36 | Finds all unique pairs of ('geo', 'geo.group') in the GeoTimeseries. 37 | 'geo.group' can have missing values. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/ExtractGeoStrata.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/extractgeostrata.R 5 | \name{ExtractGeoStrata} 6 | \alias{ExtractGeoStrata} 7 | \alias{ExtractGeoStrata.GeoExperimentData} 8 | \alias{ExtractGeoStrata.GeoTimeseries} 9 | \title{Extract a GeoStrata object from an object.} 10 | \usage{ 11 | ExtractGeoStrata(obj, ...) 12 | 13 | \method{ExtractGeoStrata}{GeoTimeseries}(obj, volume = NULL, ...) 14 | 15 | \method{ExtractGeoStrata}{GeoExperimentData}(obj, volume = NULL, ...) 16 | } 17 | \arguments{ 18 | \item{obj}{an object.} 19 | 20 | \item{...}{further arguments passed to or from other methods.} 21 | 22 | \item{volume}{(string) name of a metric from which to generate the 23 | \code{volume} column.} 24 | } 25 | \value{ 26 | A GeoStrata object. 27 | } 28 | \description{ 29 | Extract a GeoStrata object from an object. 30 | 31 | Extract a GeoStrata object from a GeoTimeseries. 32 | } 33 | 34 | -------------------------------------------------------------------------------- /man/ExtractGeos.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/extractgeos.R 5 | \name{ExtractGeos} 6 | \alias{ExtractGeos} 7 | \alias{ExtractGeos.GeoTimeseries} 8 | \title{Extract a Geos object from an object.} 9 | \usage{ 10 | ExtractGeos(obj, ...) 11 | 12 | \method{ExtractGeos}{GeoTimeseries}(obj, volume = NULL, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{an object.} 16 | 17 | \item{...}{other arguments passed to the methods.} 18 | 19 | \item{volume}{(string) name of a metric in the GeoTimeseries over which to 20 | generate the 'volume' column. If omitted, the first metric is used. 21 | The volumes have to be non-negative.} 22 | } 23 | \value{ 24 | A 'Geos' object. 25 | 26 | A Geos object, with the average weekly volume of all metrics in 27 | 'obj'. 28 | } 29 | \description{ 30 | Extract a Geos object from an object. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/ExtractTreatmentAssignment.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/extracttreatmentassignment.R 5 | \name{ExtractTreatmentAssignment} 6 | \alias{ExtractTreatmentAssignment} 7 | \alias{ExtractTreatmentAssignment.GeoTimeseries} 8 | \title{Extracts a TreatmentAssignment object.} 9 | \usage{ 10 | ExtractTreatmentAssignment(obj, ...) 11 | 12 | \method{ExtractTreatmentAssignment}{GeoTimeseries}(obj, strict = TRUE, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{An object.} 16 | 17 | \item{...}{further arguments passed to or from other methods.} 18 | 19 | \item{strict}{(flag) if FALSE, the function returns NULL if either of the 20 | columns 'geo.group' or 'period' does not exist. Otherwise, throws an 21 | error.} 22 | } 23 | \value{ 24 | A TreatmentAssignment object. 25 | } 26 | \description{ 27 | Extracts a TreatmentAssignment object. 28 | } 29 | \note{ 30 | \code{ExtractTreatmentAssignment.GeoTimeseries}: \code{obj} is 31 | supposed to have the columns 'period', 'geo.group', and 'assignment'.\cr 32 | 33 | A well-defined (period, group) pair (i.e., neither of them is missing) in 34 | the data frame implies that the corresponding (date, geo) pair is part of 35 | the experiment and \emph{must} be therefore associated a treatment 36 | condition. Otherwise, if a date or a geo is not part of the experiment, the 37 | (date, geo) pair \emph{must} have \emph{no} treatment condition 38 | assignment. In other words, any (period, group) pair that maps to a 39 | non-missing treatment assignment must have no missing values. Conversely, 40 | any (period, group) pair with a missing value must map to a missing 41 | treatment assignment. 42 | } 43 | 44 | -------------------------------------------------------------------------------- /man/FormatText.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_strings.R 5 | \name{FormatText} 6 | \alias{FormatText} 7 | \title{Compose text strings conditional on values of an object.} 8 | \usage{ 9 | FormatText(x, ..., quote = "'") 10 | } 11 | \arguments{ 12 | \item{x}{an integer-valued numeric scalar or a logical vector. In the former 13 | case, indicates a number of items; in the latter case, indicates 14 | which items in a vector were affected. May have the 'names' attribute 15 | set.} 16 | 17 | \item{...}{one or more character vectors that are pasted together 18 | (collapsed) after concatenating the vectors one after another.} 19 | 20 | \item{quote}{the quote character to use.} 21 | } 22 | \value{ 23 | A character string. 24 | } 25 | \description{ 26 | Compose text strings conditional on values of an object. 27 | } 28 | \details{ 29 | The function replaces the following special character patterns: 30 | \itemize{ 31 | \item{\code{\{a|b}\}}: 'a' if \code{sum(x) == 1} and 'b' otherwise. 32 | \item{\code{\{z|a|b\}}}: 'z' if \code{sum(x) == 0}, otherwise works 33 | like \code{{a|b}}. 34 | \item{\code{$N}}: \code{sum(x)}. 35 | \item{\code{$P}}: \code{sprintf("\%.1f", 100 * mean(x))}. 36 | \item{\code{$L}}: \code{length(x)}. The following patterns are 37 | replaced with comma-separated lists of: 38 | \itemize{ 39 | \item{\code{$w}}: \code{which(x)}. 40 | \item{\code{$W}}: \code{which(x)}, each item quoted. 41 | \item{\code{$x}}: \code{names(x)[which(x)]}. 42 | \item{\code{$X}}: \code{names(x)[which(x)]}, each item quoted. 43 | } 44 | } 45 | 46 | Exception: These four patterns output only up to the Kth item, where 47 | \code{K = getOption('FormatTextMaxOutput', default=7L)}. 48 | } 49 | \examples{ 50 | \dontrun{ 51 | FormatText(n, "There {is|are} {no|one|$N} item{|s}.") 52 | FormatText(is.na(x), "Found $N NAs ($P\% of all $L) in rows $w")} 53 | } 54 | 55 | -------------------------------------------------------------------------------- /man/GenerateStrata.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geostrata.R 5 | \name{.GenerateStrata} 6 | \alias{.GenerateStrata} 7 | \title{[internal] Generate stratum numbers along a given vector.} 8 | \usage{ 9 | .GenerateStrata(geo.group, group.ratios) 10 | } 11 | \arguments{ 12 | \item{geo.group}{(integer vector of length equal to number of geos) a vector 13 | of geo group numbers (may be NAs).} 14 | 15 | \item{group.ratios}{(integer vector of length equal to number of geo groups) 16 | vector of ratios of the sizes of each group.} 17 | } 18 | \value{ 19 | An integer vector of the same length as 'geo.group', with the 20 | corresponding stratum numbers. '0' signifies a geo that is excluded from the 21 | set. Otherwise the numbers identify the strata. There are no NAs. 22 | } 23 | \description{ 24 | [internal] Generate stratum numbers along a given vector. 25 | } 26 | \note{ 27 | For internal use; no checking of arguments is done. 28 | } 29 | 30 | -------------------------------------------------------------------------------- /man/GeoAssignment.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geoassignment.R 5 | \name{GeoAssignment} 6 | \alias{GeoAssignment} 7 | \title{Constructs a GeoAssignment object.} 8 | \usage{ 9 | GeoAssignment(x) 10 | } 11 | \arguments{ 12 | \item{x}{a data frame with columns 'geo' (character) and 'geo.group' 13 | (integer-valued, positive). 'geo.group' indicates the group (1, 2, 14 | ...) the corresponding geo belongs to. Other columns are allowed but 15 | not checked. If 'geo' is an integer-valued numeric or factor, it is 16 | coerced to character} 17 | } 18 | \value{ 19 | An object of class 'GeoAssignment'. 20 | } 21 | \description{ 22 | Constructs a GeoAssignment object. 23 | } 24 | \details{ 25 | The group numbers must be integers (integer-valued numeric are 26 | allowed as input), starting with 1. The column 'geo.group' *can* have 27 | missing values (NA), unlike 'geo', which must have no missing values, 28 | and no duplicates. A missing value in geo.group simply indicates that 29 | the mapping from a geo is not available. When associating the geo 30 | assignment with a GeoExperimentData object, the effect will be the same 31 | as if the geo with 'geo.group'==NA was not in the mapping in the first 32 | place. 33 | } 34 | 35 | -------------------------------------------------------------------------------- /man/GeoExperimentData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geoexperimentdata.R 5 | \name{GeoExperimentData} 6 | \alias{GeoExperimentData} 7 | \title{Constructs a GeoExperimentData object.} 8 | \usage{ 9 | GeoExperimentData(geo.timeseries, periods, geo.assignment, treat.assignment) 10 | } 11 | \arguments{ 12 | \item{geo.timeseries}{a GeoTimeseries object.} 13 | 14 | \item{periods}{an \code{ExperimentPeriods} object, specifying the start and 15 | end dates of each period in the experiment. Or, \code{NULL} if the dates are yet 16 | unknown. Or, leave unspecified to extract this information from the column 17 | 'periods' of the \code{geo.timeseries}; in this case the column \emph{must} 18 | exist in the data frame.} 19 | 20 | \item{geo.assignment}{a \code{GeoAssignment} object, specifying the mapping 21 | from a geo to a geo group. Or, \code{NULL} if the geo assignment is yet 22 | unknown. Or, leave unspecified to extract this information from the column 23 | 'geo.group' of \code{geo.timeseries}; in this case the column \emph{must} 24 | exist in the data frame.} 25 | 26 | \item{treat.assignment}{a \code{TreatmentAssignment} object, specifying the 27 | mapping from (period, geo) to a treatment assignment condition (treatment 28 | intervention type). Or, \code{NULL} if the treatment assignment is yet 29 | unknown. Or, leave unspecified to extract this information from the column 30 | \code{assignment} of \code{geo.timeseries}. If the column \code{assignment} 31 | does not exist, the resulting object will have the column \code{assignment} 32 | filled with \code{NA}s.} 33 | } 34 | \value{ 35 | A GeoExperimentData object. 36 | } 37 | \description{ 38 | Constructs a GeoExperimentData object. 39 | } 40 | \details{ 41 | If any of the arguments \code{periods}, \code{geo.assignment}, or 42 | \code{treat.assignment} is \code{NULL}, the corresponding column 43 | (\code{period}, \code{geo.group}, \code{assignment}) in the resulting 44 | \code{GeoExperimentData} object will have only \code{NA}s.\cr 45 | 46 | If \code{geo.timeseries} has columns \code{period}, \code{geo.group}, or 47 | \code{assignment}, they will be overwritten by the values specified by 48 | \code{periods}, \code{geo.assignment}, and \code{treat.assignment}.\cr 49 | 50 | The resulting object \emph{may} have undefined \code{periods}, 51 | \code{geo.group}, or \code{assignment}. The missing parts may be filled in 52 | by using the functions \code{SetExperimentPeriods}, \code{SetGeoAssignment}, 53 | and \code{SetTreatmentAssignment}. 54 | } 55 | 56 | -------------------------------------------------------------------------------- /man/GeoExperimentPreanalysisData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geoxpreanalysisdata.R 5 | \name{GeoExperimentPreanalysisData} 6 | \alias{GeoExperimentPreanalysisData} 7 | \title{Creates a GeoExperimentPreanalysisData object.} 8 | \usage{ 9 | GeoExperimentPreanalysisData(obj, period.lengths, geos, recycle = TRUE) 10 | } 11 | \arguments{ 12 | \item{obj}{a GeoTimeseries object.} 13 | 14 | \item{period.lengths}{an integer-valued vector of length 2 or 3, denoting 15 | the lengths (in days) of pre-period, test, and the (optional) 16 | cooldown periods, respectively. The test period must be at least 7 17 | days; the pre-period must be at least as long as the test period. The 18 | cooldown period can be 0 or more days; if it is zero, it will be 19 | ignored as if there were only 2 periods.} 20 | 21 | \item{geos}{(GeoStrata or GeoAssignment object) object to use for choosing 22 | the geo groups at the time of simulating (using 23 | SimulateGeoExperimentData); if 'geos' is a GeoAssignment object, then 24 | the geo assignment will be fixed; iteration; if 'geos' is a 25 | GeoStrata, then the geo assignment will be generated by a call to 26 | 'Randomize'.} 27 | 28 | \item{recycle}{(flag) if TRUE, creates an augmented data set in order to 29 | create a larger time series, reusing data from the head of the time 30 | series.} 31 | } 32 | \value{ 33 | A GeoExperimentPreanalysis object, which inherits from 34 | GeoExperimentData, with NAs in 'geo.group', 'period', and 35 | 'assignment'. The default treatment assignment (spend change only for 36 | period 1 and group 2) is stored into the object. 37 | } 38 | \description{ 39 | Creates a GeoExperimentPreanalysisData object. 40 | } 41 | \note{ 42 | A GeoExperimentPreanalysisData object stores a historical data set 43 | and the information about the length of the experiment periods. It is 44 | used as the generator of pseudo-data sets for simulation purposes. See 45 | also: 'SimulateGeoExperimentData' to generate a GeoExperimentData 46 | object. 47 | } 48 | 49 | -------------------------------------------------------------------------------- /man/GeoStrata.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geostrata.R 5 | \name{GeoStrata} 6 | \alias{GeoStrata} 7 | \title{Constructor for \code{GeoStrata} objects.} 8 | \usage{ 9 | GeoStrata(geos, n.groups = 2, group.ratios = rep(1, length.out = n.groups)) 10 | } 11 | \arguments{ 12 | \item{geos}{a \code{Geos} object.} 13 | 14 | \item{n.groups}{number of groups. At least 2 and at most the number of geos.} 15 | 16 | \item{group.ratios}{(integer vector of length n.groups) vector of ratios of 17 | the sizes of each group. By default each group is assumed to have equal 18 | ratios. The sum of these numbers also imply the size of a stratum. For 19 | example, \code{c(2, 1)} implies that group 1 should be 2 times larger than 20 | group 2, and the stratum size is 2 + 1 = 3. Note: the ratios do not have to 21 | be normalized to have greatest common divisor 1. For example, c(4, 2) 22 | implies that the ratio of group sizes is 2:1 but the stratum size is 4 + 2 = 23 | 6.} 24 | } 25 | \value{ 26 | A \code{GeoStrata} object that inherits from \code{Geos}. There is 27 | an extra column \code{stratum} that indicates the stratum number to be used 28 | in randomization, and column \code{geo.group} for fixing the geo-to-group 29 | mapping. 30 | } 31 | \description{ 32 | Constructor for \code{GeoStrata} objects. 33 | } 34 | \details{ 35 | \code{GeoStrata} objects are used for (stratified) randomization of 36 | geos into groups. The geos are sorted by their 'volume' (definable by the 37 | user) and then divided into strata of size n.groups (column 'stratum'). 38 | This object has also a column \code{geo.group}, which offers the possibility to 39 | fix certain geos to certain groups. By default, this column is filled with 40 | \code{NA}s, indicating that none of the geos are mapped to any groups. The 41 | randomization itself is done by the method \code{Randomize}.\cr 42 | 43 | Any individual geo -> geo.group mappings should be fixed by using the 44 | \code{SetGeoGroup<-} method on a \code{GeoStrata} object.\cr 45 | 46 | A stratum number \code{0} indicates a geo that is excluded from the scheme 47 | stratification. Any geo that is mapped to group \code{0} will have stratum 48 | number \code{0}; for example if geo \code{2} was omitted (geo.groups were 49 | \code{NA, 0, NA, NA, NA, ...}) with group.ratios \code{c(2, 1)}, the strata 50 | would be assigned as \code{1, 0, 1, 1, 2, 2, 2, 3, 3, 3, 4, ...}\cr 51 | 52 | Setting \code{group.ratios} to some other value than the default 53 | \code{1,1,...} enables creating groups that have different sizes. The 54 | stratum size is then determined by the sum of the number in 55 | \code{group.ratios}. For example, \code{group.ratios=c(1, 2)} implies a 56 | ratio of 1:2. Each stratum has size 3; the 3 geos in this stratum are 57 | assigned a random sample with replacement from the set 58 | \code{1,2,2}. Similarly, \code{c(3, 1)} implies that group 1 will be on 59 | average 3 times as large as group 2.\cr 60 | } 61 | \note{ 62 | The ratios do not have to be normalized to have greatest common 63 | divisor 1. For example, \code{c(4, 2)} implies that the ratio of group sizes is 2:1 64 | but the stratum size is 4 + 2 = 6. 65 | } 66 | \seealso{ 67 | \code{\link{Randomize}}, \code{\link{SetGeoGroup<-}}. 68 | } 69 | 70 | -------------------------------------------------------------------------------- /man/GeoTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geotimeseries.R 5 | \name{GeoTimeseries} 6 | \alias{GeoTimeseries} 7 | \title{Constructs a \code{GeoTimeseries} object.} 8 | \usage{ 9 | GeoTimeseries(x, metrics = character(0), date.format = "\%Y-\%m-\%d") 10 | } 11 | \arguments{ 12 | \item{x}{a \emph{plain} \code{data.frame} or an object that has to be 13 | coercible to a plain \code{data.frame} with columns \code{date}, 14 | \code{geo}. \code{date} must be a \code{Date} object or a character vector 15 | or factor coercible to Date, and 'geo' must be a character vector, factor, 16 | or integer-valued. All columns that start with a dot (\code{.}) are 17 | removed. If \code{geo} is an integer-valued numeric or factor, it is coerced 18 | to character silently without error. If \code{date} is a character or 19 | factor, it is silently coerced to \code{Date}. An error is output if the 20 | date conversion fails.} 21 | 22 | \item{metrics}{(character) column names that point to numeric columns. At 23 | least one metric must be specified. All metrics have to be not all 24 | \code{NA}.} 25 | 26 | \item{date.format}{(string, optional) format of the column \code{date} in 27 | the form understood by \code{as.Date()}. Used only if the \code{date} column 28 | is of character type.} 29 | } 30 | \value{ 31 | A \code{GeoTimeseries} object, which is a \code{data.frame}, 32 | with the required columns, 33 | \itemize{ 34 | \item{\code{date}}: a vector of class \code{Date}. 35 | \item{\code{geo}}: a \code{character}-valued vector of Geo IDs. 36 | \item{\code{metrics}} : one or more numeric metrics. In addition, optionally 37 | any other user-definable columns. (These are ignored by the specified 38 | methods but may be convenient for the user). Three columns are added, 39 | for convenience: 40 | \itemize{ 41 | \item{\code{.weekday}}: day number (1=Monday, 2=Tuesday, ..., 7=Sunday) 42 | \item{\code{.weeknum}}: week number in the year from 0 to 53. 43 | \item{\code{.weekindex}}: absolute index of week, year + weeknum 44 | (e.g., \code{201542}) 45 | } 46 | } 47 | These should be convenient for generating totals and averages, using the 48 | \code{aggregate} method. The columns 'date' and 'geo' form the primary 49 | keys: it is guaranteed that no duplicate ('date', 'geo') pairs exist. 50 | 51 | The object includes fields stored in the attribute 'info': 52 | \itemize{ 53 | \item\code{metrics}: names of the metric columns. 54 | \item\code{other}: names of the other user-supplied columns. 55 | } 56 | } 57 | \description{ 58 | Constructs a \code{GeoTimeseries} object. 59 | } 60 | 61 | -------------------------------------------------------------------------------- /man/Geos.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geos.R 5 | \name{Geos} 6 | \alias{Geos} 7 | \title{Constructor for Geos objects.} 8 | \usage{ 9 | Geos(x, volume = NULL) 10 | } 11 | \arguments{ 12 | \item{x}{a data frame with column 'geo' and optionally other columns. Each 13 | 'geo' must be unique.} 14 | 15 | \item{volume}{name of the column that represents the 'volume' of the geo. 16 | The proportion of volume is computed. If omitted, the assumed volumes 17 | will be 1 for each geo. The volumes have to be non-negative and sum 18 | up to a positive value.} 19 | } 20 | \value{ 21 | An object of class 'Geos', which is a data frame with the column 22 | 'geo', the column 'proportion' and 'volume', and other optional 23 | columns. The rows are sorted by the descending order of 'volume'. 24 | } 25 | \description{ 26 | Constructor for Geos objects. 27 | } 28 | 29 | -------------------------------------------------------------------------------- /man/GetGeoNames.GeoStrata.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/getgeonames.R 5 | \name{GetGeoNames.GeoStrata} 6 | \alias{GetGeoNames.GeoStrata} 7 | \title{Extracts the unique names of the geos from a GeoStrata object.} 8 | \usage{ 9 | \method{GetGeoNames}{GeoStrata}(obj, groups = NULL) 10 | } 11 | \arguments{ 12 | \item{obj}{a GeoStrata object.} 13 | 14 | \item{groups}{(NULL, integer vector) id number(s) of the groups whose geos 15 | to obtain, or NULL for all geos. NA is allowed.} 16 | } 17 | \value{ 18 | A character vector of unique geo identifiers, sorted. 19 | } 20 | \description{ 21 | Extracts the unique names of the geos from a GeoStrata object. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/GetGeoNames.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/getgeonames.R 5 | \name{GetGeoNames} 6 | \alias{GetGeoNames} 7 | \alias{GetGeoNames.GeoAssignment} 8 | \alias{GetGeoNames.GeoExperimentData} 9 | \alias{GetGeoNames.GeoTimeseries} 10 | \alias{GetGeoNames.Geos} 11 | \title{Extracts the names of the geos from the object.} 12 | \usage{ 13 | GetGeoNames(obj, groups = NULL) 14 | 15 | \method{GetGeoNames}{GeoTimeseries}(obj, groups = NULL) 16 | 17 | \method{GetGeoNames}{GeoExperimentData}(obj, groups = NULL) 18 | 19 | \method{GetGeoNames}{GeoAssignment}(obj, groups = NULL) 20 | 21 | \method{GetGeoNames}{Geos}(obj, groups = NULL) 22 | } 23 | \arguments{ 24 | \item{obj}{an object.} 25 | 26 | \item{groups}{(NULL, or integer vector) id number(s) of the groups whose 27 | geos to obtain, or NULL for all geos. \code{NA} is allowed.} 28 | } 29 | \value{ 30 | A character vector of unique geo identifiers, sorted. Can be empty 31 | if there are no geos matching 'groups'. Will be empty if the geo 32 | assignment object does not exist in the object. 33 | } 34 | \description{ 35 | Extracts the names of the geos from the object. 36 | } 37 | 38 | -------------------------------------------------------------------------------- /man/GetInfo.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_class.R 5 | \name{GetInfo} 6 | \alias{GetInfo} 7 | \title{Get a value of the 'info' attribute of an object.} 8 | \usage{ 9 | GetInfo(obj, field) 10 | } 11 | \arguments{ 12 | \item{obj}{any R object.} 13 | 14 | \item{field}{(string) name of the field the value of which to retrieve.} 15 | } 16 | \value{ 17 | The requested value (object). 18 | } 19 | \description{ 20 | Get a value of the 'info' attribute of an object. 21 | } 22 | 23 | -------------------------------------------------------------------------------- /man/GetMessageContextString.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_messaging.R 5 | \name{GetMessageContextString} 6 | \alias{GetMessageContextString} 7 | \title{Get the current message context string.} 8 | \usage{ 9 | GetMessageContextString() 10 | } 11 | \value{ 12 | The current message context string. If not available, returns an 13 | empty string (""). 14 | } 15 | \description{ 16 | Get the current message context string. 17 | } 18 | \note{ 19 | Pastes the strings together with '>' 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/GetModelIds.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/constants.R 5 | \name{GetModelIds} 6 | \alias{GetModelIds} 7 | \title{Returns the list of available model identifiers.} 8 | \usage{ 9 | GetModelIds() 10 | } 11 | \value{ 12 | A character vector of the available model IDs. The 'names' 13 | attribute shows the methodology ID (gbr, tbr). 14 | } 15 | \description{ 16 | Returns the list of available model identifiers. 17 | } 18 | 19 | -------------------------------------------------------------------------------- /man/GetOneTBRDataFrameForGgplot.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_tbrplotdata.R 5 | \name{.GetOneTBRDataFrameForGgplot} 6 | \alias{.GetOneTBRDataFrameForGgplot} 7 | \title{[internal] Arranges a TBRPlotData or TBRROASPlotData object into a data 8 | frame for plotting.} 9 | \usage{ 10 | .GetOneTBRDataFrameForGgplot(panel, obj, lower, upper, panel.info) 11 | } 12 | \arguments{ 13 | \item{panel}{name of the panel to plot. Must be one of those in 14 | \code{Get(kTBRPlotPanels)}.} 15 | 16 | \item{obj}{a TBRPlotData or TBRROASPlotData object.} 17 | 18 | \item{lower}{(0 < number < upper) lower quantile.} 19 | 20 | \item{upper}{(lower < number < 1) upper quantile.} 21 | 22 | \item{panel.info}{(list) information about the data frame columns for each 23 | of the available panels.} 24 | } 25 | \value{ 26 | A data frame with the columns: 27 | \itemize{ 28 | \item\code{date} date. 29 | \item\code{observed} an observed time series. 30 | \item\code{predicted} a predicted time series. 31 | \item\code{lower} lower bound of the predicted time series. 32 | \item\code{upper} lower bound of the predicted time series. 33 | \item\code{panel.label} panel label to be shown in the plot.} 34 | } 35 | \description{ 36 | [internal] Arranges a TBRPlotData or TBRROASPlotData object into a data 37 | frame for plotting. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/GetPreanalysisSummary.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateroasanalysis.R 5 | \name{.GetPreanalysisSummary} 6 | \alias{.GetPreanalysisSummary} 7 | \alias{.GetPreanalysisSummary.GBRROASAnalysisFitGbr1} 8 | \alias{.GetPreanalysisSummary.TBRROASAnalysisFit} 9 | \title{[internal] Derives a short summary of the quantities for the preanalysis.} 10 | \usage{ 11 | .GetPreanalysisSummary(obj, i, geo.assignment, sim) 12 | 13 | \method{.GetPreanalysisSummary}{TBRROASAnalysisFit}(obj, i, geo.assignment, sim) 14 | 15 | \method{.GetPreanalysisSummary}{GBRROASAnalysisFitGbr1}(obj, i, geo.assignment, 16 | sim) 17 | } 18 | \arguments{ 19 | \item{obj}{an object.} 20 | 21 | \item{i}{(integer) index of the data set.} 22 | 23 | \item{geo.assignment}{(a \code{GeoAssignment} object) the actual 24 | geo assignment of the data set.} 25 | 26 | \item{sim}{(integer >= 0) number of the simulation.} 27 | } 28 | \value{ 29 | A \code{ROASAnalysisFit} object. 30 | } 31 | \description{ 32 | [internal] Derives a short summary of the quantities for the preanalysis. 33 | } 34 | \note{ 35 | No integrity checking of the arguments is done. 36 | } 37 | 38 | -------------------------------------------------------------------------------- /man/GetTBRDataFrameForGgplot.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_tbrplotdata.R 5 | \name{.GetTBRDataFrameForGgplot} 6 | \alias{.GetTBRDataFrameForGgplot} 7 | \title{[internal] Arranges a TBRPlotData or TBRROASPlotData object into a data 8 | frame for plotting.} 9 | \usage{ 10 | .GetTBRDataFrameForGgplot(obj, panels, periods, lower, upper, panel.info) 11 | } 12 | \arguments{ 13 | \item{obj}{a TBRPlotData or TBRROASPlotData object.} 14 | 15 | \item{panels}{names of the panels to plot. Available names are those in 16 | \code{(kTBRPlotPanels)}.} 17 | 18 | \item{periods}{(vector of strings) names of the periods to show.} 19 | 20 | \item{lower}{(0 < number < upper) lower quantile.} 21 | 22 | \item{upper}{(lower < number < 1) upper quantile.} 23 | 24 | \item{panel.info}{(list) information about the data frame columns for each 25 | of the available panels.} 26 | } 27 | \value{ 28 | A data frame with the columns: 29 | \itemize{ 30 | \item\code{date} date. 31 | \item\code{observed} an observed time series. 32 | \item\code{predicted} a predicted time series. 33 | \item\code{lower} lower bound of the predicted time series. 34 | \item\code{upper} lower bound of the predicted time series. 35 | \item\code{panel.label} panel label to be shown in the plot. 36 | } 37 | } 38 | \description{ 39 | [internal] Arranges a TBRPlotData or TBRROASPlotData object into a data 40 | frame for plotting. 41 | } 42 | 43 | -------------------------------------------------------------------------------- /man/GetTBRPlotPanelNames.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/constants.R 5 | \name{GetTBRPlotPanelNames} 6 | \alias{GetTBRPlotPanelNames} 7 | \title{Returns the names of available TBR panels in the default order of 8 | plotting.} 9 | \usage{ 10 | GetTBRPlotPanelNames() 11 | } 12 | \value{ 13 | A character vector of the available panel IDs. 14 | } 15 | \description{ 16 | Returns the names of available TBR panels in the default order of 17 | plotting. 18 | } 19 | 20 | -------------------------------------------------------------------------------- /man/GetWeeklyAverages.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/getweeklyaverages.R 5 | \name{GetWeeklyAverages} 6 | \alias{GetWeeklyAverages} 7 | \alias{GetWeeklyAverages.GeoTimeseries} 8 | \title{Calculates the weekly averages of the metrics per geo.} 9 | \usage{ 10 | GetWeeklyAverages(obj, ...) 11 | 12 | \method{GetWeeklyAverages}{GeoTimeseries}(obj, na.rm = TRUE, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{an object.} 16 | 17 | \item{...}{further arguments passed to or from other methods.} 18 | 19 | \item{na.rm}{(flag) remove NAs?} 20 | } 21 | \value{ 22 | A data frame with one row per 'geo', and the weekly averages of 23 | each metric in the columns. 24 | } 25 | \description{ 26 | Calculates the weekly averages of the metrics per geo. 27 | } 28 | \note{ 29 | Does not handle incomplete weeks. Each week is supposed to have the 30 | complete total sales of the week. If for example the first and last 31 | weeks of a daily data set are incomplete, the weekly average will be 32 | underestimated. Works for both weekly and daily data. The averages are 33 | calculated by first calculating the weekly sums for each geo, and then 34 | taking the averages over the weeks. \code{NA}s are removed by default. 35 | } 36 | 37 | -------------------------------------------------------------------------------- /man/GetWeeklyShadedBackgroundDataFrameForGgplot.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/plot_tbrplotdata.R 5 | \name{.GetWeeklyShadedBackgroundDataFrameForGgplot} 6 | \alias{.GetWeeklyShadedBackgroundDataFrameForGgplot} 7 | \title{[internal] Create a data.frame to plot a weekly shaded background to 8 | highlight weekly patterns.} 9 | \usage{ 10 | .GetWeeklyShadedBackgroundDataFrameForGgplot(plot.data) 11 | } 12 | \arguments{ 13 | \item{plot.data}{the output of .GetTBRDataFrameForGgplot.} 14 | } 15 | \value{ 16 | A data.frame with the columns: 17 | \itemize{ 18 | \item\code{xmin}. 19 | \item\code{panel.label}. 20 | \item\code{ymin}. 21 | \item\code{ymax}. 22 | \item\code{xmax}. 23 | } 24 | } 25 | \description{ 26 | [internal] Create a data.frame to plot a weekly shaded background to 27 | highlight weekly patterns. 28 | } 29 | 30 | -------------------------------------------------------------------------------- /man/IsFixedRandomization.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geostrata.R 5 | \name{IsFixedRandomization} 6 | \alias{IsFixedRandomization} 7 | \title{Test if randomizing the geostrata can lead only to a single outcome.} 8 | \usage{ 9 | IsFixedRandomization(geostrata) 10 | } 11 | \arguments{ 12 | \item{geostrata}{a GeoStrata object.} 13 | } 14 | \value{ 15 | \code{TRUE} if randomizing the geostrata can only lead to a single 16 | \code{GeoAssignment}, \code{FALSE} otherwise. 17 | } 18 | \description{ 19 | Test if randomizing the geostrata can lead only to a single outcome. 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/IsInPeriod.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/isinperiod.R 5 | \name{IsInPeriod} 6 | \alias{IsInPeriod} 7 | \alias{IsInPeriod.TBRAnalysisData} 8 | \alias{IsInPeriod.TBRAnalysisFitTbr1} 9 | \alias{IsInPeriod.TBRQuantiles} 10 | \alias{IsInPeriod.TBRROASAnalysisFit} 11 | \title{[internal] Returns a logical vector indicating which of the rows are in 12 | the specified period(s).} 13 | \usage{ 14 | IsInPeriod(obj, periods) 15 | 16 | \method{IsInPeriod}{TBRAnalysisData}(obj, periods) 17 | 18 | \method{IsInPeriod}{TBRAnalysisFitTbr1}(obj, periods) 19 | 20 | \method{IsInPeriod}{TBRROASAnalysisFit}(obj, periods) 21 | 22 | \method{IsInPeriod}{TBRQuantiles}(obj, periods) 23 | } 24 | \arguments{ 25 | \item{obj}{some object.} 26 | 27 | \item{periods}{names of the periods.} 28 | } 29 | \value{ 30 | A logical vector of length \code{nrow(obj)}, \code{TRUE} for a row 31 | that is within the given period(s), \code{FALSE} otherwise. No \code{NA}s. 32 | } 33 | \description{ 34 | [internal] Returns a logical vector indicating which of the rows are in 35 | the specified period(s). 36 | } 37 | \note{ 38 | \code{TBRROASAnalysisFit} consists of simulations with rows only for 39 | the prediction period, not for the preanalysis period. 40 | 41 | \code{TBRQuantiles} consists of simulations with rows only for the 42 | prediction period, not for the preanalysis period. 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/IsStratumCompatibleWithRatios.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/geostrata.R 5 | \name{IsStratumCompatibleWithRatios} 6 | \alias{IsStratumCompatibleWithRatios} 7 | \title{Checks whether strata are compatible with group.ratios.} 8 | \usage{ 9 | IsStratumCompatibleWithRatios(geo.group, group.ratios) 10 | } 11 | \arguments{ 12 | \item{geo.group}{(integer vector of length equal to number of geos) a vector 13 | of geo group numbers (may be NAs, but zeros are not allowed).} 14 | 15 | \item{group.ratios}{(integer vector of length equal to number of geo groups) 16 | vector of ratios of the sizes of each group.} 17 | } 18 | \value{ 19 | TRUE if geo.group is compatible with group.ratios, i.e. no group 20 | has been assigned more geos than what group.ratios allows. FALSE 21 | otherwise. 22 | } 23 | \description{ 24 | Checks whether strata are compatible with group.ratios. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/Message.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_messaging.R 5 | \name{Message} 6 | \alias{Message} 7 | \title{Form a message, prefixed with the message context string.} 8 | \usage{ 9 | Message(...) 10 | } 11 | \arguments{ 12 | \item{...}{R vectors, usually character, to be collapsed using 'paste0'.} 13 | } 14 | \value{ 15 | A string. 16 | } 17 | \description{ 18 | Form a message, prefixed with the message context string. 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/Messagef.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_messaging.R 5 | \name{Messagef} 6 | \alias{Messagef} 7 | \title{Form a message, using sprintf.} 8 | \usage{ 9 | Messagef(fmt, ...) 10 | } 11 | \arguments{ 12 | \item{fmt}{a character vector of format strings (see 'sprintf' for details).} 13 | 14 | \item{...}{values to be passed to 'fmt'.} 15 | } 16 | \value{ 17 | A string. 18 | } 19 | \description{ 20 | Form a message, using sprintf. 21 | } 22 | 23 | -------------------------------------------------------------------------------- /man/ROASAnalysisResults.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/roasanalysisresults.R 5 | \name{ROASAnalysisResults} 6 | \alias{ROASAnalysisResults} 7 | \title{Constructs a \code{ROASAnalysisResults} object.} 8 | \usage{ 9 | ROASAnalysisResults(estimate, lower, upper, level, incr.resp, incr.cost, 10 | threshold, post.prob, model) 11 | } 12 | \arguments{ 13 | \item{estimate}{(number) iROAS point estimate.} 14 | 15 | \item{lower}{(number) lower bound of the interval estimate.} 16 | 17 | \item{upper}{(number or Inf) upper bound of the interval estimate.} 18 | 19 | \item{level}{(number between 0 and 1) confidence level.} 20 | 21 | \item{incr.resp}{(number) point estimate of the total incremental response.} 22 | 23 | \item{incr.cost}{(number) point estimate of the total incremental cost.} 24 | 25 | \item{threshold}{(number) threshold for calculating the posterior 26 | probability \code{Pr(iROAS>thres|data)}.} 27 | 28 | \item{post.prob}{(number) posterior probability Pr(beta2 > threshold|data).} 29 | 30 | \item{model}{(string) id string indicating the model used.} 31 | } 32 | \value{ 33 | An object of class \code{ROASAnalysisResults}. 34 | This is a \code{data.frame} with the columns: 35 | \itemize{ 36 | \item\code{estimate}: point estimate of the incremental ROAS. 37 | \item\code{precision}: confidence/credible interval half-width. 38 | Calculated as \code{0.5} times the difference between upper and 39 | lower bounds; if upper is \code{Inf}, then precision is 40 | the distance between the 41 | estimate and the lower bound. 42 | \item\code{lower}: lower bound of the interval estimate. 43 | \item\code{upper}: upper bound of the interval estimate 44 | (can be \code{Inf}). 45 | \item\code{level}: confidence level. 46 | \item\code{incr.resp}: estimated incremental response. 47 | \item\code{incr.cost}: estimated incremental cost. 48 | \item\code{thres}: threshold for the posterior tail probability. 49 | \item\code{prob}: posterior tail probability 50 | \code{Pr(iROAS>thres|data)}. 51 | \item\code{model}: model id. 52 | } 53 | } 54 | \description{ 55 | Constructs a \code{ROASAnalysisResults} object. 56 | } 57 | 58 | -------------------------------------------------------------------------------- /man/ROASPreanalysisFitRow.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateroasanalysis.R 5 | \name{.ROASPreanalysisFitRow} 6 | \alias{.ROASPreanalysisFitRow} 7 | \title{[internal] Constructs a \code{ROASPreanalysisFit}-compatible object with one 8 | single row. To be bound together row-wise with other such objects.} 9 | \usage{ 10 | .ROASPreanalysisFitRow(sim, model, estimate, sd, df, i, geo.assignment) 11 | } 12 | \arguments{ 13 | \item{sim}{(integer >= 0) number of the simulation.} 14 | 15 | \item{model}{(string) model id.} 16 | 17 | \item{estimate}{(real number) point estimate.} 18 | 19 | \item{sd}{(real number > 0) posterior s.d.} 20 | 21 | \item{df}{(integer > 0) degrees of freedom of the t distribution that is the 22 | posterior of the iROAS estimate.} 23 | 24 | \item{i}{(integer >= 1) index of the data set.} 25 | 26 | \item{geo.assignment}{(a \code{GeoAssignment} object) the actual geo 27 | assignment used.} 28 | } 29 | \value{ 30 | A \code{ROASPreanalysisFitRow} object. 31 | } 32 | \description{ 33 | [internal] Constructs a \code{ROASPreanalysisFit}-compatible object with one 34 | single row. To be bound together row-wise with other such objects. 35 | } 36 | \note{ 37 | No integrity checking of the arguments is done. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/Randomize.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/randomize.R 5 | \name{Randomize} 6 | \alias{Randomize} 7 | \alias{Randomize.GeoStrata} 8 | \alias{Randomize.Geos} 9 | \title{Randomize geos to groups.} 10 | \usage{ 11 | Randomize(obj, ...) 12 | 13 | \method{Randomize}{Geos}(obj, n.groups = 2, group.ratios = rep(1, length.out 14 | = n.groups), ...) 15 | 16 | \method{Randomize}{GeoStrata}(obj, ...) 17 | } 18 | \arguments{ 19 | \item{obj}{an object.} 20 | 21 | \item{...}{arguments passed to other methods.} 22 | 23 | \item{n.groups}{(integer) number of groups.} 24 | 25 | \item{group.ratios}{(integer vector of length n.groups) vector of ratios of 26 | the sizes of each group. By default each group is assumed to have 27 | equal ratios.} 28 | } 29 | \value{ 30 | A \code{GeoAssignment} object. 31 | 32 | A \code{GeoAssignment} object. 33 | } 34 | \description{ 35 | Randomize geos to groups. 36 | 37 | Randomize geos, assigning geo groups by strata. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/RenameColumns.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_general.R 5 | \name{RenameColumns} 6 | \alias{RenameColumns} 7 | \title{Renames columns of a data frame.} 8 | \usage{ 9 | RenameColumns(x, map = character(0)) 10 | } 11 | \arguments{ 12 | \item{x}{a data frame.} 13 | 14 | \item{map}{a named character vector, mapping old column names to new ones 15 | such that the new ones are in 'names' and the values are the old 16 | ones. For example, \code{c(geo='GMA', date='Week Ending')}. If 'map' 17 | has length 0, the original data frame is returned.} 18 | } 19 | \value{ 20 | The data frame, with the column names renamed. 21 | } 22 | \description{ 23 | Renames columns of a data frame. 24 | } 25 | 26 | -------------------------------------------------------------------------------- /man/SetExperimentPeriods.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/setexperimentperiods.R 5 | \name{SetExperimentPeriods<-} 6 | \alias{SetExperimentPeriods<-} 7 | \alias{SetExperimentPeriods<-.GeoExperimentData} 8 | \title{Associates the object with an ExperimentPeriods object.} 9 | \usage{ 10 | SetExperimentPeriods(obj, ...) <- value 11 | 12 | \method{SetExperimentPeriods}{GeoExperimentData}(obj, strict = TRUE, ...) <- 13 | value 14 | } 15 | \arguments{ 16 | \item{obj}{the object to change.} 17 | 18 | \item{...}{further arguments passed to methods.} 19 | 20 | \item{value}{a ExperimentPeriods object.} 21 | 22 | \item{strict}{(flag) insist that data has all specified experiment periods?} 23 | } 24 | \value{ 25 | The object that has been modified in place. 26 | } 27 | \description{ 28 | Associates the object with an ExperimentPeriods object. 29 | } 30 | \note{ 31 | The 'date' column is mapped to the 'period' column. The 'period' slot 32 | is assigned with the new value and the columns 'period' and 'assignment' are 33 | changed to reflect the new date ranges. 34 | } 35 | 36 | -------------------------------------------------------------------------------- /man/SetGeoAssignment.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/setgeoassignment.R 5 | \name{SetGeoAssignment<-} 6 | \alias{SetGeoAssignment<-} 7 | \alias{SetGeoAssignment<-.GeoExperimentData} 8 | \title{Associates the object with a \code{GeoAssignment} object.} 9 | \usage{ 10 | SetGeoAssignment(obj, ...) <- value 11 | 12 | \method{SetGeoAssignment}{GeoExperimentData}(obj, strict = TRUE, ...) <- value 13 | } 14 | \arguments{ 15 | \item{obj}{the object to change.} 16 | 17 | \item{...}{further arguments passed to methods.} 18 | 19 | \item{value}{a \code{GeoAssignment} object.} 20 | 21 | \item{strict}{(flag) insist that all geos in the data are mapped? Also, warn 22 | if some geos are not found in the data?} 23 | } 24 | \value{ 25 | The object (that has been modified in place). 26 | } 27 | \description{ 28 | Associates the object with a \code{GeoAssignment} object. 29 | 30 | Associates the object with a GeoAssignment object, mapping geos into geo 31 | group numbers. 32 | } 33 | \details{ 34 | If \code{value} is \code{NULL}, the geo assignment and the treatment 35 | assignment are removed, and their corresponding columns in the data frame 36 | are reset to 'NA'. An error is thrown if any geo in data cannot be mapped to 37 | a group (due to the \code{GeoAssignment} object not having such a mapping). 38 | Setting 'strict' to \code{FALSE} will avert this. An error is thrown if some 39 | of the geos in the mapping were not present in the data. Setting 'strict' to 40 | \code{FALSE} will avert this. 41 | 42 | \code{geo.assignment} slot is assigned with the new value and the columns 43 | \code{geo.group} and \code{assignment} are changed to reflect the new geo 44 | assignment. 45 | } 46 | 47 | -------------------------------------------------------------------------------- /man/SetIncrementalResponse.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/setincrementalresponse.R 5 | \name{SetIncrementalResponse<-} 6 | \alias{SetIncrementalResponse<-} 7 | \alias{SetIncrementalResponse<-.GeoExperimentData} 8 | \title{Sets an incremental response for simulation purposes.} 9 | \usage{ 10 | SetIncrementalResponse(obj, response, periods = "all") <- value 11 | 12 | \method{SetIncrementalResponse}{GeoExperimentData}(obj, response, 13 | periods = "all") <- value 14 | } 15 | \arguments{ 16 | \item{obj}{an object with the column '.spend'.} 17 | 18 | \item{response}{(string) name of the column which acts as the response 19 | metric.} 20 | 21 | \item{periods}{numbers of the periods which are affected; if this is "all", 22 | all periods are affected.} 23 | 24 | \item{value}{the absolute value of the incremental return on ad spend. Can 25 | also be negative. Can also be NA, in the case of which the column 26 | \code{.response} will be reset to NA.} 27 | } 28 | \value{ 29 | The object, with the modfied spend change column \code{.response}. 30 | } 31 | \description{ 32 | Sets an incremental response for simulation purposes. 33 | } 34 | \note{ 35 | Creates a column \code{.response} if it does not exist, and registers it 36 | as a metric. The column \code{.response} contains the baseline response and 37 | the incremental response, which is defined as the specified incremental 38 | ROAS ('value') times the column '.spend'. 39 | } 40 | 41 | -------------------------------------------------------------------------------- /man/SetInfo.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_class.R 5 | \name{SetInfo} 6 | \alias{SetInfo} 7 | \title{Set the values of the 'info' attribute of an object.} 8 | \usage{ 9 | SetInfo(obj, ..., info = NULL) 10 | } 11 | \arguments{ 12 | \item{obj}{some object.} 13 | 14 | \item{...}{name-value pairs to set in the list-valued attribute 'info'.} 15 | 16 | \item{info}{the initial value of the 'info' attribute; if specified, will 17 | re-set the value before changing the individual name-value pairs.} 18 | } 19 | \value{ 20 | The object ('obj') that was changed. 21 | } 22 | \description{ 23 | Set the values of the 'info' attribute of an object. 24 | } 25 | \note{ 26 | Used only internally in this package. Do not use for data tables. 27 | } 28 | 29 | -------------------------------------------------------------------------------- /man/SetMessageContextString.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_messaging.R 5 | \name{SetMessageContextString} 6 | \alias{SetMessageContextString} 7 | \title{Save a string representing the current context of the program flow.} 8 | \usage{ 9 | SetMessageContextString(context) 10 | } 11 | \arguments{ 12 | \item{context}{(a string) context of the message; to be displayed in (error) 13 | messages.} 14 | } 15 | \value{ 16 | The previous message context strings (a character vector). 17 | } 18 | \description{ 19 | Save a string representing the current context of the program flow. 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/SetSpendChange.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/setspendchange.R 5 | \name{SetSpendChange<-} 6 | \alias{SetSpendChange<-} 7 | \alias{SetSpendChange<-.GeoExperimentData} 8 | \title{Sets the spend change in a geo experiment for simulation purposes.} 9 | \usage{ 10 | SetSpendChange(obj, prop.to, periods = "all") <- value 11 | 12 | \method{SetSpendChange}{GeoExperimentData}(obj, prop.to, periods = "all") <- 13 | value 14 | } 15 | \arguments{ 16 | \item{obj}{an object with the column 'assignment'.} 17 | 18 | \item{prop.to}{(existing) name of the column in proportion to which the 19 | spend change will be spread across the geos.} 20 | 21 | \item{periods}{numbers of the periods which are affected; if this is 22 | \code{"all"}, all periods are affected and the spend change will be spread 23 | across all periods that have spend change (determined by the column 24 | \code{assignment}).} 25 | 26 | \item{value}{the total absolute value of the spend change. Can also be NA, 27 | in the case of which the spend change column will be reset to NA.} 28 | } 29 | \value{ 30 | The object, with the modified spend change column \code{.spend}. 31 | } 32 | \description{ 33 | Sets the spend change in a geo experiment for simulation purposes. 34 | } 35 | \note{ 36 | Creates a column \code{.spend}. The spend change type is determined by the 37 | \code{assignment} column. The absolute value of the spend change will be 38 | spread across geos in the proportion of the given column (\code{prop.to}); 39 | the sign of the change is determined by the type of change: for 40 | treatment assignments set to 'decrease', the sign will be negative, 41 | otherwise positive. 42 | } 43 | 44 | -------------------------------------------------------------------------------- /man/SetTreatmentAssignment.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/settreatmentassignment.R 5 | \name{SetTreatmentAssignment<-} 6 | \alias{SetTreatmentAssignment<-} 7 | \alias{SetTreatmentAssignment<-.GeoExperimentData} 8 | \title{Associates the object with an TreatmentAssignment object.} 9 | \usage{ 10 | SetTreatmentAssignment(obj, ...) <- value 11 | 12 | \method{SetTreatmentAssignment}{GeoExperimentData}(obj, strict = TRUE, ...) <- 13 | value 14 | } 15 | \arguments{ 16 | \item{obj}{the object to change.} 17 | 18 | \item{...}{further arguments passed to methods.} 19 | 20 | \item{value}{a TreatmentAssignment object.} 21 | 22 | \item{strict}{(flag) insist that data has all treatment combinations?} 23 | } 24 | \value{ 25 | The object (that has been modified in place). 26 | } 27 | \description{ 28 | Associates the object with an TreatmentAssignment object. 29 | } 30 | \note{ 31 | The value pairs ('period', 'geo.group') are mapped to a (treatment) 32 | 'assignment' column. 33 | 34 | If 'strict' is TRUE, throws an error if some treatment assignments 35 | are not found in the data. If 'strict' is FALSE, no warnings or errors 36 | are thrown. 37 | } 38 | 39 | -------------------------------------------------------------------------------- /man/SimulateGeoExperimentData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulategeoxdataset.R 5 | \name{SimulateGeoExperimentData} 6 | \alias{SimulateGeoExperimentData} 7 | \alias{SimulateGeoExperimentData.GeoExperimentPreanalysisData} 8 | \title{Returns a geo experiment data set.} 9 | \usage{ 10 | SimulateGeoExperimentData(obj, ...) 11 | 12 | \method{SimulateGeoExperimentData}{GeoExperimentPreanalysisData}(obj, 13 | i = NA_integer_, ...) 14 | } 15 | \arguments{ 16 | \item{obj}{an object.} 17 | 18 | \item{...}{further arguments passed to or from other methods.} 19 | 20 | \item{i}{(positive integer or NA) number of the pseudo data set; if NA, the 21 | number will be drawn from a uniform discrete distribution.} 22 | } 23 | \value{ 24 | A GeoExperimentData object with the experiment periods, geo 25 | assignment, and the treatment assignment set. 26 | } 27 | \description{ 28 | Returns a geo experiment data set. 29 | 30 | Returns a set number i from the GeoExperimentPreanalysisData object. 31 | } 32 | \note{ 33 | If the embedded 'geos' object is GeoStrata, a randomization is done 34 | and the geo assignment applied. 35 | } 36 | 37 | -------------------------------------------------------------------------------- /man/SimulatePosterior.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateposterior.R 5 | \name{SimulatePosterior} 6 | \alias{SimulatePosterior} 7 | \alias{SimulatePosterior.TBRAnalysisFitTbr1} 8 | \title{Draws a sample from a posterior distribution.} 9 | \usage{ 10 | SimulatePosterior(obj, n.sims = 1e+05, ...) 11 | 12 | \method{SimulatePosterior}{TBRAnalysisFitTbr1}(obj, n.sims = 1e+05, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{an object.} 16 | 17 | \item{n.sims}{(integer >= 2) number of simulations to draw.} 18 | 19 | \item{...}{other arguments passed on to the methods.} 20 | } 21 | \value{ 22 | A PosteriorSimulations object, which is a matrix with 'n.sims' 23 | columns and as many rows as there are time points in the test period. 24 | Each row corresponds to one time point in the test period, with the 25 | draws from the pointwise distribution of the incremental effect. 26 | } 27 | \description{ 28 | Draws a sample from a posterior distribution. 29 | } 30 | \details{ 31 | \code{SimulatePosterior.TBRAnalysisFitTbr1}: Draws from the 32 | posterior distribution of the pointwise incremental effect over the test 33 | period. 34 | } 35 | \note{ 36 | The 'standard' noninformative prior is assumed: uniform on (beta, log 37 | sigma). Reference: Gelman et al. Bayesian Data Analysis (2nd ed.), 38 | section 14.2, formula (14.8). To obtain the simulations for the 39 | cumulative distribution, use the \code{cumsum} method. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/SimulateROASAnalysis.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateroasanalysis.R 5 | \name{.SimulateROASAnalysis} 6 | \alias{.SimulateROASAnalysis} 7 | \title{[internal] Performs a ROAS analysis on one simulated data set drawn from 8 | the \code{GeoExperimentPreanalysisData} object.} 9 | \usage{ 10 | .SimulateROASAnalysis(sim, randomize.i, obj, response, prop.to, cost = 1, 11 | models = GetModelIds(), swap.and.redo = FALSE) 12 | } 13 | \arguments{ 14 | \item{sim}{(integer >= 1) number of the simulation; if 'randomize.i' is 15 | \code{FALSE}, 'sim' will be used as the number of the data set to draw.} 16 | 17 | \item{randomize.i}{(flag) if TRUE, the number of the data set will be drawn 18 | at random. If \code{FALSE}, the number of the data set will be set equal 19 | to \code{sim}.} 20 | 21 | \item{obj}{a \code{GeoExperimentPreanalysisData} object.} 22 | 23 | \item{response}{(string) name of the metric column to use as the response 24 | variable.} 25 | 26 | \item{prop.to}{(string) an existing name of the column in proportion to 27 | which the spend change will be distributed across the geos.} 28 | 29 | \item{cost}{(real number) incremental cost, assumed fixed and known.} 30 | 31 | \item{models}{(vector of nonempty strings) one or more analysis model ids. 32 | The simulated data set is apply to simulated data set. By default, 33 | all possible models are fit.} 34 | 35 | \item{swap.and.redo}{(flag) swap groups and redo the analysis? Note: number 36 | of groups must be 2 if this flag is TRUE. Since this produces two 37 | simulations, the indices of simulations that are registered will be 38 | \code{2 * sim - 1} and \code{2 * sim}.} 39 | } 40 | \value{ 41 | A \code{ROASAnalysisFit} object, a data frame with one or more 42 | rows. 43 | } 44 | \description{ 45 | [internal] Performs a ROAS analysis on one simulated data set drawn from 46 | the \code{GeoExperimentPreanalysisData} object. 47 | } 48 | \note{ 49 | This is an internal function, called from another function. No 50 | integrity checking of the parameters is done; this must be done by the 51 | enclosing function. 52 | } 53 | 54 | -------------------------------------------------------------------------------- /man/Subset.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/subset.R 5 | \name{Subset} 6 | \alias{Subset} 7 | \alias{Subset.GeoExperimentData} 8 | \alias{Subset.GeoTimeseries} 9 | \title{Returns a subset of the object, ensuring that the resulting object is of 10 | the same class.} 11 | \usage{ 12 | Subset(obj, ...) 13 | 14 | \method{Subset}{GeoTimeseries}(obj, rows, columns, ...) 15 | 16 | \method{Subset}{GeoExperimentData}(obj, rows, columns, ...) 17 | } 18 | \arguments{ 19 | \item{obj}{an object.} 20 | 21 | \item{...}{further arguments passed to or from other methods.} 22 | 23 | \item{rows}{logical vector indicating rows to keep. No missing values are 24 | allowed.} 25 | 26 | \item{columns}{character vector indicating columns of the data frame to 27 | keep. Columns such as 'date', 'geo', 'period', 'geo.group' and 28 | 'assignment', if they exist, they are always included.} 29 | } 30 | \value{ 31 | An object of the same class as '\code{obj}'. 32 | } 33 | \description{ 34 | Returns a subset of the object, ensuring that the resulting object is of 35 | the same class. 36 | 37 | Extract a subset of GeoTimeseries. 38 | } 39 | \note{ 40 | The arguments 'rows' and 'columns' are *not* evaluated in the 41 | environment of the columns of 'obj'; the expressions must be evaluable 42 | in the enclosing environment. This behavior is deliberately different 43 | from that of 'subset'. The original experiment configuration (periods, 44 | geo assignment, treatment assignment) is preserved. 45 | } 46 | 47 | -------------------------------------------------------------------------------- /man/TBRAnalysisData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/tbranalysisdata.R 5 | \name{TBRAnalysisData} 6 | \alias{TBRAnalysisData} 7 | \title{Constructs a TBRAnalysisData object.} 8 | \usage{ 9 | TBRAnalysisData(x) 10 | } 11 | \arguments{ 12 | \item{x}{a _plain_ \code{data.frame} or an object that has to be coercible 13 | to a _plain_ \code{data.frame} with the required columns \code{data}, which 14 | _must_ be a \code{Date} vector; integer-valued column \code{period} 15 | indicating the pre-experiment, pretest, intervention, cooldown, and posttest 16 | periods; numeric columns \code{y} (response), \code{x} 17 | (covariate). Optionally the data frame can have other columns, which are 18 | ignored but whose names cannot start with a dot ('.'). No missing values are 19 | allowed in the pretest and test periods (but allowed outside of either 20 | period).#'} 21 | } 22 | \value{ 23 | A \code{TBRAnalysisData} object, which is similarly a 24 | \code{data.frame} with the columns: 25 | 26 | \code{TBRAnalysisData} is a \code{data.frame}, with the required columns, 27 | \itemize{ 28 | \item{\code{date}}: a 'Date'-valued vector. 29 | \item{\code{period}}: numeric indicator of various periods. 30 | \code{0} indicates the pretest period. \code{NA} indicates a date 31 | that has been excluded from the analyses. 32 | \item{\code{y}}: numeric values of the metric of the Treatment group. 33 | \item{\code{x}}: numeric values of the metric in the Control group. 34 | In addition, optionally any other user-definable columns. 35 | } 36 | } 37 | \description{ 38 | Constructs a TBRAnalysisData object. 39 | } 40 | \note{ 41 | The column \code{date} is the primary key; it is guaranteed that no 42 | rows with duplicate geos exist and that the rows are in temporal order. 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/TreatmentAssignment.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/treatmentassignment.R 5 | \name{TreatmentAssignment} 6 | \alias{DefaultTreatmentAssignment} 7 | \alias{TreatmentAssignment} 8 | \title{Constructs a TreatmentAssignment object.} 9 | \usage{ 10 | TreatmentAssignment(x) 11 | 12 | DefaultTreatmentAssignment() 13 | } 14 | \arguments{ 15 | \item{x}{(data frame) a mapping from (period, group) to treatment assignment 16 | condition. The data frame must have the columns 'period' 17 | (integer-valued), 'geo.group' (integer-valued, positive), and 18 | 'assignment' (integer-valued, one of 0, 1, -1), Each row specifies 19 | the mapping of one (period, group) pair. No missing values are 20 | allowed.} 21 | } 22 | \value{ 23 | An object of class 'TreatmentAssignment'. 24 | } 25 | \description{ 26 | Constructs a TreatmentAssignment object. 27 | } 28 | \note{ 29 | Not used in the analysis methods, only for 30 | \code{\link{SetSpendChange<-}}. 31 | 32 | \code{DefaultTreatmentAssignment} generates the default treatment 33 | assignment condition, which assigns a change ('some intervention') to Period 34 | 1 of group 2. 35 | } 36 | \seealso{ 37 | \code{\link{TreatmentAssignment}}, \code{\link{SetSpendChange<-}}. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/aggregate.GeoTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/aggregate.R 5 | \name{aggregate.GeoTimeseries} 6 | \alias{aggregate.GeoTimeseries} 7 | \title{Aggregate the Metrics of a GeoTimeseries.} 8 | \usage{ 9 | \method{aggregate}{GeoTimeseries}(x, by = kGeo, FUN = base::sum, 10 | metrics = NULL, ...) 11 | } 12 | \arguments{ 13 | \item{x}{a GeoTimeseries object.} 14 | 15 | \item{by}{(character vector) name(s) of column(s) by which to group.} 16 | 17 | \item{FUN}{(function) function to apply to each metric column.} 18 | 19 | \item{metrics}{(character vector) metrics to aggregate. Default is all 20 | metrics.} 21 | 22 | \item{...}{optional arguments passed to FUN.} 23 | } 24 | \value{ 25 | A data.frame object. 26 | } 27 | \description{ 28 | Aggregate the Metrics of a GeoTimeseries. 29 | } 30 | \note{ 31 | Uses \code{aggregate.data.frame} to do the aggregation. This function 32 | omits rows that have missing values in the '\code{by}' columns. 33 | } 34 | \seealso{ 35 | AggregateTimeseries. 36 | } 37 | 38 | -------------------------------------------------------------------------------- /man/as.GBRROASAnalysisData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_gbrroasanalysisdata.R 5 | \name{as.GBRROASAnalysisData} 6 | \alias{as.GBRROASAnalysisData} 7 | \alias{as.GBRROASAnalysisData.GeoExperimentData} 8 | \title{Coerces an object to a GBRROASAnalysisData object.} 9 | \usage{ 10 | as.GBRROASAnalysisData(obj, ...) 11 | 12 | \method{as.GBRROASAnalysisData}{GeoExperimentData}(obj, 13 | response = character(0), cost = character(0), pretest.period = 0L, 14 | intervention.period = 1L, cooldown.period = NULL, control.group = 1L, 15 | treatment.group = 2L, ...) 16 | } 17 | \arguments{ 18 | \item{obj}{an object.} 19 | 20 | \item{...}{further arguments to be passed to or from other methods.} 21 | 22 | \item{response}{(string) name of the response variable column.} 23 | 24 | \item{cost}{(string) name of the cost variable column.} 25 | 26 | \item{pretest.period}{(vector of non-negative integers) number(s) of the 27 | period(s) forming the pretest period.} 28 | 29 | \item{intervention.period}{(vector of non-negative integers) number(s) of 30 | the period(s) forming the intervention period. All must be larger 31 | than the largest period in the pretest period.} 32 | 33 | \item{cooldown.period}{(NULL or vector of non-negative integers) number(s) 34 | of the period(s) forming the cooldown period. All must be larger than 35 | the largest period in the intervention period.} 36 | 37 | \item{control.group}{(NULL or a vector of positive integers) number(s) of 38 | geo groups forming the control group.} 39 | 40 | \item{treatment.group}{(NULL or a vector of positive integers) number(s) of 41 | geo groups forming the control group.} 42 | } 43 | \value{ 44 | A GBRROASAnalysisData object. 45 | } 46 | \description{ 47 | Coerces an object to a GBRROASAnalysisData object. 48 | } 49 | \seealso{ 50 | \code{\link{DoGBRROASAnalysis}}. 51 | } 52 | 53 | -------------------------------------------------------------------------------- /man/as.GeoExperimentData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_geoexperimentdata.R 5 | \name{as.GeoExperimentData} 6 | \alias{as.GeoExperimentData} 7 | \alias{as.GeoExperimentData.GeoTimeseries} 8 | \title{Coerces an object to a GeoExperimentData object.} 9 | \usage{ 10 | as.GeoExperimentData(obj, ...) 11 | 12 | \method{as.GeoExperimentData}{GeoTimeseries}(obj, strict = TRUE, ...) 13 | } 14 | \arguments{ 15 | \item{obj}{an object.} 16 | 17 | \item{...}{further arguments passed to methods.} 18 | 19 | \item{strict}{(flag) if FALSE, the additional columns are optional and no 20 | error is thrown if any of them is missing;} 21 | } 22 | \value{ 23 | A GeoExperimentData object. 24 | 25 | A GeoExperimentData object. 26 | } 27 | \description{ 28 | Coerces an object to a GeoExperimentData object. 29 | 30 | Coerces a GeoTimeseries object to a GeoExperiment object. 31 | } 32 | \note{ 33 | The GeoTimeseries object is supposed to have the columns 'period', 34 | 'geo.group', and 'assignment'. If any of these columns are missing, 35 | the corresponding columns in the resulting object will be 'NA'. 36 | } 37 | 38 | -------------------------------------------------------------------------------- /man/as.GeoTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_geotimeseries.R 5 | \name{as.GeoTimeseries} 6 | \alias{as.GeoTimeseries} 7 | \title{Coerce an object to a GeoTimeseries object.} 8 | \usage{ 9 | as.GeoTimeseries(obj, ...) 10 | } 11 | \arguments{ 12 | \item{obj}{an object.} 13 | 14 | \item{...}{additional arguments to be passed to or from methods.} 15 | } 16 | \value{ 17 | A GeoTimeseries object. 18 | } 19 | \description{ 20 | Coerce an object to a GeoTimeseries object. 21 | } 22 | 23 | -------------------------------------------------------------------------------- /man/as.TBRAnalysisData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_tbranalysisdata.R 5 | \name{as.TBRAnalysisData} 6 | \alias{as.TBRAnalysisData} 7 | \alias{as.TBRAnalysisData.GeoExperimentData} 8 | \title{Coerces an object to a TBRAnalysisData object.} 9 | \usage{ 10 | as.TBRAnalysisData(obj, ...) 11 | 12 | \method{as.TBRAnalysisData}{GeoExperimentData}(obj, response = character(0), 13 | control.group = 1L, treatment.group = 2L, pretest.period = 0L, 14 | intervention.period = 1L, cooldown.period = NULL, ...) 15 | } 16 | \arguments{ 17 | \item{obj}{an object.} 18 | 19 | \item{...}{further arguments to be passed to or from other methods.} 20 | 21 | \item{response}{(string) name of the response metric to analyze.} 22 | 23 | \item{control.group}{(positive integer) number of the control group 24 | (matching one of the groups in the column 'geo.group'). This is 25 | typically 1.} 26 | 27 | \item{treatment.group}{(positive integer) number of the treatment group 28 | (matching one of the groups in the column 'geo.group'). This is 29 | typically 2.} 30 | 31 | \item{pretest.period}{(non-negative integers) number of the pretest period, 32 | typically 0. Can also be one or more numbers, if periods are to be 33 | collapsed.} 34 | 35 | \item{intervention.period}{(vector of non-negative integers) number(s) of 36 | the period(s) forming the intervention period. All must be larger 37 | than the largest period in the pretest period.} 38 | 39 | \item{cooldown.period}{(NULL or vector of non-negative integers) number(s) 40 | of the period(s) forming the cooldown period. All must be larger than 41 | the largest period in the intervention period.} 42 | } 43 | \value{ 44 | A TBRAnalysisData object. 45 | } 46 | \description{ 47 | Coerces an object to a TBRAnalysisData object. 48 | } 49 | \seealso{ 50 | \code{\link{DoTBRAnalysis}}, \code{\link{DoTBRROASAnalysis}}. 51 | } 52 | 53 | -------------------------------------------------------------------------------- /man/as.TBRPlotData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_tbrplotdata.R 5 | \name{as.TBRPlotData} 6 | \alias{as.TBRPlotData} 7 | \alias{as.TBRPlotData.TBRAnalysisFitTbr1} 8 | \alias{as.TBRPlotData.TBRROASAnalysisFit} 9 | \title{Coerces an object to a TBRPlotData object.} 10 | \usage{ 11 | as.TBRPlotData(obj, panels, periods, quantiles = c(0.1, 0.9), ...) 12 | 13 | \method{as.TBRPlotData}{TBRAnalysisFitTbr1}(obj, 14 | panels = GetTBRPlotPanelNames(), periods = c("pretest", "prediction"), 15 | quantiles = c(0.1, 0.9), ...) 16 | 17 | \method{as.TBRPlotData}{TBRROASAnalysisFit}(obj, panels = "cumulative", 18 | periods = "prediction", quantiles = c(0.1, 0.9), ...) 19 | } 20 | \arguments{ 21 | \item{obj}{an object to coerce.} 22 | 23 | \item{panels}{(vector of strings or NULL) names of the panels to be plotted. 24 | By default, all available panels.} 25 | 26 | \item{periods}{(vector of strings or NULL) names of the periods to show. By 27 | default, all default periods.} 28 | 29 | \item{quantiles}{(real vector of length 2) lower and upper quantiles of the 30 | credible interval to show.} 31 | 32 | \item{...}{further arguments passed to the methods.} 33 | } 34 | \value{ 35 | A TBRPlotData object. 36 | } 37 | \description{ 38 | Coerces an object to a TBRPlotData object. 39 | } 40 | 41 | -------------------------------------------------------------------------------- /man/as.matrix.GeoTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_matrix.R 5 | \name{as.matrix.GeoTimeseries} 6 | \alias{as.matrix.GeoTimeseries} 7 | \title{Coerces a response metric of a GeoTimeseries to a matrix representation 8 | with geos in rows, dates in columns.} 9 | \usage{ 10 | \method{as.matrix}{GeoTimeseries}(x, response, ...) 11 | } 12 | \arguments{ 13 | \item{x}{a GeoTimeseries object.} 14 | 15 | \item{response}{(string) name of the response metric to use.} 16 | 17 | \item{...}{ignored.} 18 | } 19 | \value{ 20 | A numeric matrix of the response metric, geos in rows, dates in 21 | columns. 22 | } 23 | \description{ 24 | Coerces a response metric of a GeoTimeseries to a matrix representation 25 | with geos in rows, dates in columns. 26 | } 27 | 28 | -------------------------------------------------------------------------------- /man/as.matrix.TBRQuantiles.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/as_matrix.R 5 | \name{as.matrix.TBRQuantiles} 6 | \alias{as.matrix.TBRQuantiles} 7 | \title{Extracts the real-valued matrix of quantiles from a TBRQuantiles object.} 8 | \usage{ 9 | \method{as.matrix}{TBRQuantiles}(x, ...) 10 | } 11 | \arguments{ 12 | \item{x}{a TBRQuantiles object.} 13 | 14 | \item{...}{ignored.} 15 | } 16 | \value{ 17 | A real-valued matrix of the quantiles. The column names are the 18 | same as those in the TBRQuantiles object. 19 | } 20 | \description{ 21 | Extracts the real-valued matrix of quantiles from a TBRQuantiles object. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/coef.GBRROASAnalysisFitGbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/gbrroasanalysisfit_gbr1.R 5 | \name{coef.GBRROASAnalysisFitGbr1} 6 | \alias{coef.GBRROASAnalysisFitGbr1} 7 | \title{Returns the model coefficients.} 8 | \usage{ 9 | \method{coef}{GBRROASAnalysisFitGbr1}(object, ...) 10 | } 11 | \arguments{ 12 | \item{object}{a GBRROASAnalysisFitGbr1 object.} 13 | 14 | \item{...}{ignored.} 15 | } 16 | \value{ 17 | A named numeric vector with the model coefficients from the GBR 18 | analysis. 19 | } 20 | \description{ 21 | Returns the model coefficients. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/confint.GBRROASAnalysisFitGbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/gbrroasanalysisfit_gbr1.R 5 | \name{confint.GBRROASAnalysisFitGbr1} 6 | \alias{confint.GBRROASAnalysisFitGbr1} 7 | \title{Returns the confidence intervals associated with the model parameters.} 8 | \usage{ 9 | \method{confint}{GBRROASAnalysisFitGbr1}(object, parm = "incr.cost", 10 | level = 0.95, ...) 11 | } 12 | \arguments{ 13 | \item{object}{a GBRROASAnalysisFitGbr1 object.} 14 | 15 | \item{parm}{(character vector) a specification of which parameters are to be 16 | given confidence intervals, either a vector of numbers or a vector of 17 | names.} 18 | 19 | \item{level}{(number between 0 and 1) the confidence level required.} 20 | 21 | \item{...}{ignored.} 22 | } 23 | \value{ 24 | A matrix with the confidence intervals from the 'confint.lm' 25 | method. 26 | } 27 | \description{ 28 | Returns the confidence intervals associated with the model parameters. 29 | } 30 | 31 | -------------------------------------------------------------------------------- /man/cumsum.PosteriorSimulations.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateposterior.R 5 | \name{cumsum.PosteriorSimulations} 6 | \alias{cumsum.PosteriorSimulations} 7 | \title{Returns simulations of the posterior cumulative joint distribution.} 8 | \usage{ 9 | \method{cumsum}{PosteriorSimulations}(x) 10 | } 11 | \arguments{ 12 | \item{x}{a PosteriorSimulations object.} 13 | } 14 | \value{ 15 | A PosteriorSimulations object, with the cumulative sums in the 16 | columns. 17 | } 18 | \description{ 19 | Returns simulations of the posterior cumulative joint distribution. 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/doroasanalysis.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/doroasanalysis.R 5 | \name{DoROASAnalysis} 6 | \alias{DoROASAnalysis} 7 | \title{Performs a ROAS analysis using the given model.} 8 | \usage{ 9 | DoROASAnalysis(obj, model, ...) 10 | } 11 | \arguments{ 12 | \item{obj}{an object.} 13 | 14 | \item{model}{(string) id of the model to use. Available models are 'gbr1', 15 | 'tbr1'.} 16 | 17 | \item{...}{further arguments passed to or from other models.} 18 | } 19 | \value{ 20 | A GBRROASAnalysisFit (for 'gbr1') or a TBRROASAnalysisFit object 21 | (for 'tbr1'). 22 | } 23 | \description{ 24 | Performs a ROAS analysis using the given model. 25 | } 26 | \note{ 27 | Dispatches the right method for the given model type. 28 | } 29 | \seealso{ 30 | \code{\link{DoGBRROASAnalysis}}, \code{\link{DoTBRROASAnalysis}}. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/gbrroasanalysisdata.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/gbrroasanalysisdata.R 5 | \name{GBRROASAnalysisData} 6 | \alias{GBRROASAnalysisData} 7 | \title{Constructs a GBRROASAnalysisData object.} 8 | \usage{ 9 | GBRROASAnalysisData(x) 10 | } 11 | \arguments{ 12 | \item{x}{a _plain_ 'data.frame' or an object that has to be coercible to a 13 | _plain_ 'data.frame' with the required columns 'geo', which is a 14 | character vector; numeric columns 'resp.pre', 'resp.test', 15 | 'cost.pre', 'cost.test', and a logical (TRUE/FALSE) column 'control'. 16 | Optionally the data frame can have other columns, whose names can not 17 | start with a dot ('.'). No missing values are allowed.} 18 | } 19 | \value{ 20 | A GBRROASAnalysisData object, which is similarly a 'data.frame' 21 | with the same columns as described above. 22 | } 23 | \description{ 24 | Constructs a GBRROASAnalysisData object. 25 | } 26 | \note{ 27 | 'GBRROASAnalysisData' is a 'data.frame', with the required columns, 28 | \itemize{ 29 | \item\code{geo} a 'character'-valued vector of Geo IDs. 30 | \item\code{resp.pre} numeric values of the response metric in the 31 | pre-test period. 32 | \item\code{resp.test} numeric values of the response metric in the test 33 | period. 34 | \item\code{cost.pre} numeric values of the cost metric in the pre-test 35 | period. 36 | \item\code{cost.test} numeric values of the response metric in the test 37 | period. 38 | \item\code{control} : indicator ('TRUE'/'FALSE') of which columns are 39 | in the Control group.} In addition, optionally any other user-definable 40 | columns. The column 'geo' is the primary key; it is guaranteed that no 41 | rows with duplicate geos exist. The object includes the following 42 | fields stored in the attribute 'info': 43 | \itemize{ 44 | \item\code{keys}: names of the primary key columns ('geo'). 45 | \item\code{required}: names of the required columns. 46 | \item\code{metrics}: names of the columns representing metric data. 47 | } 48 | } 49 | 50 | -------------------------------------------------------------------------------- /man/geoassignment-data.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | \name{geoassignment} 4 | \docType{data} 5 | \alias{geoassignment} 6 | \title{Sample Geo Assignment Data} 7 | \usage{data(geoassignment)} 8 | \description{ 9 | A data frame, with columns. 10 | \describe{ 11 | \item{geo:}{Geo ID.} 12 | \item{geo.group:}{Geo Group ID.} 13 | } 14 | } 15 | \source{ 16 | Simulated data. 17 | } 18 | -------------------------------------------------------------------------------- /man/getgeogroup.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/getgeogroup.R 5 | \name{GetGeoGroup} 6 | \alias{GetGeoGroup} 7 | \alias{GetGeoGroup.GeoAssignment} 8 | \alias{GetGeoGroup.GeoExperimentData} 9 | \alias{GetGeoGroup.GeoStrata} 10 | \title{Returns the geo-to-geo group mapping.} 11 | \usage{ 12 | GetGeoGroup(obj, geo = NULL, ...) 13 | 14 | \method{GetGeoGroup}{GeoAssignment}(obj, geo = NULL, ...) 15 | 16 | \method{GetGeoGroup}{GeoExperimentData}(obj, geo = NULL, ...) 17 | 18 | \method{GetGeoGroup}{GeoStrata}(obj, geo = NULL, ...) 19 | } 20 | \arguments{ 21 | \item{obj}{an object with the columns 'geo' and 'geo.group'.} 22 | 23 | \item{geo}{(character vector or NULL) names of geos for which to obtain the 24 | geo group ids.} 25 | 26 | \item{...}{other arguments passed on to the methods.} 27 | } 28 | \value{ 29 | A named integer-valued vector, with the geo names in the names 30 | attribute, mapping geos to geo group ids. 31 | } 32 | \description{ 33 | Returns the geo-to-geo group mapping. 34 | } 35 | \note{ 36 | If a specified 'geo' does not exist in the GeoAssignment object, the 37 | corresponding geo group will be an NA. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/mapgeogroups.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/mapgeogroups.R 5 | \name{MapGeoGroups<-} 6 | \alias{MapGeoGroups} 7 | \alias{MapGeoGroups<-} 8 | \alias{MapGeoGroups<-.GeoAssignment} 9 | \alias{MapGeoGroups<-.GeoExperimentData} 10 | \title{Map or merge geo group numbers into new group ids.} 11 | \usage{ 12 | MapGeoGroups(obj) <- value 13 | 14 | \method{MapGeoGroups}{GeoAssignment}(obj) <- value 15 | 16 | \method{MapGeoGroups}{GeoExperimentData}(obj) <- value 17 | } 18 | \arguments{ 19 | \item{obj}{an object.} 20 | 21 | \item{value}{(integer vector, NA allowed, NULL or empty integer vector 22 | allowed) mapping of old group numbers to new ones. The length must be 23 | exactly equal to the number of old groups in the object. The old 24 | numbers match the positions of the index, and the new ones are the 25 | values in the vector. For example, c(2, 1) maps 1->2 and 2->1; c(3, 26 | 2, 1) maps 1->3, 3->1 and 2 stays unchanged; '1:2' has no effect; 27 | NOTE: c(1, 1) merges groups 1 and 2 into 1! If the 'geo.group' is NA 28 | in the object, its value will be NOT changed. If the data has only 29 | NAs, the only mapping that is allowed is an empty vector, resulting 30 | in no change in the original object. The special value '0' (group of 31 | excluded geos) will also be unchanged.} 32 | } 33 | \value{ 34 | An object identical to 'obj' except the 'geo.groups' column has 35 | (possibly) changed. 36 | } 37 | \description{ 38 | Map or merge geo group numbers into new group ids. 39 | } 40 | \note{ 41 | If all group ids in 'geo.group' are NA, nothing changes as 'NAs' 42 | cannot be mapped. Try 'SetGeoGroup<-' instead, to map specific geos 43 | first into group ids.\cr The group number '0' (group of excluded geos) 44 | remains unchanged. It is not possible to map this group to another. For 45 | that purpose, map geos explicitly to desired groups using the 46 | replacement method 'SetGeoGroup<-'.\cr It is however possible to 47 | exclude a complete group by mapping it to 0 by including 0 in the map, 48 | for example c(1, 2, 0) maps group 3 to 0, leaving group numbers 1 and 2 49 | unchanged. 50 | } 51 | \seealso{ 52 | \code{\link{SetGeoGroup<-}}. 53 | } 54 | 55 | -------------------------------------------------------------------------------- /man/merge.GeoExperimentData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/merge_methods.R 5 | \name{merge.GeoExperimentData} 6 | \alias{merge.GeoExperimentData} 7 | \title{Merges two GeoExperimentData objects.} 8 | \usage{ 9 | \method{merge}{GeoExperimentData}(x, y, ...) 10 | } 11 | \arguments{ 12 | \item{x}{a GeoExperimentData object.} 13 | 14 | \item{y}{a GeoExperimentData object.} 15 | 16 | \item{...}{ignored.} 17 | } 18 | \value{ 19 | A GeoExperimentData object. 20 | } 21 | \description{ 22 | Merges two GeoExperimentData objects. 23 | } 24 | \note{ 25 | The object created is a GeoExperimentData that includes all the 26 | columns of x, and all the columns of y that were not in x. Columns of y 27 | that have the same name as columns of x are ignored and a warning is 28 | issued whenever y and x share some column name(s). The merging is done 29 | by kDate, kGeo, kPeriod, kGeoGroup, kAssignment. 30 | } 31 | 32 | -------------------------------------------------------------------------------- /man/merge.GeoTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/merge_methods.R 5 | \name{merge.GeoTimeseries} 6 | \alias{merge.GeoTimeseries} 7 | \title{Merges two GeoTimeseries objects.} 8 | \usage{ 9 | \method{merge}{GeoTimeseries}(x, y, ...) 10 | } 11 | \arguments{ 12 | \item{x}{a GeoTimeseries object.} 13 | 14 | \item{y}{a GeoTimeseries object.} 15 | 16 | \item{...}{ignored.} 17 | } 18 | \value{ 19 | A GeoTimeseries object. 20 | } 21 | \description{ 22 | Merges two GeoTimeseries objects. 23 | } 24 | \note{ 25 | The object created is a GeoTimeseries that includes all the columns 26 | of x, and all the columns of y that were not in x. Columns of y that 27 | have the same name as columns of x are ignored and a warning is issued 28 | whenever y and x share some column name(s). The merging is done by 29 | kDate, kGeo. 30 | } 31 | 32 | -------------------------------------------------------------------------------- /man/plot.GeoTimeseries.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/plot_methods.R 5 | \name{plot.GeoTimeseries} 6 | \alias{plot.GeoTimeseries} 7 | \title{Generate a (gg)plot of a GeoTimeseries object.} 8 | \usage{ 9 | \method{plot}{GeoTimeseries}(x, y = NULL, by = NULL, subset = NULL, 10 | aggregate = FALSE, title = y, log.scale = FALSE, legend = TRUE, ...) 11 | } 12 | \arguments{ 13 | \item{x}{a GeoTimeseries object.} 14 | 15 | \item{y}{(string) name of the metric to plot. If omitted, plots the first 16 | metric in the object by default.} 17 | 18 | \item{by}{(string) group by which column? Default is 'geo'.} 19 | 20 | \item{subset}{(vector) subset of the items in column 'by' to use.} 21 | 22 | \item{aggregate}{(flag) aggregate over?} 23 | 24 | \item{title}{(string) a title string. By default, the name of the metric to 25 | plot.} 26 | 27 | \item{log.scale}{(flag) plot y-axis on log scale?} 28 | 29 | \item{legend}{(flag) plot the legend?} 30 | 31 | \item{...}{ignored.} 32 | } 33 | \value{ 34 | A ggplot object. 35 | } 36 | \description{ 37 | Generate a (gg)plot of a GeoTimeseries object. 38 | } 39 | \note{ 40 | Sets the lower y-axis limit to zero if all 'y' values are nonnegative 41 | and log.scale=\code{FALSE}. 42 | } 43 | 44 | -------------------------------------------------------------------------------- /man/plot.Geos.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/plot_methods.R 5 | \name{plot.Geos} 6 | \alias{plot.Geos} 7 | \title{Generate a (gg)plot of a Geos object.} 8 | \usage{ 9 | \method{plot}{Geos}(x, y = NULL, geom = c("bar", "point", "rect"), 10 | sort.by = y, log.scale = FALSE, ...) 11 | } 12 | \arguments{ 13 | \item{x}{a Geos object.} 14 | 15 | \item{y}{(string) name of the metric to plot. If omitted, plots the volume 16 | defined in the object by default.} 17 | 18 | \item{geom}{(string) short name of the geom ggplot2 method to be used.} 19 | 20 | \item{sort.by}{(string) name of the column to sort the plot by, defaults to 21 | y. If the column contains string, alphabetical order will be used 22 | unless every string can be coerced to an integer in which case 23 | numerical (ascending) order will be used. If the column contains 24 | numerical values, numerical (descending) order will be used.} 25 | 26 | \item{log.scale}{(flag) plot y-axis on log scale?} 27 | 28 | \item{...}{ignored.} 29 | } 30 | \value{ 31 | A ggplot object. 32 | } 33 | \description{ 34 | Generate a (gg)plot of a Geos object. 35 | } 36 | 37 | -------------------------------------------------------------------------------- /man/plot.TBRAnalysisFitTbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/plot_tbrplotdata.R 5 | \name{plot.TBRAnalysisFitTbr1} 6 | \alias{plot.TBRAnalysisFitTbr1} 7 | \title{Creates a graph of the TBR analysis fit.} 8 | \usage{ 9 | \method{plot}{TBRAnalysisFitTbr1}(x, y, panels = GetTBRPlotPanelNames(), 10 | periods = c("pretest", "prediction"), quantiles = c(0.1, 0.9), 11 | highlight.weeks = TRUE, date.format = "\%Y-\%m-\%d", ...) 12 | } 13 | \arguments{ 14 | \item{x}{a TBRAnalysisFitTbr1 object.} 15 | 16 | \item{y}{ignored.} 17 | 18 | \item{panels}{(vector of strings) names of the panels to be plotted.} 19 | 20 | \item{periods}{(vector of strings) names of the periods to show.} 21 | 22 | \item{quantiles}{(real vector of length 2) lower and upper quantiles of the 23 | credible interval to show.} 24 | 25 | \item{highlight.weeks}{(flag), alternate background shading to highlight 26 | weeks?} 27 | 28 | \item{date.format}{(string) date format.} 29 | 30 | \item{...}{further arguments passed to methods 'as.TBRPlotData' and 31 | 'plot.TBRPlotData'.} 32 | } 33 | \value{ 34 | A ggplot2 object. 35 | } 36 | \description{ 37 | Creates a graph of the TBR analysis fit. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/plot.TBRPlotData.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/plot_tbrplotdata.R 5 | \name{plot.TBRPlotData} 6 | \alias{plot.TBRPlotData} 7 | \title{Creates a graph of the TBRPlotData object.} 8 | \usage{ 9 | \method{plot}{TBRPlotData}(x, y, highlight.weeks = TRUE, 10 | date.format = "\%Y-\%m-\%d", ...) 11 | } 12 | \arguments{ 13 | \item{x}{a TBRPlotData object.} 14 | 15 | \item{y}{ignored.} 16 | 17 | \item{highlight.weeks}{(flag), alternate background shading to highlight 18 | weeks?} 19 | 20 | \item{date.format}{(string) date format.} 21 | 22 | \item{...}{ignored.} 23 | } 24 | \value{ 25 | A ggplot2 object. 26 | } 27 | \description{ 28 | Creates a graph of the TBRPlotData object. 29 | } 30 | 31 | -------------------------------------------------------------------------------- /man/plot.TBRROASAnalysisFit.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/plot_tbrplotdata.R 5 | \name{plot.TBRROASAnalysisFit} 6 | \alias{plot.TBRROASAnalysisFit} 7 | \title{Creates a graph of the TBR ROAS analysis fit.} 8 | \usage{ 9 | \method{plot}{TBRROASAnalysisFit}(x, y, panels = "cumulative", 10 | periods = "prediction", quantiles = c(0.1, 0.9), highlight.weeks = TRUE, 11 | date.format = "\%Y-\%m-\%d", ...) 12 | } 13 | \arguments{ 14 | \item{x}{a TBRROASAnalysisFit object.} 15 | 16 | \item{y}{ignored.} 17 | 18 | \item{panels}{(vector of strings) names of the panels to be plotted.} 19 | 20 | \item{periods}{(vector of strings) names of the periods to show.} 21 | 22 | \item{quantiles}{(real vector of length 2) lower and upper quantiles of the 23 | credible interval to show.} 24 | 25 | \item{highlight.weeks}{(flag), alternate background shading to highlight 26 | weeks?} 27 | 28 | \item{date.format}{(string) date format.} 29 | 30 | \item{...}{further arguments passed to methods \code{\link{as.TBRPlotData}} and 31 | \code{\link{plot.TBRPlotData}}.} 32 | } 33 | \value{ 34 | A ggplot2 object. 35 | } 36 | \description{ 37 | Creates a graph of the TBR ROAS analysis fit. 38 | } 39 | 40 | -------------------------------------------------------------------------------- /man/print.GBRROASAnalysisFitGbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/gbrroasanalysisfit_gbr1.R 5 | \name{print.GBRROASAnalysisFitGbr1} 6 | \alias{print.GBRROASAnalysisFitGbr1} 7 | \title{Shows a summary of GBR analysis results.} 8 | \usage{ 9 | \method{print}{GBRROASAnalysisFitGbr1}(x, ...) 10 | } 11 | \arguments{ 12 | \item{x}{a GBRROASAnalysisFitGbr1 object.} 13 | 14 | \item{...}{ignored.} 15 | } 16 | \value{ 17 | The object itself, invisibly. As a side effect, prints the default 18 | summary of 'x' on the console. 19 | } 20 | \description{ 21 | Shows a summary of GBR analysis results. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/print.ROASPreanalysisFit.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateroasanalysis.R 5 | \name{print.ROASPreanalysisFit} 6 | \alias{print.ROASPreanalysisFit} 7 | \title{Prints a summary of the \code{ROASPreanalysisFit} method.} 8 | \usage{ 9 | \method{print}{ROASPreanalysisFit}(x, ...) 10 | } 11 | \arguments{ 12 | \item{x}{a \code{ROASPreanalysisFit} object.} 13 | 14 | \item{...}{arguments passed to the 'summary' method.} 15 | } 16 | \value{ 17 | Prints the summary of \code{x} and returns the summary of \code{x} 18 | invisibly. 19 | } 20 | \description{ 21 | Prints a summary of the \code{ROASPreanalysisFit} method. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/print.TBRROASAnalysisFit.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/dotbrroasanalysis.R 5 | \name{print.TBRROASAnalysisFit} 6 | \alias{print.TBRROASAnalysisFit} 7 | \title{Shows a summary of TBR analysis results.} 8 | \usage{ 9 | \method{print}{TBRROASAnalysisFit}(x, ...) 10 | } 11 | \arguments{ 12 | \item{x}{a TBRROASAnalysisFit object.} 13 | 14 | \item{...}{ignored.} 15 | } 16 | \value{ 17 | The object itself, invisibly. As a side effect, prints the default 18 | summary of 'x' on the console. 19 | } 20 | \description{ 21 | Shows a summary of TBR analysis results. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/quantile.PosteriorSimulations.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/simulateposterior.R 5 | \name{quantile.PosteriorSimulations} 6 | \alias{quantile.PosteriorSimulations} 7 | \title{Compute the quantiles for the posterior simulations.} 8 | \usage{ 9 | \method{quantile}{PosteriorSimulations}(x, probs = c(0.05, 0.1, 0.5, 0.9, 10 | 0.95), names = TRUE, ...) 11 | } 12 | \arguments{ 13 | \item{x}{a PosteriorSimulations object.} 14 | 15 | \item{probs}{(numeric vector) of probabilities.} 16 | 17 | \item{names}{(flag) if TRUE, the result has a 'names' attribute.} 18 | 19 | \item{...}{possibly other arguments passed on to 'quantile'.} 20 | } 21 | \value{ 22 | A matrix with n rows and m columns, where n = rows in 'x' and m = 23 | length of 'probs'. 24 | } 25 | \description{ 26 | Compute the quantiles for the posterior simulations. 27 | } 28 | 29 | -------------------------------------------------------------------------------- /man/quantile.TBRAnalysisFitTbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/quantile.R 5 | \name{quantile.TBRAnalysisFitTbr1} 6 | \alias{quantile.TBRAnalysisFitTbr1} 7 | \title{Computes quantiles of the cumulative, pointwise, or the counterfactual 8 | (posterior) distribution of the causal lift, from the beginning of 9 | pretest to the end of posttest.} 10 | \usage{ 11 | \method{quantile}{TBRAnalysisFitTbr1}(x, probs = c(0.1, 0.5, 0.9), 12 | distribution = c("cumulative", "pointwise", "counterfactual"), ...) 13 | } 14 | \arguments{ 15 | \item{x}{a TBRAnalysisFitTbr1 object.} 16 | 17 | \item{probs}{(numeric vector, each >= 0 and <= 1) quantiles to calculate.} 18 | 19 | \item{distribution}{(string) either 'cumulative' or 'pointwise' or 20 | 'counterfactual'.} 21 | 22 | \item{...}{ignored.} 23 | } 24 | \value{ 25 | A TBRQuantiles object, which is a data frame with each row 26 | corresponding to a day in the pretest and the prediction period, with 27 | columns 'date', 'test', and the columns for the quantiles. 28 | } 29 | \description{ 30 | Computes quantiles of the cumulative, pointwise, or the counterfactual 31 | (posterior) distribution of the causal lift, from the beginning of 32 | pretest to the end of posttest. 33 | } 34 | 35 | -------------------------------------------------------------------------------- /man/quantile.TBRROASAnalysisFit.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/quantile.R 5 | \name{quantile.TBRROASAnalysisFit} 6 | \alias{quantile.TBRROASAnalysisFit} 7 | \title{Computes quantiles of the cumulative or pointwise distribution of the 8 | incremental ROAS, for each of the days in the pretest and the 9 | prediction period.} 10 | \usage{ 11 | \method{quantile}{TBRROASAnalysisFit}(x, probs = c(0.1, 0.5, 0.9), 12 | distribution = c("cumulative", "pointwise"), ...) 13 | } 14 | \arguments{ 15 | \item{x}{a TBRROASAnalysisFit object.} 16 | 17 | \item{probs}{(numeric vector, each >= 0 and <= 1) quantiles to calculate.} 18 | 19 | \item{distribution}{(string) either 'cumulative' or 'pointwise'.} 20 | 21 | \item{...}{ignored.} 22 | } 23 | \value{ 24 | A TBRQuantiles object, which is a data frame with each row 25 | corresponding to a day in the pretest and the prediction period, with 26 | columns 'date', 'test', and the columns for the quantiles. 27 | } 28 | \description{ 29 | Computes quantiles of the cumulative or pointwise distribution of the 30 | incremental ROAS, for each of the days in the pretest and the 31 | prediction period. 32 | } 33 | \note{ 34 | The pretest period is included solely for the purpose of obtaining 35 | objects of conforming size from both quantile methods (that of 36 | TBRAnalysisFitTbr1 and of this one). 37 | } 38 | 39 | -------------------------------------------------------------------------------- /man/round.ROASAnalysisResults.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/roasanalysisresults.R 5 | \name{round.ROASAnalysisResults} 6 | \alias{round.ROASAnalysisResults} 7 | \title{Rounds the estimates to a given number of decimal places.} 8 | \usage{ 9 | \method{round}{ROASAnalysisResults}(x, digits = 1) 10 | } 11 | \arguments{ 12 | \item{x}{a \code{ROASAnalysisResults} object.} 13 | 14 | \item{digits}{number of digital places to round to.} 15 | } 16 | \value{ 17 | A \code{ROASAnalysisResults} object, with estimates appropriately 18 | rounded. 19 | } 20 | \description{ 21 | Rounds the estimates to a given number of decimal places. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/salesandcost-data.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | \name{salesandcost} 4 | \docType{data} 5 | \alias{salesandcost} 6 | \title{Sales and Cost Data} 7 | \usage{data(salesandcost)} 8 | \description{ 9 | A data frame with 9225 rows, with the columns: 10 | \describe{ 11 | \item{date:}{A character string representing a date in the format 12 | MM/DD/YYYY.} 13 | \item{geo:}{Geo id, integer.} 14 | \item{sales:}{Sales for the corresponding geo and day, numeric.} 15 | \item{cost:}{Cost of advertising, numeric.} 16 | } 17 | } 18 | \source{ 19 | Simulated data. 20 | } 21 | -------------------------------------------------------------------------------- /man/setgeogroup.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/setgeogroup.R 5 | \name{SetGeoGroup<-} 6 | \alias{SetGeoGroup} 7 | \alias{SetGeoGroup<-} 8 | \alias{SetGeoGroup<-.GeoAssignment} 9 | \alias{SetGeoGroup<-.GeoExperimentData} 10 | \alias{SetGeoGroup<-.GeoStrata} 11 | \title{Modifies the geo assignment in an object.} 12 | \usage{ 13 | SetGeoGroup(obj) <- value 14 | 15 | \method{SetGeoGroup}{GeoStrata}(obj) <- value 16 | 17 | \method{SetGeoGroup}{GeoAssignment}(obj) <- value 18 | 19 | \method{SetGeoGroup}{GeoExperimentData}(obj) <- value 20 | } 21 | \arguments{ 22 | \item{obj}{an object with the columns 'geo' and 'geo.group'.} 23 | 24 | \item{value}{a GeoAssignment object.} 25 | } 26 | \value{ 27 | The object with the modfied geo-to-geo.group mapping. 28 | } 29 | \description{ 30 | Modifies the geo assignment in an object. 31 | } 32 | \note{ 33 | The \code{\link{GeoExperimentData}} object must contain a valid 34 | \code{\link{GeoAssignment}} object. (Use \code{\link{SetGeoAssignment<-}} to 35 | associate a \code{\link{GeoAssignment}} object to the 36 | \code{\link{GeoExperimentData}} object.) 37 | } 38 | \seealso{ 39 | \code{\link{SetGeoAssignment<-}}, \code{\link{MapGeoGroups<-}}. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/signif.ROASAnalysisResults.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/roasanalysisresults.R 5 | \name{signif.ROASAnalysisResults} 6 | \alias{signif.ROASAnalysisResults} 7 | \title{Rounds the estimates to a given number of significant digits.} 8 | \usage{ 9 | \method{signif}{ROASAnalysisResults}(x, digits = 1) 10 | } 11 | \arguments{ 12 | \item{x}{a \code{ROASAnalysisResults} object.} 13 | 14 | \item{digits}{number of significant digits to round to.} 15 | } 16 | \value{ 17 | A \code{ROASAnalysisResults} object, with estimates appropriately 18 | rounded. 19 | } 20 | \description{ 21 | Rounds the estimates to a given number of significant digits. 22 | } 23 | 24 | -------------------------------------------------------------------------------- /man/summary.GBRROASAnalysisFitGbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/gbrroasanalysisfit_gbr1.R 5 | \name{summary.GBRROASAnalysisFitGbr1} 6 | \alias{summary.GBRROASAnalysisFitGbr1} 7 | \title{Returns a concise summary of the ROAS estimate and confidence interval and 8 | the total incremental cost and incremental response.} 9 | \usage{ 10 | \method{summary}{GBRROASAnalysisFitGbr1}(object, level = 0.9, 11 | interval.type = c("one-sided", "two-sided"), threshold = 0, ...) 12 | } 13 | \arguments{ 14 | \item{object}{a GBRROASAnalysisFitGbr1 object.} 15 | 16 | \item{level}{(number between 0 and 1) confidence level.} 17 | 18 | \item{interval.type}{(string) 'one-sided', or 'two-sided' (interval).} 19 | 20 | \item{threshold}{(numeric vector) threshold(s) for the right-tail posterior 21 | probabilities of beta2.} 22 | 23 | \item{...}{ignored.} 24 | } 25 | \value{ 26 | A ROASAnalysisResults object. 27 | } 28 | \description{ 29 | Returns a concise summary of the ROAS estimate and confidence interval and 30 | the total incremental cost and incremental response. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/summary.ROASPreanalysisFit.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/doroaspreanalysis.R 5 | \name{summary.ROASPreanalysisFit} 6 | \alias{summary.ROASPreanalysisFit} 7 | \title{Computes a summary of the predicted ROAS estimate and associated 8 | incremental cost.} 9 | \usage{ 10 | \method{summary}{ROASPreanalysisFit}(object, level = 0.9, 11 | interval.type = c("one-sided", "two-sided"), precision = 1, 12 | cost = NA_real_, ...) 13 | } 14 | \arguments{ 15 | \item{object}{a \code{ROASPreanalysisFit} object.} 16 | 17 | \item{level}{(number between 0 and 1) confidence level.} 18 | 19 | \item{interval.type}{(string) 'one-sided', 'two-sided'.} 20 | 21 | \item{precision}{(number) target precision of the estimate; the distance 22 | between the lower bound of the confidence interval and the point 23 | estimate. Note: if \code{cost} is given, this will be ignored and the CI 24 | half-width will be computed based on \code{cost}.} 25 | 26 | \item{cost}{(number) cost difference (ad spend difference); if missing, 27 | will be computed based on \code{precision}.} 28 | 29 | \item{...}{ignored.} 30 | } 31 | \value{ 32 | A ROASPreanalysisResults object. 33 | } 34 | \description{ 35 | Computes a summary of the predicted ROAS estimate and associated 36 | incremental cost. 37 | } 38 | 39 | -------------------------------------------------------------------------------- /man/summary.TBRAnalysisFitTbr1.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/summary_tbranalysisfit_tbr1.R 5 | \name{summary.TBRAnalysisFitTbr1} 6 | \alias{summary.TBRAnalysisFitTbr1} 7 | \title{Returns a concise summary of the incremental response estimate and its 8 | confidence interval for the model 'tbr1'.} 9 | \usage{ 10 | \method{summary}{TBRAnalysisFitTbr1}(object, level = 0.9, 11 | interval.type = c("one-sided", "two-sided"), threshold = 0, ...) 12 | } 13 | \arguments{ 14 | \item{object}{a \code{TBRAnalysisFit} object.} 15 | 16 | \item{level}{(number between 0 and 1) confidence level.} 17 | 18 | \item{interval.type}{(string) 'one-sided', 'two-sided' (interval).} 19 | 20 | \item{threshold}{(numeric vector) threshold(s) for the right-tail posterior.} 21 | 22 | \item{...}{ignored.} 23 | } 24 | \value{ 25 | A \code{TBRAnalysisResults} object. 26 | } 27 | \description{ 28 | Returns a concise summary of the incremental response estimate and its 29 | confidence interval for the model 'tbr1'. 30 | } 31 | 32 | -------------------------------------------------------------------------------- /man/summary.TBRROASAnalysisFit.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/dotbrroasanalysis.R 5 | \name{summary.TBRROASAnalysisFit} 6 | \alias{summary.TBRROASAnalysisFit} 7 | \title{Returns a concise summary of the incremental response estimate and its 8 | confidence interval for a TBR ROAS analysis.} 9 | \usage{ 10 | \method{summary}{TBRROASAnalysisFit}(object, level = 0.9, 11 | interval.type = c("one-sided", "two-sided"), threshold = 0, ...) 12 | } 13 | \arguments{ 14 | \item{object}{a TBRROASAnalysisFit object.} 15 | 16 | \item{level}{(number between 0 and 1) confidence level.} 17 | 18 | \item{interval.type}{(string) 'one-sided', 'two-sided' (interval).} 19 | 20 | \item{threshold}{(numeric vector) threshold(s) for the right-tail posterior 21 | probabilities of the total cumulative iROAS.} 22 | 23 | \item{...}{ignored.} 24 | } 25 | \value{ 26 | A ROASAnalysisResults object. 27 | } 28 | \description{ 29 | Returns a concise summary of the incremental response estimate and its 30 | confidence interval for a TBR ROAS analysis. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/utils_check_objects.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_check_objects.R 5 | \name{assert_tests} 6 | \alias{assert_tests} 7 | \alias{is.character.vector} 8 | \alias{is.empty.string} 9 | \alias{is.inf} 10 | \alias{is.integer.valued} 11 | \alias{is.logical.vector} 12 | \alias{is.named.list} 13 | \alias{is.nonempty.string} 14 | \alias{is.numeric.vector} 15 | \alias{is.plain.list} 16 | \alias{is.real.number} 17 | \alias{is.vector.of.nonempty.strings} 18 | \title{Various tests.} 19 | \usage{ 20 | is.character.vector(x) 21 | 22 | is.nonempty.string(x) 23 | 24 | is.vector.of.nonempty.strings(x) 25 | 26 | is.plain.list(x) 27 | 28 | is.named.list(x) 29 | 30 | is.integer.valued(x) 31 | 32 | is.logical.vector(x) 33 | 34 | is.empty.string(x) 35 | 36 | \method{is.numeric}{vector}(x) 37 | 38 | is.real.number(x) 39 | 40 | is.inf(x) 41 | } 42 | \arguments{ 43 | \item{x}{object to test.} 44 | } 45 | \value{ 46 | These are typically used in statements with \code{assert_that(...)}. 47 | Each function returns either \code{TRUE} or \code{FALSE}; some functions 48 | may return \code{NA}. 49 | 50 | #' \itemize{ 51 | \item{\code{is.character.vector}}: \code{TRUE} if and only if \code{x} is a 52 | character vector of positive length, otherwise \code{FALSE}. 53 | \item{\code{is.nonempty.string}}: \code{TRUE} if and only if \code{x} is a 54 | character vector of length 1 with a component that is nonempty and non-NA, 55 | otherwise \code{FALSE}. 56 | \item{\code{is.vector.of.nonempty.strings}}: \code{TRUE} if and only if 57 | \code{x} is a vector of nonempty strings none of which is an NA, otherwise 58 | \code{FALSE}. Empty vectors yield \code{FALSE}. 59 | \item{\code{is.plain.list}}: \code{TRUE} if and only if \code{x} is a list 60 | but does not have the object class set. Otherwise \code{FALSE}. 61 | \item{\code{is.plain.list}}: \code{TRUE} if and only if \code{x} is a list 62 | but does not have the object class set. Otherwise \code{FALSE}. 63 | \item{\code{is.named.list}}: \code{TRUE} if and only if \code{x} is a plain 64 | list with a names attribute with non-empty strings for names, otherwise 65 | \code{FALSE}. 66 | \item{\code{is.integer.valued}}: \code{TRUE} if and only if \code{x} is 67 | either of type integer, or numeric and all components coercible to 68 | integer, otherwise \code{FALSE}. NAs are allowed. 69 | \item{\code{is.logical.vector}}: \code{TRUE} if and only if \code{x} is a 70 | logical vector of positive length, otherwise \code{FALSE}. 71 | \item{\code{is.empty.string}}: A logical vector of the same length as 72 | \code{x}, #' with '\code{TRUE}' if and only if the string is empty, 73 | NA if the string is NA, otherwise \code{FALSE}. If \code{x} is not 74 | character, throws an error. NA maps to NA. 75 | \item{\code{is.numeric.vector}}: \code{TRUE} if and only if \code{x} is a 76 | numeric vector of positive length, otherwise \code{FALSE}. 77 | \item{\code{is.real.number}}: \code{TRUE} if and only if \code{x} is a 78 | numeric scalar, not an NA, and not infinite, otherwise \code{FALSE}. 79 | \item{\code{is.inf}}: \code{TRUE} if and only if \code{x} is \code{Inf} or 80 | \code{-Inf}. 81 | } 82 | } 83 | \description{ 84 | Various tests. 85 | } 86 | 87 | -------------------------------------------------------------------------------- /man/utils_check_vectors.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_check_vectors.R 5 | \name{is.treatment.assignment} 6 | \alias{is.geo.group.number} 7 | \alias{is.period.number} 8 | \alias{is.treatment.assignment} 9 | \title{Tests each component of the vector 'x' for valid values.} 10 | \usage{ 11 | is.treatment.assignment(x) 12 | 13 | is.geo.group.number(x) 14 | 15 | is.period.number(x) 16 | } 17 | \arguments{ 18 | \item{x}{object to test.} 19 | } 20 | \value{ 21 | A logical vector of the same length as 'x', with 'TRUE' if and only 22 | if the string is a valid value, NA if the string is NA, otherwise FALSE. If 23 | 'x' is not character, throws an error. 24 | } 25 | \description{ 26 | Tests each component of the vector 'x' for valid values. 27 | } 28 | \note{ 29 | NA in a component returns NA. These are supposed to be tested 30 | separately. 31 | 32 | \itemize{ 33 | \item{\code{is.treatment.assignment}} The valid treatment assignment 34 | symbols can be found in the constant \code{kTreatmentAssignment}. 35 | Note however that the treatment assignment symbols are not used 36 | in the current version of the package (included for possible future 37 | use). 38 | \item{\code{is.geo.group.number}} The value '0' has a special meaning: 39 | it indicates a geo that has been omitted from the experiment. 40 | \item{\code{is.period.number}} Negative period numbers are allowed. 41 | } 42 | } 43 | 44 | -------------------------------------------------------------------------------- /man/utils_time.Rd: -------------------------------------------------------------------------------- 1 | % Copyright (C) 2017 Google, Inc. 2 | 3 | % Generated by roxygen2: do not edit by hand 4 | % Please edit documentation in R/utils_time.R 5 | \name{date_utilities} 6 | \alias{.GetLastDayOfMonth} 7 | \alias{.GetLastDayOfWeek} 8 | \alias{.GetWeekIndex} 9 | \alias{.GetWeekNumbers} 10 | \alias{.GetWeekdays} 11 | \alias{date_utilities} 12 | \title{Utilities to manipulate Date objects.} 13 | \usage{ 14 | .GetWeekdays(x) 15 | 16 | .GetWeekIndex(x) 17 | 18 | .GetWeekNumbers(x) 19 | 20 | .GetLastDayOfWeek(x, last.day = 7L) 21 | 22 | .GetLastDayOfMonth(x) 23 | } 24 | \arguments{ 25 | \item{x}{a Date object (vector).} 26 | 27 | \item{last.day}{(integer) number of the day to translate the date to. Monday 28 | is 1, Sunday is 7.} 29 | } 30 | \value{ 31 | \itemize{ 32 | \item{\code{.GetWeekdays}}: Indicator for weekday, given a 33 | date: an integer vector of the same length as \code{x}, indicating 34 | the number of the weekday, Monday=1, Tuesday=2, ..., Sunday=7. 35 | \item{\code{.GetWeekIndex}}: An indicator for an 'absolute' week number: 36 | an integer vector of the same length as \code{x}, indicating the week 37 | number, composed of the 4-digit year and the number of the week within 38 | the year. 39 | \item{\code{.GetWeekNumbers}}: Indicators for week numbers within the 40 | year: an integer vector of the same length as 'x', indicating the week 41 | number, 0 .. 53. 42 | \item{code{.GetLastDayOfWeek}}: Translates the given date(s) to the date 43 | of the last day of the corresponding week: a date object of the same 44 | length as 'x', with the corresponding dates shifted to the next (future) 45 | day given by 'last.day'. 46 | \item{\code{.GetLastDayOfMonth}}: Translates the given date(s) to the last 47 | day of the month of the corresponding month. A date object of the same 48 | length as 'x', with the corresponding dates shifted to the last day of 49 | the month. 50 | } 51 | } 52 | \description{ 53 | Utilities to manipulate Date objects. 54 | } 55 | \note{ 56 | As a convention, a week starts on Monday and ends on Sunday. 57 | } 58 | 59 | -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | library(testthat) 16 | library(GeoexperimentsResearch) 17 | 18 | test_check("GeoexperimentsResearch") 19 | -------------------------------------------------------------------------------- /tests/testthat/test_002_utils_messaging.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("Set/GetMessageContextString") 16 | 17 | test_that("by default, message context string is ''", { 18 | options(geoexperiments=NULL) 19 | expect_identical(GetMessageContextString(), "") 20 | options(geoexperiments=list()) 21 | expect_identical(GetMessageContextString(), "") 22 | }) 23 | 24 | test_that("setting the message context strings works like a fifo stack", { 25 | options(geoexperiments=list()) 26 | string <- c("Foo", "Bar") 27 | SetMessageContextString(string[1L]) 28 | expect_identical(GetMessageContextString(), string[1L]) 29 | SetMessageContextString(string[2L]) 30 | string2 <- paste(string, collapse=">") 31 | expect_identical(GetMessageContextString(), string2) 32 | SetMessageContextString() 33 | expect_identical(GetMessageContextString(), string[1L]) 34 | SetMessageContextString() 35 | expect_identical(GetMessageContextString(), "") 36 | }) 37 | 38 | test_that("subsequent resetting of message context strings have no effect", { 39 | options(geoexperiments=list()) 40 | string <- "Foo" 41 | SetMessageContextString(string) 42 | expect_identical(GetMessageContextString(), string) 43 | SetMessageContextString() 44 | expect_identical(GetMessageContextString(), "") 45 | SetMessageContextString() 46 | expect_identical(GetMessageContextString(), "") 47 | }) 48 | 49 | test_that("Message() shows the context string", { 50 | options(geoexperiments=list()) 51 | expect_identical(Message("msg"), "msg") 52 | string <- "Foo" 53 | SetMessageContextString(string) 54 | expect_identical(Message("msg"), 55 | paste0(string, ": msg")) 56 | SetMessageContextString() 57 | expect_identical(Message("msg"), "msg") 58 | }) 59 | 60 | test_that("Messagef() works like sprintf", { 61 | options(geoexperiments=list()) 62 | expect_identical(Messagef("n=%d.", 314L), "n=314.") 63 | string <- "Foo" 64 | SetMessageContextString(string) 65 | expect_identical(Messagef("n=%d.", 314L), 66 | paste0(string, ": n=314.")) 67 | SetMessageContextString() 68 | expect_identical(Messagef("n=%d.", 314L), "n=314.") 69 | }) 70 | -------------------------------------------------------------------------------- /tests/testthat/test_004_utils_class.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("SetInfo") 16 | 17 | test_that("SetInfo rejects 'obj' that are not objects", { 18 | info <- list(a=1L, b=2L) 19 | obj <- list(foo=1) 20 | # 'obj' must not be a plain list or other non-object. 21 | expect_error(SetInfo(obj, info=info), 22 | regexp="is\\.object\\(obj\\) is not TRUE") 23 | # 'obj' can be any object. 24 | obj <- as.data.frame(obj) 25 | expect_is(SetInfo(obj, info=info), "data.frame") 26 | }) 27 | 28 | test_that("SetInfo rejects 'info' that are not plain, named lists", { 29 | obj <- data.frame(foo=1) 30 | expect_error(SetInfo(obj, info=data.frame(a=1)), 31 | regexp="'info' is not a named list or an empty list") 32 | expect_error(SetInfo(obj, info=list(1)), 33 | regexp="'info' is not a named list or an empty list") 34 | }) 35 | 36 | test_that("SetInfo changes the 'info' attribute as expected", { 37 | info <- list(a=1L, b=2L) 38 | x <- data.frame(x=1) 39 | obj <- SetInfo(x, info=info) 40 | expect_is(obj, "data.frame") 41 | expect_identical(attr(obj, "info"), info) 42 | info2 <- list(c=3L, d=4L) 43 | obj2 <- SetInfo(obj, info=info2) 44 | expect_identical(attr(obj2, "info"), info2) 45 | }) 46 | 47 | test_that("SetInfo changes key-value pairs of the 'info' attribute", { 48 | x <- data.frame(x=1) 49 | attr(x, "info") <- list(a=1L, b=2L) 50 | obj <- SetInfo(x, a=0L) 51 | expect_identical(attr(obj, "info"), list(a=0L, b=2L)) 52 | obj <- SetInfo(x, a=3L, b=4L) 53 | expect_identical(attr(obj, "info"), list(a=3L, b=4L)) 54 | }) 55 | 56 | test_that("SetInfo creates a new 'info' if it does not exist", { 57 | x <- data.frame(x=1) 58 | obj <- SetInfo(x, a=0L) 59 | expect_identical(attr(obj, "info"), list(a=0L)) 60 | }) 61 | 62 | test_that("SetInfo creates a new key if it does not exist", { 63 | x <- data.frame(x=1) 64 | attr(x, "info") <- list(a=1L, b=2L) 65 | obj <- SetInfo(x, c=3L) 66 | expect_identical(attr(obj, "info"), list(a=1L, b=2L, c=3L)) 67 | }) 68 | 69 | 70 | context("GetInfo") 71 | 72 | test_that("GetInfo retrieves the 'info' attribute if no key is specified", { 73 | info <- list(a=1L, b=2L) 74 | x <- data.frame(x=1) 75 | attr(x, "info") <- info 76 | expect_identical(GetInfo(x), info) 77 | }) 78 | 79 | test_that("GetInfo retrieves the value by key", { 80 | info <- list(a=1L, b=2L) 81 | x <- data.frame(x=1) 82 | attr(x, "info") <- info 83 | expect_identical(GetInfo(x, "a"), 1L) 84 | }) 85 | 86 | test_that("GetInfo throws an error if the key does not exist", { 87 | info <- list(a=1L, b=2L) 88 | x <- data.frame(x=1) 89 | attr(x, "info") <- info 90 | expect_error(GetInfo(x, "c"), 91 | regexp=paste0("Field 'c' does not exist in this object of ", 92 | "class 'data.frame'")) 93 | }) 94 | -------------------------------------------------------------------------------- /tests/testthat/test_007_utils_general.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("RenameColumns") 16 | 17 | d <- dfged2[c(kDate, kGeo, "sales")] 18 | 19 | test_that("if 'map' is not given or is NULL, 'x' is returned unchanged", { 20 | expect_identical(d, RenameColumns(d)) 21 | expect_identical(d, RenameColumns(d, map=NULL)) 22 | expect_identical(d, RenameColumns(d, map=character(0))) 23 | }) 24 | 25 | test_that("errors are thrown if 'x' is not a data frame", { 26 | m <- as.matrix(d) 27 | for (x in list(m, as.list(d), NULL)) { 28 | expect_error(RenameColumns(x), 29 | msg="x is not a data frame") 30 | } 31 | }) 32 | 33 | test_that("errors are thrown if 'map' is not a named character vector", { 34 | for (map in list(NA_character_, "", kDate, c(date=1))) { 35 | expect_error(RenameColumns(d, map=map), 36 | msg="'map' must be a named character vector") 37 | } 38 | }) 39 | 40 | test_that("column name is changed if it is not a duplicate", { 41 | expect_is(x <- RenameColumns(d, map=c(date2=kDate)), "data.frame") 42 | expect_identical(names(x), c("date2", names(d)[2:3])) 43 | # Nothing else has changed: 44 | names(x) <- names(d) 45 | expect_identical(x, d) 46 | }) 47 | 48 | test_that("column names can be swapped", { 49 | expect_identical(c(kGeo, kDate, "sales"), 50 | names(RenameColumns(d, map=c(geo=kDate, date=kGeo)))) 51 | }) 52 | 53 | test_that("an error is thrown if a column name is changed to a duplicate", { 54 | expect_error(RenameColumns(d, map=c(date=kGeo))) 55 | }) 56 | 57 | 58 | context("GetModelIds") 59 | 60 | test_that("the returned object is identical to kModels", { 61 | expect_identical(GetModelIds(), kModels) 62 | }) 63 | -------------------------------------------------------------------------------- /tests/testthat/test_030_methods_aggregate.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("method aggregate.GeoTimeseries / GeoExperimentData") 16 | 17 | obj.gts <- GeoTimeseries(dfged2, metrics=metrics.df2) 18 | obj.ged <- GeoExperimentData(obj.gts) 19 | obj.list <- list(obj.gts, obj.ged) 20 | 21 | # Test for both GeoTimeseries and GeoExperimentData. 22 | for (i in seq_along(obj.list)) { 23 | 24 | obj <- obj.list[[i]] 25 | switch(paste(i), 26 | "1"=context("method aggregate.GeoTimeseries"), 27 | "2"=context("method aggregate.GeoExperimentData"), 28 | stop("cannot happen")) 29 | 30 | test_that("by default, all metrics are aggregated as expected, by geo", { 31 | obj.sub <- aggregate(obj) 32 | expect_false(inherits(obj.sub, "GeoTimeseries")) 33 | dfx <- as.data.frame(obj) 34 | metrics <- GetInfo(obj, "metrics") 35 | default.by <- kGeo 36 | dfa <- aggregate(dfx[metrics], by=dfx[default.by], FUN=base::sum) 37 | expect_identical(dfa, obj.sub) 38 | }) 39 | 40 | test_that("FUN is a function", { 41 | expect_error(aggregate(obj, FUN="sum"), 42 | regexp="FUN is not a function") 43 | }) 44 | 45 | test_that("nonexisting 'metrics' and 'by' are detected", { 46 | expect_error(aggregate(obj, metrics=paste0(metrics.df2, collapse="")), 47 | regexp=paste0("The specified column 'salesconversions' ", 48 | "is not in the data frame")) 49 | expect_error(aggregate(obj, by=paste0(metrics.df2, collapse="")), 50 | regexp=paste0("The specified column 'salesconversions' ", 51 | "is not in the data frame")) 52 | }) 53 | 54 | test_that("'metrics' and 'by' cannot intersect", { 55 | expect_error(aggregate(obj, metrics=metrics.df2, by=metrics.df2[1L]), 56 | regexp="'metrics' and 'by' cannot intersect") 57 | }) 58 | } 59 | -------------------------------------------------------------------------------- /tests/testthat/test_043_aggregatetimeseries.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("AggregateTimeseries.GeoTimeseries") 16 | 17 | n.days2 <- (7L * 52L) 18 | dfgt <- .SimulateGeoTimeseries(n.geos=n.geos, n.days=n.days2, date.col=kDate, 19 | date.from="2015-01-05", # Monday. 20 | geo.col=kGeo, metric.col=metric.df1, seed=SEED) 21 | sales <- metric.df1 22 | daily <- 2L 23 | dfgt[[sales]] <- daily 24 | obj2 <- GeoTimeseries(dfgt, metrics=sales) 25 | 26 | test_that("Argument 'freq' is mandatory", { 27 | expect_error(AggregateTimeseries(obj2)) 28 | }) 29 | 30 | test_that("a daily is aggregated to weekly data properly", { 31 | expect_is(obj.agg <- AggregateTimeseries(obj2, freq="weekly"), 32 | "GeoTimeseries") 33 | expect_equal(nrow(obj.agg), nrow(obj2) %/% 7L) 34 | expect_true(all(obj.agg[[sales]] %in% (7L * daily))) 35 | expect_equal(length(unique(obj.agg[[kDate]])), n.days2 / 7) 36 | }) 37 | 38 | test_that("a daily data set is aggregated to monthly data properly", { 39 | expect_is(obj.agg <- AggregateTimeseries(obj2, freq="monthly"), 40 | "GeoTimeseries") 41 | expect_equal(sum(obj.agg[[sales]]), sum(obj2[[sales]])) 42 | expect_equal(length(unique(obj.agg[[kDate]])), n.days2 / 28) 43 | }) 44 | 45 | test_that("a daily data set is aggregated to weekly data properly", { 46 | expect_is(obj.agg <- AggregateTimeseries(obj2, freq="weekly"), 47 | "GeoTimeseries") 48 | expect_equal(nrow(obj.agg), nrow(obj2) %/% 7L) 49 | expect_true(all(obj.agg[[sales]] %in% (7L * daily))) 50 | expect_equal(length(unique(obj.agg[[kDate]])), n.days2 / 7) 51 | }) 52 | -------------------------------------------------------------------------------- /tests/testthat/test_075_getweeklyaverages.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("GetWeeklyAverages.GeoTimeseries") 16 | 17 | first.date <- as.Date("2016-09-26") 18 | df.gts <- expand.grid(date=first.date + c(0:13), 19 | geo=c("01", "02", "03", "04")) 20 | daily.avg.sales <- 1000 21 | daily.avg.other <- 10 22 | df.gts[["sales"]] <- (as.integer(df.gts[[kGeo]]) * daily.avg.sales) 23 | df.gts[["other"]] <- (as.integer(df.gts[[kGeo]]) * daily.avg.other) 24 | obj.gts <- GeoTimeseries(df.gts, metrics=c("sales", "other")) 25 | 26 | test_that("output is a d.f. with weekly avg of sales, other for each geo", { 27 | expect_is(obj <- GetWeeklyAverages(obj.gts), "data.frame") 28 | expect_identical(obj[["sales"]], 29 | 7 * daily.avg.sales * as.integer(obj[[kGeo]])) 30 | expect_identical(obj[["other"]], 31 | 7 * daily.avg.other * as.integer(obj[[kGeo]])) 32 | }) 33 | 34 | test_that("NAs are removed, also by default", { 35 | obj.gts[1, "sales"] <- NA 36 | expect_is(obj1 <- GetWeeklyAverages(obj.gts, na.rm=TRUE), "data.frame") 37 | expect_true(!anyNA(obj1[["sales"]])) 38 | expect_is(obj2 <- GetWeeklyAverages(obj.gts), "data.frame") 39 | expect_identical(obj1, obj2) 40 | }) 41 | 42 | test_that("na.rm=FALSE gives a sum == NA", { 43 | geo1.gts <- (obj.gts[[kGeo]] %in% "01") 44 | obj.gts[which(geo1.gts)[1], "sales"] <- NA # Insert a single NA. 45 | expect_is(obj <- GetWeeklyAverages(obj.gts, na.rm=FALSE), "data.frame") 46 | geo1 <- (obj[[kGeo]] %in% "01") 47 | expect_true(is.na(obj[["sales"]][geo1])) 48 | expect_true(!anyNA(obj[["sales"]][!geo1])) 49 | }) 50 | -------------------------------------------------------------------------------- /tests/testthat/test_087_getgeogroup.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("GetGeoGroup") 16 | 17 | geos.df <- data.frame(geo=base::LETTERS[1:12], sales=12:1) 18 | geos <- Geos(geos.df, volume="sales") 19 | geos[[kGeoGroup]] <- 1:2 20 | obj.ga <- GeoAssignment(geos) 21 | obj.gs <- GeoStrata(geos, n.groups=2) 22 | obj.gs[[kGeoGroup]] <- 2:1 23 | obj.gs[[kGeoGroup]][1] <- NA_integer_ 24 | 25 | 26 | context("GetGeoGroup.GeoAssignment") 27 | 28 | map0 <- structure(obj.ga[[kGeoGroup]], names=obj.ga[[kGeo]]) 29 | 30 | test_that("by default the complete mapping is returned.", { 31 | expect_identical(map0, GetGeoGroup(obj.ga)) 32 | }) 33 | 34 | test_that("a single mapping can be returned.", { 35 | expect_identical(map0["A"], GetGeoGroup(obj.ga, geo="A")) 36 | }) 37 | 38 | test_that("multiple mappings can be returned.", { 39 | expect_identical(map0[c("A", "B")], GetGeoGroup(obj.ga, geo=c("A", "B"))) 40 | }) 41 | 42 | 43 | context("GetGeoGroup.GeoStrata") 44 | 45 | map0 <- structure(obj.gs[[kGeoGroup]], names=obj.gs[[kGeo]]) 46 | 47 | test_that("by default the complete mapping is returned.", { 48 | expect_identical(map0, GetGeoGroup(obj.gs)) 49 | }) 50 | 51 | test_that("a single mapping can be returned.", { 52 | expect_identical(map0["A"], GetGeoGroup(obj.gs, geo="A")) 53 | }) 54 | 55 | test_that("multiple mappings can be returned.", { 56 | expect_identical(map0[c("A", "B")], GetGeoGroup(obj.gs, geo=c("A", "B"))) 57 | }) 58 | 59 | 60 | context("GetGeoGroup.GeoExperimentData") 61 | 62 | obj.gts <- GeoTimeseries(dfged2, metrics=metric.df1) 63 | obj.trt <- ExtractTreatmentAssignment(obj.gts) 64 | obj.ga <- ExtractGeoAssignment(obj.gts) 65 | obj.per <- ExtractExperimentPeriods(obj.gts) 66 | obj.ged <- GeoExperimentData(obj.gts, 67 | periods=obj.per, 68 | geo.assignment=obj.ga, 69 | treat.assignment=obj.trt) 70 | 71 | map0 <- structure(obj.ga[[kGeoGroup]], names=obj.ga[[kGeo]]) 72 | 73 | test_that("by default the complete mapping is returned.", { 74 | expect_identical(map0, GetGeoGroup(obj.ged)) 75 | }) 76 | 77 | test_that("a single mapping can be returned.", { 78 | expect_identical(map0["1"], GetGeoGroup(obj.ged, geo="1")) 79 | }) 80 | 81 | test_that("multiple mappings can be returned.", { 82 | expect_identical(map0[c("1", "5")], GetGeoGroup(obj.ged, geo=c("1", "5"))) 83 | }) 84 | 85 | obj.ged <- GeoExperimentData(obj.gts, 86 | periods=obj.per, 87 | geo.assignment=NULL, 88 | treat.assignment=obj.trt) 89 | 90 | test_that("an error is thrown if no geo.assignment was set in the object.", { 91 | expect_error(GetGeoGroup(obj.ged), 92 | regexp="No geo.assignment found") 93 | }) 94 | -------------------------------------------------------------------------------- /tests/testthat/test_130_doroasanalysis.R: -------------------------------------------------------------------------------- 1 | # Copyright 2016 Google Inc. All Rights Reserved. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | context("DoROASAnalysis") 16 | 17 | first.date <- as.Date("2016-09-26") 18 | geo.names <- c("01", "02", "03", "04", "05") 19 | df.gts <- expand.grid(date=first.date + seq(from=0, to=7 * 7 - 1), 20 | geo=geo.names) 21 | df.gts[["sales"]] <- runif(nrow(df.gts), min=0, 22 | max=100 * as.integer(df.gts[[kGeo]])) 23 | obj.gts <- GeoTimeseries(df.gts, metrics="sales") 24 | obj.per <- ExperimentPeriods(first.date + c(0L, 3 * 7, 5 * 7, 6 * 7 - 1), 25 | period.names=c("Pretest", "Test", "Cooldown")) 26 | obj.ga <- GeoAssignment(data.frame(geo=geo.names, geo.group=c(1, 2, 1, 2, 1))) 27 | obj.ged <- GeoExperimentData(obj.gts, period=obj.per, geo.assignment=obj.ga, 28 | treat.assignment=DefaultTreatmentAssignment()) 29 | SetSpendChange(obj.ged, prop.to="sales") <- 1 30 | 31 | test_that("GBR analysis is dispatched correctly", { 32 | expect_is(x <- DoROASAnalysis(obj.ged, model=kGBRModel1, 33 | response="sales", cost=kSpendChange), 34 | "GBRROASAnalysisFitGbr1") 35 | gbr.fit <- DoGBRROASAnalysis(obj.ged, response="sales", cost=kSpendChange) 36 | expect_equivalent(x, gbr.fit) 37 | }) 38 | 39 | test_that("TBR analysis is dispatched correctly", { 40 | set.seed(1) 41 | expect_is(x <- DoROASAnalysis(obj.ged, model=kTBRModel1, 42 | response="sales", cost=kSpendChange, n.sims=12), 43 | "TBRROASAnalysisFit") 44 | set.seed(1) 45 | tbr.fit <- DoTBRROASAnalysis(obj.ged, model=kTBRModel1, response="sales", 46 | cost=kSpendChange, n.sims=12) 47 | expect_equivalent(x, tbr.fit) 48 | }) 49 | 50 | test_that("unknown model throws an error", { 51 | expect_error(DoROASAnalysis(obj.ged, model="f00"), 52 | regexp="Unknown model: 'f00'") 53 | }) 54 | --------------------------------------------------------------------------------