
<!-- README.md is generated from README.Rmd. Please edit that file -->

# `allofus` R Package

<!-- badges: start -->

[![R-CMD-check](https://github.com/roux-ohdsi/allofus/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/roux-ohdsi/allofus/actions/workflows/R-CMD-check.yaml)
[![CRAN
status](https://www.r-pkg.org/badges/version/allofus)](https://CRAN.R-project.org/package=allofus)
[![](http://cranlogs.r-pkg.org/badges/grand-total/allofus)](https://cran.r-project.org/package=allofus)
[![](https://img.shields.io/badge/DOI-10.1093%2Fjamia%2Focae198-007ec6)](https://www.doi.org/10.1093/jamia/ocae198)
<!-- badges: end -->

The goal of the `allofus` R package is to streamline the use of R within
the [All of Us Researcher
Workbench](https://www.researchallofus.org/data-tools/workbench/). It
has 4 primary goals:

1.  Facilitate the use of popular `tidyverse` ecosystem of R packages on
    the Researcher Workbench
2.  Help researchers more efficiently and accurately extract and
    synthesize survey data and EHR data
3.  Increase the interoperability between tools created by the
    Observational Health Data Sciences and Informatics community (OHDSI)
    for the [OMOP
    CDM](https://www.researchallofus.org/faq/what-is-omop/)) and the
    Researcher Workbench
4.  Make connecting to the database and managing files simple

*The `allofus` R package was developed by Louisa Smith and Rob Cavanaugh
at [Northeastern University](https://ohdsi.northeastern.edu) and is not
affiliated with or endorsed by the All of Us Research Program.*

### Installation

Install the released version of `allofus` from CRAN:

``` r
install.packages("allofus")
```

Install the development version from Github:

``` r
install.packages("pak")
pak::pak("roux-ohdsi/allofus")
```

### Use

Read through the [getting
started](https://roux-ohdsi.github.io/allofus/vignettes/allofus.html)
vignette to learn how to use the package.

### A note on “Workbench 2.0”

The All of Us Researcher Workbench has migrated to a new, Verily-based
platform (“Workbench 2.0”). A few things work differently there compared
to the original workbench:

- **Buckets aren’t created automatically.** Workbench 2.0 workspaces no
  longer come with a `WORKSPACE_BUCKET` set up for you. Run
  `aou_create_bucket()` once per workspace to create one (or
  `aou_create_bucket(temporary = TRUE)` for a bucket that auto-deletes
  its contents after a couple of weeks) before using `aou_ls_bucket()`
  and related functions.
- **Environment variables are resolved behind the scenes.**
  `WORKSPACE_CDR` and `GOOGLE_PROJECT` are no longer injected as OS
  environment variables on workbench 2.0. `allofus` resolves them
  automatically via the `wb` CLI when the package loads, and caches the
  result to `~/.aou-env` so subsequent sessions don’t need to re-resolve
  them.

This was last tested on September 2, 2026, in a workbench 2.0 workspace
using CDR version 9 and RStudio, with:

``` r
install.packages("pak")
pak::pak("roux-ohdsi/allofus")
library(allofus)
con <- aou_connect()
```

Workspaces are configured differently as the workbench changes, so
please let us know (via the “Issues” tab) if a new workspace doesn’t
work with this code.

### Citation

Please cite the `allofus` package as:
<p>

Smith LH, Cavanaugh R (2024). “allofus: An R Package to Facilitate Use
of the All of Us Researcher Workbench.” <em>Journal of the American
Medical Informatics Association</em>, ocae198.
<a href="https://doi.org/10.1093/jamia/ocae198">doi:10.1093/jamia/ocae198</a>.
</p>

or with

``` r
citation("allofus")
```

*Note: A pre-print can be found here:
<https://doi.org/10.1101/2024.04.10.24305611>, or feel free to contact
us if you can’t access the article.*

We also encourage you to reference the specific version of the package
you use for an analysis. You can look this up with

``` r
packageVersion("allofus")
```

### Bugs

Please leave us comments, requests, and report bugs using the “Issues”
tab on github.
