Important Note About the R Client
We maintain the R client to support our R user community, recognizing R as a foundational language in many data workflows. That said, the R client is built on top of the Synapse Python client via the reticulate package. This design allows us to solve complex engineering problems—such as multi-threaded uploads/downloads and file caching—at the Python layer and reuse those solutions in R.
While we aim to provide a reliable R experience, the dependency on Python introduces installation nuances, especially around environment management and package versions. If you encounter issues, we recommend using the Python client directly, which is actively developed and more broadly used.
We appreciate your patience and continued feedback as we work to improve the user experience across both ecosystems.
Introducing synapser 3.0.0
synapser 3.0.0 is a major release built on version 4.14 of the Synapse Python client. It introduces object-oriented models: create an instance of a Synapse object, such as File(path = “data.csv”, parent_id = “syn123”), then pipe it into verb functions like synStore() and synGet(). It also brings:
- No Python setup. When synapser is loaded, reticulate installs a compatible Python and the Synapse Python client for you. Python 3.10 to 3.14 is supported.
- Current R dependencies. synapser works with current versions of reticulate (1.44.0 or later) and rjson, and requires R 4.2.0 or later.
This release is not backwards compatible. Functions from earlier versions, such as synGetChildren() and synGetAnnotations(), have been removed. Before upgrading, see Key differences from the legacy API for how earlier calls map to the new API, and Supported Models and Functions for what this release supports.
Introduction
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.
Supported Models and Functions
synapser 3.0.0 supports the following Synapse models. Each model’s reference page also lists the functions that work on it, such as synGetAcl(), synSetPermissions(), or synSyncFromSynapse().
| Area | Models |
|---|---|
| Projects, folders, and files |
Project, Folder, File, Link
|
| Tables and views |
Table, Column, JsonSubColumn, VirtualTable, EntityView, MaterializedView, SubmissionView, Dataset, DatasetCollection, EntityRef
|
| Provenance |
Activity, UsedEntity, UsedURL
|
| Wikis |
WikiPage, WikiHeader, WikiHistorySnapshot, WikiOrderHint
|
| Challenges and evaluations |
Evaluation, Submission, SubmissionStatus, SubmissionBundle
|
| Users, teams, and organizations |
Team, UserProfile, UserPreference, Organization, JSONSchema
|
| Storage |
StorageLocation, StorageLocationType
|
| AI agents |
Agent, AgentSession, AgentPrompt
|
These functions work across models:
| Task | Functions |
|---|---|
| Connecting to Synapse |
synLogin, synLogout, synSetEndpoints
|
| Getting, storing, and deleting entities |
synGet, synStore, synDelete, synSetProperties
|
| Options for getting and storing |
FileOptions, ActivityOptions, TableOptions, LinkOptions, StoreFileOptions, StoreContainerOptions, StoreTableOptions, StoreJSONSchemaOptions, StoreGridOptions
|
| Querying tables and views |
synQuery, synQueryPartMask
|
| Download list (cart) |
synDownloadListAdd, synDownloadListRemove, synDownloadListClear, synDownloadListManifest, synDownloadListFiles, DownloadListItem
|
| Utilities |
synFindEntityId, synIsSynapseId, synOnweb, synPrintEntity, synMd5Query, synSendMessage
|
| REST API |
synRestGet, synRestPost, synRestPut, synRestDelete
|
See the reference index for the full list.
Requirements
- R version 4.2.0 or higher (tested up to R 4.6.1)
- reticulate 1.44.0 or higher
- Synapse account
Note: You do not need to install Python yourself. When synapser is loaded it declares its Python requirement via reticulate::py_require(), and reticulate downloads a compatible Python and the Synapse Python client into a managed environment on first use. If you would rather point synapser at a Python environment you manage, it must be Python 3.10 to 3.14 — the range supported by synapseclient 4.14. See the install guide for how reticulate chooses between the two.
Documentation
Full documentation for synapser is on the docs site:
- Reference: every model and function, organized by model.
- Installation, Authentication, and Configuration: get set up.
- Tutorials: task guides for files, folders, tables, wikis, evaluations, and more.
- Migrating to synapser 3.0: how to update scripts written for synapser 2.x.
For Internal Testing: the docs site may not show this version yet, so build it locally: from the root of your synapser clone, run pkgdown::build_site() and open docs/index.html in a browser.
Installation
synapser is available as a ready-built package for Microsoft Windows and Mac OSX. For Linux systems, it is available to install from source. Please also check out our System Dependencies article for instructions on how to install system dependencies on Linux environments.
Check out the dedicated install guide for additional instructions
In short you may install synapser via:
For Internal Testing:
# Install remotes if not already installed
if (!require("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github("Sage-Bionetworks/synapser", ref = "SYNR-1649-upgrade-pythonclient-4-14")We recommend that you DO NOT update synapser’s dependencies during installation.
Release Candidate Installation (WIP)
If you have been asked to validate a release candidate, please use:
remotes::install_github("Sage-Bionetworks/synapser")
remotes::install_cran("synapser", repos = c("http://staging-ran.synapse.org"))Troubleshooting Installation Issues (WIP)
If installation fails, please see our Troubleshooting vignette for detailed resolution steps. Note that the rjson and reticulate version conflicts reported against synapser 2.x no longer apply: 3.0.0 works with current versions of both.
R Version Compatibility (WIP)
Important: synapser 3.0.0 requires R 4.2.0 or later. R 4.1.x is not supported — it is the last Windows release with 32-bit (i386) multiarch, and the version of reticulate that synapser requires does not build for 32-bit Windows.
-
Check your R version: Run
R.version.stringin R to see your current version - If your R is older than 4.2.0: see How to Upgrade R below
Under the hood, synapser uses reticulate and the synapsePythonClient. reticulate provisions a compatible Python for you on first use, so you only need to install Python yourself if you prefer to manage your own environment. See instructions below on installing/upgrading Python.
Usage
To get started, try logging into Synapse. If you don’t already have a Synapse account, register here:
Please visit the synapser docs site or view our vignettes for using the synapser package:
browseVignettes(package = "synapser")Usage Examples
knit2synapse
Knit RMarkdown files to Synapse wikis
syndccutils
Code for managing data coordinating operations (e.g., development of the CSBC/PS-ON Knowledge Portal and individual Center pages) for Sage-supported communities through Synapse.
How to Upgrade Python
On Windows
Download the Python installer from the Official Website of Python here.
Install the Downloaded Python Installer
check Install Python and Check the “Add python.ext to PATH”, then click on the “Install Now” button.
-
Verify the Update
NoteIf it still shows the old version, you may restart your system. Or uninstall the old version from the control panel.
On macOS
-
Both python 2x and 3x can stay installed in a MAC. Mac comes with python 2x version. To check the default python version in your MAC, open the terminal and type
If you don’t then go ahead and install it with the installer. Go the the python’s official site here.
-
Now restart the terminal and check again with both commands python —version
-
Oruse toinstall last version
How to Upgrade R
- Verify R version
- Open RStudio > At the top of the Console you will see session info > The first line tells you which version of R you are using.
-
orwrite in console >‘R.version.string’ to print out the R version. - go to Tools > Check for Package Updates. If there’s an update available for tidyverse, install it.
On Windows
- To update R on Windows, try using the package installer (only for Windows).
- Got to Tools (at the top) > Check for package updates. If tidyverse shows up on the list, select it, then click “Install Updates.”
On Mac
- Go to here.
- Click the link you need to update R pkg
- When the file finishes downloading, double-click to install. You should be able to click “Next” to all dialogs to finish the installation.
- From within RStudio, go to Help > Check for Updates to install newer version of RStudio (if available, optional).
- To update packages, go to Tools > Check for Package Updates. If updates are available, select All (or just tidyverse), and click Install Updates.