fastq-quality-scores
Skill8 starsChanged 5 months agoMITView on GitHub
Access, filter, and trim Phred quality scores in FASTQ reads using Biopython 1.83+ — including per-position profiles and encoding auto-detection.
In this repository125 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/AGENTS.mdAGENTS.md
- batch-processingSkill
- bowtie2-alignmentSkill
- bwa-alignmentSkill
- bwa-mem2-alignmentSkill
- codon-usageSkill
- compressed-sequence-filesSkill
- filter-sequencesSkill
- format-conversionSkill
- hisat2-alignmentSkill
- motif-searchSkill
- paired-end-fastqSkill
- pysam-genomicsSkill
- read-write-sequencesSkill
- reverse-complementSkill
- sam-bam-basicsSkill
- samtools-bam-processingSkill
- seq-objectsSkill
- sequence-propertiesSkill
- sequence-slicingSkill
- sequence-statisticsSkill
- star-alignmentSkill
- transcription-translationSkill
- academic-cvSkill
- faculty-interviewSkill
- fellowship-applicationSkill
- industry-transitionSkill
- negotiationSkill
- tenure-dossierSkill
- admet-predictionSkill
- conformer-generationSkill
- covalent-designSkill
- docking-rescoringSkill
- free-energy-calculationsSkill
- generative-designSkill
- molecular-descriptorsSkill
- molecular-ioSkill
- molecular-standardizationSkill
- pharmacophore-modelingSkill
- pose-validationSkill
- protac-degradersSkill
- qsar-modelingSkill
- retrosynthesisSkill
- scaffold-analysisSkill
- shape-similaritySkill
- similarity-searchingSkill
- substructure-searchSkill
- virtual-screeningSkill
- snakemake-workflow-engineSkill
- ai-disclosureSkill
- data-privacySkill
- image-integritySkill
- irb-protocolSkill
- ai-detection-awarenessSkill
- ai-disclosure-statementSkill
- scientific-voice-styleSkill
- text-humanizing-editorialSkill
- cellprofiler-pipelinesSkill
- image-analysis-best-practicesSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
No fabricated citations: Every cited work must resolve to a verifiable
- Distinctive: line 21
No claim without provenance: Every quantitative or factual claim
- Distinctive: line 22
No silent failure: Every script invocation, API call, or tool use must declare its exit status and what to do on non-zero.
- Very specific: line 188
Aggressive trimming collapses reads to 0 length: Always check len(rec) > 0 after trim and skip empties.
- Very specific: line 190
Forgetting reads are variable length: when building a 2D NumPy matrix.
- Very specific: line 195
After a Q30 filter, the output mean quality (across all kept reads) is ≥ 30.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- metadata:
category: bioinformatics-sequence
oversight: low
version: 1.0.0
author: Pradyumna Jayaram
tags: [bioinformatics-sequence, research]
difficulty: intermediate
-->FASTQ Quality Scores
Hard rules
- No fabricated citations. Every cited work must resolve to a verifiable
- No claim without provenance. Every quantitative or factual claim
- No silent failure. Every script invocation, API call, or tool use must declare its exit status and what to do on non-zero. A skill that silently swallows errors is a violation.
When to use
- Computing per-read mean quality, per-position mean quality, or quality histograms.
- Filtering reads by mean or minimum quality.
- Trimming 3' ends or sliding-window trimming when no FASTP/Cutadapt step exists.
- Converting legacy Illumina/Solexa FASTQ to Phred+33.
When NOT to use
- Production FASTQ QC → use
fastp(ors-bioinformatics-sequence-fastp-workflow),fastqc+MultiQC, ornf-coremodules. - Adapter trimming → use
fastporTrim Galore(CUTADAPT). - UMI handling → use
umis/umitools(seeors-bioinformatics-sequence-umi-processing).
Prerequisites
biopython>=1.83,numpy>=1.26.- For production work:
fastp≥ 0.23.
Core workflow
"
- Read with
SeqIO.parse(..., "fastq")— Phred+33 is the default in Biopython 1.83+. - Pull quality via
record.letter_annotations["phred_quality"]— it's a list of ints aligned 1-to-1 with the bases. - Compute per-read and per-position aggregates in a single streaming pass.
- Filter with a generator — don't materialize the full file unless you must.
- For trimming, use sliding-window Trimmomatic-style logic or hand off to
fastp.
Code patterns
Read quality scores
from Bio import SeqIO
for rec in SeqIO.parse("reads.fastq", "fastq"):
quals = rec.letter_annotations["phred_quality"]
# Process quals, which is a list[int] aligned with basesMean quality per read
def mean_q(rec):
q = rec.letter_annotations["phred_quality"]
return sum(q) / len(q)
for rec in SeqIO.parse("reads.fastq", "fastq"):
print(f"{rec.id}\t{mean_q(rec):.1f}")Filter reads by mean quality
from Bio import SeqIO
def keep(rec, min_mean=30):
q = rec.letter_annotations["phred_quality"]
return (sum(q) / len(q)) >= min_mean
with open("q30.fastq", "w") as out:
SeqIO.write((r for r in SeqIO.parse("reads.fastq", "fastq") if keep(r)),
out, "fastq")3' trimming (drop trailing low-quality bases)
def trim_3p(rec, min_q=20):
q = rec.letter_annotations["phred_quality"]
cut = len(q)
for i in range(len(q) - 1, -1, -1):
if q[i] >= min_q:
cut = i + 1
break
return rec[:cut] if cut > 0 else None
from Bio import SeqIO
SeqIO.write((trim_3p(r) for r in SeqIO.parse("reads.fastq", "fastq") if trim_3p(r)),
"trimmed.fastq", "fastq")Sliding-window trim (Trimmomatic LEADING/TRAILING style)
def sliding_window_trim(rec, window=4, min_avg=20):
q = rec.letter_annotations["phred_quality"]
n = len(q)
for i in range(n - window + 1):
if sum(q[i:i+window]) / window < min_avg:
return rec[:i] if i > 0 else None
return recPer-position mean quality (full FASTQ in one pass)
from collections import defaultdict
from Bio import SeqIO
by_pos = defaultdict(list)
for rec in SeqIO.parse("reads.fastq", "fastq"):
for i, q in enumerate(rec.letter_annotations["phred_quality"]):
by_pos[i].append(q)
# Print first 30 positions
for i in range(30):
vals = by_pos[i]
print(f"pos {i}\tmean={sum(vals)/len(vals):.1f}\tn={len(vals)}")Percentile quality profile with NumPy
import numpy as np
from Bio import SeqIO
# Read all qualities into a 2D matrix (padded with -1 if reads differ in length)
maxlen = 0
rows = []
for rec in SeqIO.parse("reads.fastq", "fastq"):
q = rec.letter_annotations["phred_quality"]
rows.append(q)
maxlen = max(maxlen, len(q))
mat = np.full((len(rows), maxlen), -1, dtype=np.int16)
for i, q in enumerate(rows):
mat[i, :len(q)] = q
mask = mat >= 0
p50 = np.where(mask, mat, np.nan)
print("per-position Q50:", np.nanpercentile(p50, 50, axis=0)[:20])Detect FASTQ quality encoding (Sanger / Solexa / Illumina 1.3+)
def detect_encoding(path: str, sample=4000) -> str:
mn = 126
with open(path) as fh:
i = n = 0
for line in fh:
if i % 4 == 3:
mn = min(mn, min(ord(c) for c in line.rstrip()))
n += 1
if n >= sample:
break
i += 1
if mn < 59: return "fastq" # Sanger / Illumina 1.8+ (Phred+33)
if mn < 64: return "fastq-solexa" # Solexa+64
return "fastq-illumina" # Illumina 1.3-1.7 (Phred+64)Convert legacy FASTQ to Phred+33
from Bio import SeqIO
# Read old variant, write as standard
records = SeqIO.parse("legacy.fastq", detect_encoding("legacy.fastq"))
SeqIO.write(records, "modern.fastq", "fastq")Common pitfalls
- Wrong FASTQ variant string.
KeyError: 'phred_quality'→ not Phred+33; tryfastq-illuminaorfastq-solexa. - Aggressive trimming collapses reads to 0 length. Always check
len(rec) > 0after trim and skip empties. - Confusing
record.letter_annotations["phred_quality"]withrecord.seq. Quality is not in the sequence; it's a parallel list of ints. - Forgetting reads are variable length when building a 2D NumPy matrix. Pad with a sentinel (
-1orNaN) and mask. - Solexa scores are not Phred for low values. The encoding differs below Q14 — don't compare raw integers.
Validation
- After a
Q30filter, the output mean quality (across all kept reads) is ≥ 30. - A per-position profile shows the expected Illumina decay at read 3' end.
- Round-trip: a converted FASTQ, re-detected, returns
"fastq"(Phred+33).
Open alternatives
| Need | Tool | Notes |
| Single-pass FASTQ QC + trim | fastp ≥ 0.23 | 10-50x faster than Python, reports HTML/JSON |
| Detailed per-base reports | FastQC + MultiQC | Standard in nf-core pipelines |
| UMI-aware trimming | umitools trim | Handles UMI + adapter in one pass |
| Long-read quality | NanoPlot, PycoQC | ONT/PacBio specific |
References
- Phred+33 / Solexa encoding table: https://en.wikipedia.org/wiki/Phred_quality_score
- Biopython QualityIO: https://biopython.org/docs/latest/api/Bio.SeqIO.QualityIO.html
- fastp paper: Chen et al., 2018, Bioinformatics —
10.1093/bioinformatics/bty560 - Companion:
ors-bioinformatics-sequence-fastp-workflow,ors-bioinformatics-sequence-umi-processing.
Changelog
- 1.0.0 (2026-06-10): Initial adaptation by Pradyumna Jayaram from
bio-fastq-quality(bioSkills-main/sequence-io/fastq-quality).
Cross-references
Other skills in this category:
- batch-processing
- bowtie2-alignment
- bwa-alignment
- bwa-mem2-alignment
- codon-usage
- compressed-sequence-files
- filter-sequences
- format-conversion
- hisat2-alignment
- motif-search
- paired-end-fastq
- pysam-genomics
- read-write-sequences
- reverse-complement
- sam-bam-basics
- samtools-bam-processing
- seq-objects
- sequence-properties
- sequence-slicing
- sequence-statistics
- star-alignment
- transcription-translation
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

