query: Search-like function that can obtain linked data from...
In magmaR: R-Client for 'Magma' of the 'UCSF Mount Etna Data Library'

Description Usage Arguments Details Value See Also Examples

Analogous to the '/query' function of magma.

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

`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.

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

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

OR A dataframe conversion if format = "df"

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.

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)
}