views.Rmd

---
title: "Views"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Views}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Views

A view is a view of all entities (File, Folder, Project, Table, Docker Repository, View) within one or more Projects or Folders. Views can:

* Provide a way of isolating or linking data based on similarities
* Provide the ability to link entities together by their annotations
* Allow view/editing entities attributes in bulk
* Allow entities to be easily searched and queried
    
Preliminaries:
```{r collapse=TRUE}
library(reticulate)
library(synapser)
syn <- reticulate::import("synapseclient")
EntityViewType <- syn$EntityViewType
synLogin()
# Create a new project
# use hex_digits to generate random string
hex_digits <- c(as.character(0:9), letters[1:6])
projectName <- sprintf("My unique project %s", paste0(sample(hex_digits, 32, replace = TRUE), collapse = ""))
project <- Project(projectName)
project <- synStore(project)

# Create some files
filePath <- tempfile()
connection <- file(filePath)
writeChar("this is the content of the first file", connection, eos = NULL)
close(connection)
file <- File(path = filePath, parent = project)
# Add some annotations
file$annotations = list(contributor = "UW", rank = "X")
file <- synStore(file)

filePath2 <- tempfile()
connection2 <- file(filePath2)
writeChar("this is the content of the second file", connection, eos = NULL)
close(connection2)
file2 <- File(path = filePath2, parent = project)
file2$annotations = list(contributor = "UW", rank = "X")
file2 <- synStore(file2)

```

Creating a View:
```{r collapse=TRUE}
view <- EntityViewSchema(name = "my first file view",
                         columns = c(
                           Column(name = "contributor", columnType = "STRING"),
                           Column(name = "class", columnType = "STRING"),
                           Column(name = "rank", columnType = "STRING"),
                           Column(name = "string_list", columnType = "STRING_LIST")),
                         parent = project$properties$id,
                         scopes = project$properties$id,
                         includeEntityTypes = c(EntityViewType$FILE, EntityViewType$FOLDER),
                         add_default_columns = TRUE)

view <- synStore(view)
```

We support the following entity type in a View:
```{r collapse=TRUE}
EntityViewType
```

```{r include = FALSE}
# wait for the view to be created
Sys.sleep(10)
```

To see the content of your newly created View, use synTableQuery():
```{r collapse=TRUE}
queryResults <- synTableQuery(sprintf("select * from %s", view$properties$id))
```
```{r}
data <- as.data.frame(queryResults)
data
```

## Updating Annotations using View

To update 'class' and 'string_list' annotations for all files in the view, simply update the view:
```{r collapse=TRUE, eval=FALSE}
data["class"] <- list(c("V", "VI"))
# update string_list annotation
string_list_values <- list(list("a,b,c"), list("d,e,f"))
data["string_list"] <- sapply(string_list_values, function(x) rjson::toJSON(x))
synStore(Table(view$properties$id, data))
```

The change in annotations is reflected in synGetAnnotations():
```{r collapse=TRUE, eval=FALSE}
synGetAnnotations(file2$properties$id)
```

A unique etag is associated with every file that updates when changes are made to a file, including the contents, annotations, or metadata. Any updates pushed to Synapse will change an object's etag.
```{r collapse=TRUE, eval=FALSE}
data$etag
```

There may be cases where you want to update the annotations on a subset of files in a view. In order to preserve the etag, and thus the file history, you will need to store only the rows that have been modified.
```{r collapse=TRUE}
data$contributor[1] <- c("Sage Bionetworks")
synStore(Table(view$properties$id, data[1,]))
```

## Update View's Content

A view can contain different types of entity. To change the types of entity that will show up in a view:
```{r collapse=TRUE}
view <- synGet(view$properties$id)
view$set_entity_types(list(EntityViewType$FILE))
```

A View is a Table. Please visit [Tables vignettes](tables.html) to see how to change schema, update content, and other operations that can be done on View.

```{r collapse=TRUE}
synDelete(project)
```