From 17bcdb6227f8e934e1b1bdb11f6dab842e1a3d4b Mon Sep 17 00:00:00 2001
From: Phil Ewels <phil.ewels@seqera.io>
Date: Fri, 29 May 2026 10:51:38 +0200
Subject: [PATCH] Add mean and median sequence length to Basic Statistics

Implements #203. The Basic Statistics module currently reports only the
range of read lengths; this adds "Mean sequence length" and "Median
sequence length" rows so users (and downstream tools such as MultiQC) get
accurate values straight from the source rather than estimating them.

The mean is total bases / total sequences (2 d.p.); the median is derived
from a per-length histogram over non-filtered sequences (for an even count,
the two central values averaged and rounded up). Both are added to the
ResultsTable model, so they appear in the interactive results panel, the
HTML report, and fastqc_data.txt together.

Integration test approved files updated accordingly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...tentsTest_complex_fastqc_data.approved.txt |  2 +
 ...tsTest_complex_fastqc_report.approved.html |  8 +++
 ...tentsTest_minimal_fastqc_data.approved.txt |  2 +
 ...tsTest_minimal_fastqc_report.approved.html |  8 +++
 uk/ac/babraham/FastQC/Modules/BasicStats.java | 63 +++++++++++++++++--
 5 files changed, 78 insertions(+), 5 deletions(-)

diff --git a/test/integration/FileContentsTest_complex_fastqc_data.approved.txt b/test/integration/FileContentsTest_complex_fastqc_data.approved.txt
index b967956..d4a75e7 100644
--- a/test/integration/FileContentsTest_complex_fastqc_data.approved.txt
+++ b/test/integration/FileContentsTest_complex_fastqc_data.approved.txt
@@ -8,6 +8,8 @@ Total Sequences	5
 Total Bases	80 bp
 Sequences flagged as poor quality	0
 Sequence length	16
+Mean sequence length	16.00
+Median sequence length	16
 %GC	50
 >>END_MODULE
 >>Per base sequence quality	pass
diff --git a/test/integration/FileContentsTest_complex_fastqc_report.approved.html b/test/integration/FileContentsTest_complex_fastqc_report.approved.html
index 3e032bd..327775a 100644
--- a/test/integration/FileContentsTest_complex_fastqc_report.approved.html
+++ b/test/integration/FileContentsTest_complex_fastqc_report.approved.html
@@ -255,6 +255,14 @@ <h2 id="M0"><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYA
        <td>Sequence length</td>
        <td>16</td>
       </tr>
+      <tr>
+       <td>Mean sequence length</td>
+       <td>16.00</td>
+      </tr>
+      <tr>
+       <td>Median sequence length</td>
+       <td>16</td>
+      </tr>
       <tr>
        <td>%GC</td>
        <td>50</td>
diff --git a/test/integration/FileContentsTest_minimal_fastqc_data.approved.txt b/test/integration/FileContentsTest_minimal_fastqc_data.approved.txt
index 48db11a..c1f0bdb 100644
--- a/test/integration/FileContentsTest_minimal_fastqc_data.approved.txt
+++ b/test/integration/FileContentsTest_minimal_fastqc_data.approved.txt
@@ -8,6 +8,8 @@ Total Sequences	1
 Total Bases	16 bp
 Sequences flagged as poor quality	0
 Sequence length	16
+Mean sequence length	16.00
+Median sequence length	16
 %GC	0
 >>END_MODULE
 >>Per base sequence quality	pass
diff --git a/test/integration/FileContentsTest_minimal_fastqc_report.approved.html b/test/integration/FileContentsTest_minimal_fastqc_report.approved.html
index a4e6c00..5d6f9a9 100644
--- a/test/integration/FileContentsTest_minimal_fastqc_report.approved.html
+++ b/test/integration/FileContentsTest_minimal_fastqc_report.approved.html
@@ -255,6 +255,14 @@ <h2 id="M0"><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYA
        <td>Sequence length</td>
        <td>16</td>
       </tr>
+      <tr>
+       <td>Mean sequence length</td>
+       <td>16.00</td>
+      </tr>
+      <tr>
+       <td>Median sequence length</td>
+       <td>16</td>
+      </tr>
       <tr>
        <td>%GC</td>
        <td>0</td>
