api_interface.R

# interface to end points version 2 via R using httr #

# David L Gibbs
# Institute for Systems Biology
# Sept 22, 2016

# The API v2
# https://apis-explorer.appspot.com/apis-explorer/?base=https://api-dot-isb-cgc.appspot.com/_ah/api#p/isb_cgc_api/v2/

################################################################################
#  google httr tutorial
#  Huge thanks to Hadley: https://github.com/hadley/httr/blob/master/demo/oauth2-google.r
#
# 1. Find OAuth settings for google:
#    https://developers.google.com/accounts/docs/OAuth2InstalledApp
#oauth_endpoints("google")
#
# 2. Register an application at https://cloud.google.com/console#/project
#myapp <- oauth_app("google", key = CLIENT_ID, secret = CLIENT_SECRET)
#
# 3. Get OAuth credentials
#google_token <- oauth2.0_token(oauth_endpoints("google"), myapp, scope = "https://www.googleapis.com/auth/userinfo.profile")
#
# 4. Use API
#req <- GET("https://www.googleapis.com/oauth2/v1/userinfo", config(token = google_token))
#stop_for_status(req)
#content(req)
###############################################################################


library(httr)

#' Initialize the authorization
#'
#' Creates a auth token needed for cohort related functions.
#'
#' @details Uses the httr package to create an OAuth2.0 token with Google.
#'
#' @return An Oauth token
#' @examples
#' \dontrun{
#' isb_init()
#' }
#' @export
isb_init <- function() {
	library(httr)
	# for native application - same as settings.INSTALLED_APP_CLIENT_ID
	CLIENT_ID = "907668440978-0ol0griu70qkeb6k3gnn2vipfa5mgl60.apps.googleusercontent.com"
	# NOTE: this is NOT actually a 'secret' -- we're using the 'installed
	# application' OAuth pattern here
	CLIENT_SECRET = "To_WJH7-1V-TofhNGcEqmEYi"
	EMAIL_SCOPE = "https://www.googleapis.com/auth/userinfo.email"
	myapp <- oauth_app("google", key = CLIENT_ID, secret = CLIENT_SECRET)
	isb_token <- oauth2.0_token(oauth_endpoints("google"), myapp, scope = EMAIL_SCOPE)
	isb_token
}


#' Data file filter
#'
#' Filter the results from datafilenamekeys
#'
#' The call to the datafilenamekeys API returns a list with platform types
#' in the strings. This filters down the list of files by platform.
#'
#' @param filelist The return data, a vector of characters, from sample_files
#' @param filterby A string, naming a platform
#' @return List of files
#'
#' @examples
#' \dontrun{
#'   fs <- sample_files("TCGA-A7-A6VV-10A")
#'   datafile_filter(sf, ".bam")
#'  }
#' @export
datafile_filter <- function(filelist, filterby) {
	x <- filelist$datafilenamekeys
  y <- x[str_detect(x, filterby)]
	unlist(y)
}


#' Get cloud file paths
#'
#' Get file locations using sample barcode
#'
#' Uses the API to get a list of files for a given barcode.
#'
#' @param sample_barcode A TCGA barcode.
#' @return List of files across platforms.
#' @examples
#' \dontrun{
#'   fs <- sample_cloud_storage_file_paths("TCGA-A7-A6VV-10A")
#'  }
#' @export
sample_cloud_storage_file_paths <- function(sample_barcode) {
  b <- paste("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_tcga_api/v3/samples/",sample_barcode,"/cloud_storage_file_paths", sep="")
	content(GET(url=b))
}


#' sample_get
#'
#' Get details on a particular sample, given a sample barcode
#'
#' @param sample_barcode A TCGA sample barcode
#'
#' @returns List Details on a given sample_details
#'
#' @examples
#' \dontrun{
#'   sample_get("TCGA-A7-A6VV-10A")
#' }
#' @export
sample_get <- function(sample_barcode) {
	b <- paste("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_tcga_api/v3/samples/", sample_barcode, sep="")
	content(GET(b))
}


