Set Up an R Environment to Use synapser and synapserutils

Overview

This guide walks you through creating a reliable R environment to authenticate with and work on Synapse using the synapser and synapserutils packages. It covers prerequisites, OS-specific setup, installation methods, proxies/SSL, authentication, and verification. Follow the method that best matches your system and governance requirements.

At-a-Glance: Supported Setups

• R 4.1+ recommended (works on macOS, Windows, Linux)

• Minium friction: Install from CRAN-like repositories (if available to your org)

• Standard: Install via reticulate + Python Synapse client (not required)

• Preferred: Install R-native binaries from the official channel or source via remotes

• Authentication: Personal Access Token (PAT) preferred over username/password

Prerequisites

Accounts and Access

• Active Synapse account

• Personal Access Token (PAT) with least-privilege scopes for your work

System Requirements

• R 4.1 or newer, and RTools (Windows) or Xcode CLTs (macOS) for source builds

• Internet access to reach package repos and Synapse APIs (HTTPS port 443)

• Optional but recommended: Quarto/R Markdown, Git, and renv for reproducibility

• Python 3.10-3.11 installed with pip

Install R and Build Toolchain

macOS

1. Install R from CRAN.

2. Install Xcode Command Line Tools: run in Terminal: xcode-select --install.

3. Optional: Homebrew for utilities: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)".

Windows

1. Install R from CRAN.

2. Install RTools (matching your R major.minor version) and ensure it’s on PATH.

3. Ensure corporate antivirus allows R package builds and HTTPS downloads.

Linux (Ubuntu/Debian)

1. Install system deps (example): sudo apt-get update && sudo apt-get install -y build-essential libcurl4-openssl-dev libssl-dev libxml2-dev

2. Install R from your distro or CRAN binaries (prefer CRAN for newer versions).

Install Python and Pip

Install synapseR/synapser with mamba (miniforge/mambaforge)

synapseR/synapser wraps the Python synapseclient and uses reticulate to build/use Python from R. By default, reticulate may search /usr/local/bin first and not auto-detect a mamba (miniforge/mambaforge) installation.

• Point reticulate to mamba's Python by setting environment variables in ~/.Renviron, ~/.Rprofile, or your project .Renviron:

• Bash

  # Example (Linux, miniforge in /home/$USER/miniforge3)
  RETICULATE_PYTHON=/home/$USER/miniforge3/bin/python
  RETICULATE_PYTHON_FALLBACK=/home/$USER/miniforge3/bin/python
  LD_LIBRARY_PATH=/usr/lib64/R/lib:/usr/lib/jvm/java-25-openjdk/lib/server
  

• Adjust paths for macOS/Windows; verify the target python path exists (e.g., which python).

• Ensure your mamba/conda env includes readline >= 8.3:

• Bash

  mamba install -c conda-forge 'readline>=8.3'
  

synapser installation with mamba (reticulate)

synapser (aka synapseR) wraps the Python synapseclient via reticulate. By default, reticulate may choose /usr/local/bin/python and not detect a mamba/miniforge Python, leading to build/load issues.

• Fix: point reticulate to your mamba/miniforge Python by setting these in ~/.Renviron or ~/.Rprofile (or a project .Renviron):

• Bash

  RETICULATE_PYTHON=/home/$USER/miniforge3/bin/python
  RETICULATE_PYTHON_FALLBACK=/home/$USER/miniforge3/bin/python
  LD_LIBRARY_PATH=/usr/lib64/R/lib:/usr/lib/jvm/java-25-openjdk/lib/server
  

• Notes:

• Adjust paths for your install (macOS/Windows/Linux) and verify the python path exists.

• After changing ~/.Renviron or ~/.Rprofile, restart R/RStudio so changes take effect.

• Ensure mamba environment has readline >= 8.3:

• Bash

  mamba install -c conda-forge 'readline>=8.3'
  

1. Python is only needed if you plan to use tools that rely on Python (e.g., via reticulate). Use Python 3.10–3.11 and ensure pip is available.

2. Instalython 3.10–3.11 and ensure pip works.

