Merge branch 'main' into dev

_pkgdown.yml

@@ -2,10 +2,29 @@ use_url: ~
 template:
   bootstrap: 5
 
-articles:
-- title: Main
-  navbar: ~
-  contents:
-  - faq
-  - table1
-  - estimators
+navbar:
+  structure:
+    left:  [intro, faq, tables, more]
+    right: [search, github]
+  components:
+   faq:
+    text: FAQ
+    href: articles/faq.html
+   tables:
+    text: Example Tables
+    menu:
+    - text: A Descriptive Table 1
+      href: articles/table1.html
+    - text: Binary Outcomes
+      href: articles/estimators_binary.html
+    - text: Continuous Outcomes
+      href: articles/estimators_continuous.html
+    - text: Survival Outcomes
+      href: articles/estimators_survival.html
+   more:
+    text: More
+    menu:
+    - text: Function reference
+      href: reference/index.html
+    - text: Changelog
+      href: news/index.html

vignettes/estimators_binary.Rmd

@@ -0,0 +1,71 @@
+---
+title: "Binary outcomes"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Binary outcomes}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+# Example
+
+The example uses the `breastcancer` data set from the risks package and compares the risk of death (a binary variable in this case) by categories of cancer stage.
+
+```{r example, message = FALSE}
+library(rifttable)
+library(dplyr)
+data(breastcancer, package = "risks")
+
+tibble::tribble(
+  ~label,                      ~type,
+  "**Absolute estimates**",    "",
+  "Observations",              "total",
+  "Outcomes",                  "outcomes",
+  "Outcomes/Total",            "outcomes/total",
+  "Cases/Controls",            "cases/controls",
+  "Risk",                      "risk",
+  "Risk (95% CI)",             "risk (ci)",
+  "Outcomes (Risk)",           "outcomes (risk)",
+  "Outcomes/Total (Risk)",     "outcomes/total (risk)",
+  "",                          "",
+  "**Comparative estimates**", "",
+  "Risk ratio (95% CI)",       "rr",
+  "Risk difference (95% CI)",  "rd",
+  "Odds ratio (95% CI)",       "or") %>%
+  mutate(
+    exposure = "stage",
+    outcome = "death") %>%
+  rifttable(
+    data = breastcancer,
+    overall = TRUE) %>%
+  rt_gt()  # Formatted output
+```
+
+
+# Absolute estimates per exposure category
+
+`type` | Description | Options (`arguments = `)
+-------+-------------+--------------
+`"cases/controls"` | Cases and non-cases (events and non-events); useful for case-control studies.
+`"outcomes"` | Outcome count.
+`"outcomes (risk)"` | A combination: Outcomes followed by risk in parentheses.
+`"outcomes/total (risk)"` | A combination: Outcomes slash total followed by risk in parentheses.
+`"risk"` | Risk (or prevalence), calculated as a proportion, *i.e.*, outcomes divided by number of observations. Change between display as proportion or percent using the parameter `risk_percent` of `rifttable()`.
+`"risk (ci)"` | Risk with confidence interval (default: 95%): Wilson score interval for binomial proportions, see `rifttable::scoreci()`.
+
+
+# Comparative estimates with confidence intervals
+
+`type` | Description | Options (`arguments = `)
+-------+-------------+--------------
+`"irr"` | Incidence rate ratio for count outcomes from Poisson regression model, with confidence interval (default: 95%).
+`"or"` | Odds ratio from logistic regression, with confidence interval (default: 95%).
+`"rd"` | Risk difference (or prevalence difference) from risks::riskdiff(), with confidence interval (default: 95%). | `list(approach = "margstd_boot", bootrepeats = 2000)` to request model fitting via marginal standardization with 2000 bootstraps.
+`"rr"` | Risk ratio (or prevalence ratio) from `risks::riskratio()`, with confidence interval (default: 95%). | See `"rd"`.

vignettes/estimators_continuous.Rmd

