cardx readme update

.Rbuildignore

@@ -35,6 +35,7 @@ pkgdown
 # others
 ^renv$
 ^renv\.lock$
+^README\.Rmd$
 ^.revdeprefs\.yaml$
 ^revdep$
 ^\.covrignore$

README.Rmd

@@ -0,0 +1,87 @@
+---
+output: github_document
+editor_options: 
+  markdown: 
+    wrap: 72
+---
+
+# cardx <a href="https://insightsengineering.github.io/cardx"><img src="man/figures/logo.png" alt="cardx website" align="right" height="138"/></a>
+
+[![R-CMD-check](https://github.com/insightsengineering/cardx/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/insightsengineering/cardx/actions/workflows/R-CMD-check.yaml)
+[![Codecov test
+coverage](https://codecov.io/gh/insightsengineering/cardx/branch/main/graph/badge.svg)](https://app.codecov.io/gh/insightsengineering/cardx?branch=main)
+[![Lifecycle:
+experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+
+The **{cardx}** package is an extension of the {cards} package, providing additional functions to create Analysis Results Data Objects (ARDs) using the **R** programming language.
+The {cardx} package exports ARD functions that uses utility functions from {cards} and statistical functions from additional packages (such as, {stats}, {mmrm}, {emmeans}, {car}, {survey}, etc.) to construct summary objects.
+
+Summary objects can be used to:
+
+-   **Generate Tables and visualizations for Regulatory Submission**
+    easily in **R**. Perfect for presenting descriptive statistics,
+    statistical analyses, regressions, etc. and more.
+
+-   **Conduct Quality Control checks on existing Tables** in R.
+    Storing both the results and test parameters supports the re-use and
+    verification of data analyses.
+
+## Installation
+
+Install cards from CRAN with:
+
+```r
+install.packages("cardx")
+```
+
+You can install the development version of cards from [GitHub](https://github.com/) with:
+
+``` r
+# install.packages("devtools")
+devtools::install_github("insightsengineering/cardx")
+```
+
+## Examples
+
+### Example ARD Creation
+
+Example t-test:
+
+```{r}
+library(cardx)
+
+cards::ADSL |>
+  # keep two treatment arms for the t-test calculation
+  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
+  cardx::ard_stats_t_test(by = ARM, variable = AGE)
+```
+
+Note that the returned ARD contains the analysis results in addition to
+the function parameters used to calculate the results allowing for
+reproducible future analyses and further customization.
+
+### Model Input
+
+Some {cardx} functions accept regression model objects as input:
+
+```{r, eval=FALSE}
+lm(AGE ~ ARM, data = cards::ADSL) |>
+  ard_aod_wald_test()
+```
+
+Note that the [Analysis Results Standard](https://www.cdisc.org/standards/foundational/analysis-results-standard) should begin with a data set rather than a model object.
+To accomplish this we include model construction helpers.
+
+```{r}
+construct_model(
+  x = cards::ADSL,
+  formula = reformulate2("ARM", response = "AGE"),
+  method = "lm"
+) |>
+  ard_aod_wald_test()
+```
+
+## Additional Resources
+
+-   The best resources are the help documents accompanying each {cardx} function.
+-   Supporting documentation for both companion packages [{cards}](https://insightsengineering.github.io/cards/) and {[gtsummary](https://www.danieldsjoberg.com/gtsummary/index.html)} will be useful for understanding the ARD workflow and capabilities.

README.md

@@ -1,19 +1,124 @@
-# cardx <a href="https://insightsengineering.github.io/cardx"><img src="man/figures/logo.png" align="right" height="138" alt="cardx website" /></a>
 
-<!-- badges: start -->
+# cardx <a href="https://insightsengineering.github.io/cardx"><img src="man/figures/logo.png" alt="cardx website" align="right" height="138"/></a>
+
 [![R-CMD-check](https://github.com/insightsengineering/cardx/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/insightsengineering/cardx/actions/workflows/R-CMD-check.yaml)
-[![Codecov test coverage](https://codecov.io/gh/insightsengineering/cardx/branch/main/graph/badge.svg)](https://app.codecov.io/gh/insightsengineering/cardx?branch=main)
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
-<!-- badges: end -->
+[![Codecov test
+coverage](https://codecov.io/gh/insightsengineering/cardx/branch/main/graph/badge.svg)](https://app.codecov.io/gh/insightsengineering/cardx?branch=main)
+[![Lifecycle:
+experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+
+The **{cardx}** package is an extension of the {cards} package,
+providing additional functions to create Analysis Results Data Objects
+(ARDs) using the **R** programming language. The {cardx} package exports
+ARD functions that uses utility functions from {cards} and statistical
+functions from additional packages (such as, {stats}, {mmrm}, {emmeans},
+{car}, {survey}, etc.) to construct summary objects.
 
+Summary objects can be used to:
 
-This is the source repository of the `cardx` R package.
+- **Generate Tables and visualizations for Regulatory Submission**
+  easily in **R**. Perfect for presenting descriptive statistics,
+  statistical analyses, regressions, etc. and more.
+
+- **Conduct Quality Control checks on existing Tables** in R. Storing
+  both the results and test parameters supports the re-use and
+  verification of data analyses.
 
 ## Installation
 
-The latest development version of `{cardx}` can directly be installed from GitHub by running the following:
+Install cards from CRAN with:
+
+``` r
+install.packages("cardx")
+```
+
+You can install the development version of cards from
+[GitHub](https://github.com/) with:
+
+``` r
+# install.packages("devtools")
+devtools::install_github("insightsengineering/cardx")
+```
+
+## Examples
+
+### Example ARD Creation
+
+Example t-test:
+
+``` r
+library(cardx)
+
+cards::ADSL |>
+  # keep two treatment arms for the t-test calculation
+  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
+  cardx::ard_stats_t_test(by = ARM, variable = AGE)
+```
+
+    ## {cards} data frame: 14 x 9
+
+    ##    group1 variable   context   stat_name stat_label      stat
+    ## 1     ARM      AGE stats_t_…    estimate  Mean Dif…     0.828
+    ## 2     ARM      AGE stats_t_…   estimate1  Group 1 …    75.209
+    ## 3     ARM      AGE stats_t_…   estimate2  Group 2 …    74.381
+    ## 4     ARM      AGE stats_t_…   statistic  t Statis…     0.655
+    ## 5     ARM      AGE stats_t_…     p.value    p-value     0.513
+    ## 6     ARM      AGE stats_t_…   parameter  Degrees …   167.362
+    ## 7     ARM      AGE stats_t_…    conf.low  CI Lower…    -1.668
+    ## 8     ARM      AGE stats_t_…   conf.high  CI Upper…     3.324
+    ## 9     ARM      AGE stats_t_…      method     method Welch Tw…
+    ## 10    ARM      AGE stats_t_… alternative  alternat… two.sided
+    ## 11    ARM      AGE stats_t_…          mu    H0 Mean         0
+    ## 12    ARM      AGE stats_t_…      paired  Paired t…     FALSE
+    ## 13    ARM      AGE stats_t_…   var.equal  Equal Va…     FALSE
+    ## 14    ARM      AGE stats_t_…  conf.level  CI Confi…      0.95
+
+    ## ℹ 3 more variables: fmt_fn, warning, error
+
+Note that the returned ARD contains the analysis results in addition to
+the function parameters used to calculate the results allowing for
+reproducible future analyses and further customization.
+
+### Model Input
+
+Some {cardx} functions accept regression model objects as input:
+
+``` r
+lm(AGE ~ ARM, data = cards::ADSL) |>
+  ard_aod_wald_test()
+```
+
+Note that the [Analysis Results
+Standard](https://www.cdisc.org/standards/foundational/analysis-results-standard)
+should begin with a data set rather than a model object. To accomplish
+this we include model construction helpers.
 
-```r
-if (!require("pak")) install.packages("pak")
-pak::pak("insightsengineering/cardx")
+``` r
+construct_model(
+  x = cards::ADSL,
+  formula = reformulate2("ARM", response = "AGE"),
+  method = "lm"
+) |>
+  ard_aod_wald_test()
 ```
+
+    ## {cards} data frame: 6 x 8
+
+    ##      variable   context stat_name stat_label     stat fmt_fn
+    ## 1 (Intercept) aod_wald…        df  Degrees …        1      1
+    ## 2 (Intercept) aod_wald… statistic  Statistic 7126.713      1
+    ## 3 (Intercept) aod_wald…   p.value    p-value        0      1
+    ## 4         ARM aod_wald…        df  Degrees …        2      1
+    ## 5         ARM aod_wald… statistic  Statistic    1.046      1
+    ## 6         ARM aod_wald…   p.value    p-value    0.593      1
+
+    ## ℹ 2 more variables: warning, error
+
+## Additional Resources
+
+- The best resources are the help documents accompanying each {cardx}
+  function.
+- Supporting documentation for both companion packages
+  [{cards}](https://insightsengineering.github.io/cards/) and
+  {[gtsummary](https://www.danieldsjoberg.com/gtsummary/index.html)}
+  will be useful for understanding the ARD workflow and capabilities.

_pkgdown.yml

@@ -22,10 +22,8 @@ authors:
 
 reference:
   - title: "ARD Creation"
-  - subtitle: "Inference"
+  - subtitle: "{stats} package"
   - contents:
-      - ard_aod_wald_test
-      - ard_car_anova
       - ard_stats_anova
       - ard_stats_aov
       - ard_stats_chisq_test
@@ -37,23 +35,46 @@ reference:
       - ard_stats_prop_test
       - ard_stats_t_test
       - ard_stats_wilcox_test
-      - ard_survey_svychisq
-      - ard_survey_svyranktest
-      - ard_survey_svyttest
-      - ard_survival_survdiff
 
-  - subtitle: "Estimation"
+  - subtitle: "{aod} package"
+  - contents:
+      - ard_aod_wald_test
+
+  - subtitle: "{car} package"
   - contents:
+      - ard_car_anova
       - ard_car_vif
+
+  - subtitle: "{effectsize} package"
+  - contents:
       - ard_effectsize_cohens_d
       - ard_effectsize_hedges_g
+
+  - subtitle: "{emmeans} package"
+  - contents:
       - ard_emmeans_mean_difference
+
+  - subtitle: "{smd} package"
+  - contents:
+      - ard_smd_smd
+
+  - subtitle: "{survey} package"
+  - contents:
+      - ard_survey_svychisq
+      - ard_survey_svycontinuous
+      - ard_survey_svyranktest
+      - ard_survey_svyttest
+
+  - subtitle: "{survival} package"
+  - contents:
+    - ard_survival_survfit
+    - ard_survival_survdiff
+
+  - subtitle: "Other ARD functions"
+  - contents:
       - ard_proportion_ci
       - ard_regression
       - ard_regression_basic
-      - ard_smd_smd
-      - ard_survival_survfit
-      - ard_survey_svycontinuous
 
   - title: "Helpers"
   - contents:

inst/WORDLIST

@@ -1,4 +1,5 @@
 ARD
+ARDs
 Biopharmaceutical
 CMD
 Chisq
@@ -26,7 +27,9 @@ de
 deff
 emmeans
 funder
+gtsummary
 jeffreys
+mmrm
 pearson
 pre
 quosures

tests/testthat/test-ard_regression.R

@@ -24,7 +24,7 @@ test_that("ard_regression() works", {
 test_that("ard_regression() works specifying custom tidier", {
   skip_if_not(is_pkg_installed(pkg = c("lme4", "broom.mixed"), reference_pkg = "cardx"))
   expect_snapshot(
-   lme4::lmer(mpg ~ hp + (1 | cyl), data = mtcars) |>
+    lme4::lmer(mpg ~ hp + (1 | cyl), data = mtcars) |>
       ard_regression(tidy_fun = broom.mixed::tidy) |>
       as.data.frame() |>
       dplyr::select(-context, -stat_label, -fmt_fn) |>