retrieve {magmaR}

Download data from magma as a tsv, and convert to a data.frame

Description

Analogous to the '/retrieve' function of magma, with format = "tsv"

Usage

retrieve(
  target,
  projectName,
  modelName,
  recordNames = "all",
  attributeNames = "all",
  filter = "",
  page = NULL,
  pageSize = 10,
  showDisconnected = FALSE,
  ...
)

Arguments

target

A list, which can be created using magmaRset, containing your authorization 'token' (a string), a 'url' of magma to target (a string), and optional 'opts' for specifying additions parameters for curl requests (a named list).

projectName

Single string. The name of the project you would like to interact with. For options, see retrieveProjects.

modelName

Single string. The name of the subset data structure within the project, which are referred to as 'model's in magma, to interact with. For options, see retrieveModels or https://timur.ucsf.edu/<projectName>/map.

recordNames

Single string or string vector indicating which particular sample/tube/etc. records to target. Options are "all" or any combination of individual record names. To retrieve individual options, see retrieveIds.

attributeNames

Single string or string vector indicating which features of the data to target. Options are "all" or any combination of individual attribute names. To retrieve individual options, see retrieveAttributes.

filter

String. Potential filter(s) of the data. Example: "<targetAttributeName>~GYN" to filter to records where <targetAttributeName> contains "GYN".

Refer to https://mountetna.github.io/magma.html#retrieve for more details about options and format.

page

Integer. For retrieving just a portion of the data, sets which slice to get.

pageSize

Integer. For retrieving just a portion of the data, sets slice/page size, which is equivalent to the a number of rows.

showDisconnected

Boolean. Set to true to access "disconnected" records, which are records that are missing an (upstream) parent linkage, and so do not connect up with the project's top-level project record. Generally, disconnected records are ones that were deemed low quality in some way, thus were purposefully disconnected from the rest of the dataset. But sometimes a record might just be disconnected because an upload went awry.

...

Additional parameters passed along to the internal '.retrieve()', '.query()', or '.update()' functions, for troubleshooting or advanced-user purposes only:

• request.only (Logical) & json.params.only (Logical) which 1) stop the function before its main curl request to magma and 2) returns the values that would have been sent to magma in either of two formats.

• verbose (Logical) sets whether to report the status of the curl request after it is performed.

Details

This function makes a curl get request to magma/retrieve, with properly reformatted versions of user inputs, plus format = "tsv". Then, it converts the tsv-string output into a dataframe.

Note: When format = "tsv", magma/retrieve returns just an identifier for matrix-type attributes. To retrieve underlying data for such attributes, use the specialized retrieveMatrix function.

Value

A dataframe

See Also

retrieveMatrix for retrieving attributes of type matrix.

retrieveJSON for similar functionality to retrieve, but where the call to magma/retrieve is made with format = "json" and the output is a list. This output often contains more information, and can retrieve data for attribute types of type matrix, which are not returned by the current function. But in most cases, the data returned by retrieve and retrieveMatrix will suffice.

https://mountetna.github.io/magma.html#retrieve for documentation of the underlying magma/retrieve function.

Examples

if (interactive()) {
    # First, we use magmaRset to create an object which will tell other magmaR
    #  functions our authentication token (as well as some other optional bits).
    # When run in this way, it will ask you to give your token.
    magma <- magmaRset()
    
    # Now we can retrieve data with...
    retrieve(
        target = magma,
        projectName = "example",
        modelName = "rna_seq",
        recordNames = "all",
        attributeNames = "all",
        filter = "")
}