nf-core · mashehu · Feb 27, 2025 · Feb 27, 2025 · Feb 27, 2025 · Feb 27, 2025
diff --git a/.github/workflows/nf-test.yml b/.github/workflows/nf-test.yml
@@ -64,11 +64,12 @@ jobs:
     runs-on: # use self-hosted runners
       - runs-on=${{ github.run_id }}-nf-test
       - runner=4cpu-linux-x64
+      - disk=large
     strategy:
       fail-fast: false
       matrix:
         shard: ${{ fromJson(needs.nf-test-changes.outputs.shard) }}
-        profile: [conda, docker, singularity]
+        profile: [docker, singularity] # TODO: add conda back, but only for cellpose
         isMain:
           - ${{ github.base_ref == 'master' || github.base_ref == 'main' }}
         # Exclude conda and singularity on dev

diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,7 @@ testing/
 testing*
 *.pyc
 null/
+sandbox
+samplesheets
+lint_*
+.nf-test*
diff --git a/.nf-core.yml b/.nf-core.yml
@@ -9,8 +9,9 @@ lint:
   files_unchanged:
     - .github/CONTRIBUTING.md
     - assets/sendmail_template.txt
-    - .github/CONTRIBUTING.md
-    - assets/sendmail_template.txt
+    - assets/nf-core-sopa_logo_light.png
+    - docs/images/nf-core-sopa_logo_light.png
+    - docs/images/nf-core-sopa_logo_dark.png
   multiqc_config: false
 nf_core_version: 3.3.2
 repository_type: pipeline
@@ -27,4 +28,4 @@ template:
     - igenomes
     - multiqc
     - fastqc
