From 90cc4cf73b2cb5603574c40cd9578e6cae98b7fd Mon Sep 17 00:00:00 2001 From: Kiah McIntosh Date: Fri, 22 May 2026 10:44:40 +0000 Subject: [PATCH] Update readme for alignment and ingress outputs [CW-7270] --- README.md | 18 +++++------------- docs/06_pipeline_overview.md | 12 ++++-------- docs/08_outputs.md | 4 ---- docs/10_troubleshooting.md | 2 +- output_definition.json | 32 -------------------------------- 5 files changed, 10 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index f64cc96..58dc786 100644 --- a/README.md +++ b/README.md @@ -176,8 +176,7 @@ The workflow's choice of SQANTI3 as a companion QC and annotation layer matches The shared EPI2ME input handling collects FASTQ or BAM inputs, works out whether you have a single sample or a multiplexed run, and produces per-sample -FASTQ files plus read statistics. These files are published under -`ingress_results//` and are used in the downstream report. +FASTQ files plus read statistics. These files are used in the downstream report. ### 2. Sample sheet formulation @@ -220,7 +219,7 @@ requirements for a two-group DE/DTU comparison. Each sample is aligned to the supplied reference genome with [`minimap2`](https://github.com/lh3/minimap2), then sorted and indexed with [`samtools`](https://www.htslib.org/). The aligned BAMs under -`cohort/alignments/` are the main alignment files used for transcriptome +`samples//alignment/` are the main alignment files used for transcriptome analysis, optional `SQANTI3` QC, and optional IGV viewing. ### 4. Cohort transcriptome construction @@ -277,11 +276,8 @@ The workflow's analysis is controlled by a user provided genome, annotation, and The published outputs are organised around a small number of top-level directories: -+ `ingress_results//` contains prepared reads, read statistics, and sample - metadata for each sample -+ `cohort/` contains the primary joint `bambu` transcriptome, count tables, - alignments, and optional cohort `SQANTI3` outputs -+ `samples//` contains the independent per-sample `bambu` outputs and ++ `cohort/` contains the primary joint `bambu` transcriptome, count tables, and optional cohort `SQANTI3` outputs ++ `samples//` contains alignments, independent per-sample `bambu` outputs and optional per-sample `SQANTI3` outputs + `de_analysis//` contains DE and DTU results for each contrast when differential analysis is enabled @@ -362,10 +358,6 @@ Output files may be aggregated including information for all samples or provided | Title | File path | Description | Per sample or aggregated | |-------|-----------|-------------|--------------------------| | Workflow report | wf-transcriptomes-report.html | HTML report summarising transcript discovery, quantification, optional SQANTI3 classification, and optional differential analysis results. | aggregated | -| Per-file read stats | ingress_results/{{ alias }}/fastcat_stats/per-file-stats.tsv | Read statistics for each input FASTQ file in a sample, when FASTQ read stats are available. | per-sample | -| Per-read stats | ingress_results/{{ alias }}/fastcat_stats/per-read-stats.tsv.gz | Read statistics for individual reads in a sample, when this output is enabled. | per-sample | -| Ingress reads | ingress_results/{{ alias }}/seqs.fastq.gz | Reads prepared from the input data for downstream analysis. | per-sample | -| Ingress metadata | ingress_results/{{ alias }}/metamap.json | Per-sample metadata used by the workflow. | per-sample | | Aligned BAM | samples/{{ alias }}/alignment/reads.bam | Genome-aligned BAM used for bambu, optional SQANTI3 QC, and IGV. | per-sample | | Aligned BAM index | samples/{{ alias }}/alignment/reads.bam.bai | Index for the aligned BAM. | per-sample | | Alignment summary | samples/{{ alias }}/alignment/bamstats.flagstat.tsv | bamstats flagstat summary for the aligned BAM. | per-sample | @@ -466,7 +458,7 @@ In the current version DE and DTU results are grouped by contrast under #### I expected the old output layout or transcriptome files The previous workflow version emitted one flat set of transcriptome. -In the current versions, the output folder is organised around `ingress_results/`, +In the current versions, the output folder is organised around `cohort/`, `samples//`, `de_analysis//`, and `igv_reference/`. diff --git a/docs/06_pipeline_overview.md b/docs/06_pipeline_overview.md index 3bf9347..a7f763c 100644 --- a/docs/06_pipeline_overview.md +++ b/docs/06_pipeline_overview.md @@ -21,8 +21,7 @@ The workflow's choice of SQANTI3 as a companion QC and annotation layer matches The shared EPI2ME input handling collects FASTQ or BAM inputs, works out whether you have a single sample or a multiplexed run, and produces per-sample -FASTQ files plus read statistics. These files are published under -`ingress_results//` and are used in the downstream report. +FASTQ files plus read statistics. These files are used in the downstream report. ### 2. Sample sheet formulation @@ -65,7 +64,7 @@ requirements for a two-group DE/DTU comparison. Each sample is aligned to the supplied reference genome with [`minimap2`](https://github.com/lh3/minimap2), then sorted and indexed with [`samtools`](https://www.htslib.org/). The aligned BAMs under -`cohort/alignments/` are the main alignment files used for transcriptome +`samples//alignment/` are the main alignment files used for transcriptome analysis, optional `SQANTI3` QC, and optional IGV viewing. ### 4. Cohort transcriptome construction @@ -122,11 +121,8 @@ The workflow's analysis is controlled by a user provided genome, annotation, and The published outputs are organised around a small number of top-level directories: -+ `ingress_results//` contains prepared reads, read statistics, and sample - metadata for each sample -+ `cohort/` contains the primary joint `bambu` transcriptome, count tables, - alignments, and optional cohort `SQANTI3` outputs -+ `samples//` contains the independent per-sample `bambu` outputs and ++ `cohort/` contains the primary joint `bambu` transcriptome, count tables, and optional cohort `SQANTI3` outputs ++ `samples//` contains alignments, independent per-sample `bambu` outputs and optional per-sample `SQANTI3` outputs + `de_analysis//` contains DE and DTU results for each contrast when differential analysis is enabled diff --git a/docs/08_outputs.md b/docs/08_outputs.md index 6cd49e9..bdfddd2 100644 --- a/docs/08_outputs.md +++ b/docs/08_outputs.md @@ -3,10 +3,6 @@ Output files may be aggregated including information for all samples or provided | Title | File path | Description | Per sample or aggregated | |-------|-----------|-------------|--------------------------| | Workflow report | wf-transcriptomes-report.html | HTML report summarising transcript discovery, quantification, optional SQANTI3 classification, and optional differential analysis results. | aggregated | -| Per-file read stats | ingress_results/{{ alias }}/fastcat_stats/per-file-stats.tsv | Read statistics for each input FASTQ file in a sample, when FASTQ read stats are available. | per-sample | -| Per-read stats | ingress_results/{{ alias }}/fastcat_stats/per-read-stats.tsv.gz | Read statistics for individual reads in a sample, when this output is enabled. | per-sample | -| Ingress reads | ingress_results/{{ alias }}/seqs.fastq.gz | Reads prepared from the input data for downstream analysis. | per-sample | -| Ingress metadata | ingress_results/{{ alias }}/metamap.json | Per-sample metadata used by the workflow. | per-sample | | Aligned BAM | samples/{{ alias }}/alignment/reads.bam | Genome-aligned BAM used for bambu, optional SQANTI3 QC, and IGV. | per-sample | | Aligned BAM index | samples/{{ alias }}/alignment/reads.bam.bai | Index for the aligned BAM. | per-sample | | Alignment summary | samples/{{ alias }}/alignment/bamstats.flagstat.tsv | bamstats flagstat summary for the aligned BAM. | per-sample | diff --git a/docs/10_troubleshooting.md b/docs/10_troubleshooting.md index 6d0d996..3da83cf 100644 --- a/docs/10_troubleshooting.md +++ b/docs/10_troubleshooting.md @@ -50,7 +50,7 @@ In the current version DE and DTU results are grouped by contrast under #### I expected the old output layout or transcriptome files The previous workflow version emitted one flat set of transcriptome. -In the current versions, the output folder is organised around `ingress_results/`, +In the current versions, the output folder is organised around `cohort/`, `samples//`, `de_analysis//`, and `igv_reference/`. diff --git a/output_definition.json b/output_definition.json index c654378..13dd96b 100644 --- a/output_definition.json +++ b/output_definition.json @@ -8,38 +8,6 @@ "optional": false, "type": "aggregated" }, - "read-stats-per-file": { - "filepath": "ingress_results/{{ alias }}/fastcat_stats/per-file-stats.tsv", - "title": "Per-file read stats", - "description": "Read statistics for each input FASTQ file in a sample, when FASTQ read stats are available.", - "mime-type": "text/tab-separated-values", - "optional": true, - "type": "per-sample" - }, - "read-stats-per-read": { - "filepath": "ingress_results/{{ alias }}/fastcat_stats/per-read-stats.tsv.gz", - "title": "Per-read stats", - "description": "Read statistics for individual reads in a sample, when this output is enabled.", - "mime-type": "application/gzip", - "optional": true, - "type": "per-sample" - }, - "sample-fastq": { - "filepath": "ingress_results/{{ alias }}/seqs.fastq.gz", - "title": "Ingress reads", - "description": "Reads prepared from the input data for downstream analysis.", - "mime-type": "application/gzip", - "optional": true, - "type": "per-sample" - }, - "sample-metadata": { - "filepath": "ingress_results/{{ alias }}/metamap.json", - "title": "Ingress metadata", - "description": "Per-sample metadata used by the workflow.", - "mime-type": "application/json", - "optional": true, - "type": "per-sample" - }, "sample-bam": { "filepath": "samples/{{ alias }}/alignment/reads.bam", "title": "Aligned BAM",