#' case_annotations
#'
#' Get details on a particular patient, given a sample barcode
#'
#' @param sample_barcode A TCGA patient barcode like "TCGA-02-0001"
#'
#' @returns List Details on a given case
#'
#' @examples
#' \dontrun{
#'   case_annotations("TCGA-A7-A6VV")
#'  }
#' @export
case_annotations <- function(patient_barcode) {
  b = paste("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_tcga_api/v3/cases/", patient_barcode, "/annotations", sep="")
	content(GET(b))
}

#' List cohorts
#'
#' Using your auth token, as generated by isb_init(), get a list of previously created cohorts.
#' The result is a list, with two important elements: count (giving the number of saved cohorts) and items
#' (which contain the cohort ID as result$items[[x]]$id, and name as result$items[[x]]$name).
#'
#' @param a_token Auth token as returned by isb_init()
#'
#'
#' @examples
#' \dontrun{
#'   list_cohorts(mytoken)
#'  }
#' @export
list_cohorts <- function(a_token) {
  req <- GET("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_api/v3/cohorts", config(token = a_token))
	stop_for_status(req)
	content(req)
}


#' Create cohorts
#'
#' Using your auth token, create a new cohort
#'
#' @param a_token Your auth token
#' @param cohort_name The name of the new cohort
#' @param filter_list The list of filter parameters defining the cohort
#' @returns List
#'
#' @examples
#' \dontrun{
#'   create_cohorts(token, "new_cohort_jun7", list(project_short_name="TCGA-UCS", vital_status="alive"))
#' }
#' @export
create_cohorts <- function(a_token, cohort_name, filter_list) {
	b <- paste0("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_tcga_api/v3/cohorts/create?name=",cohort_name)
	req <- POST(b, query=filter_list, config(token = a_token))
	stop_for_status(req)
	content(req)
}


#' Preview cohorts
#'
#' Using your auth token, create a cohort, without saving
#'
#' @param filter_list The list of filter parameters defining the cohort
#'
#' @returns List Details on the cohort
#'
#' @examples
#' \dontrun{
#'   preview_cohort(list(project_short_name="TCGA-UCS", vital_status="alive"))
#' }
#' @export
preview_cohort <- function(filter_list) {
	# example: preview_cohort(list(Study="BRCA", vital_status="alive"))
	require(httr)
	q1 <- sapply(1:length(filter_list), function(i) paste(names(filter_list)[i], filter_list[[i]], sep="="))
	q2 <- paste(q1, collapse="&")
  b  <- paste("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_tcga_api/v3/cohorts/preview?", q2, sep="")
	content(GET(b))
}


#' Data files from a cohort
#'
#' Using a defined cohort, get file paths to a Google bucket
#'
#' @param cohort_id The list of filter parameters defining the cohort
#' @param platform The platform used for data generation
#' @param token Your auth token
#'
#' @returns List with count and file paths
#'
#' @examples
#' \dontrun{
#'   datafiles_from_cohort("69", a_token=mytoken)
#' }
#' @export
cohort_cloud_storage_file_paths <- function(cohort_id, platform=NULL, a_token) {
	require(httr)
	b <- paste("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_api/v3/cohorts/", cohort_id, "/cloud_storage_file_paths", sep="")
	if (!is.null(platform)) {
		b <- paste(b, "?platform=", platform, sep="")
	}
	content(GET(b, config(token = a_token)))
}

#' List of barcodes from a cohort
#'
#' Using a defined cohort, get sample and patient barcodes
#'
#' @param cohort_id The list of filter parameters defining the cohort
#' @param token Your auth token
#'
#' @returns List of barcodes
#'
#' @examples
#' \dontrun{
#'   sample_list_cohort(list("29"), mytoken)
#' }
#' @export
cohort_barcodes <- function(cohort_id, a_token) {
  require(httr)
  b <- paste("https://api-dot-isb-cgc.appspot.com/_ah/api/isb_cgc_api/v3/cohorts/",cohort_id,sep="")
  content(GET(b, config(token = a_token)))
}