---
title: "Data Upload, Download, and Delete"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Data Upload, Download, and Delete}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Overview

This vignette demonstrates how to upload, download, and delete data using `synapser`.

**Note on integer parameters:** R's bare numeric literals (e.g. `1`) are
doubles. Parameters that the Synapse API expects as integers — such as
`version_number` and `version` — must be written with the `L` suffix
(e.g. `1L`) to pass a true integer to Python. Passing `1` instead of `1L`
may cause unexpected behavior or an API error.

## Key differences from the legacy API:

| Task | Legacy | New pipe UI |
|---|---|---|
| Store an entity | `synStore(obj, ...)` | `File(...) |> synStore(file_options, container_options, ...)` or `synStore(entity = File(...), parent, file_options, container_options, ...)`|
| Suppress new version | `synStore(obj, forceVersion = FALSE)` | `File(...) |> synStore()` |
| Set entity properties (e.g. name) | `entity$properties$name <- "new name"` then `synStore(entity)` | `synGet(synapse_id) |> synSetProperties(name = "new name") |> synStore()` |
| Set version label | `synStore(obj, versionLabel = "2")` | `synGet(synapse_id) |> synSetProperties(version_label = "2") |> synStore()` |
| Track provenance | `synStore(obj, used = "syn123", executed = "syn456")` | `synGet(synapse_id) |> synSetProperties(activity = Activity(used = list(UsedEntity(target_id = "syn123")), executed = list(UsedEntity(target_id = "syn456")))) |> synStore()`|
| Access entity ID | `entity$properties$id` | `entity$id` |
| Get an entity | `synGet(entity, ...)` | `File(...) |> synGet(file_options, ...)` or `synGet(synapse_id, file_options, ...)` |
| Get a specific version | `synGet(entity, version = 1)` | `File(id) |> synGet(version_number = 1L)` or `synGet(synapse_id, version_number = 1L)` |
| Skip file download | `synGet(entity, downloadFile = FALSE)` | `File(...) |> synGet(file_options = FileOptions(download_file = FALSE))` or `synGet(synapse_id, file_options = FileOptions(download_file = FALSE))` |
| Delete a version | `synDelete(obj, version = 1)` | `File(...) |> synDelete(version = 1L,  version_only = TRUE)` or `synDelete(entity, version = 1L,  version_only = TRUE)` |

## Load the package
```{r eval=FALSE}
library(synapser)
```

## Login

```{r eval=FALSE}
synLogin()
```

Credentials are read from `~/.synapseConfig` or the `SYNAPSE_AUTH_TOKEN`
environment variable. See the
[Managing Credentials](manageSynapseCredentials.html) vignette for setup
details.

## Create a Project

```{r eval=FALSE}
project <- Project(
  name = paste0(
    "My uniquely named project about Alzheimer's Disease ",
    paste(sample(c(letters, LETTERS, 0:9), 8, replace = TRUE), collapse = "")
  )
) |> synStore()
cat("Created project:", project$id, "\n")
```

`synStore()` returns the stored entity with the assigned Synapse ID in
`project$id`. In the new models API, IDs are accessed directly on the object
(`project$id`) rather than through `project$properties$id`.

## Create a Folder

Create a folder inside the project:

```{r eval=FALSE}
data_folder <- Folder(
  name = "single_cell_RNAseq_batch_1",
  parent_id = project$id
) |> synStore()
cat("Created folder:", data_folder$id, "\n")
```

## Upload a File

Create a local file and upload it to the folder. 

```{r eval=FALSE}
# Create a temporary file with some content
tmp <- tempfile(fileext = ".txt")
writeLines(c("sample", "data"), tmp)

file <- File(
  path = tmp,
  parent_id = data_folder$id
) |> synStore()
cat("Uploaded file:", file$id, "\n")
```
Storing the same file path as an existing version does not create a duplicate. Synapse detects unchanged content by MD5.

## Version the file

```{r eval=FALSE}
file <- synGet(synapse_id = file$id) |>
  synSetProperties(
    version_label   = "2",
    version_comment = "Added version 2"
  ) |>
  synStore()
```

## Add, Update and Remove Annotations

Use `synSetProperties()` to add, update, and remove annotations, then `synStore()` to persist the changes. To modify annotations, you don't have to download the file.
### Add annotations to a file
```{r eval=FALSE}
file <- synGet(
  synapse_id = file$id,
  file_options = FileOptions(download_file = FALSE)
) |>
  synSetProperties(
    annotations = list(
      assay = "RNA-seq", fileType = "csv", dataStage = "processed"
    )
  ) |>
  synStore()
```

### Update annotations of a file
```{r eval=FALSE}
file <- synGet(
  synapse_id = file$id,
  file_options = FileOptions(download_file = FALSE)
)
file <- file |>
  synSetProperties(
    annotations = append(file$annotations, list(new = "new_annotation"))
  ) |>
  synStore()
```

### Remove annotations of a file
```{r eval=FALSE}
file <- synGet(
  synapse_id = file$id,
  file_options = FileOptions(download_file = FALSE)
) |>
  synSetProperties(annotations = list()) |>
  synStore()
```

## Download a File

Retrieve a file by its Synapse ID. The file is downloaded to the local cache `.synapseCache` by default. 
To set a download path, use `FileOptions(download_location = "/path/to/downloads/")` in the `file_options` parameter. 

```{r eval=FALSE}
downloaded_file <- synGet(
  file$id,
  file_options = FileOptions(download_location = "/path/to/downloads/")
)
cat("Downloaded to:", downloaded_file$path, "\n")
```

## Download a Specific Version

Use `version_number` to pin to a particular version:

```{r eval=FALSE}
version_1 <- synGet(file$id, version_number = 1L)
cat("Version 1 path:", version_1$path, "\n")
```

## Clean Up

Delete the project and all its contents when done:

```{r eval=FALSE}
synDelete(project)
```