---
title: "Synapse R Client Overview"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Synapse R Client Overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
## Overview

The `synapser` package provides an interface to [Synapse](https://www.synapse.org), 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](https://python-docs.synapse.org), [Java](https://github.com/Sage-Bionetworks/Synapse-Repository-Services/tree/develop/client/synapseJavaClient), and [the web browser](https://www.synapse.org).

If you're just getting started with `synapser`, have a look at the [Getting Started](index.html) guides: [Installation](installation.html), [Authentication](authentication.html), and [Configuration](configuration.html).

Good example projects are:

* [TCGA Pan-cancer (syn300013)](https://www.synapse.org/#!Synapse:syn300013)
* [Development of a Prognostic Model for Breast Cancer Survival in an Open Challenge Environment (syn1721874)](https://www.synapse.org/#!Synapse:syn1721874)
* [Demo projects (syn1899339)](https://www.synapse.org/#!Synapse:syn1899339)

This page gives a short tour of what you can do with `synapser`. Each section links to a tutorial that covers the topic in depth.

## Installation

Install `synapser` from the Synapse R repository (RAN):
```{r eval = FALSE}
install.packages("synapser", repos = c("http://ran.synapse.org", "https://cloud.r-project.org"))
```

Alternatively, edit your `~/.Rprofile` and configure your default repositories:
```{r eval = FALSE}
options(repos = c("http://ran.synapse.org", "https://cloud.r-project.org"))
```

after which you may run `install.packages` without specifying the repositories:
```{r eval = FALSE}
install.packages("synapser")
```

`synapser` sets up the Synapse Python client it needs the first time it is loaded, so you don't need to install Python yourself. For detailed installation instructions, including installing from GitHub, see the [Installation vignette](installation.html). For troubleshooting, see the [Troubleshooting](troubleshooting.html) guide.

## Connecting to Synapse

To use Synapse, you'll need to
[register](https://www.synapse.org/#!RegisterAccount:0) for an account. The
Synapse website can authenticate using a Google account. If you authenticate
using a Google account, you'll need to create a personal access token to log
in to Synapse through the programmatic clients. See the
[Authentication vignette](authentication.html) for more information.

Once that's done, you'll be able to load the library and login:
```{r collapse=TRUE, eval = FALSE}
library(synapser)
synLogin()
```

For more ways to manage your Synapse credentials, please see the [Authentication vignette](authentication.html), and the native reference documentation:
```{r eval = FALSE}
?synLogin
?synLogout
```

## Accessing Data

Synapse identifiers start with `syn`, followed by numbers (for example, `syn123`).
Upload a local file with `synStore()`, and download a file with `synGet()`:
```{r eval = FALSE}
file <- File(path = "/path/to/data.csv", parent_id = "syn123") |> synStore()

downloaded_file <- synGet(
  file$id,
  file_options = FileOptions(download_location = "/path/to/downloads/")
)
downloaded_file$path
```

By default, files are downloaded to the Synapse cache. See
[Data Upload, Download, and Delete](data_upload_download.html) and [Files](file.html)
for more, including versioning. To move many files at once, see
[Uploading data in bulk](upload_data_in_bulk.html),
[Downloading data in bulk](download_data_in_bulk.html), and
[Downloading data by Synapse ID](download_data_by_synid.html).

## Organizing Data in a Project

Projects and folders are containers that organize your data:
```{r eval = FALSE}
project <- Project(name = "My uniquely named project") |> synStore()
folder <- Folder(name = "raw_data", parent_id = project$id) |> synStore()
```

To list what a project or folder contains without downloading anything, sync its
metadata:
```{r eval = FALSE}
project <- project |> synSyncFromSynapse(download_file = FALSE, recursive = FALSE)
for (child in project$folders) {
  print(child$name)
}
```

See [Projects](project.html), [Folders](folder.html), and
[Structuring Your Synapse Project](structuring_your_project.html).

## Annotating Synapse Entities

Annotations are key-value metadata that make your data searchable. Set them with
`synSetProperties()` and save them with `synStore()`:
```{r eval = FALSE}
file <- synGet(file$id, file_options = FileOptions(download_file = FALSE)) |>
  synSetProperties(annotations = list(assay = "RNA-seq", fileType = "csv")) |>
  synStore()
file$annotations
```

See [Add, Update and Remove Annotations](data_upload_download.html#add-update-and-remove-annotations)
and [Properties and annotations](properties_vs_annotations.html).

## Provenance

Synapse's provenance tools record what was used, and what was executed, to create a
file. Attach an `Activity` to an entity and store it:
```{r eval = FALSE}
file <- synGet(file$id, file_options = FileOptions(download_file = FALSE)) |>
  synSetProperties(
    activity = Activity(
      name = "clustering",
      description = "whizzy clustering",
      used = list(UsedEntity(target_id = "syn1234")),
      executed = list(UsedURL(name = "analysis code", url = "https://github.com/my-org/my-analysis"))
    )
  ) |>
  synStore()
```

See [Activity/Provenance](domain_models_of_synapse.html#activityprovenance) and the
`Activity` reference documentation (`?Activity`).

## Tables

Synapse Tables store tabular data that can be queried using a SQL-like query
language. See [Tables](tables.html), [Virtual Tables](virtualtable.html), and
[Dataset Collection](datasetcollection.html).

## Wikis

Wiki pages let you describe your project and its data in Markdown:
```{r eval = FALSE}
wiki_page <- WikiPage(
  owner_id = project$id,
  title = "My Wiki Page",
  markdown = "# My Wiki Page\n\nThis is a wiki page."
) |> synStore()
```

See [Wikis](wiki.html).

## Evaluations

An Evaluation is a queue that accepts and scores submissions, for example in a
computational challenge. Submit an entity to an evaluation queue:
```{r eval = FALSE}
submission <- Submission(
  entity_id = file$id,
  evaluation_id = "9999999",
  name = "My Submission"
) |> synStore()
```

See [Evaluations](evaluation.html) and
[Submissions, SubmissionStatuses, SubmissionBundles](submission.html).

## Sharing Access to Content

By default, data you upload is private to you. Share it by setting permissions for
a user, a team, or everyone, for example to give the public read access:
```{r eval = FALSE}
project |> synSetPermissions(principal_id = 273949L, access_type = list("READ"))
```

See [Sharing Settings (ACL Management)](sharing_settings.html) and
[Access Control](access_control.html).

## File Views

A file view can be defined by its scope. It allows querying for files within the
scope using a SQL-like syntax. Please visit the [EntityView vignette](entityview.html)
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](https://rest-docs.synapse.org/rest/).

```{r eval = FALSE}
?synRestGet
?synRestPost
?synRestPut
?synRestDelete
```

## Synapse Utilities

Utilities that used to live in the separate
[synapserutils](https://github.com/Sage-Bionetworks/synapserutils) package are now
available directly in `synapser`:

* Copy files, folders, and projects with `synCopy()`.
* Upload data to Synapse in bulk with `synSyncToSynapse()` (see [Uploading data in bulk](upload_data_in_bulk.html)).
* Download data from Synapse in bulk with `synSyncFromSynapse()` (see [Downloading data in bulk](download_data_in_bulk.html)).

## More information

For more information see the
[Synapse User Guide](https://docs.synapse.org/synapse-docs).