The synapser package provides an interface to Synapse, a collaborative workspace for reproducible data intensive research projects, providing support for:

  • integrated presentation of data, code and text
  • fine grained access control
  • provenance tracking

The synapser package lets you communicate with the Synapse platform to create collaborative data analysis projects and access data using the R programming language. Other Synapse clients exist for Python, Java, and the web browser.

If you’re just getting started with Synapse, have a look at the Getting Started guides for Synapse.

Good example projects are:


synapser is available as a ready-built package for Microsoft Windows and Mac OSX. For Linux systems, it is available to install from source. It can be installed or upgraded using the standard install.packages() command, adding the Sage Bionetworks R Archive Network (RAN) to the repository list, e.g.:

install.packages("synapser", repos = c("http://ran.synapse.org", "http://cran.fhcrc.org"))

Alternatively, edit your ~/.Rprofile and configure your default repositories:

options(repos = c("http://ran.synapse.org", "http://cran.fhcrc.org"))

after which you may run install.packages without specifying the repositories:


Please see the Troubleshooting vignettes for more information.

Accessing Data

To make the example below print useful information, we prepare a file:

Synapse identifiers are used to refer to projects and data which are represented by entity objects. For example, the entity above represents a tab-delimited file containing a 2 by 3 matrix. Getting the entity retrieves an object that holds metadata describing the matrix, and also downloads the file to a local cache:

View the entity’s metadata in the R console:

This is one simple way to read in a small matrix (we load just the first few rows):

read.table(fileEntity$path, nrows = 2)
##   V1 V2 V3
## 1  a  b  c
## 2  d  e  f

View the entity in the browser:


Download Location

By default the download location will always be in the Synapse cache. You can specify the downloadLocation parameter.

entity <- synGet("syn00123", downloadLocation = "/path/to/folder")

For more details see the native reference documentation, e.g.:

Organizing Data in a Project

You can create your own projects and upload your own data sets. Synapse stores entities in a hierarchical or tree structure. Projects are at the top level and must be uniquely named:

Creating a folder:

dataFolder <- Folder("Data", parent = project)
dataFolder <- synStore(dataFolder)

Adding files to the project:

You can print the properties of an entity (such as the file we just created):

Most other properties are immutable, but you can change an entity’s name:

Update Synapse with the change:

You can list all children of an entity:

You can also filter by type:

You can avoid reading all children into memory at once by iterating through one at a time:

You can move files to a different parent:

newFolder <- Folder("New Parent", parent = project)
newFolder <- synStore(newFolder)

file <- synMove(file, newFolder)

Content can be deleted:

Deletion of a project will also delete its contents, in this case the folder:

In addition to simple data storage, Synapse entities can be annotated with key/value metadata, described in markdown documents (wikis), and linked together in provenance graphs to create a reproducible record of a data analysis pipeline.

For more details see the native reference documentation, e.g.:

Annotating Synapse Entities

# (We use a time stamp just to help ensure uniqueness.)
projectName <- sprintf("My unique project created on %s", format(Sys.time(), "%a %b %d %H%M%OS4 %Y"))
project <- Project(projectName)
project <- synStore(project)

synSetAnnotations will replace all the existing annotations with the given annotations. Hence, to add a new annotation to the ones currently defined for an entity, we must retrieve it:


Synapse provides tools for tracking ‘provenance’, or the transformation of raw data into processed results, by linking derived data objects to source data and the code used to perform the transformation.

The Activity object represents the source of a data set or the data processing steps used to produce it. Using W3C provenance ontology terms, a result is generated by a combination of data and code which are either used or executed.

Creating an activity object:

Here, syn1234 and syn1235 might be two types of measurements on a common set of samples. Some whizzy clustering code might be referred to by syn4567.

Alternatively, you can build an activity up piecemeal:

act <- Activity(name = "clustering", description = "whizzy clustering")
act$used(c("syn12345", "syn12346"))

The used and executed can reference entities in Synapse or URLs.

Entity examples:

URL examples:

Storing entities with provenance

The activity can be passed in when storing an Entity to set the Entity’s provenance:

project <- synGet(project$properties$id)
project <- synStore(project, activity = act)

We’ve now recorded that ‘project’ is the output of syn4567 applied to the data stored in syn1234 and syn1235.

Recording data source

The synStore() has shortcuts for specifying the used and executed lists directly. For example, when storing a data entity, it’s a good idea to record its source:

For more information:


Tables can be built up by adding sets of rows that follow a user-defined schema and queried using a SQL-like syntax. Please visit the Table vignettes for more information.


