Necessary inputs:

In addition to the normal target and projectName inputs here, modelName, and attributeName are also used to direct where to upload your matrix data.

A separate matrix input takes in the target data. This can be given a matrix or data.frame directly, or a string representing the path to a csv or tsv file containing such data. In all cases, matrix must be formatted to have:

• Column Names (or the first row when providing a file) = the identifiers of target records
• Column Data = the values for each record
• Row Names (or the first column when providing a file) = the names of what data is in each row, ex: gene ids for rna_Seq data. These must be among the allowed ‘options’ for the target attribute. (See the ‘See Also’ section of ?updateMatrix for one method of finding out what these ‘options’ are.)

When matrix points to a file, the optional separator input can be used to indicate between csv (default assumption) versus tsv parsing.

Example:

To update the raw counts of our “rna_seq” model from either a csv, a tsv, or directly from a matrix, we could use the code below:

### From a csv
updateMatrix(
    target = prod,
    projectName = "example",
    modelName = "rna_seq",
    attributeName = "gene_counts",
    matrix = "path/to/rna_seq_counts.csv")

### From a tsv, set the 'separator' input to "\t"
updateMatrix(
    target = prod,
    projectName = "example",
    modelName = "rna_seq",
    attributeName = "gene_counts",
    matrix = "path/to/rna_seq_counts.tsv",
    # Use separator to adjust parsing for tab-separated values
    separator = "\t")

### From an already loaded matrix:
matrix <- retrieveMatrix(target = prod, "example", "rna_seq", "all", "gene_counts")
updateMatrix(
    target = prod,
    projectName = "example",
    modelName = "rna_seq",
    attributeName = "gene_counts",
    matrix = matrix)

Let’s explore the structure of matrix a little bit, noting that:

1. Column names for the matrix are record identifiers for the target “rna_seq” model.
2. Row names for the matrix are the feature-names for the matrix. So for rna_seq data, for example, these will be gene names of some type, typically Ensembl IDs.

head(matrix, n = c(6,2))

##       EXAMPLE-HS10-WB1-RSQ1 EXAMPLE-HS11-WB1-RSQ1
## gene1                     4                     8
## gene2                   231                    43
## gene3                   861                   155
## gene4                  2077                   427
## gene5                     3                     2
## gene6                     0                     0

Necessary inputs:

In addition to the normal target and projectName inputs, here a modelName is also needed in order to direct where to upload your data.

A separate df input then takes in the target data. df can be given as a data.frame directly, or as a string representing the path to a csv or tsv file containing such data. In all cases, df must be formatted to have:

• Rows: represent records, with the first column indicating the record identifiers.
• Columns: represent the data desired to be given for each attribute.
• Column Names (or the top row when providing a file): attribute names.
  • When modelName targets a ‘standard’ model that uses identifiers, the first column must provide current identifiers. A separate column can be named as the identifier attribute if there is need to update record names.
  • When modelName targets a ‘table’ model that does not rely on identifiers, at least one column must be named after the parent model Except for the first column (ignored as this column’s data are used as identifiers), all column names must be valid attribute names of the target modelName.

When df points to a file, the optional separator input can be used to indicate between csv (default assumption) versus tsv parsing.

Example1, ‘standard’ model:

To update multiple attributes of multiple records of our “rna_seq” model from either a csv, a tsv, or directly from a data.frame, we could use the code below:

### From a csv
updateFromDF(
    target = prod,
    projectName = "example",
    modelName = "rna_seq",
    df = "path/to/rna_seq_attributes.csv")

### From a tsv, set the 'separator' input to "\t"
updateFromDF(
    target = prod,
    projectName = "example",
    modelName = "rna_seq",
    df = "path/to/rna_seq_attributes.tsv",
    # Use separator to adjust parsing for tab-separated values
    separator = "\t")

### From an already loaded data.frame:
df <- retrieve(target = prod, "example", "rna_seq", "all",
               c("tube_name", "cell_number", "fraction"))
updateFromDF(
    target = prod,
    projectName = "example",
    modelName = "rna_seq",
    df = df)

Let’s explore the structure of df a little bit, noting that:

1. The left-most column holds record identifiers.
2. Column 2 onwards are data columns which hold intended data for attributes of each target record.
3. Column names for column 2 onwards are the target attribute-names.

head(df, n = c(6,3))

##               tube_name cell_number fraction
## 1 EXAMPLE-HS10-WB1-RSQ1       50000   Tcells
## 2 EXAMPLE-HS11-WB1-RSQ1       50000   Tcells
## 3 EXAMPLE-HS12-WB1-RSQ1       50000   Tcells
## 4  EXAMPLE-HS1-WB1-RSQ1       50000   Tcells
## 5  EXAMPLE-HS2-WB1-RSQ1       50000   Tcells
## 6  EXAMPLE-HS3-WB1-RSQ1       50000   Tcells

