query {magmaR}

Search-like function that can obtain linked data from distinct models.

Description

Analogous to the '/query' function of magma.

Usage

query(target, projectName, queryTerms = list(), format = c("list", "df"), ...)

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.

queryTerms

A list of strings where list elements are query predicates and verbs. See https://mountetna.github.io/magma.html#query for details.

format

Either "list" or "df" (=dataframe). This sets the desired output format. The list option is the more raw form.

...

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 initially mimics the activity of the magma's /query functionality, which is documented here https://mountetna.github.io/magma.html#query.

Afterwards, the json list output of magma/query is converted into an R list, and then the format input determines whether it should be wrangled further:

• format = "list", default: R list output directly.

• format = "df": R list converted into a dataframe where data comes from the list$answer and column names come from the list$format

Value

A list, default, if format == "list",

OR A dataframe conversion if format = "df"

See Also

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

retrieveProjects for exploring options for the projectName input.

retrieveModels, retrieveIds, and retrieveAttributes and retrieveTemplate for exploring the project structure and determining queryTerm options.

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()
    
    ### To obtain the 'group' attribute, from the subject-model, that are
    #   associated with records of the rna_seq-model:

    # "Raw" output of query:
    query_list <- query(
        target = magma,
        projectName = "example",
        queryTerms = 
            list('rna_seq',
                 '::all',
                 'biospecimen',
                 'subject',
                 'group'))
    print(query_list)
                 
    # Or instead re-formatted to a dataframe, which may be easier for
    #   downstream applications in R:
    query_df <- query(
        target = magma,
        projectName = "example",
        queryTerms = 
            list('rna_seq',
                 '::all',
                 'biospecimen',
                 'subject',
                 'group'),
        format = 'df')
    print(query_df)
}