MarketMatching (version 1.2.1)

inference: Given a test market, analyze the impact of an intervention

Description

inference Analyzes the causal impact of an intervention using the CausalImpact package, given a test market and a matched_market object from the best_matches function. The function returns an object of type "market_inference" which contains the estimated impact of the intervention (absolute and relative).

Usage

inference(matched_markets=NULL,
          bsts_modelargs=NULL,
          test_market=NULL,
          end_post_period=NULL,
          alpha=0.05,
          prior_level_sd=0.01,
          control_matches=5, 
          analyze_betas=FALSE, 
          nseasons=NULL)

Value

Returns an object of type inference. The object has the following elements:

AbsoluteEffect

The estimated absolute effect of the intervention

AbsoluteEffectLower

The lower limit of the estimated absolute effect of the intervention. This is based on the posterior interval of the counterfactual predictions. The width of the interval is determined by the alpha parameter.

AbsoluteEffectUpper

The upper limit of the estimated absolute effect of the intervention. This is based on the posterior interval of the counterfactual predictions. The width of the interval is determined by the alpha parameter.

RelativeEffectLower

Same as the above, just for relative (percentage) effects

RelativeEffectUpper

Same as the above, just for relative (percentage) effects

TailProb

Posterior probability of a non-zero effect

PrePeriodMAPE

Pre-intervention period MAPE

DW

Durbin-Watson statistic. Should be close to 2.

PlotActualVersusExpected

Plot of actual versus expected using ggplot2

PlotCumulativeEffect

Plot of the cumulative effect using ggplot2

PlotPointEffect

Plot of the pointwise effect using ggplot2

PlotActuals

Plot of the actual values for the test and control markets using ggplot2

PlotPriorLevelSdAnalysis

Plot of DW and MAPE for different values of the local level SE using ggplot2

PlotLocalLevel

Plot of the local level term using ggplot2

TestData

A data.frame with the test market data

ControlData

A data.frame with the data for the control markets

PlotResiduals

Plot of the residuals using ggplot2

TestName

The name of the test market

TestName

The name of the control market

zooData

A zoo time series object with the test and control data

Predictions

Actual versus predicted values

CausalImpactObject

The CausalImpact object created

Coefficients

The average posterior coefficients

Arguments

matched_markets

A matched_market object created by the market_matching function

bsts_modelargs

A list() that passes model parameters directly to bsts -- such as list(niter = 1000, nseasons = 52, prior.level.sd=0.1) This parameter will overwrite the values specified in prior_level_sd and nseasons. ONLY use this if you're using intricate bsts settings For most use-cases, using the prior_level_sd and nseasons parameters should be sufficient

test_market

The name of the test market (character)

end_post_period

The end date of the post period. Must be a character of format "YYYY-MM-DD" -- e.g., "2015-11-01"

alpha

Desired tail-area probability for posterior intervals. For example, 0.05 yields 0.95 intervals

prior_level_sd

Prior SD for the local level term (Gaussian random walk). Default is 0.01. The bigger this number is, the more wiggliness is allowed for the local level term. Note that more wiggly local level terms also translate into larger posterior intervals This parameter will be overwritten if you're using the bsts_modelargs parameter

control_matches

Number of matching control markets to use in the analysis (default is 5)

analyze_betas

Controls whether to test the model under a variety of different values for prior_level_sd.

nseasons

Seasonality for the bsts model -- e.g., 52 for weekly seasonality

Examples

if (FALSE) {
library(MarketMatching)
##-----------------------------------------------------------------------
## Analyze causal impact of a made-up weather intervention in Copenhagen
## Since this is weather data it is a not a very meaningful example. 
## This is merely to demonstrate the function.
##-----------------------------------------------------------------------
data(weather, package="MarketMatching")
mm <- best_matches(data=weather, 
                   id="Area",
                   markets_to_be_matched=c("CPH", "SFO"),
                   date_variable="Date",
                   matching_variable="Mean_TemperatureF",
                   parallel=FALSE,
                   warping_limit=1, # warping limit=1
                   dtw_emphasis=0, # rely only on dtw for pre-screening
                   matches=5, # request 5 matches
                   start_match_period="2014-01-01",
                   end_match_period="2014-10-01")
library(CausalImpact)
results <- inference(matched_markets=mm,
                     test_market="CPH",
                     analyze_betas=FALSE,
                     control_matches=5, # use all 5 matches for inference
                     end_post_period="2015-12-15",
                     prior_level_sd=0.002)
}