Skip to content

Using Tags with Data Items

Jump to bottom
Irzam Sarfraz edited this page Sep 22, 2021 · 10 revisions

The tagging mechanism within singleCellTK allows setting of tags to all data items including assays, subsets (altExperiments) and reducedDims for easier tracking during manipulation of these data items in downstream analysis. This particularly helps in differentiating between multiple types of data items during an analysis workflow, e.g., all assays processed through normalization (either through UI or console) are tagged as "normalized" and those processed through feature selection are tagged as "hvg" and so on. In the UI, this tagging mechanism allows the developers to populate the selectInput data selection UI elements to populate the data items separated by their tags and further use these data items through a common interface within the processing functions.

Basic Workflow

  1. Add tag to an assay (or a subset) at the time of setting that assay (or a subset) using the expData<- method. If assays are already present in an object, default tag can be set to all assays in the object using expSetDataTag method (and setting append parameter to FALSE).
  2. Populate data items selectInput by specifying the tags against which the assays should be populated in the user-interface using the updateSelectInputTag function.
  3. Retrieve a data item (an assay or a subset (altExp) or a reducedDim) by calling the expData method.

A summary of the tagging workflow can be better understood from the figure below: Tagging Workflow

Setting a tag

Tags can be set to a data item through either one of the following two ways:

  1. Add a tag to an assay when setting that assay to the object by using the expData<- setter method (instead of the assay<- setter method). The basic usage of expData<- method is same as assay<- setter method:
    expData(vals$counts, "CPMCounts") <- calculateCPM(assay(vals$counts, “counts”))

    By default “uncategorized” tag is set to all assays stored with the expData<- method call when tag parameter is missing or NULL as in the code snippet given above. To set a tag other than “uncategorized”, specify the tag name in the tag parameter of the method call:
    expData(vals$counts, "CPMCounts", tag = "normalized") <- calculateCPM(assay(vals$counts, “counts”))

    The same method can also be used to store a subset (as an altExperiment) by specifying the tag parameter and setting altExp parameter to TRUE:
    expData(vals$counts, “subset1”, tag = “hvg”, altExp = TRUE) <- FindHVG()

  2. Set a tag to a data item manually by using the expSetDataTag function. This function works in two ways based on the value of the append parameter, which by default is set to TRUE.

    Using expSetDataTag function with append set to TRUE adds a tag against a new assay that has just been stored:
    sce <- expSetDataTag(sce, "raw", "counts", append = TRUE)

    The above approach (with append value set to TRUE is not generally recommended, instead expData<- method should be used directly while storing a data item to set a tag.

    Using expSetDataTag function with append set to FALSE overrides the tag against a vector (or a character value) of assay names that correspond to a certain tag:
    sce <- expSetDataTag(sce, "raw", assayNames(sce), append = FALSE)

    The above function should be used specifically when a data object is uploaded without having tags previously stored.

Populating selectInputs with Tags

The selectInputs in the toolkit can be populated with all data items (assays, altExperiments/subsets or reducedDims) by using the appropriate call to the updateSelectInputTag function.

In the UI file:
Create a uiOutput:
uiOutput("dimRedAssaySelect")

In the server file:
Inside the updateAssayInputs function, you can use the following calls to populate the selectInput with the specified data items:

  1. Populate the selectInput with all available assays but do not separate by tags:
    updateSelectInputTag(session, "dimRedAssaySelect", choices = currassays)

  2. Populate the selectInput with all available assays and separate by tags:
    updateSelectInputTag(session, "dimRedAssaySelect", choices = currassays, showTags = TRUE)

  3. Populate the selectInput with only the assays from a particular tag or a list of tags:
    updateSelectInputTag(session, "dimRedAssaySelect", tags = c("raw", "normalized"))

  4. Populate the selectInput with only assays from a particular tag or list of tags and set one of these tags as “recommended”:
    updateSelectInputTag(session, "dimRedAssaySelect", tags = c("raw", "normalized"), recommended = "raw")

  5. By default the “label” for the selectInput is set to “Select assay:”, but can be changed by passing a value to the “label” parameter:
    updateSelectInputTag(session, "dimRedAssaySelect", tags = c("raw", "normalized"), recommended = "raw", label = "Select normalized assay:")

  6. This method can also be used to populate the reducedDims from the object in the selectInput:
    updateSelectInputTag(session, “assaySelect”, tags = c(“raw”, “normalized”), recommended = “normalized”, redDims = TRUE)

Supporting Methods

  • expSetDataTag: Manually assign a tag to an assay. The append parameter in the function (default to TRUE) decides if an assay with a tag should be appended to the existing tags (TRUE) or if all tags should be overridden with the current assignment (FALSE).
  • expDataNames: Returns a combined vector of all data items including assays, subsets (altExperiments) and reducedDims.
  • expData: Returns a data item from the object including assay, subset (altExperiment) or reducedDim based upon the name in the i parameter. Remaining parameters are same as assay method.
  • expData<-: Store an assay and assign a tag to it but using an additional parameter tag. Remaining parameters are same as assay<- method.
  • expTaggedData: Returns a list of names of data items from the input object based upon the input parameters, i.e. tags parameter ensures that names of data items from the specified tags are returned, and redDims indicates if reducedDims should also be returned in the list.
  • expDeleteDataTag: Deletes a tag against a specified assay.

Workflow Example

  1. Store an assay and assign a tag to it in the server file:
    expData(sce, "counts", tag = "raw") <- rawMatrix

  2. Populate the data items in the UI (assuming that UI file has a uiOutput with id dimRedAssaySelect) from the server file:
    updateSelectInputTag(session, "dimRedAssaySelect", tags = c("raw"), recommended = "raw")

  3. Inside R functions, use a check to make sure that the data item exists in the object (can be an assay, or a subset/altExperiment or a reducedDim):
    if(assayName %in% expDataNames(sce)) stop("Data item does not exist in the input object")

    Use expData method (instead of the assay method) to retrieve and use the data:
    expData(sce, "normalizedCounts", tag = "normalized") <- someMethod(expData(sce, "counts"))

List of selectInputs in the Toolkit

Input Id File
dimRedAssaySelect ui_04_fs_dimred.R
dimRedAssaySelect_tsneUmap ui_04_fs_dimred.R
batchCorrAssay ui_04_batchcorrect.R
batchCheckAssay -
batchCheckOrigAssay ui_04_batchcorrect.R
deAssay ui_05_1_diffex.R
fmAssay ui_05_2_findMarker.R
fmHMAssay server.R
pathwayAssay ui_06_1_pathway.R
modifyAssaySelect ui_04_batchcorrect.R
normalizeAssaySelect ui_04_batchcorrect.R
seuratSelectNormalizationAssay ui_09_2_seuratWorkflow.R
assaySelectFS_Norm ui_04_fs_dimred.R
filterAssaySelect partials.R
qcAssaySelect ui_02_qc.R
celdaAssay ui_celda.R
celdaAssayGS ui_celda.R
celdaAssaytSNE ui_celda.R
celdaAssayProbabilityMap ui_celda.R
celdaAssayModuleHeatmap ui_celda.R
depthAssay ui_07_subsample.R
cellsAssay ui_07_subsample.R
snapshotAssay ui_07_subsample.R
exportAssay ui_export.R
hmAssay ui_08_3_heatmap.R

List of tabs in the Toolkit with their recommended tags

Tab Methods Recommended Tag(s)
QC all raw
Normalization all raw
Normalization - Assay Options log, log1p raw, normalized
Normalization - Assay Options z.score normalized
Batch Correction FastMNN, Limma, MNN normalized
Batch Correction ZINBWaVE, ComBatSeq raw
Batch Correction BBKNN scaled
Feature Selection all normalized, scaled
Dimensionality Reduction all normalized, scaled
Clustering
Differential Expression all normalized, scaled
Find Markers all normalized, scaled
Cell Type Labeling all normalized
GSVA all normalized, scaled
EnrichR
Sample Size Calculator
Curated Workflows all untagged

Last Updated: March 13, 2021

Report Issues

Open a Github issue and assign to irzamsarfraz or email to irzam9095@gmail.com.

Clone this wiki locally