-  version: 1.0.0dev
+  version: 1.0.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,14 +3,10 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v1.0.0dev - [date]
+## v1.0.0 - [2025-07-22]
 
 Initial release of nf-core/sopa, created with the [nf-core](https://nf-co.re/) template.
 
 ### `Added`
 
-### `Fixed`
-
-### `Dependencies`
-
-### `Deprecated`
+Sopa can be run with all the technologies currently supported - including Visium HD.
diff --git a/CITATIONS.md b/CITATIONS.md
@@ -1,5 +1,9 @@
 # nf-core/sopa: Citations
 
+## [sopa](https://www.nature.com/articles/s41467-024-48981-z)
+
+> Blampey, Q., Mulder, K., Gardet, M. et al. Sopa: a technology-invariant pipeline for analyses of image-based spatial omics. Nat Commun 15, 4981 (2024). https://doi.org/10.1038/s41467-024-48981-z
+
 ## [nf-core](https://pubmed.ncbi.nlm.nih.gov/32055031/)
 
 > Ewels PA, Peltzer A, Fillinger S, Patel H, Alneberg J, Wilm A, Garcia MU, Di Tommaso P, Nahnsen S. The nf-core framework for community-curated bioinformatics pipelines. Nat Biotechnol. 2020 Mar;38(3):276-278. doi: 10.1038/s41587-020-0439-x. PubMed PMID: 32055031.
@@ -10,6 +14,22 @@
 
 ## Pipeline tools
 
+- [AnnData](https://github.com/scverse/anndata)
+
+  > Virshup I, Rybakov S, Theis FJ, Angerer P, Wolf FA. bioRxiv 2021.12.16.473007; doi: https://doi.org/10.1101/2021.12.16.473007
+
+- [Scanpy](https://github.com/theislab/scanpy)
+
+  > Wolf F, Angerer P, Theis F. SCANPY: large-scale single-cell gene expression data analysis. Genome Biol 19, 15 (2018). doi: https://doi.org/10.1186/s13059-017-1382-0
+
+- [Space Ranger](https://www.10xgenomics.com/support/software/space-ranger)
+
+  > 10x Genomics Space Ranger 2.1.0 [Online]
+
+- [SpatialData](https://www.biorxiv.org/content/10.1101/2023.05.05.539647v1)
+
+  > Marconato L, Palla G, Yamauchi K, Virshup I, Heidari E, Treis T, Toth M, Shrestha R, Vöhringer H, Huber W, Gerstung M, Moore J, Theis F, Stegle O. SpatialData: an open and universal data framework for spatial omics. bioRxiv 2023.05.05.539647; doi: https://doi.org/10.1101/2023.05.05.539647
+
 ## Software packaging/containerisation tools
 
 - [Anaconda](https://anaconda.com)

diff --git a/README.md b/README.md
@@ -20,47 +20,52 @@
 
 ## Introduction
 
-**nf-core/sopa** is a bioinformatics pipeline that ...
+**nf-core/sopa** is the Nextflow version of [Sopa](https://github.com/gustaveroussy/sopa). Built on top of [SpatialData](https://github.com/scverse/spatialdata), Sopa enables processing and analyses of spatial omics data with single-cell resolution (spatial transcriptomics or multiplex imaging data) using a standard data structure and output. We currently support the following technologies: Xenium, Visium HD, MERSCOPE, CosMX, PhenoCycler, MACSima, Molecural Cartography, and others. It outputs a `.zarr` directory containing a processed [SpatialData](https://github.com/scverse/spatialdata) object, and a `.explorer` directory for visualization.
 
-<!-- TODO nf-core:
-   Complete this sentence with a 2-3 sentence summary of what types of data the pipeline ingests, a brief overview of the
-   major pipeline sections and the types of output it produces. You're giving an overview to someone new
-   to nf-core here, in 15-20 seconds. For an example, see https://github.com/nf-core/rnaseq/blob/master/README.md#introduction
--->
+> [!WARNING]
+> If you are interested in the main Sopa python package, refer to [this Sopa repository](https://github.com/gustaveroussy/sopa). Else, if you want to use Nextflow, you are in the good place.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gustaveroussy/sopa/main/docs/assets/overview_white.png" alt="sopa_overview" width="100%"/>
+</p>
+
+1. (Visium HD only) Raw data processing with Space Ranger
+2. (Optional) Tissue segmentation
+3. Cell segmentation with Cellpose, Baysor, Proseg, Comseg, Stardist, ...
+4. Aggregation, i.e. counting the transcripts inside the cells and/or averaging the channel intensities inside cells
+5. (Optional) Cell-type annotation
+6. User-friendly output creation for visualization and quick analysis
+7. Full [SpatialData](https://github.com/scverse/spatialdata) object export as a `.zarr` directory
 
-<!-- TODO nf-core: Include a figure that guides the user through the major workflow steps. Many nf-core
-     workflows use the "tube map" design for that. See https://nf-co.re/docs/guidelines/graphic_design/workflow_diagrams#examples for examples.   -->
-<!-- TODO nf-core: Fill in short bullet-pointed list of the default steps in the pipeline -->
+After running `nf-core/sopa`, you can continue analyzing your `SpatialData` object with [`sopa` as a Python package](https://github.com/gustaveroussy/sopa).
 
 ## Usage
 
 > [!NOTE]
 > If you are new to Nextflow and nf-core, please refer to [this page](https://nf-co.re/docs/usage/installation) on how to set-up Nextflow. Make sure to [test your setup](https://nf-co.re/docs/usage/introduction#how-to-run-a-pipeline) with `-profile test` before running the workflow on actual data.
 
-<!-- TODO nf-core: Describe the minimum required steps to execute the pipeline, e.g. how to prepare samplesheets.
-     Explain what rows and columns represent. For instance (please edit as appropriate):
-
-First, prepare a samplesheet with your input data that looks as follows:
+First, prepare a samplesheet that lists the `data_path` to each sample data directory (typically, the per-sample output of the Xenium/MERSCOPE/etc, see more info [here](https://gustaveroussy.github.io/sopa/faq/#what-are-the-inputs-of-sopa)). You can optionally add `sample` to provide a name to your output directory, else it will be named based on `data_path`. Here is a samplesheet example:
 
 `samplesheet.csv`:
 
 ```csv
-sample,fastq_1,fastq_2
-CONTROL_REP1,AEG588A1_S1_L002_R1_001.fastq.gz,AEG588A1_S1_L002_R2_001.fastq.gz
+sample,data_path
+SAMPLE1,/path/to/one/merscope_directory
+SAMPLE2,/path/to/one/merscope_directory
 ```
 
-Each row represents a fastq file (single-end) or a pair of fastq files (paired end).
+> [!WARNING]
+> If you have Visium HD data, the samplesheet will have a different format than the one above. Directly refer to the [usage documentation](https://nf-co.re/sopa/usage) and the [parameter documentation](https://nf-co.re/sopa/parameters).
 
--->
+Then, choose the Sopa parameters. You can find existing Sopa params files [here](https://github.com/gustaveroussy/sopa/tree/main/workflow/config), and follow the [corresponding README instructions](https://github.com/gustaveroussy/sopa/blob/main/workflow/config/README.md) of to get your `-params-file` argument.
 
 Now, you can run the pipeline using:
 
-<!-- TODO nf-core: update the following command to include all required parameters for a minimal example -->
-
 ```bash
 nextflow run nf-core/sopa \
    -profile <docker/singularity/.../institute> \
    --input samplesheet.csv \
+   -params-file <PARAMS_FILE> \
    --outdir <OUTDIR>
 ```
 
@@ -77,7 +82,7 @@ For more details about the output files and reports, please refer to the
 
 ## Credits
 
-nf-core/sopa was originally written by Quentin Blampey.
+nf-core/sopa was originally written by Quentin Blampey during his work at the following institutions: CentraleSupélec, Gustave Roussy Institute, and Université Paris-Saclay.
 
 We thank the following people for their extensive assistance in the development of this pipeline:
 
@@ -94,10 +99,16 @@ For further information or help, don't hesitate to get in touch on the [Slack `#
 <!-- TODO nf-core: Add citation for pipeline after first release. Uncomment lines below and update Zenodo doi and badge at the top of this file. -->
 <!-- If you use nf-core/sopa for your analysis, please cite it using the following doi: [10.5281/zenodo.XXXXXX](https://doi.org/10.5281/zenodo.XXXXXX) -->
 
-<!-- TODO nf-core: Add bibliography of tools and data used in your pipeline -->
-
 An extensive list of references for the tools used by the pipeline can be found in the [`CITATIONS.md`](CITATIONS.md) file.
 
+You can cite the `sopa` publication as follows:
+
+> Sopa: a technology-invariant pipeline for analyses of image-based spatial omics.
+>
+> Quentin Blampey, Kevin Mulder, Margaux Gardet, Stergios Christodoulidis, Charles-Antoine Dutertre, Fabrice André, Florent Ginhoux & Paul-Henry Cournède.
+>
+> _Nat Commun._ 2024 June 11. doi: [10.1038/s41467-024-48981-z](https://doi.org/10.1038/s41467-024-48981-z)
+
 You can cite the `nf-core` publication as follows:
 
 > **The nf-core framework for community-curated bioinformatics pipelines.**

diff --git a/assets/schema_input.json b/assets/schema_input.json
@@ -10,24 +10,84 @@
             "sample": {
                 "type": "string",
                 "pattern": "^\\S+$",
-                "errorMessage": "Sample name must be provided and cannot contain spaces",
+                "errorMessage": "Sample name cannot contain spaces",
                 "meta": ["id"]
             },
-            "fastq_1": {
+            "data_path": {
                 "type": "string",
-                "format": "file-path",
+                "pattern": "^\\S+$",
+                "format": "path",
+                "exists": true,
+                "errorMessage": "Data path must exist and not contain spaces"
+            },
+            "fastq_dir": {
+                "type": "string",
+                "pattern": "^\\S+$",
+                "format": "path",
+                "exists": true,
+                "errorMessage": "Path to the fastq directory must exist and not contain spaces",
+                "meta": ["fastq_dir"]
+            },
+            "cytaimage": {
+                "type": "string",
+                "pattern": "^\\S+(tif|tiff)$",
+                "format": "path",
+                "exists": true,
+                "errorMessage": "Path to the cytaimage file must exist, not contain spaces, and be a .tif or .tiff file",
+                "meta": ["cytaimage"]
+            },
+            "colorizedimage": {
+                "type": "string",
+                "pattern": "^\\S+(tif|tiff|jpg|jpeg)$",
+                "format": "path",
+                "exists": true,
+                "errorMessage": "Path to the colorizedimage file must exist, not contain spaces, and be a .tif, .tiff, .jpg or .jpeg file",
+                "meta": ["colorizedimage"]
+            },
+            "darkimage": {
+                "type": "string",
+                "pattern": "^\\S+(tif|tiff|jpg|jpeg)$",
+                "format": "path",
+                "exists": true,
+                "errorMessage": "Path to the darkimage file must exist, not contain spaces, and be a .tif, .tiff, .jpg or .jpeg file",
+                "meta": ["darkimage"]
+            },
+            "image": {
+                "type": "string",
+                "pattern": "^\\S+(tif|tiff|jpg|jpeg)$",
+                "format": "path",
+                "exists": true,
+                "errorMessage": "Path to the image must exist, not contain spaces, and be a .tif, .tiff, .jpg or .jpeg file",
+                "meta": ["image"]
+            },
+            "slide": {
+                "type": "string",
+                "pattern": "^\\S+$",
+                "errorMessage": "Slide name cannot contain spaces",
+                "meta": ["slide"]
+            },
+            "area": {
+                "type": "string",
+                "pattern": "^\\S+$",
+                "errorMessage": "Area name cannot contain spaces",
+                "meta": ["area"]
+            },
+            "manual_alignment": {
+                "type": "string",
+                "pattern": "^\\S+json$",
+                "format": "path",
                 "exists": true,
-                "pattern": "^([\\S\\s]*\\/)?[^\\s\\/]+\\.f(ast)?q\\.gz$",
-                "errorMessage": "FastQ file for reads 1 must be provided, cannot contain spaces and must have extension '.fq.gz' or '.fastq.gz'"
+                "errorMessage": "Path to the manual_alignment must exist, not contain spaces, and be a .json file",
+                "meta": ["manual_alignment"]
             },
-            "fastq_2": {
+            "slidefile": {
                 "type": "string",
-                "format": "file-path",
+                "pattern": "^\\S+json$",
+                "format": "path",
                 "exists": true,
-                "pattern": "^([\\S\\s]*\\/)?[^\\s\\/]+\\.f(ast)?q\\.gz$",
-                "errorMessage": "FastQ file for reads 2 cannot contain spaces and must have extension '.fq.gz' or '.fastq.gz'"
+                "errorMessage": "Path to the slidefile must exist, not contain spaces, and be a .json file",
+                "meta": ["slidefile"]
             }
-        },
-        "required": ["sample", "fastq_1"]
+        }
     }
 }
diff --git a/conf/base.config b/conf/base.config
@@ -9,8 +9,6 @@
 */
 
 process {
-
-    // TODO nf-core: Check the defaults for all processes
     cpus   = { 1      * task.attempt }
     memory = { 6.GB   * task.attempt }
     time   = { 4.h    * task.attempt }
@@ -19,13 +17,6 @@ process {
     maxRetries    = 1
     maxErrors     = '-1'
 
-    // Process-specific resource requirements
-    // NOTE - Please try and reuse the labels below as much as possible.
-    //        These labels are used and recognised by default in DSL2 files hosted on nf-core/modules.
-    //        If possible, it would be nice to keep the same label naming convention when
-    //        adding in your local modules too.
-    // TODO nf-core: Customise requirements for specific processes.
-    // See https://www.nextflow.io/docs/latest/config.html#config-process-selectors
     withLabel:process_single {
         cpus   = { 1                   }
         memory = { 6.GB * task.attempt }
@@ -52,6 +43,11 @@ process {
     withLabel:process_high_memory {
         memory = { 200.GB * task.attempt }
     }
+    withName:PATCH_SEGMENTATION_PROSEG {
+        cpus   = { 8      * task.attempt }
+        memory = { 200.GB * task.attempt }
+        time   = { 10.d   * task.attempt }
+    }
     withLabel:error_ignore {
         errorStrategy = 'ignore'
     }

diff --git a/conf/modules.config b/conf/modules.config
@@ -11,11 +11,12 @@
 */
 
 process {
-
-    publishDir = [
-        path: { "${params.outdir}/${task.process.tokenize(':')[-1].tokenize('_')[0].toLowerCase()}" },
-        mode: params.publish_dir_mode,
-        saveAs: { filename -> filename.equals('versions.yml') ? null : filename }
-    ]
-
+    withName: SPACERANGER_COUNT {
+        ext.args = '--create-bam="false"'
+        publishDir = [
+            path: { "${params.outdir}/${meta.id}_spaceranger" },
+            mode: params.publish_dir_mode,
+            saveAs: { filename -> filename.equals('versions.yml') ? null : filename },
+        ]
+    }
 }
diff --git a/conf/test.config b/conf/test.config
@@ -14,16 +14,49 @@ process {
     resourceLimits = [
         cpus: 4,
         memory: '15.GB',
-        time: '1.h'
+        time: '1.h',
     ]
 }
 
 params {
-    config_profile_name        = 'Test profile'
-    config_profile_description = 'Minimal test dataset to check pipeline function'
+    config_profile_name    = 'Test profile with Proseg'
+config_profile_description = 'Minimal test dataset to check pipeline function'
 
     // Input data
-    // TODO nf-core: Specify the paths to your test data on nf-core/test-datasets
-    // TODO nf-core: Give any required params for the test so that command line flags are not needed
-    input  = params.pipelines_testdata_base_path + 'viralrecon/samplesheet/samplesheet_test_illumina_amplicon.csv'
+    input = "${baseDir}/tests/samplesheet.csv"
+
+    read = [
+        technology: "toy_dataset",
+        kwargs: [
+            genes: 500
+        ],
+    ]
+
+    patchify = [
+        patch_width_microns: 400,
+        patch_overlap_microns: 20,
+    ]
+
+    segmentation.proseg.prior_shapes_key = "auto"
+
+    aggregate = [
+        aggregate_channels: true,
+        min_transcripts: 5,
+    ]
+
+    annotation = [
+        method: "fluorescence",
+        args: [
+            marker_cell_dict: [
+                CK: "Tumoral cell",
+                CD3: "T cell",
+                CD20: "B cell",
+            ]
+        ],
+    ]
+
+    explorer = [
+        ram_threshold_gb: 4,
+        pixel_size: 0.1,
+    ]
 }