Package 'WhatIf'

An object of class "whatif", the output of the function whatif.

A character string; the type of plot of the cumulative frequencies of the distances to be produced. Possible types are: "f" for cumulative frequencies only; "l" for LOWESS smoothing of cumulative frequencies only; and "b" for both cumulative frequencies and LOWESS smoothing. The default is "f".

A numeric vector; the specific counterfactuals to be plotted. Each element represents a counterfactual, specifically its row number from the matrix or data frame of counterfactuals. By default, all counterfactuals are plotted. Default is NULL.

A Boolean; should an encapsulated postscript file be generated? Setting the argument equal to TRUE generates an .eps file, which is saved to your working directory with file name of form 'graph_'type'_'numcf'.eps', where 'type' and 'numcf' are the values of the respective arguments. Specifically, 'numcf' takes the value of the first element of the argument numcf unless all counterfactuals were plotted, in which case all appears in the place of 'numcf'. Default is FALSE, which instead prints the graph to the screen.

Further arguments passed to and from other methods.

An object of class "summary.whatif", the output of the function summary.whatif.

Further arguments passed to and from other methods.

An object of class "whatif", the output of the function whatif.

A Boolean; should the matrix of pairwise distances between each counterfactual and data point be printed to the screen, if it was returned? Default is FALSE.

A Boolean; should the matrix of cumulative frequencies of distances for each counterfactual be printed to the screen? Default is FALSE.

Further arguments passed to and from other methods.

An object of class "whatif", the output of the function whatif.

Further arguments passed to and from other methods.

The original call to whatif.

A scalar. The total number of counterfactuals evaluated.

A scalar. The number of counterfactuals evaluated that are in the convex hull of the observed covariate data.

A scalar. The average percentage of data nearby each counterfactual, where the average is taken over all counterfactuals.

A data frame with three columns and $m$ rows, where $m$ is the number of counterfactuals. The first column, cfact, indexes the counterfactuals. The second column, in.hull, contains the results of the convex hull test. The third column, per.near, contains the percentage of data points nearby each counterfactual.

An optional formula without a dependent variable that is of class "formula" and that follows standard R conventions for formulas, e.g. ~ x1 + x2. Allows you to transform or otherwise re-specify combinations of the variables in both data and cfact. To use this parameter, both data and cfact must be coercable to data frames; the variables of both data and cfact must be labeled; and all variables appearing in formula must also appear in both data and cfact. Otherwise, errors are returned. The intercept is automatically dropped. Default is NULL.

May take one of the following forms:

1. A R model output object, such as the output from calls to lm, glm, and zelig. If it is not a zelig object, such an output object must be a list. It must additionally have either a formula or terms component and either a data or model component; if it does not, an error is returned. Of the latter, whatif first looks for data, which should contain either the original data set supplied as part of the model call (as in glm) or the name of this data set (as in zelig), which is assumed to reside in the global environment. If data does not exist, whatif then looks for model, which should contain the model frame (as in lm). The intercept is automatically dropped from the extracted observed covariate data set if the original model included one.

2. A $n$-by-$k$ non-character (logical or numeric) matrix or data frame of observed covariate data with $n$ data points or units and $k$ covariates. All desired variable transformations and interaction terms should be included in this set of $k$ covariates unless formula is alternatively used to produce them. However, an intercept should not be. Such a matrix may be obtained by passing model output (e.g., output from a call to lm) to model.matrix and excluding the intercept from the resulting matrix if one was fit. Note that whatif will attempt to coerce data frames to their internal numeric values. Hence, data frames should only contain logical, numeric, and factor columns; character columns will lead to an error being returned.

3. A string. Either the complete path (including file name) of the file containing the data or the path relative to your working directory. This file should be a white space delimited text file. If it contains a header, you must include a column of row names as discussed in the help file for the R function read.table. The data in the file should be as otherwise described in (2).

Missing data is allowed and will be dealt with via the argument missing. It should be flagged using R's standard representation for missing data, NA.

A R object or a string. If a R object, a $m$-by-$k$ non-character matrix or data frame of counterfactuals with $m$ counterfactuals and the same $k$ covariates (in the same order) as in data. However, if formula is used to select a subset of the $k$ covariates, then cfact may contain either only these $j \leq k$ covariates or the complete set of $k$ covariates. An intercept should not be included as one of the covariates. It will be automatically dropped from the counterfactuals generated by Zelig if the original model contained one. Data frames will again be coerced to their internal numeric values if possible. If a string, either the complete path (including file name) of the file containing the counterfactuals or the path relative to your working directory. This file should be a white space delimited text file. See the discussion under data for instructions on dealing with a header. All counterfactuals should be fully observed: if you supply counterfactuals with missing data, they will be list-wise deleted and a warning message will be printed to the screen.

