From da8c3ed0ec300dac220bb2a9237fa1aedecfb5cc Mon Sep 17 00:00:00 2001 From: Can Kockan Date: Fri, 17 Nov 2023 11:42:24 -0500 Subject: [PATCH 1/2] Updated the SamToFastq documentation to clarify that the tool works properly for both name-sorted and coordinate-sorted inputs. Fixed some whitespace issues. --- src/main/java/picard/sam/SamToFastq.java | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/main/java/picard/sam/SamToFastq.java b/src/main/java/picard/sam/SamToFastq.java index 3e814c9a5c..de4d39e744 100755 --- a/src/main/java/picard/sam/SamToFastq.java +++ b/src/main/java/picard/sam/SamToFastq.java @@ -81,13 +81,14 @@ @DocumentedFeature public class SamToFastq extends CommandLineProgram { static final String USAGE_SUMMARY = "Converts a SAM/BAM/CRAM file to FASTQ."; - static final String USAGE_DETAILS = " Extracts read sequences and qualities from the input SAM/BAM/CRAM file and writes them into" + - "the output file in Sanger FASTQ format." + - "See MAQ FASTQ specification for details." + + static final String USAGE_DETAILS = "Extracts read sequences and qualities from the input SAM/BAM/CRAM file " + + "and writes them into the output file in Sanger FASTQ format. " + + "See MAQ FASTQ specification for details. " + "This tool can be used by way of a pipe to run BWA MEM on unmapped BAM (uBAM) files efficiently.

" + - "

In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome," + - "the read's sequence from input sam file will be reverse-complemented prior to writing it to FASTQ in order restore correctly" + - "the original read sequence as it was generated by the sequencer.

" + + "

In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome, " + + "the read's sequence from input sam file will be reverse-complemented prior to writing it to FASTQ in order restore correctly " + + "the original read sequence as it was generated by the sequencer. " + + "This tool works with both coordinate-sorted and name-sorted inputs.

" + "
" + "

Usage example:

" + "
" +

From 0da3afa6ca9d51dc537b628625c667a0d2803d95 Mon Sep 17 00:00:00 2001
From: Can Kockan 
Date: Fri, 12 Jan 2024 11:53:52 -0500
Subject: [PATCH 2/2] Additional clarifications to the documentation.

---
 src/main/java/picard/sam/SamToFastq.java | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/src/main/java/picard/sam/SamToFastq.java b/src/main/java/picard/sam/SamToFastq.java
index de4d39e744..3fbf5c91d0 100755
--- a/src/main/java/picard/sam/SamToFastq.java
+++ b/src/main/java/picard/sam/SamToFastq.java
@@ -59,12 +59,17 @@
 
 /**
  * 
 Extracts read sequences and qualities from the input SAM/BAM file and writes them into
- * the output file in Sanger FASTQ format.  .
+ * the output file in Sanger FASTQ format.
  * See MAQ FASTQ specification for details.
  * This tool can be used by way of a pipe to run BWA MEM on unmapped BAM (uBAM) files efficiently.
  * 
In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome,
- * the read's sequence from input sam file will be reverse-complemented prior to writing it to FASTQ in order restore correctly
- * the original read sequence as it was generated by the sequencer.
+ * the read's sequence from input SAM file will be reverse-complemented prior to writing it to FASTQ
+ * in order restore correctly the original read sequence as it was generated by the sequencer.
+ * 
Note: This tool works with both coordinate-sorted and name-sorted inputs. Although mates come with the
+ * same order in both FASTQ files, the behavior is different between coordinate-sorted versus name-sorted BAM files.
+ * Name-sorted BAM files will produce the very same FASTQs generated from the sequencer, whereas coordinate-sorted
+ * BAMs will result in a scrambled FASTQ file where mates match but the reads are not sorted by name.
+ * This may result in slightly different outcomes when used with non-deterministic mappers such as BWA.
  * 

  * 
Usage example:

  * 
@@ -86,9 +91,13 @@ public class SamToFastq extends CommandLineProgram {
             "See MAQ FASTQ specification for details. " +
             "This tool can be used by way of a pipe to run BWA MEM on unmapped BAM (uBAM) files efficiently.
" +
             "
In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome, " +
-            "the read's sequence from input sam file will be reverse-complemented prior to writing it to FASTQ in order restore correctly " +
-            "the original read sequence as it was generated by the sequencer. " +
-            "This tool works with both coordinate-sorted and name-sorted inputs.
" +
+            "the read's sequence from input SAM file will be reverse-complemented prior to writing it to FASTQ " +
+            "in order restore correctly the original read sequence as it was generated by the sequencer.
" +
+            "
Note: This tool works with both coordinate-sorted and name-sorted inputs. Although mates come with the " +
+            "same order in both FASTQ files, the behavior is different between coordinate-sorted versus name-sorted BAM files. " +
+            "Name-sorted BAM files will produce the very same FASTQs generated from the sequencer, whereas coordinate-sorted " +
+            "BAMs will result in a scrambled FASTQ file where mates match but the reads are not sorted by name. " +
+            "This may result in slightly different outcomes when used with non-deterministic mappers such as BWA.
" +
             "
" +
             "
Usage example:
" +
             "
" +