Skip to contents

Tutorial: Pushing annotations to the Portal

Tutorial_Annotations_to_Portal.Rmd

Pushing annotation sets to the Portal

Once you have generated an annotation set in Workbench, you may want to view these annotations as an overlay in the Visualizer or perform exploratory analyses based on these annotations in the Explorer. For this, you will have to push the annotations to the Portal. This can be done using the SpatialMap function uploadCellMetadata.

First, you will need to have a SpatialMap object in your session which has the cells annotated as intended.

sm <- readRDS("sm_post_clustering.RDS")

For most cases the only parameters you need to specify for uploadCellMetadata are object and metadata_names. Some other useful parameters to include are uploaded_name, and annotation_description. If your annotations were generated after performing QC, you may also want to specify the associated QC annotation id using quality_filter_id. If you do not intend to use the Explorer with this annotation set, specify create_explorer_output = FALSE. See ?uploadCellMetadata for more details.

uploadCellMetadata(
  object = sm,
  metadata_names = ".clusters",
  uploaded_name = "First pass clustering no labels", #optional
  annotation_description = "The first run of leiden clustering, before cell type labels were assigned", #optional
  quality_filter_id = NULL, #optional, fill in the annotation ID generated for any quality control filters used
  create_explorer_output = FALSE #optional
)

RStudio will then prompt you to input your Portal account password. Once the upload is complete, you should see the annotation set on the Portal soon! You will get a notification on the Portal once the annotation has finished processing.

Pushing QC results to the Portal

QC results are a specific type of cell annotation that you may want to overlay in the Visualizer. You can also associate any other cell annotations generated on workbench with a QC filter, which will exclude the filtered cells from other apps in the Analyzer. Try uploading QC results to the Portal right after finalizing your QC settings, but before removing poor quality cells from your sm object.

Taking this step will ensure that poor quality cells can be filtered out when running Analyzer apps and are excluded from exploratory analyses based on cell annotations for good quality cells in the Explorer. This can be done using the SpatialMap function uploadQC, which is a wrapper around uploadCellMetadata.

For most cases the only parameter you need to specify for uploadQC is object. See ?uploadQC for more details.

uploadQC(
  object = sm,
  uploaded_name = "QC result" #optional
  )

Editing annotations uploaded from Workbench

If you want to edit the name or description of an annotation that you’ve uploaded from workbench, you can use the emconnect function edit_cell_annotation.

You’ll need two pieces of information to use this function:

  1. The annotation_id of the annotation set you’d like to change. This is printed out in the log after running uploadCellMetadata and uploadQC. You can also find this information in the analysis version metadata page in the Study Details page for your study on the portal.

  2. The study_id of the study that contains the annotation set. This is in the projectMetadata slot of your SpatialMap object (projectMetadata(sm)$study_id).

edit_cell_annotation(annotation_id = 54321,
                     study_id = 12345,
                     new_name = "Fixed annotation name",
                     new_description = "Fixed description")
Scroll to top