New --multi_cram option to produce a multi-query CRAM file combining all the alignments

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### `Added`
 
+- New `--multi_cram` option to produce a multi-query CRAM file combining all the alignments ([#60](https://github.com/nf-core/pairgenomealign/pull/60)).
 - New `--multiqc_thumbs` option to produce alignment thumbnails in the MultiQC report ([#93](https://github.com/nf-core/pairgenomealign/pull/93)).
 - New `--strand` option to index only one strand of the genome, which reduces memory usage at the expense of speed, and suppresses `-/+` alignments ([#97](https://github.com/nf-core/pairgenomealign/pull/97)).
 - New `--query` and `--queryName` convenience options to skip samplesheet creation when there is only one _query_ genome to align ([#112](https://github.com/nf-core/pairgenomealign/pull/112)).
@@ -15,11 +16,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 | Old parameter | New parameter      |
 | ------------- | ------------------ |
+|               | `--multi_cram`     |
 |               | `--multiqc_thumbs` |
 |               | `--query`          |
 |               | `--queryName`      |
 |               | `--strand`         |
 
+### `Dependencies`
+
+| Dependency       | Old version | New version |
+| ---------------- | ----------- | ----------- |
+| `SAMTOOLS_MERGE` |             | 1.23.1      |
+
 ## [v2.2.3](https://github.com/nf-core/pairgenomealign/releases/tag/2.2.3) "Reitou mikan" - [May 20th 2026]
 
 ### `Fixed`

conf/modules.config

@@ -111,6 +111,16 @@ process {
         ext.prefix = { "${meta.id}.m2m_plt_filtered" }
     }
 
+    withName: ALIGNMENT_CRAM {
+        publishDir = [
+            enabled: false
+        ]
+    }
+
+    withName: ALIGNMENT_MERGE {
+        ext.args = { "-O cram,version=3.0 --write-index" }
+    }
+
     withName: 'MULTIQC' {
         ext.args   = { params.multiqc_title ? "--title \"$params.multiqc_title\"" : '' }
         publishDir = [
@@ -140,6 +150,8 @@ process {
         ]
     }
 
+    // FASTA_BGZIP_INDEX_DICT_SAMTOOLS subworkflow:
+
     withName: 'SAMTOOLS_BGZIP' {
         publishDir = [
             path: { "${params.outdir}/alignment" },
@@ -158,7 +170,8 @@ process {
     withName: 'SAMTOOLS_DICT' {
         ext.args = { "-u ./${fasta} -a ${meta.id}" }
         publishDir = [
-            enabled: false
+            path: { "${params.outdir}/alignment" },
+            mode: params.publish_dir_mode,
         ]
     }
 

docs/output.md

@@ -44,6 +44,8 @@ Basic statistics on nucleotide content and contig length are collected for align
   - `*.o2o_aln.maf.gz` is the _**one-to-one**_ alignment between the _target_ and _query_ genomes.
   - `*.o2o_aln.tsv` reports nucleotide percent identity of the _**one-to-one**_ alignment for MultiQC.
   - For each _**one-to-one**_ alignment there will be an additional file in a format such as Axt, Chain, GFF or SAM/BAM/CRAM if you used the `--export_aln_to` parameter. These extra files are always compressed with gzip when their format is text-based. The SAM/BAM/CRAM files are always sorted. Their header features all sequences from the _target_ genome, including the ones that did not align to the _query_ so that alignment files can be merged without disturbing the sort order.
+  - The _target_ genome sequence, compressed with `bgzip` and indexed by `samtools` is also present when BAM or CRAM files are produced.
+  - A multi-_query_ CRAM sequence is present when `--multi_cram` is used, named like the _target_ genome but with the `cram` suffix.
 
 </details>
 

docs/usage.md

@@ -51,6 +51,7 @@ The parameters are described in details in the [online documentation](https://nf
 - `--m2m` enables the computation of the _many-to-many_ alignment, which reports alignments without enforcing uniqueness. This mode is required for self‑alignments and is useful for duplication or repeat analyses, but can exhaust computing resources on large or highly repetitive genomes.
 - The `--skip_dotplot_*` options disable dotplot visualisations. This is particularly useful when comparing very similar and repetitive genomes (for example, two vertebrate genomes from the same species), where dotplots other than the _one‑to‑one_ alignment can become extremely dense and difficult to interpret, without affecting the underlying alignments.
 - Users who need formats other than MAF can use the `--export_aln_to` parameter to generate additional coordinate‑based (PSL, GFF) or full alignment (SAM/BAM/CRAM) outputs for downstream analyses. Other formats like Axt or Chain are also supported.
+- `--multi_cram` produces a single CRAM file that combines all alignments. It is neither a pangenome nor a multiple sequence alignment; however, once you make use of it—by loading it into the [Integrative Genomics Viewer](https://igv.org/), or extracting slices and converting them into multiple sequence alignments—it becomes a very powerful resource.
 
 ## Fixed arguments (taken from the [LAST cookbook][] and the [LAST tuning][] manual)
 

modules.json

@@ -60,6 +60,12 @@
                         "git_sha": "9a48bce39a67e2cb34b8f125fc1d50f0ad98b616",
                         "installed_by": ["modules"]
                     },
+                    "samtools/merge": {
+                        "branch": "master",
+                        "git_sha": "6d46786420b4d7bc88eba026eb389c0c5535d120",
+                        "installed_by": ["modules"],
+                        "patch": "modules/nf-core/samtools/merge/samtools-merge.diff"
+                    },
                     "seqtk/cutn": {
                         "branch": "master",
                         "git_sha": "a46713779030a5f508117080cbf4b693dd4c6e33",