getHighdimData: Obtain a high dimensional dataset for a certain study
In thehyve/heim-RInterface: R Client for accessing the tranSMART RESTful API

Description Usage Arguments Details Value Note Author(s) See Also Examples

This function will retrieve a highdimensional dataset for a specific concept of a certain study. It retrieves the data from the server and parses it, converting the high dimensional data to a data.frame.

1
2
3

getHighdimData(study.name, concept.match = NULL, concept.link = NULL, projection = NULL,
                progress.download = .make.progresscallback.download(),
                progress.parse = .make.progresscallback.parse())

`study.name`	a character string giving the name of a study.
`concept.match`	a character string containing the concept name that should be matched. The `getHighdimData` function will search within the requested study for the first concept which name matches the given string value. It uses the name column of the result from `getConcepts` to perform the matching.
`concept.link`	a character string containing the link pointing to the location of the data on the server. Candidate values for this argument can be found in `api.link.self.href` column of the `getConcepts` results. It is the most exact way to refer to a concept, and it overwrites the `concept.match` argument.
`projection`	a character string specifying what part of the dataset should be returned: should all data be returned or only a certain type of data, for example only the log values for an mRNA data set. Candidate values can be obtained, see details section on how. (note: the types of data present may differ between studies).
`progress.download`	(The default should be fine for most users) A list of functions that will be called during the download, this allows displaying download progress to the user. The list must contain three items of the following signature: `progress.download$start <- function(total) {...} progress.download$update <- function(current, total) {...} progress.download$end <- function() {...}` `start` is called before the download starts, with `total` set to the total number of bytes to be processed. `total` may be `NA` if this information is not available. `update` is called during the download, with `total` as the total number of bytes to be processed and `current` the current number of bytes that have been processed. `total` will generally be the same value as in the call to `start()`. `close` will be called once the download has finished.
`progress.parse`	(The default should be fine for most users) This argument functions identical to `progress.download` but the functions will be called before, during and after the parsing of the downloaded data.

Retrieving and parsing the data may take some time, depending on the size of the data requested and on your connection characteristics.

A dataframe containing the high dimensional data will only be returned if a projection is specified.

To discover what projections are possible call getHighDimData, while only providing a study name and concept, i.e. getHighdimData(study.name, concept.match) or getHighDimData(study.name, concept.link).

If a projection is specified, this function returns a list containing the highdimensional data, with the following components:

`data`	a dataframe containing the high dimensional data.
`labelToBioMarkerMap`	a hash describing which (column) labels refer to which bioMarker. This component will only be present if biomarker data is available for this particular dataset. See `hash` for more details about how to use hashes.

If no projection is specified this function returns a list of the projections available for the requested study. No highdimensional data is returned. It will also print the instruction to set the projection argument and a list of the projections that are available.

To be able to access a transmart database, you need to be connected to the server the database is on. If you haven't connected to the server yet, establish a connection using the connectToTransmart function.

Tim Dorscheidt, Jan Kanis, Rianne Jansen. Contact: development@thehyve.nl

hash, getStudies, getConcepts.

## Not run: 

  # if a concept contains high dimensional data, use the following command to obtain this data:
  getHighdimData(study.name = "GSE8581", concept.match = "Lung")

  # you will be told that one of the listed projections needs to be selected: 
  "No valid projection selected.
  Set the projection argument to one of the following options:
    default_real_projection 
    zscore 
    log_intensity 
    all_data"
 
  # the following will return the actual data:
  data <- getHighdimData(study.name = "GSE8581", concept.match = "Lung", projection = "zscore")
  
## End(Not run)