merge in changes from master branch (#93)

* update the documentation for needtworows as a raw output

* udpate readme to include ITCV

R/pkonfound.R

@@ -59,6 +59,7 @@
 #'   \item{starting_table}{Observed 2 by 2 table before replacement and switching. Implied table for logistic regression.}
 #'   \item{final_table}{The 2 by 2 table after replacement and switching.}
 #'   \item{user_SE}{user entered standard error. Only applicable for logistic regression.}
+#'   \item{needtworows}{whether double row switches are needed.}
 #'   \item{analysis_SE}{the standard error used to generate a plausible 2 by 2 table. Only applicable for logistic regression.}
 #'   \item{Fig_ITCV}{figure for ITCV.} 
 #'   \item{Fig_RIR}{figure for RIR.}

README.Rmd

@@ -42,7 +42,7 @@ devtools::install_github("konfound-project/konfound")
 
 ## pkonfound() for published studies
 
-`pkonfound()`, for published studies, calculates (1) how much bias there must be in an estimate to invalidate/sustain an inference, and interprets in terms of how much data would need to be replaced to nullify an inference; (2) the impact of an omitted variable necessary to invalidate/sustain an inference for a regression coefficient:
+`pkonfound()`, for published studies, calculates (1) how much bias there must be in an estimate to invalidate/sustain an inference, and interprets in terms of how much data would need to be replaced to nullify an inference (Robustness of an Inference to Replacement, RIR); (2) the impact of an omitted variable necessary to invalidate/sustain an inference for a regression coefficient (Impact Threshold of a Confounding Variable, ITCV). RIR is reported by default. ITCV can be generated by specifying `index = "IT"`.
 
 ```{r, eval = T}
 library(konfound)
@@ -53,6 +53,11 @@ pkonfound(est_eff = 2,
           std_err = .4, 
           n_obs = 100, 
           n_covariates = 3)
+pkonfound(est_eff = 2, 
+          std_err = .4, 
+          n_obs = 100, 
+          n_covariates = 3, 
+          index = "IT")
 ```
 
 ## konfound() for models fit in R
@@ -71,6 +76,11 @@ Sensitivity analysis for the effect for `wt` on `mpg` can be carried out as foll
 konfound(m1, wt)
 ```
 
+Similar to `pkonfound`, ITCV can be generated by specifying `index = "IT"`.
+```{r}
+konfound(m1, wt, index = "IT")
+```
+
 ## mkonfound for meta-analyses including sensitivity analysis
 
 `mkonfound()` supports sensitivity that can be compared or synthesized across multiple analyses. We can use an existing (and built-in) dataset, such as `mkonfound_ex`.

README.md

@@ -40,8 +40,11 @@ devtools::install_github("konfound-project/konfound")
 `pkonfound()`, for published studies, calculates (1) how much bias there
 must be in an estimate to invalidate/sustain an inference, and
 interprets in terms of how much data would need to be replaced to
-nullify an inference; (2) the impact of an omitted variable necessary to
-invalidate/sustain an inference for a regression coefficient:
+nullify an inference (Robustness of an Inference to Replacement, RIR);
+(2) the impact of an omitted variable necessary to invalidate/sustain an
+inference for a regression coefficient (Impact Threshold of a
+Confounding Variable, ITCV). RIR is reported by default. ITCV can be
+generated by specifying `index = "IT"`.
 
 ``` r
 library(konfound)
@@ -76,6 +79,39 @@ pkonfound(est_eff = 2,
 #> For other forms of output, run
 #>           ?pkonfound and inspect the to_return argument
 #> For models fit in R, consider use of konfound().
+pkonfound(est_eff = 2, 
+          std_err = .4, 
+          n_obs = 100, 
+          n_covariates = 3, 
+          index = "IT")
+#> Impact Threshold for a Confounding Variable (ITCV):
+#> 
+#> The minimum impact of an omitted variable to invalidate an inference for
+#> a null hypothesis of an effect of nu (0) is based on a correlation of 0.566
+#> with the outcome and 0.566 with the predictor of interest (conditioning
+#> on all observed covariates in the model; signs are interchangeable). This is
+#> based on a threshold effect of 0.2 for statistical significance (alpha = 0.05).
+#> 
+#> Correspondingly the impact of an omitted variable (as defined in Frank 2000) must be 
+#> 0.566 X 0.566 = 0.321 to invalidate an inference for a null hypothesis of an effect of nu (0).
+#> 
+#> For calculation of unconditional ITCV using pkonfound(), additionally include
+#> the R2, sdx, and sdy as input, and request raw output.
+#> 
+#> See Frank (2000) for a description of the method.
+#> 
+#> Citation:
+#> Frank, K. (2000). Impact of a confounding variable on the inference of a
+#> regression coefficient. Sociological Methods and Research, 29 (2), 147-194
+#> 
+#> Accuracy of results increases with the number of decimals reported.
+#> 
+#> The ITCV analysis was originally derived for OLS standard errors. If the
+#> standard errors reported in the table were not based on OLS, some caution
+#> should be used to interpret the ITCV.
+#> For other forms of output, run
+#>           ?pkonfound and inspect the to_return argument
+#> For models fit in R, consider use of konfound().
 ```
 
 ## konfound() for models fit in R
@@ -141,6 +177,37 @@ konfound(m1, wt)
 #> NULL
 ```
 
+Similar to `pkonfound`, ITCV can be generated by specifying
+`index = "IT"`.
+
+``` r
+konfound(m1, wt, index = "IT")
+#> Impact Threshold for a Confounding Variable (ITCV):
+#> 
+#> The minimum (in absolute value) impact of an omitted variable to invalidate
+#> an inference for a null hypothesis of an effect of nu (0) is based on
+#> a correlation of -0.425 with the outcome and 0.425 with the predictor of
+#> interest (conditioning on all observed covariates in the model; signs are
+#> interchangeable). This is based on a threshold effect of -0.355 for statistical
+#> significance (alpha = 0.05).
+#> 
+#> Correspondingly the impact of an omitted variable (as defined in Frank 2000) must be
+#> -0.425 X 0.425 = -0.18 to invalidate an inference for a null hypothesis of an effect of nu (0).
+#> 
+#> See Frank (2000) for a description of the method.
+#> 
+#> Citation:
+#> Frank, K. (2000). Impact of a confounding variable on the inference of a
+#> regression coefficient. Sociological Methods and Research, 29 (2), 147-194
+#> 
+#> Accuracy of results increases with the number of decimals reported.
+#> 
+#> The ITCV analysis was originally derived for OLS standard errors. If the
+#> standard errors reported in the table were not based on OLS, some caution
+#> should be used to interpret the ITCV.
+#> NULL
+```
+
 ## mkonfound for meta-analyses including sensitivity analysis
 
 `mkonfound()` supports sensitivity that can be compared or synthesized