One final note: The identifier column’s name, though accurately the name of the identifier attribute here, does not actually matter. ‘tube_name’ is the name of the identifier attribute of this “rna_seq” model, but we could have named the column anything. This is an intended feature as it allows users to adjust records’ identifiers with this function by providing a separate data column, of new identifiers, with the identifier attribute name as its name!

Example2, ‘table’-type model:

To update multiple entries of a table-type “demographics” model from a data.frame…

df <- data.frame(
    "subject" = paste0("EXAMPLE-HS", c(1:4,1:4)),
    "name" = rep(c("Sex at Birth", "Race"), each = 4),
    "value" = c("Male", "Male", "Female", "Female",
                "White", "Black or African American",
                "Asian", "Decline to answer")
)
df

##       subject         name                     value
## 1 EXAMPLE-HS1 Sex at Birth                      Male
## 2 EXAMPLE-HS2 Sex at Birth                      Male
## 3 EXAMPLE-HS3 Sex at Birth                    Female
## 4 EXAMPLE-HS4 Sex at Birth                    Female
## 5 EXAMPLE-HS1         Race                     White
## 6 EXAMPLE-HS2         Race Black or African American
## 7 EXAMPLE-HS3         Race                     Asian
## 8 EXAMPLE-HS4         Race         Decline to answer

there is one extra decision to be made:

Is your goal extending the data that already exists for the targeted subjects? Or else is the current upload comprehensive for these subjects to where all previous data, in this table, attached to targeted parent records, should be cleared? The answer to this question determines what options to set for the table.method parameter. It must either be set to “append”, or “replace”.

In the code below, we exemplify an “append” case:

updateFromDF(
    target = prod,
    projectName = "example",
    modelName = "demographic",
    table.method = "append",
    df = df)

Note: When using table.method = "append", running the same code multiple times WILL create multiple instances of the same data being put into the model. This is allowed by design. In the example here, it’s likely that you would never want to have multiple entries for a single individual’s “Sex at Birth”, but this same model-type can also be used for treatment information. Having multiple table entries with same name=“drug_name” and and different value=“drug1” or “drug2” attached to the same parent record does make sense.

Necessary inputs:

In addition to the normal target and projectName inputs, revisions is the primary input of updateValues():

• revisions includes information about which model(s), which record(s), and which attribute(s) to update, and with what value(s). Each of these levels are encoded as a nested list where the format looks something like:

revisions = list(
    modelName = list(
        recordName = list(
            attributeName = value(s)
        )
    )
)

To make more than one update within a single call, you can simply add an additional index at any of these levels.

For example, the below revisions would encode some very different updates

# 2 attributes for the same record
revisions = list(
    modelName = list(
        recordName = list(
            attributeName1 = value(s),
            attributeName2 = value(s)
            )
        )
    )

# The same attribute for 2 different records
revisions = list(
    modelName = list(
        recordName1 = list(
            attributeName1 = value(s)
            ),
        recordName2 = list(
            attributeName1 = value(s)
            )
        )
    )

# Some attribute for 2 different records of two different models
revisions = list(
    modelName1 = list(
        recordName1 = list(
            attributeName1 = value(s)
            )
        ),
    modelName2 = list(
        recordName2 = list(
            attributeName2 = value(s)
            )
        )
    )

Say we wanted to update the “biospecimen_type” attribute of 2 records from the “biospecimen” model, and the “fraction” attribute for 1 record from the “rna_seq” model. The code for this could be:

# Create 'revisions'
revs <- list(
    "biospecimen" = list(
        "EXAMPLE-HS1-WB1" = list(biospecimen_type = "Whole Blood"),
        "EXAMPLE-HS2-WB1" = list(biospecimen_type = "Whole Blood")
        ),
    "rna_seq" = list(
        "EXAMPLE-HS1-WB1-RSQ1" = list(fraction = "Tcells")
    )
)

# Run update()
updateValues(
    target = prod,
    project = "example",
    revisions = revs)

A user would then see a summary of models/records to be updated, followed by a prompt to proceed or not:

For model "biospecimen", this update() will update 2 records:
    EXAMPLE-HS1-WB1
    EXAMPLE-HS2-WB1
For model "rna_seq", this update() will update 1 records:
    EXAMPLE-HS1-WB1-RSQ1

Proceed, Y/n?

As mentioned previously, it is highly recommended that summary outputs be checked carefully for accuracy before proceeding.

However, for running update*() code in non-interactive modes, like scripts or .Rmd knits, this user-prompt step can also be turned off by adding the input auto.proceed = TRUE. Example:

updateValues(
    target = prod,
    project = "example",
    revisions = revs,
    auto.proceed = TRUE)

## For model "biospecimen", this update will update 2 records:
##     EXAMPLE-HS1-WB1
##     EXAMPLE-HS2-WB1
## For model "rna_seq", this update will update 1 records:
##     EXAMPLE-HS1-WB1-RSQ1
## /update: successful.

After a successful update() a user should see this message (unless verbose has been set to FALSE):

/update: successful.