Summary

A Nextflow plugin for accessing Synapse (Sage Bionetworks) files using syn:// URIs. It enables transparent read access to Synapse files in pipelines and supports publishing pipeline outputs directly to Synapse folders. The plugin handles versioned files, automatic subfolder creation, secure authentication, and retains original Synapse filenames when staging files.

Get Started

Installation

Note: This plugin is not yet published to the Nextflow plugin registry. You must build and install locally.

# Clone the repo
git clone https://github.com/Sage-Bionetworks-Workflows/nf-synapse-plugin.git
cd nf-synapse-plugin

# Build and install to ~/.nextflow/plugins
make install

Then add to your nextflow.config:

plugins {
    id 'nf-synapse@0.1.0'
}

synapse {
    authToken = secrets.SYNAPSE_AUTH_TOKEN
}

Authentication

Set your Synapse Personal Access Token as a Nextflow secret:

nextflow secrets set SYNAPSE_AUTH_TOKEN syn_pat_xxxxxxxxxx

You can create a Personal Access Token at: https://www.synapse.org/#!PersonalAccessTokens:

Optional Settings

synapse {
    authToken = secrets.SYNAPSE_AUTH_TOKEN
    endpoint = 'https://repo-prod.prod.sagebase.org'  // default
}

Examples

Direct File Access

// Access a Synapse file (latest version)
synapse_file = file('syn://syn26947830')

// Access a specific version
versioned_file = file('syn://syn26947830.1')

Files are automatically downloaded and staged with their original Synapse filename (e.g., film_default.png).

In a Process

process ANALYZE {
    input:
    path input_file

    output:
    path "result.txt"

    script:
    """
    echo "Processing: ${input_file}"
    analyze.sh ${input_file} > result.txt
    """
}

workflow {
    synapse_file = file('syn://syn26947830')
    ANALYZE(synapse_file)
}

With Samplesheets

// samplesheet.csv:
// sample_id,synapse_uri
// sample1,syn://syn26947830
// sample2,syn://syn26947830.1

Channel.fromPath('samplesheet.csv')
    .splitCsv(header: true)
    .map { row -> tuple(row.sample_id, file(row.synapse_uri)) }
    .set { samples_ch }

samples_ch.view { sample_id, f -> "Sample: ${sample_id}, File: ${f.name}" }

Publishing to Synapse

params.outDir = 'syn://syn25858544'  // Synapse folder ID

process ANALYZE {
    publishDir params.outDir, mode: 'copy'

    input:
    path input_file

    output:
    path "results.txt"

    script:
    """
    analyze.sh ${input_file} > results.txt
    """
}

Publishing to Subfolders

process ANALYZE {
    publishDir "${params.outDir}/${sample_id}/results", mode: 'copy'

    input:
    tuple val(sample_id), path(input_file)

    output:
    path "output.txt"

    script:
    """
    analyze.sh ${input_file} > output.txt
    """
}

For example, publishing to syn://syn25858544/sample1/results/output.txt will:

1. Check if sample1 folder exists under syn25858544, create if not
2. Check if results folder exists under sample1, create if not
3. Upload output.txt to the results folder

License

Apache License 2.0