Synapse files can be created by uploading content from your local computer or linking to digital files on the web. You can annotate files with custom metadata, embed files into Synapse wiki pages, or associate them with a DOI. Files in Synapse always have a “parent”, which could be a project or a folder. You can organize collections of files into folders and sub-folders, just as you would on your local computer.

Synapse files (as well as folders and projects) are identified by a unique identifier called a Synapse ID, or synID. The synID is represented by the prefix “syn” followed by numbers (for example, syn12345678). This identifier can be used to refer to a specific file on the web and through the programmatic clients.

You can control who has access to files that you upload in two ways. First, you can apply sharing settings, which are permissions that control who can view, edit, download, or delete a file. Second, you can also apply conditions for use, which are additional requirements that Synapse users must meet before accessing your file. By default, files inherit the conditions for use of the Synapse folder where they are uploaded. You can also add additional conditions for use on specific files within a folder. To read more about how to use sharing settings and conditions for use together, see the Sharing and Accessing Data page.

Uploading a File

You can upload a file to Synapse by using the web interface or programmatically by using the command line, Python, or R clients. By default, all files uploaded to Synapse are placed in Synapse storage, which is freely available to you. Files can also be stored on your own Amazon S3 bucket (see Custom storage locations) or other custom locations.

Web

To upload a file from the web, navigate to the project where you would like to add a file. Click on the Files tab within the project. Click on File Tools and then on Upload or Link to File to upload a local file from your computer or to link to a URL.

Command line

The command line has the sub-command store, which can be used to upload and add a file to Synapse.

# Add a local file to an existing project (syn12345) on Synapse
synapse store raw_data.txt --parentId syn12345
CODE

Python

The main function for uploading or updating a file in the Python client is through the store function. For more information about this function, see the Python Docs.

import synapseclient
from synapseclient import File
syn = synapseclient.login()

# Add a local file to an existing project (syn12345) on Synapse
file = File(path='/path/to/raw_data.txt', parent='syn12345')
file = syn.store(file)
PY

R

The main function for uploading or updating a file in the Python client is through the synStore function. For more information about this function, see the R Docs.

library(synapser)
synLogin()

# Add a local file to an existing project (syn12345) on Synapse
file <- File(path='/path/to/raw_data.txt', parentId='syn12345')
file <- synStore(file)
R

Moving a File or Folder

All Synapse clients offer a way to move files and folders. On the web, you can move single files one at a time, or you can move entire folders containing many files. If you wish to move a batch or subset of files from one location to another, you must use one of the programmatic clients. To move batches of files at once, you must use one of the programmatic clients. On the web, it is only possible to move a single file at a time. For this reason, if you are primarily using the web interface to manage your files, you should consider your folder structure carefully when you create your initial project.

Web

Navigate to the file or folder you would like to move. To move a file, select File Tools and then Move File. To move a folder, select Folder Tools and then Move Folder. In the resulting pop-up window, browse for the destination folder or project. Alternatively, use the search bar to enter the Synapse ID of the new location.

Command line

The command line client has a sub-command mv which can be used to move files and folders.

# move a file or folder (syn123) to a different folder/project (syn456)
synapse mv --id syn123 --parentId syn456
NONE

Python

You can change the file or folder location in the Python client by fetching the file information, changing the parent property, and storing the change.

import synapseclient
syn = synapseclient.login()

# fetch the file/folder to move (syn123 in this example)
# note the downloadFile=False parameter to fetch only the file's metadata and not the entire file
foo = syn.get('syn123', downloadFile=False)
# change the parentId to the new location, can be a folder or project (syn456 in this example)
foo.properties.parentId = 'syn456'
# store the file/folder to move it
syn.store(foo)
PY

R

You can change the file or folder location in the R client by fetching the file information, changing the parent property, and storing the change.

library(synapser)
synLogin()

# fetch the file/folder to move (syn123 in this example)
# note the downloadFile=False parameter to fetch only the file's metadata and not the entire file
foo <- synGet('syn123', downloadFile = FALSE)
# change the parentId to the new location, can be a folder or project (syn456 in this example)
foo$properties$parentId <- 'syn10056031'
# store the file/folder to move it
synStore(foo)
R

Deleting a File

Deleting a file will permanently remove it from Synapse. The synID that was associated with the deleted file will not be re-used.

Web

To delete a file, navigate to the project where the file is located and then select the Files tab. From the list of files and folders, navigate to the file you want to delete and click on the file name. From the File Tools menu, select Delete File.

Command line

synapse delete syn56789
NONE

Python

import synapseclient
syn = synapseclient.login()

entity = syn.delete("syn56789")
PY

R

library(synapser)
synLogin()

entity <- synDelete("syn56789")
R

File Previews

Synapse has a viewer for certain file types so that you can preview them before you download. Synapse previews will show the contents of the following file types:

  • PDFs

  • CSV (may show a portion of the table only)

  • Videos (.mp4, .webm, .ogg)

  • Jupyter notebooks (.ipybn)

  • Images (.jpeg, .png, .gif, .svg)

  • HTML (limited rendering only)

  • Markdown (.md or .rmd)

To see a file preview, navigate to the Files tab of a project and click on the file name. If a file preview is available, it will be visible in the left window.

File previews can also be embedded in wikis using the Insert menu in the wiki editing window. See the Wiki page for more information.

ProvenanceAnnotations and QueriesDownloading Data


Need More Help? Ask a question in the Synapse Help Forum. Your feedback is key to improving our documentation, so contact us if something is unclear or open an issue.