updateValues {magmaR}

Analogous to the '/update' function of magma

Description

Analogous to the '/update' function of magma, allows data to be sent to magma (by users with at least "editor" authorization).

Usage

updateValues(
  target,
  projectName,
  revisions = list(),
  auto.proceed = FALSE,
  autolink = FALSE,
  dryRun = 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.

revisions

A list of named lists containing the data to be updated.

List structure:

• top level name(s): modelNames, can be 1 or more.

• 2nd level name(s): recordNames, can be 1 or more.

• 3rd level name(s) & contents: the attributes to update & the values to use.

See https://mountetna.github.io/magma.html#update for additional formatting details.

auto.proceed

Logical. When set to TRUE, the function does not ask before proceeding forward with the 'magma/update'.

autolink

Logical. FALSE by default for safety, but often you will want to set it to TRUE. Passed through to magma, this parameter controls whether the system will attempt to connect all targeted records up with the project's root. Specifically, this means the system will 1) determine parent records of all targeted records if it can, based on the project's gnomon grammar, 2) continue parent determination for those parent records, repeating this process until reaching the project's root (the project record), then 3) creates any of these records that don't currently exist, and finally 4) creates all the assumed parent-child linkages

dryRun

Logical. FALSE by default. Passed through to magma, this parameter controls whether the system will only test whether the update is valid without making changes to the database.

...

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 mimics the activity of the magma/update function, documented here https://mountetna.github.io/magma.html#update, with the main difference being that the revisions input should be in nested list format rather than nested hash (because R does not support hash structures).

Internally, the function:

1. Summarizes records of each model that will be targeted for updating.

2. Prompts the user before proceeding (unless auto.proceed is set to TRUE)

3. Directly passes its inputs along to magma/update via a curl request.

Value

None directly.

The function sends data to magma, and the only outputs are information reported via the console.

See Also

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

updateMatrix for a matrix-dedicated version of this function which can be provided a matrix, or matrix's file location, directly.

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()
    
    # Note that you likely do not have write-permissions for the 'example'
    # project, so this code can be expected to give an authorization error.

    updateValues(
        target = magma,
        projectName = "example",
        autolink = TRUE,
        dryRun = FALSE,
        revisions = list(
            # model
            'rna_seq' = list(
                # record
                'EXAMPLE-HS1-WB1-RSQ1' = list(
                    # attribute
                    'fraction' = list(
                        # value(s)
                        "Tcells"
                        )
                    )
                )
            )
        )
}