Phenotype playlists

In this example, we’re going to demonstrate how to interact with the phenotype playlist API using the gorr package.

One or more phenotypes can be grouped into a playlist. A playlist works like an added layer of curation on the phenotypes. For example, it could be a set of heart failure-related phenotypes or a set of principle components. It may just be an easy way to share work between people working on a team. Playlists make it easier to recall work between days. The methods for working with playlists are below:

Loading required packages

library(gorr)
library(magrittr) # pipe

Connect to Genuity Science’s services.

First we’ll need to establish a connection to our API services. To do that we’ll need to call platform_connect and provide it with the relevant parameters pointing to the phenotype-catalog-service, i.e. api_key and project:

conn <- platform_connect(api_key = Sys.getenv("GOR_API_KEY"),
                          project = Sys.getenv("GOR_API_PROJECT"))
conn
#> ── GOR API service connection ──────────────────────────────────────────────────
#> • Service Root/s: https://platform.wuxinextcodedev.com/api/query, https://platform.wuxinextcodedev.com/api/phenotype-catalog, https://platform.wuxinextcodedev.com/queryserver, https://platform.wuxinextcodedev.com/workflow
#> • Project: ukbb_hg38
#> • API key issued at: 2022-05-18 10:18:54
#> • API key expires at: Never
#> • Access token issued at: 2022-06-16 15:56:07
#> • Access token expires at: 2022-06-17 15:56:07

If everything goes as planned, we’ll have a conn object to pass into subsequent functions.

List available playlists

Playlists available to users can be listed by passing the conn object to get_playlists.

playlists <- get_playlists(conn)
playlists
#>  [1] "oktobertest1634900223" "oktobertest1634905751" "oktobertest1634907885"
#>  [4] "My covariates14"       "Basic statistics"      "Pulmonology"          
#>  [7] "Cancers"               "Eye diseases"          "Age of diagnoses"     
#> [10] "Anna's playlist"       "Anna's playlist2"      "Asthma"               
#> [13] "Demo Playlist"         "andri tests"           "rtestpack_pl227"      
#> [16] "rtestpack_pl742"       "oktobertest"           "rtestpack_pl477"      
#> [19] "rtestpack_pl871"       "oktobertest17"         "oktobertest18"        
#> [22] "oktobertest1634815382" "oktobertest1634815564" "oktobertest1634818035"
#> [25] "oktobertest1634826210" "oktobertest1634828000"

The results come back as a vector of playlist names available to the user.

Create playlist

If we want to add a new playlist to the catalog we can do so using create_playlist along with the name of the playlist and optionally description and name of phenotypes to be addied to the playlist. To add multiple phenotypes when initializing a new playlist you can either do so by providing a comma seperated string, "pheno1,pheno2" or character vector c("pheno1","pheno2")

NB: Before adding phenotype/s to a playlist, make sure the phenotypes exist in the project, to list all phenotypes see get_phenotypes.

name <- paste0("Diabetes", sample(1:99,1)) # Name of new playlist
descr <- "A set of all phenotypes related to diabetes in UKBB"
new_playlist <- create_playlist(name, conn, description = descr)

A new playlist has now been added to the project. The results come back as a playlist object.

#> ── Phenotype playlist ──────────────────────────────────────────────────────────
#>  $name: Diabetes73
#>  $id: 715
#>  $description: A set of all phenotypes related to diabetes in UKBB
#>  $phenotypes: 
#>  $created_by: andri@genuitysci.com

Get playlist

We can also get an existing playlist by providing the playlist’s name (or id) along with the connection obect.

pl <- get_playlist(name = name, conn = conn)

As before the results come back as a playlist object.

If needed, playlists can be refreshed for fetching most recent info on the playlist by calling playlist_refresh as follows:

new_playlist <- playlist_refresh(new_playlist, conn)
#> Warning in deprecated_argument_msg(conn) %>% warning(): conn argument deprecated

Add phenotype to playlist

Once a playlist has been fetched or created we can add phenotypes to it. As for adding phenotypes when creating a new playlist we need to make sure that the phenotype does exist in the catalog and has not been assigned to the playlist already.

# Create a test phenotype 
pheno_name <- paste0("rtest_pheno", sample(1:1000,1)) # Name of new phenotype
result_type <- "CATEGORY" # Type of phenotype (either "QT", "SET" or "CATEGORY")
tmp_phenotype <- create_phenotype(pheno_name, result_type, conn)
new_playlist  <- playlist_add_phenotype(pheno_name, new_playlist, conn)
#> Warning in deprecated_argument_msg(conn) %>% warning(): conn argument deprecated
print(new_playlist$phenotypes[1:4])
#> $rtest_pheno209
#> ── Phenotype ───────────────────────────────────────────────────────────────────
#>  $name: rtest_pheno209
#>  $description: 
#>  $result_type: CATEGORY
#>  $tag_list: 
#>  $pn_count: 
#>  $query: 
#> 
#> $<NA>
#> NULL
#> 
#> $<NA>
#> NULL
#> 
#> $<NA>
#> NULL

Delete playlist

A playlist can easily be deleted by passing a playlist object to the playlist_delete function.

playlist_delete(new_playlist, conn)
#> Warning in deprecated_argument_msg(conn) %>% warning(): conn argument deprecated
#> Response [https://platform.wuxinextcodedev.com/api/phenotype-catalog/projects/ukbb_hg38/playlists/715]
#>   Date: 2022-06-16 15:56
#>   Status: 204
#>   Content-Type: <unknown>
#> <EMPTY BODY>
#Clean up phenotype
phenotype_delete(tmp_phenotype, conn)
#> Warning in deprecated_argument_msg(conn) %>% warning(): conn argument deprecated
#> Response [https://platform.wuxinextcodedev.com/api/phenotype-catalog/projects/ukbb_hg38/phenotypes/rtest_pheno209]
#>   Date: 2022-06-16 15:56
#>   Status: 204
#>   Content-Type: <unknown>
#> <EMPTY BODY>

Andri M. Stefansson andri@genuitysci.com