An optional numeric vector of length $k$, where $k$ is the number of covariates. Each element represents the range of the corresponding covariate for use in calculating Gower distances. Use this argument when covariate data do not represent the population of interest, such as selection by stratification or experimental manipulation. By default, the range of each covariate is calculated from the data (the difference of its maximum and minimum values in the sample), which is appropriate when a simple random sampling design was used. To supply your own range for the $k$th covariate, set the $k$th element of the vector equal to the desired range and all other elements equal to NA. Default is NULL.

An optional numeric vector of any positive length, the elements of which comprise a set of distances. Used in calculating cumulative frequency distributions for the distances of the data points from each counterfactual. For each such distance and counterfactual, the cumulative frequency is the fraction of observed covariate data points with distance to the counterfactual less than or equal to the supplied distance value. The default varies with the distance measure used. When the Gower distance measure is employed, frequencies are calculated for the sequence of Gower distances from 0 to 1 in increments of 0.05. When the Euclidian distance measure is employed, frequencies are calculated for the sequence of Euclidian distances from the minimum to the maximum observed distances in twenty equal increments, all rounded to two decimal places. Default is NULL.

An optional scalar indicating which observed data points are considered to be nearby (i.e., withing ‘nearby’ geometric variances of) the counterfactuals. Used to calculate the summary statistic returned by the function: the fraction of the observed data nearby each counterfactual. By default, the geometric variance of the covariate data is used. For example, setting nearby to 2 will identify the proportion of data points within two geometric variances of a counterfactual. Default is NULL.

An optional string indicating which of two distance measures to employ. The choices are either "gower", Gower's non-parametric distance measure ($G^2$), which is suitable for both qualitative and quantitative data; or "euclidian", squared Euclidian distance, which is only suitable for quantitative data. The default is "gower".

An optional string indicating the strategy for dealing with missing data in the observed covariate data set. whatif supports two possible missing data strategies: "list", list-wise deletion of missing cases; and "case", ignoring missing data case-by-case. Note that if "case" is selected, cases with missing values are deleted listwise for the convex hull test and for computing Euclidian distances, but pairwise deletion is used in computing the Gower distances to maximally use available information. The user is strongly encouraged to treat missing data using specialized tools such as Amelia prior to feeding the data to whatif. Default is "list".

An optional string indicating which analyses to undertake. The options are either "hull", only perform the convex hull membership test; "distance", do not perform the convex hull test but do everything else, such as calculating the distance between each counterfactual and data point; or "both", undertake both the convex hull test and the distance calculations (i.e., do everything). Default is "both".

A Boolean; should the processed observed covariate and counterfactual data matrices on which all whatif computations are performed be returned? Processing refers to internal whatif operations such as the subsetting of covariates via formula, the deletion of cases with missing values, and the coercion of data frames to numeric matrices. Primarily intended for diagnostic purposes. If TRUE, these matrices are returned as a list. Default is FALSE.

A Boolean; should the matrix of distances between each counterfactual and data point be returned? If TRUE, this matrix is returned as part of the output; if FALSE, it is not. Default is FALSE due to the large size that this matrix may attain.

The number of cores to use for the convex hull test, i.e. at most how many child processes will be run simultaneously. Must be at least one, and parallelization requires at least two cores. The default is set by detectCores

Further arguments passed to and from other methods.

The original call to whatif.

A list with two elements, data and cfact. Only present if return.inputs was set equal to TRUE in the call to whatif. The first element is the processed observed covariate data matrix on which all whatif computations were performed. The second element is the processed counterfactual data matrix.

A logical vector of length $m$, where $m$ is the number of counterfactuals. Each element of the vector is TRUE if the corresponding counterfactual is in the convex hull and FALSE otherwise.

A $m$-by-$n$ numeric matrix, where $m$ is the number of counterfactuals and $n$ is the number of data points (units). Only present if return.distance was set equal to TRUE in the call to whatif. The $[i, j]$th entry of the matrix contains the distance between the $i$th counterfactual and the $j$th data point.

A scalar. The geometric variability of the observed covariate data.

A numeric vector of length $m$, where $m$ is the number of counterfactuals. The $m$th element contains the summary statistic for the corresponding counterfactual. This summary statistic is the fraction of data points with distances to the counterfactual less than the argument nearby, which by default is the geometric variability of the covariates.

A numeric matrix. By default, the matrix has dimension $m$-by-21, where $m$ is the number of counterfactuals; however, if you supplied your own frequencies via the argument freq, the matrix has dimension $m$-by-$f$, where $f$ is the length of freq. Each row of the matrix contains the cumulative frequency distribution for the corresponding counterfactual calculated using either the distance measure-specific default set of distance values or the set that you supplied (see the discussion under the argument freq). Hence, the $[i, j]$th entry of the matrix is the fraction of data points with distances to the $i$th counterfactual less than or equal to the value represented by the $j$th column. The column names contain these values.