From 01cc8c144b663384d308370d38cfae3125b9365c Mon Sep 17 00:00:00 2001
From: Anh Nguyet Vu <anngvu@gmail.com>
Date: Fri, 15 Nov 2024 08:10:02 -0800
Subject: [PATCH] Add more introductory annotation vignette

---
 vignettes/annotate-data-intro.Rmd | 90 +++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 vignettes/annotate-data-intro.Rmd

diff --git a/vignettes/annotate-data-intro.Rmd b/vignettes/annotate-data-intro.Rmd
new file mode 100644
index 00000000..588f7526
--- /dev/null
+++ b/vignettes/annotate-data-intro.Rmd
@@ -0,0 +1,90 @@
+---
+title: "Introduction to utils for annotating data"
+output: rmarkdown::html_vignette
+date: 2022-10-17
+vignette: >
+  %\VignetteIndexEntry{annotating-nextflow-processed-data}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Intro
+
+This introduces the annotation utilities with typical examples. 
+This is expected to be the more useful starting point for using nfportalutils for annotation tasks, to be followed by the more specialized vignetted for annotating NF processed data if needed.
+
+### Set up 
+```{r, eval=FALSE}
+library(nfportalutils)
+
+syn_login()
+
+# Change this to a dev project you have access to  
+PROJECT <- "syn26462036"
+```
+
+### Set annotations on a single file
+
+Create a demo entity.
+```{r, eval=FALSE}
+
+synapseclient <- reticulate::import("synapseclient")
+# Create an entity with some initial annotations
+entity <- synapseclient$Folder("Demo Entity",
+                               parent = PROJECT,
+                               annotations = list(foo = "bar", favorites = c("raindrops", "whiskers")))
+
+entity <- .syn$store(entity)
+```
+
+`set_annotations` can be used to add new annotations or correct an existing annotation on an entity. 
+This wraps the Python client to make it more intuitive to pass in an R list as the annotations as above. 
+Here, add another annotation *and* correct the `favorites` to "chocolate". 
+The returned data shows the unchanged `foo`, the updated `favorites`, and a new `n`. 
+```{r, eval=FALSE}
+set_annotations(id = entity$properties$id, annotations = list(favorites = "chocolate", n = 7L))
+```
+
+Cleanup.
+```{r, eval=FALSE}
+.syn$delete(entity)
+```
+
+### Annotate in batch using a manifest
+
+A better way to use `set_annotations` for a set of entities, usually files.
+
+First create multiple entities that need to be annotated or corrected in batch.
+```{r, eval=FALSE}
+objs <- make_folder(parent = PARENT_TEST_PROJECT, folders = c("mock_file_1", "mock_file_2", "mock_file_3"))
+ids <- sapply(objs, function(x) x$properties$id)
+```
+
+Create example manifest. Note: Another way includes reading in a shematic csv manifest with entityIds and Filenames.
+```{r, eval=FALSE}
+manifest <- data.table(
+     entityId = ids,
+     assay = "drugScreen",
+     experimentalTimepoint = c(1L, 3L, 7L),
+     experimentalTimepointUnit = "days",
+     cellType = list(c("schwann", "macrophage"), c("schwann", "macrophage"), c("schwann", "macrophage"))
+   )
+manifest
+```
+
+Apply:
+```{r, eval=FALSE}
+annotate_with_manifest(manifest)
+```
+
+Cleanup.
+```{r, eval=FALSE}
+for (id in ids) .syn$delete(id)
+```