Data Upload, Download, and Delete

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

library(synapser)

Create a Project

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:

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.

# 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

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

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

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

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.

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:

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:

synDelete(project)