diff --git a/uk/ac/babraham/FastQC/Modules/BasicStats.java b/uk/ac/babraham/FastQC/Modules/BasicStats.java
index 9e37a1a..e0e877a 100644
--- a/uk/ac/babraham/FastQC/Modules/BasicStats.java
+++ b/uk/ac/babraham/FastQC/Modules/BasicStats.java
@@ -21,6 +21,7 @@
 
 import java.awt.BorderLayout;
 import java.io.IOException;
+import java.util.Locale;
 
 import javax.swing.JLabel;
 import javax.swing.JPanel;
@@ -41,6 +42,9 @@ public class BasicStats extends AbstractQCModule {
 	private long filteredCount = 0;
 	private int minLength = 0;
 	private int maxLength = 0;
+	// Histogram of read lengths (over non-filtered sequences), indexed by
+	// length. Used to calculate the median read length.
+	private long [] lengthCounts = new long[0];
 	private long totalBases = 0;
 	private long gCount = 0;
 	private long cCount = 0;
@@ -74,6 +78,7 @@ public JPanel getResultsPanel() {
 	public void reset () {
 		minLength = 0;
 		maxLength = 0;
+		lengthCounts = new long[0];
 		gCount = 0;
 		cCount = 0;
 		aCount = 0;
@@ -123,6 +128,17 @@ public void processSequence(Sequence sequence) {
 			if (sequence.getSequence().length() > maxLength) maxLength = sequence.getSequence().length();
 		}
 
+		// Record the length in the histogram (used for the median).
+		int len = sequence.getSequence().length();
+		if (len+1 > lengthCounts.length) {
+			long [] newLengthCounts = new long[len+1];
+			for (int i=0;i<lengthCounts.length;i++) {
+				newLengthCounts[i] = lengthCounts[i];
+			}
+			lengthCounts = newLengthCounts;
+		}
+		++lengthCounts[len];
+
 		String seq = sequence.getSequence();
 		int seqLen = seq.length();
 		for (int c=0;c<seqLen;c++) {
@@ -157,6 +173,41 @@ public boolean ignoreInReport () {
 		return false;
 	}
 	
+	// Mean read length over all non-filtered sequences. Returns 0 for an empty file.
+	private double meanLength () {
+		if (actualCount == 0) return 0;
+		return (double)totalBases / actualCount;
+	}
+
+	// Median read length over all non-filtered sequences. For an even number
+	// of sequences this is the mean of the two central values, rounded up.
+	// Returns 0 for an empty file.
+	private long medianLength () {
+		if (actualCount == 0) return 0;
+		if (actualCount % 2 == 1) {
+			return lengthAtRank(actualCount/2);
+		}
+		else {
+			long lo = lengthAtRank((actualCount/2) - 1);
+			long hi = lengthAtRank(actualCount/2);
+			// Integer ceiling division: rounds a halfway average (e.g. 15.5) up.
+			return (lo + hi + 1) / 2;
+		}
+	}
+
+	// Returns the read length at the given zero-based rank in ascending order
+	// of length (i.e. as if all read lengths were sorted).
+	private long lengthAtRank (long rank) {
+		long cumulative = 0;
+		for (int length=0;length<lengthCounts.length;length++) {
+			cumulative += lengthCounts[length];
+			if (cumulative > rank) {
+				return length;
+			}
+		}
+		return 0;
+	}
+
 	public static String formatLength (long originalLength) {
 		
 		double length = originalLength;
@@ -223,8 +274,10 @@ private class ResultsTable extends AbstractTableModel {
 				"Total Bases",
 				"Sequences flagged as poor quality",
 				"Sequence length",
+				"Mean sequence length",
+				"Median sequence length",
 				"%GC",
-		};		
+		};
 		
 		// Sequence - Count - Percentage
 		public int getColumnCount() {
@@ -253,16 +306,16 @@ public Object getValueAt(int rowIndex, int columnIndex) {
 						else {
 							return minLength+"-"+maxLength;
 						}
-						
-						
-					case 7 : 
+					case 7 : return String.format(Locale.ROOT, "%.2f", meanLength());
+					case 8 : return ""+medianLength();
+					case 9 :
 						if (aCount+tCount+gCount+cCount > 0) {
 							return ""+(((gCount+cCount)*100)/(aCount+tCount+gCount+cCount));
 						}
 						else {
 							return 0;
 						}
-					
+
 					}
 			}
 			return null;