3. Install Python (official sources first):

   • macOS: https://www.python.org/downloads/macos/ (official installer) or Homebrew: brew install python@3.11

   • Windows: https://www.python.org/downloads/windows/ (check "Add python.exe to PATH") or winget: winget install Python.Python.3.11

   • Linux (Ubuntu/Debian): apt packages: sudo apt-get update && sudo apt-get install -y python3.11 python3.11-venv python3-pip (or your distro's package manager).

4. Verify Python:

5. Bash

   python3 --version
   python --version
   

6. Ensure pip is installed:

7. Bash

   python -m pip --version
   python3 -m pip --version
   

8. If pip isn’t available, try the built-in bootstrapper (ensurepip):

9. Bash

   python -m ensurepip --upgrade
   python3 -m ensurepip --upgrade
   

10. Windows PowerShell:

11. PowerShell

    py -m ensurepip --upgrade
    py -m pip --version
    

12. If pip still isn’t available, follow the official pip installation documentation: Installation - pip documentation

13. Corporate networks and SSL notes:

    • If downloads fail behind a proxy, set http_proxy / https_proxy environment variables (see the Networking/Proxy section below).

    • If you see SSL/certificate errors, your org may require installing an internal CA certificate in your OS trust store.

Create a Reproducible Project Environment

1. Create a new project directory.

2. Initialize renv to isolate dependencies.

install.packages("renv")
renv::init()
renv::install("rstudio/reticulate@v1.28")
renv::install("cran/rjson@0.2.21")
install.packages("synapser", repos =
  c("http://ran.synapse.org",
  "https://cloud.r-project.org"))
install.packages("synapserutils", repos=c("http://ran.synapse.org", "https://cloud.r-project.org"))

Authenticate and Configure

Recommended: Personal Access Token (PAT)

# Store token securely in environment variable before starting R (preferred):
# macOS/Linux (bash): echo 'export SYNAPSE_AUTH_TOKEN="<token>"' >> ~/.Renviron
# Windows: writeLines('SYNAPSE_AUTH_TOKEN=<token>', con = file.path(Sys.getenv("USERPROFILE"), ".Renviron"))

# In R:
library(synapser)
synLogin(authToken = "SYNAPSE_AUTH_TOKEN")

Persisted Credentials

After a successful login, a cached session may be used. To explicitly logout or switch accounts:

synLogout()
synLogin(authToken = Sys.getenv("SYNAPSE_AUTH_TOKEN"))

Quick Start: Upload Files

library(synapser)
library(synapserutils)

# Assume you have authenticated (see above).
# Use an existing project or folder as the parent.
# Example uses a freshly created project; replace with your own parentId if known.
proj <- synStore(Project(name = paste0("Upload Demo ", format(Sys.time(), "%Y%m%d-%H%M%S"))))
parentId <- proj$properties$id  # or set: parentId <- 'syn123'

# 1) Upload a single file
tmp <- tempfile(fileext = ".txt"); writeLines("hello synapse", tmp)
fileEntity <- File(path = tmp, parent = parentId)
fileEntity <- synStore(fileEntity)

# 2) Upload multiple files from a folder (non-recursive)
dirPath <- tempdir()
file.create(file.path(dirPath, c("a.txt", "b.txt")))
paths <- list.files(dirPath, pattern = \"\\.txt$\\", full.names = TRUE)
ents <- lapply(paths, function(p) synStore(File(path = p, parent = parentId)))

# 3) Set annotations during upload
annFile <- File(path = tmp, parent = parentId)
annotations(annFile) <- list(sample_id = "S1", assay = "rna-seq", qc_passed = TRUE)
annFile <- synStore(annFile)

# Verify uploads
children <- synapserutils::synGetChildrenAsList(parentId, includeTypes = c("file"))
print(vapply(children, function(x) x$name, character(1)))

Using synapserutils Effectively (Uploads)

• Bulk uploads: iterate files and call synStore(File(...)) or use helper patterns to walk directories.

• List and verify: synapserutils::synGetChildrenAsList(parentId, includeTypes = c("file")) to confirm uploads.

• Annotations during upload: set annotations(entity) <- list(...) before synStore for consistent metadata.

# Create a table schema
schema <- Schema(name = "demo_table", columns = list(
  Column(name = "sample_id", columnType = "STRING"),
  Column(name = "value", columnType = "DOUBLE")
), parent = proj$properties$id)
schema <- synStore(schema)

# Store data
df <- data.frame(sample_id = c("s1","s2","s3"), value = c(1.2, 3.4, 5.6))
tbl <- synStore(Table(schema, df))

# Query
q <- synTableQuery(sprintf("select * from %s where value > 2.0", schema$properties$id))
as.data.frame(q)

Networking, Proxy, and SSL

• .Renviron

  • https_proxy=http://user:pass@proxy:port

  • http_proxy=http://user:pass@proxy:port

  • no_proxy=localhost,127.0.0.1,.yourdomain

• Corporate SSL interception may require adding your org root CA to the OS trust store.

• If using curl/httr, ensure system OpenSSL is current.

Team and CI/CD Practices

• Lock dependencies: renv::snapshot() and commit renv.lock.

• Non-interactive auth in CI: inject SYNAPSE_AUTH_TOKEN as a masked secret in the pipeline environment, then synLogin(authToken = Sys.getenv("SYNAPSE_AUTH_TOKEN")).

• Pin package versions for pipelines to avoid surprise breakage.

Common Errors and Fixes

• 403/401 on API calls: token expired or missing scopes → create a new PAT and retry.

• SSL certificate verify failed: update OS CA store; confirm corporate proxy settings.

• Package load fails with binary incompatibility: rebuild from source with matching R version.

• Windows path issues with long paths: enable long paths in Group Policy or shorten project paths.

Uninstall or Reset

remove.packages(c("synapser", "synapserutils"))
renv::restore()  # to revert to the lockfile state
# Clear cached auth if needed:
synLogout()

FAQ

References

Common Upload Workflows

• renv documentation

• CRAN: R and packages

• Sage-Bionetworks/synapser

• Sage-Bionetworks/synapserutils

Common Upload Workflows