An Evaluation is a Synapse construct useful for building processing pipelines and for scoring predictive modeling and data analysis challenges.

Creating an Evaluation:

Retrieving the created Evaluation:

Submitting a file to an existing Evaluation:

List submissions:

submissions <- synGetSubmissionBundles(eval)
## [[1]]
## [[1]][[1]]
## {
##   "contributors": [
##     {
##       "createdOn": "2019-03-14T19:12:42.262Z",
##       "principalId": "3323137"
##     }
##   ],
##   "createdOn": "2019-03-14T19:12:42.262Z",
##   "entityBundleJSON": "{\"entityType\":\"org.sagebionetworks.repo.model.FileEntity\",\"fileHandles\":[{\"contentMd5\":\"3f466b7f85d184292a68cea1c4f7cfc2\",\"bucketName\":\"devdata.sagebase.org\",\"fileName\":\"file1580a6bca063d\",\"createdBy\":\"3323137\",\"contentSize\":27,\"concreteType\":\"org.sagebionetworks.repo.model.file.S3FileHandle\",\"etag\":\"4614201a-6e24-4218-8958-02e488c38595\",\"id\":\"609446\",\"storageLocationId\":1,\"createdOn\":\"2019-03-14T19:12:41.000Z\",\"contentType\":\"application/octet-stream\",\"key\":\"3323137/843bba17-d270-448a-9fb3-22fdd4e755b9/file1580a6bca063d\"}],\"annotations\":{\"longAnnotations\":{},\"blobAnnotations\":{},\"stringAnnotations\":{},\"etag\":\"00000000-0000-0000-0000-000000000000\",\"id\":\"syn10041117\",\"creationDate\":\"1552590760779\",\"uri\":\"/entity/syn10041117/annotations\",\"dateAnnotations\":{},\"doubleAnnotations\":{}},\"entity\":{\"dataFileHandleId\":\"609446\",\"modifiedOn\":\"2019-03-14T19:12:40.998Z\",\"versionLabel\":\"1\",\"createdBy\":\"3323137\",\"name\":\"file1580a6bca063d\",\"concreteType\":\"org.sagebionetworks.repo.model.FileEntity\",\"etag\":\"b958a52c-15e9-4713-a56b-db99b92bcfcb\",\"modifiedBy\":\"3323137\",\"id\":\"syn10041117\",\"createdOn\":\"2019-03-14T19:12:40.779Z\",\"parentId\":\"syn10041116\",\"versionNumber\":1}}",
##   "entityId": "syn10041117",
##   "evaluationId": "9606990",
##   "id": "9619303",
##   "name": "file1580a6bca063d",
##   "userId": "3323137",
##   "versionNumber": 1
## }
## [[1]][[2]]
## {
##   "entityId": "syn10041117",
##   "etag": "028035b1-5221-454d-a3c5-bb76441b61e1",
##   "id": "9619303",
##   "modifiedOn": "2019-03-14T19:12:42.262Z",
##   "status": "RECEIVED",
##   "statusVersion": 0,
##   "versionNumber": 1
## }

Retrieving submission by id:

Retrieving the submission status:

To view the annotations:

To update an annotation:

Query an evaluation:

queryString <- sprintf("query=select * from evaluation_%s LIMIT %s OFFSET %s'", eval$id, 10, 0)
synRestGET(paste("/evaluation/submission/query?", URLencode(queryString), sep = ""))
## $headers
## list()
## $rows
## list()
## $totalNumberOfResults
## [1] 0

To learn more about writing an evaluation query, please see: http://docs.synapse.org/rest/GET/evaluation/submission/query.html

For more information, please see:

Sharing Access to Content

By default, data sets in Synapse are private to your user account, but they can easily be shared with specific users, groups, or the public.

Retrieve the sharing setting on an entity:

synGetPermissions(project, principalId = 273950)
## list()

The first time an entity is shared, an ACL object is created for that entity. Let’s make project public:

Now public can read:

synGetPermissions(project, principalId = 273950)
## [[1]]
## [1] "READ"

File Views

A file view can be defined by its scope. It allows querying for FileEntity within the scope using a SQL-like syntax. Please visit the File View vignettes for more information.

Accessing the API Directly

These methods enable access to the Synapse REST(ish) API taking care of details like endpoints and authentication. See the REST API documentation.

Synapse Utilities

We provide some utility functions in the synapserutils package:

  • Copy Files, Folders, Tables, Links, Projects, and Wiki Pages.
  • Upload data to Synapse in bulk.
  • Download data from Synapse in bulk.

Please visit the synapserutils Github repository for instructions on how to download.

More information

For more information see the Synapse User Guide.