---
title: "Using ATLAS to create a cohort"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Using ATLAS to create a cohort}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  eval = FALSE,
  comment = "#>"
)
```

It is often useful to build more complex cohort definitions using ATLAS, a web-based application that allows users to define cohorts and run analyses on the OHDSI network. While most of the features of ATLAS are not compatible with the AllofUS researcher workbench, the All of Us R package includes a 
function to download a cohort definition from ATLAS and generate the cohort in the All of Us database.

To use this feature of the `allofus `package, you'll also need to install the [`ROhdsiWebApi`](https://github.com/OHDSI/ROhdsiWebApi) package from GitHub. This package is used to query the ATLAS API and download the cohort definition and SQL query. The package is not available on CRAN (and is therefore not included with the `allofus package`), but it can be installed using the `pak` package:

```{r install}
install.packages("pak")
pak::pak("ohdsi/ROhdsiWebApi")
```

After installing the `ROhdsiWebApi` package, load the `allofus` package and the `ROhdsiWebApi` package:

```{r load}
library(allofus)
library(ROhdsiWebApi)
```

If you haven't already, this is the time to build your cohort definition in ATLAS. You can use the publicly available [demo version of ATLAS](https://atlas-demo.ohdsi.org) which is pre-populated with many sample cohort definitions (though keep in mind that they are not validated). You can also use an ATLAS instance
in your organization's OMOP CDM. (A free, instructional course for using ATLAS is available through [EHDEN Academy](https://academy.ehden.eu/).)

In this case, we'll use the cohort definition 1788061, which is a simple stroke cohort definition.

Using `ROhdsiWebApi`, we can download the cohort definition and SQL query from ATLAS:

```{r ohdsiweb}
cd <- ROhdsiWebApi::getCohortDefinition(1788061, "https://atlas-demo.ohdsi.org/WebAPI")
cd_sql <- ROhdsiWebApi::getCohortSql(cd, "https://atlas-demo.ohdsi.org/WebAPI")
```

*Note: Occasionally, some of the code in `getCohortSql()` is not compatible with `aou_atlas_cohort()`. If you encounter an error, try setting
`generateStats = FALSE` in `ROhdsiWebApi::getCohortSql()` and running `aou_atlas_cohort()` again*

Then, we can use the `aou_atlas_cohort()` function to generate the cohort in the All of Us database.

```{r cohort}
cohort <- aou_atlas_cohort(
  cohort_definition = cd,
  cohort_sql = cd_sql
)
```

Because the All of Us program does not use the [typical heuristics](https://ohdsi.github.io/CommonDataModel/ehrObsPeriods.html) for the `observation_period` table, observation periods are first generated for each subject using the `aou_observation_period()` function. After generating a new `observation_period` table, the SQL from `ROhdsiWebApi::getCohortSql()` will extract a cohort from the All of Us database - resulting in a *local* dataframe with the cohort start and end dates for each subject who fell within the cohort definition. (The function is based on code from https://github.com/cmayer2/r4aou with some tweaks to generate the appropriate observation periods and incorporate other package functions.)

```{r}
head(cohort)
```
```
#> # A tibble: 6 × 4
#>   cohort_definition_id person_id cohort_start_date cohort_end_date
#>                  <int> <int>     <date>            <date>         
#> 1              1788061 xxxxxxx   1995-03-27        1995-03-27     
#> 2              1788061 xxxxxxx   2012-01-07        2012-01-21     
#> 3              1788061 xxxxxxx   2010-06-17        2016-04-05     
#> 4              1788061 xxxxxxx   2015-08-12        2017-08-30     
#> 5              1788061 xxxxxxx   2017-01-24        2019-01-24     
#> 6              1788061 xxxxxxx   2008-07-09        2019-01-24
```

To use this cohort table further, you can join it to other tables from the All of Us database (after they have been "collected"). Or, 
to use this table to limit the person table (or other OMOP CDM tables) to only your cohort, filter for the values in the `cohort$person_id` column:

```{r}
dplyr::tbl(con, "person") %>%
  dplyr::filter(person_id %in% !!cohort$person_id)
```