File Upload

Tom Yu

2024-08-21

File Upload

Files in Synapse are versionable. Please see Files and Versioning for more information about how versions in Files work.

Preliminaries:

library(synapser)
## 
## TERMS OF USE NOTICE:
##   When using Synapse, remember that the terms and conditions of use require that you:
##   1) Attribute data contributors when discussing these data or results from these data.
##   2) Not discriminate, identify, or recontact individuals or groups represented by the data.
##   3) Use and contribute only data de-identified to HIPAA standards.
##   4) Redistribute data only under these same terms of use.
synLogin()
## NULL
# 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 a file
file_path <- tempfile("testUpload.txt")
connection <- file(file_path)
writeChar("this is the content of the file", connection, eos = NULL)
close(connection)
file <- File(path = file_path, parent = project)
file <- synStore(file)
file_id <- file$properties$id

Uploading a New Version

Uploading a new version follows the same steps as uploading a file for the first time - use the same file name and store it in the same location (e.g., the same parentId). It is recommended to add a comment to the new version in order to easily track differences at a glance. The example file testUpload.txt will now have a version of 2 and a comment describing the change.

Explicit example:

# fetch the file in Synapse
file_to_update <- synGet(file_id, downloadFile = FALSE)

# create the second version as a separated file
file_path <- tempfile("testUpload.txt")
connection <- file(file_path)
writeChar("this is version 2", connection, eos = NULL)
close(connection)

# save the local path to the new version of the file
file_to_update$path <- file_path

# add a version comment
file_to_update$versionComment <- 'change the file content'

# store the new file
updated_file <- synStore(file_to_update)

Implicit example:

# To create a new version of that file, make sure you store it with the exact same name
new_file <- synStore(File(file_path,  parentId = project$properties$id))

Updating Annotations or Provenance without Changing Versions

Any change to a File will automatically update its version. If this isn’t the desired behavior, such as minor changes to the metadata, you can set forceVersion=FALSE with the Python client.

Important: Because Provenance is tracked by version, set forceVersion=FALSE for minor changes to avoid breaking Provenance.

Setting Annotations without Changing Version

# Get file from Synapse, set downloadFile = FALSE since we are only updating annotations
file <- synGet(file_id, downloadFile = FALSE)

# Add annotations
file$annotations = c("fileType" = "bam", "assay" = "RNA-seq")

# Store the file without creating a new version
file <- synStore(file, forceVersion = FALSE)

Setting Provenance without Changing Version

To set Provenance without changing the file version:

# Get file from Synapse, set downloadFile = FALSE since we are only updating provenance
file <- synGet(file_id, downloadFile = FALSE)

# Store the file without creating a new version
file <- synStore(file,  activity = Activity(used = project$properties$id), forceVersion = FALSE)

Downloading a Specific Version

By default, the File downloaded will always be the most recent version. However, a specific version can be downloaded by passing the version parameter:

entity <- synGet(file_id, version = 1)

synDelete(project)
## NULL