@@ -0,0 +1,99 @@
+---
+title: "Continuous outcomes"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Continuous outcomes}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+# Example
+
+The example uses the `cancer` data from the survival package. To compare patient age by ECOG performance status, recode the variable `ph.ecog` to be categorical (a `factor`) and exclude patients with rare elevated `ecog.ps`:
+
+```{r ex_continuous, message = FALSE}
+library(dplyr)
+library(rifttable)
+data(cancer, package = "survival")
+cancer <- cancer %>%
+  filter(ph.ecog < 3) %>%
+  mutate(ph.ecog = factor(ph.ecog))
+attr(cancer$ph.ecog, which = "label") <- "ECOG performance status"
+
+tribble(
+  ~label,                                       ~type,
+  "**Absolute estimates**",                     "",
+  "Observations",                               "total",
+  "Range",                                      "range",
+  "Mean",                                       "", 
+  "  Mean (i.e., arithmetic mean)",             "mean",
+  "  Mean (95% CI)",                            "mean (ci)",
+  "  Mean (standard deviation)",                "mean (sd)",
+  "  Geometric mean",                           "geomean",
+  "Median",                                     "median",
+  "Median (interquartile range)",               "median (iqr)",
+  "",                                           "",
+  "**Comparative estimates**",                  "",
+  "Mean difference (95% CI)",                   "diff",
+  "Median difference (95% CI)",                 "quantreg",
+  "Mean ratio",                                 "",
+  "  of arithmetic means",                      "fold",
+  "  of arithmetic means, empirical SE",        "irrrob",
+  "  of geometric means",                       "foldlog") %>%
+  mutate(
+    exposure = "ph.ecog",
+    outcome = "age") %>%
+  rifttable(
+    data = cancer, 
+    diff_digits = 1,  # Suppress unnecessary precision in most estimates
+    # Show extraneous digits to highlight (minor) differences in ratio  models:
+    ratio_digits = 3,
+    overall = TRUE) %>%  
+  rt_gt()  # obtain formatted output
+```
+
+
+# Absolute estimates per exposure category
+
+`type` | Description | Options (`arguments = `)
+-------+-------------+--------------
+`"range"` | Range: Minimum to maximum value.
+`"mean"` | Mean (arithmetic mean).
+`"mean (ci)"` | Mean and CI (default: 95%).
+`"mean (sd)"` | Mean and standard deviation.
+`"geomean"` | Geometric mean.
+`"median"` | Median.
+`"median (iqr)"` | Median and interquartile range.
+
+
+# Comparative estimates with confidence intervals
+
+`type` | Description | Options (`arguments = `)
+-------+-------------+--------------
+`"diff"` | Mean difference from linear model. |
+`"fold"` | Fold change from generalized linear model with log link (i.e., ratio of arithmetic means).
+`"foldlog"` | Fold change from linear model after log transformation of the outcome (*i.e.*, ratio of geometric means).
+`"irrrob"` | Fold change from generalized linear model with Poisson distribution and log link and robust (sandwich) standard errors
+`"quantreg"` | Quantile difference from quantile regression using `quantreg::rq()` with `method = "fn"`. By default, this is the difference in medians. | `list(tau = 0.75)` to change the quantile to, e.g., the 75th percentile.
+
+
+# More on ratios of continuous outcomes
+
+Three types of ratios for continuous outcomes are implemented in `rifttable()`:
+
+`type =` | Ratio of ... | Model | Use
+-------|----------|-----------------------|-----------------------------
+`"fold"` | Arithmetic means | Generalized linear model with Gaussian distribution and log link: `glm(y ~ x, family = gaussian(link = "log"))` | Tolerates `0` in the `outcome` variable. May be informative if outcome is normally distributed without transformation.
+`"irrrob"` | Arithmetic means | Generalized linear model with Poisson distribution and log link: `glm(y ~ x, family = poisson())`, with robust (sandwich) standard errors | Tolerates `0` in the `outcome` variable. May be informative if outcome is normally distributed without transformation.
+`"foldlog"` | Geometric means | Linear model with log-transformed outcome: `lm(log(y) ~ x)` | Does not tolerate `0` in the `outcome` variable, as `log(0)` is undefined (R returns `-Inf`). May be informative if outcome is normally distributed after log transformation.
+
+In all models, after exponentiation, beta coefficients can be interpreted as ratios. rifttable automatically does all necessary transformations.
+
+In the `cancer` data, ratios of usual (arithmetic) means of age could be considered informative, given that `hist(cancer$age)` etc. does not show a major skew in this outcome.