updateMatrix: A matrix-specific wrapper of 'updateValues'
In magmaR: R-Client for 'Magma' of the 'UCSF Mount Etna Data Library'

Description Usage Arguments Details Value See Also Examples

A matrix-specific wrapper of updateValues which can take in a matrix, data.frame, or file path, directly.

updateMatrix(
  target,
  projectName,
  modelName,
  attributeName,
  matrix,
  separator = ",",
  auto.proceed = FALSE,
  revisions.only = FALSE,
  ...
)

`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.
`attributeName`	String naming the matrix attribute for which to upload data.
`matrix`	A matrix or dataframe containing the data to upload to magma. Alternatively, a String specifying the file path of a file containing such data. No matter the provision method, colnames must be record identifiers, and rownames should match the values of 'options' associated with the target 'attribute'. Check the 'See Also' section below for how to determine the needed 'options'.
`separator`	String indicating the field separator to use if providing `matrix` as a file path. Default = `","`.
`auto.proceed`	Logical. When set to TRUE, the function does not ask before proceeding forward with the 'magma/update'.
`revisions.only`	Logical. For troubleshooting purposes, when set to `TRUE`, no data will be sent to magma. Instead, the list structure that would have been passed to the `revisions` input of `updateValues` is returned as output.
`...`	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 utilizes the magma/query function, documented here https://mountetna.github.io/magma.html#update, to upload data to a matrix attribute (named attributeName) of the modelName model of projectName project.

matrix data are provided either as a matrix, dataframe, or file path which points toward such data. If given as a file path, the separator input can be used to adjust for whether the file is a csv (the default, separator = ","), or tsv, separator = "\t", or other format.

Data is then validated by ensuring that all row names are among the valid 'options' of the target attribute (See the See Also section below for a note on how to explore these options yourself.). Rows are reordered to be in the same order as these 'options'.

For any missing 'options', rows of NAs are added.

The data is then transformed and passed along to updateValues.

The updateValues() function will summarize records to be updated and allow the user to double-check this information before proceeding.

This user-prompt step can be bypassed (useful when running in a non-interactive way) by setting auto.proceed = TRUE, but NOTE: It is a good idea to always check carefully before proceeding, if possible. Data can be overwritten with NAs or zeros or the like, but improperly named records cannot be easily removed.

None directly.

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

updateFromDF for a more flexible function for uploading multiple attributes-worth of (non-matrix) data at a time.

updateValues for the more direct replica of magma/update which is more even more flexible that updateFromDF, though a bit more complicated to use.

retrieveTemplate, then check the <output>$models$<modelName>$template$attributes$<attributeName>$options to explore the rownames that your matrix should have.

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

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.
    
    ### Retrieve some data from magma, then update that same data.
    mat <- retrieveMatrix(magma, "example", "rna_seq", "all", "gene_tpm")

    updateMatrix(
        target = magma,
        projectName = "example",
        modelName = "rna_seq",
        attributeName = "gene_tpm",
        matrix = mat)
}