requireNamespace("knitr") knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
In this example, we're going to explore the capabilities of the phenotype-services using the gorr
package.
First load the gorr
package, the tidyverse
package is recommended in general, but not required for this example
library(gorr) library(magrittr) # pipe library(tibble)
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
If everything goes as planned, we'll have a conn
object to pass into subsequent functions.
Let's start by fethcing available phenotypes in project (first 25)
phenotypes <- get_phenotypes(conn, limit=25) print(phenotypes[1:4])
The results come back as a list
of phenotypes
Next, let's fetch a phenotype from the project. We'll use the first listed
phenotype <- get_phenotype(name = names(phenotypes)[1], conn) phenotype
The results come back as a phenotype
object, which is a list of lists containing different info on the phenotype
object.
We can add a new phenotype to the project using the create_phenotype
function as follows
name <- paste0("rtest_pheno", sample(1:99,1)) # Name of new phenotype result_type <- "CATEGORY" # Type of phenotype (either "QT", "SET" or "CATEGORY") description <- "This is a test phenotype" # Optional phenotype description new_phenotype <- create_phenotype(name, result_type, conn, description) new_phenotype
A new phenotype has now been added to the project's phenotype-catalog as well as been assigned to the variable new_phenotype
.
Phenotypes can also be created using the full set of metadata in a single call and with a GOR/NOR query.
##NOT RUN## gor_query <- " def #phenos# = added_salt_to_food; create ##aggregate## = nor UKBB/phenotypes/fields.nord -s phenotype -f #phenos# | ATMAX visit_id -gc PN,phenotype | map -h -m '#empty#' -c phenotype,value <(nor -h UKBB/phenotypes/meta/field_encoding_lookup.tsv) | REPLACE value if(meaning = '#empty#',value,meaning) | hide meaning,visit_id,index_id; nor [##aggregate##] | sort -c PN | pivot phenotype -ordered -gc PN -v #phenos# -e NA | rename (.*)_value #{1} | select PN " name2 <- paste0("rtest_pheno", sample(1:99,1)) description2 <- "A set of individuals who answered YES to the question: do you salt your food? https://biobank.ndph.ox.ac.uk/ukb/field.cgi?id=104660" result_type2 <- "SET" category2 <- "symptoms" query2 <- gor_query tags2 <- "dietary,nutrition" new_phenotype2 <- create_phenotype(name2, result_type2, conn, description2, query = query2, tags = tags2) new_phenotype2 phenotype_delete(new_phenotype2, conn)
If we see the phenotype's state is 'pending', or we simply want to refresh the phenotype for fetching most recent info on the phenotype,
we can refresh the phenotype using the phenotype_refresh
method
new_phenotype <- phenotype_refresh(new_phenotype, conn) new_phenotype
In case the query fails we can call either phenotype_get_error(phenotype, conn)
, returning latest error (formatted) or phenotype_get_errors(phenotype, conn)
which returns all errors as lists along with their timestamps.
Passing a phenotype object and a new description to phenotype_update_description
updates the phenotype's description in the project's phenotype-catalog. The output is, again, an updated phenotype
object.
new_description <- "An updated description" new_phenotype <- phenotype_update_description(new_description, new_phenotype, conn) new_phenotype
Let's start by creating a dummy dataset which is a list of list: [[PN#1, attribute], [PN#2, attribute], ... , [PN#N, attribute]]
cohort_size <- 2000 pns <- as.character(1000:cohort_size+1000) data <- lapply(pns, function(x) { list(x, if (runif(1)>0.5) 'obease' else 'lean') }) print(data[1:2]) phenotype_upload_data(new_phenotype, data, conn)
Phenotype data can then be fetched using get_data
:
get_data(new_phenotype, conn)
We can list all available tags in the catalog using get_tags
and passing the platform_connection
object.
get_tags(conn)[1:4]
Retrieve all tags for phenotype
phenotype_get_tags(new_phenotype)
Add a new tag/s to this phenotype. Multiple tags should be separated by either comma separated string, "tag1,tag2"
, character vector c("tag1", "tag2")
or a combination of the two
new_phenotype <- phenotype_add_tag(tag = "testTag2", new_phenotype, conn) phenotype_get_tags(new_phenotype)
for assurance we can get the phenotype from server and check tags
get_phenotype(name, conn) %>% phenotype_get_tags()
Set the tag list for this phenotype, overriding all previous tags, defining the tags adheres to the same rules as add_phenotype_tag
tags <- "testTag7,testTag8" new_phenotype <- phenotype_set_tags(tags, new_phenotype, conn) phenotype_get_tags(new_phenotype)
again, for assurance let's load the tags from server
get_phenotype(name, conn) %>% phenotype_get_tags()
Delete a tag/s from phenotype.
new_phenotype <- phenotype_delete_tag(tag = "testTag7", new_phenotype, conn) phenotype_get_tags(new_phenotype) #or get_phenotype(name, conn) %>% phenotype_get_tags()
A phenotype can easily be removed from a project using the phenotype_delete
function.
phenotype_delete
expects a phenotype
object. Therefore the phenotype needs to be fetched using the get_phenotype
function if it has not been assigned to a variable already.
phenotype_delete(new_phenotype, conn)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.