Documentation and Reproducibility of Preprocessing Decisions

  • Documentation and reproducibility of preprocessing decisions are essential components of reliable bioinformatics research. Sequencing data preprocessing involves several computational operations, including quality assessment, adapter removal, quality trimming, read filtering, contaminant screening, duplicate handling, and format conversion. These operations can influence the quality, quantity, and biological composition of the final dataset. Different preprocessing choices may produce different results from the same raw sequencing data, potentially affecting sequence alignment, genome assembly, variant detection, gene-expression estimates, metagenomic classification, and other downstream analyses. Therefore, researchers must document how preprocessing was performed, why particular decisions were made, and which software, parameters, and reference resources were used.
  • Reproducibility means that another researcher should be able to repeat the preprocessing procedure using the original input data, documented software environment, and recorded parameters and obtain equivalent results, allowing for expected differences caused by software versions, hardware, or nondeterministic computational procedures. Reproducibility also requires transparency about decisions that involve judgment, such as selecting quality thresholds, determining minimum read lengths, deciding whether to remove duplicates, or choosing a contaminant reference database. Simply stating that sequencing reads were quality-filtered is insufficient because it does not explain which filters were applied or how they affected the data.
  • The first requirement is to preserve the original sequencing data. Raw FASTQ files, or the original signal files when available for long-read technologies, should be retained without modification. These files provide the starting point for future reanalysis and allow researchers to distinguish original sequencing observations from processed data. For Illumina sequencing, raw FASTQ files should be preserved together with sample information and relevant sequencing-run metadata. For Oxford Nanopore sequencing, researchers may retain raw signal files such as POD5 and the corresponding basecalled FASTQ files. For PacBio sequencing, relevant original data and processing outputs should be preserved according to the available data-delivery and storage workflow. Raw data should be stored separately from trimmed, filtered, and otherwise processed files.
  • File integrity should be verified using checksums. A checksum is a calculated value used to detect whether a file has changed or become corrupted. SHA-256 is commonly used for this purpose. Researchers can calculate checksums before transferring or processing data and verify them afterward to confirm that the files remain identical. For example:

sha256sum raw_reads.fastq.gz > raw_reads.sha256

The checksum can later be verified using:

sha256sum -c raw_reads.sha256

  • A successful verification indicates that the file matches the checksum recorded earlier. Checksums are especially important when sequencing datasets are transferred between laboratories, servers, cloud storage systems, and collaborators.
  • Sample metadata should also be documented carefully. Relevant information may include sample identifiers, organism, tissue or sample type, collection date, extraction method, library preparation protocol, sequencing platform, instrument, chemistry, read configuration, and sequencing-run identifier. For RNA sequencing, metadata may include RNA extraction procedures, RNA integrity information, poly(A) selection or ribosomal RNA depletion, and strand-specific library preparation. For metagenomic studies, sample collection conditions, extraction protocols, environmental characteristics, and host-depletion procedures may be important. These details help explain differences in read quality and preprocessing requirements between samples.
  • The sequencing platform and library preparation method should be recorded because preprocessing decisions depend on the technology used. Illumina short-read data may require adapter trimming, quality trimming, and minimum-length filtering. Oxford Nanopore data may require basecalling, adapter and barcode processing, and platform-specific read filtering. PacBio data may require circular consensus sequence generation and HiFi read selection. Researchers should record the instrument model, sequencing chemistry or kit, library preparation method, sequencing mode, and relevant software versions. For long-read data, the basecaller and model should also be documented because different basecalling models can produce different sequence outputs from the same raw signal data.
  • Software documentation is another fundamental requirement. Every program used during preprocessing should be identified by name and version. Common tools include FastQC, MultiQC, fastp, Cutadapt, Trimmomatic, BBDuk, SeqKit, NanoPlot, NanoFilt, Filtlong, and platform-specific processing software. The operating system, programming language versions, package versions, and relevant dependencies should also be recorded. Software updates can change algorithms, default parameters, file-format handling, and output behavior. Consequently, specifying only the software name may not be sufficient to reproduce an analysis.
  • Command-line parameters should be recorded exactly as used. For example, a researcher who uses fastp should document the input files, output files, quality threshold, minimum read length, adapter settings, and reporting options. A command such as the following provides a reproducible record of the processing operation:

fastp \

  -i raw_R1.fastq.gz \

  -I raw_R2.fastq.gz \

  -o processed_R1.fastq.gz \

  -O processed_R2.fastq.gz \

  -q 20 \

  -l 50 \

  -h fastp_report.html \

  -j fastp_report.json

  • In this example, the command specifies paired-end input files, processed output files, a quality-filtering threshold, and a minimum read length. The values are illustrative rather than universal recommendations. The actual values used in a study should be recorded without replacing them with generic examples in the methods section.
  • Adapter sequences and primer definitions should also be documented. Different library preparation kits may use different adapter sequences, and amplicon studies may use specific primer pairs. Researchers should record the exact sequences supplied to trimming software, including whether adapters were specified as full sequences or partial sequences. If automatic adapter detection was used, this should be stated. The software’s adapter-detection settings and any manual corrections should also be recorded where relevant. This information is important because different adapter definitions can produce different processed reads.
  • Quality thresholds require particular attention because they can influence which sequences remain in the final dataset. Researchers should record minimum and maximum read lengths, average quality thresholds, per-base quality requirements, ambiguous-base limits, and any other filtering criteria. The reasons for selecting these values should be explained. For example, a minimum length may be selected because shorter reads are unsuitable for a particular alignment strategy, while a quality threshold may be chosen to reduce the proportion of low-confidence bases. Thresholds should be justified according to the sequencing technology, library design, sample characteristics, and downstream analysis rather than selected arbitrarily.
  • Researchers should also document whether filtering was performed before or after adapter trimming and quality trimming. The order of preprocessing operations can affect the final results. For example, a read that initially exceeds the minimum length may fall below the threshold after adapter and low-quality bases are removed. If minimum-length filtering is performed before trimming, that read may be retained temporarily and then become too short for downstream analysis. Recording the order of operations makes the workflow easier to interpret and reproduce.
  • Duplicate handling should be described separately from ordinary read filtering. Researchers should state whether duplicate reads were identified, marked, or removed, and which tool and parameters were used. For example, Picard MarkDuplicates and SAMtools markdup can be used in suitable alignment-based workflows, while UMI-aware tools such as UMI-tools can identify duplicate molecules using unique molecular identifiers. The rationale for duplicate handling should be explained because duplicate reads may represent PCR amplification artifacts, optical duplicates, or genuine biological abundance. In RNA sequencing and targeted sequencing, repeated observations may be biologically expected, so indiscriminate duplicate removal can distort the data.
  • Contaminant screening decisions should also be recorded. Researchers should identify the reference genomes, databases, or sequence collections used to detect host reads, microbial contaminants, vector sequences, and other unwanted material. Database versions or download dates should be included where possible because reference content changes over time. The alignment or classification software, identity thresholds, mapping criteria, and treatment of ambiguous matches should also be described. For example, removing reads that align to a host genome requires specifying the host reference assembly and the alignment criteria used to classify reads as host-derived.
  • Quality-control reports should be preserved before and after preprocessing. These reports provide evidence of the original data characteristics and the effects of filtering and trimming. FastQC reports can document short-read metrics such as per-base quality, GC distribution, adapter content, sequence duplication, and overrepresented sequences. MultiQC can combine reports from multiple samples and tools. For long-read sequencing, NanoPlot and NanoStat can summarize read-length distributions, quality scores, and sequencing yield. Platform-specific reports may provide additional information about basecalling, polymerase reads, CCS generation, or HiFi yield.
  • The number of reads and bases removed at each preprocessing step should be recorded. This information helps researchers determine how much data were retained and whether filtering affected samples differently. A useful preprocessing summary includes the initial read count, initial number of bases, reads removed during adapter trimming, reads removed during quality filtering, reads removed by minimum-length filtering, reads removed during contaminant screening, final read count, and final total base yield. The percentage of reads and bases retained should also be calculated. Reporting only the final number of reads makes it difficult to understand the effect of preprocessing.
  • A simple preprocessing summary table can be used to document these changes:
Processing stageNumber of readsTotal bases
Raw sequencing data10,000,0001,500 Mb
After adapter trimming9,700,0001,430 Mb
After quality filtering9,100,0001,320 Mb
After minimum-length filtering8,700,0001,250 Mb
Final processed data8,700,0001,250 Mb
  • The values in this table are illustrative. In an actual study, the table should contain the measured values from the preprocessing reports. If several filtering operations are performed in one command, researchers should use the tool’s available reports or separate processing steps when necessary to understand the contribution of each operation.
  • A processing log is another useful reproducibility resource. It records the commands executed, the date and time of processing, software versions, input and output file names, and any errors or warnings. Logs are particularly important when processing large datasets or running analyses on high-performance computing systems. They help identify failed jobs, incomplete outputs, and differences between processing runs. A simple Bash command can save terminal output and error messages to a log file:

fastp \

  -i raw_R1.fastq.gz \

  -I raw_R2.fastq.gz \

  -o processed_R1.fastq.gz \

  -O processed_R2.fastq.gz \

  -q 20 \

  -l 50 \

  -h fastp_report.html \

  -j fastp_report.json \

  2>&1 | tee fastp_processing.log

  • This example records the command output in a log file while also displaying it in the terminal. Researchers should retain the generated HTML and JSON reports alongside the log and processed FASTQ files.
  • Workflow automation improves reproducibility by organizing preprocessing operations into explicit, repeatable steps. Workflow management systems such as Snakemake and Nextflow allow researchers to define input files, software requirements, parameters, dependencies, and output files. They can automate processing across many samples and help ensure that the same procedures are applied consistently. A workflow can also include quality-control checkpoints so that processing stops or generates warnings when unexpected results are detected.
  • A simplified Snakemake example illustrates how a preprocessing operation can be documented as a reproducible workflow rule:

rule filter_reads:

    input:

        r1=”raw/{sample}_R1.fastq.gz”,

        r2=”raw/{sample}_R2.fastq.gz”

    output:

        r1=”processed/{sample}_R1.fastq.gz”,

        r2=”processed/{sample}_R2.fastq.gz”

    log:

        “logs/{sample}_fastp.log”

    params:

        quality=20,

        min_length=50

    shell:

        “””

        fastp \

          -i {input.r1} \

          -I {input.r2} \

          -o {output.r1} \

          -O {output.r2} \

          -q {params.quality} \

          -l {params.min_length} \

          -h processed/{wildcards.sample}_fastp.html \

          -j processed/{wildcards.sample}_fastp.json \

          2>&1 | tee {log}

        “””

  • This rule demonstrates how input files, output files, parameters, and logs can be defined explicitly. A complete workflow would also include software environment specifications, quality-control steps, error handling, and validation of expected outputs.
  • Software environments should be preserved to reduce differences caused by changing dependencies. Conda or Mamba environment files can specify software packages and versions. For example:

name: sequencing-preprocessing

channels:

  – conda-forge

  – bioconda

dependencies:

  – fastp=0.23.4

  – fastqc=0.12.1

  – multiqc=1.21

  – cutadapt=4.8

  • The versions shown are illustrative and should not be treated as recommendations for every project. A suitable environment should be tested and recorded for the actual workflow. Researchers can create the environment using:

conda env create -f environment.yml

conda activate sequencing-preprocessing

  • For greater reproducibility, an exact environment lock file or container image can be retained. Docker and Apptainer/Singularity can package software and dependencies into portable environments, helping reduce differences between computers and computational systems. Container images should be identified by a specific version or immutable digest rather than relying only on a mutable tag such as latest.
  • Version control systems such as Git can be used to track changes in preprocessing scripts, workflow definitions, configuration files, and documentation. This is particularly useful when researchers modify filtering thresholds or update software during a project. A Git repository can preserve the history of these changes and identify which version of the workflow generated a particular dataset. Large sequencing files are usually stored separately from the code repository, while their locations, checksums, metadata, and processing relationships are documented in version-controlled files.
  • A configuration file can separate preprocessing parameters from the workflow code. This makes it easier to inspect and modify thresholds without changing the underlying script. For example:

input_directory: raw

output_directory: processed

quality_filtering:

  minimum_quality: 20

  minimum_length: 50

adapter_trimming:

  enabled: true

quality_control:

  fastqc: true

  multiqc: true

  • This example illustrates a simple configuration structure. The workflow must be programmed to read these values, and the actual settings used should be preserved with the results. For each sample, the configuration should also identify the relevant input files, sample identifiers, and any sample-specific exceptions.
  • Preprocessing decisions should be justified in the scientific methods section of a publication or technical report. Researchers should explain why particular filters were selected and how they relate to the study objectives. For example, a minimum read length may be selected to improve alignment specificity, while adapter trimming may be necessary because the insert sizes are shorter than the sequencing read length. If a threshold was selected after inspecting quality-control reports, this should be stated. If different samples required different preprocessing settings, the reason for these differences should be documented and the consequences considered when comparing samples.
  • It is also important to document changes made after the initial analysis. Researchers may discover that an adapter sequence was incorrectly specified, a contaminant reference was incomplete, or a quality threshold removed too many useful reads. When the workflow is corrected, the change should be recorded along with the reason, the affected samples, and the outputs regenerated. Original processed files should not be silently overwritten without preserving their provenance. Clear versioning helps distinguish preliminary results from final analysis outputs.
  • Data provenance describes the history and origin of data, including the operations used to generate a particular output. In sequencing preprocessing, provenance connects raw sequencing files to processed FASTQ files, quality-control reports, alignment files, and downstream analytical results. A provenance record should identify the input files, processing software, parameters, reference databases, output files, and timestamps. Standardized metadata and workflow descriptions can make this information easier to exchange between researchers and computational systems.
  • FAIR principles—Findability, Accessibility, Interoperability, and Reusability—provide a useful framework for managing bioinformatics data and documentation. Findability involves using clear identifiers and metadata so that datasets and processing records can be located. Accessibility concerns the availability of data and documentation under appropriate access conditions. Interoperability involves using standard file formats and metadata structures that can be understood by different tools. Reusability requires sufficient information about sample characteristics, software, parameters, and processing history to allow other researchers to interpret and reuse the data. Sensitive human genomic data may require controlled access rather than unrestricted public release, but the associated metadata and processing documentation should still be managed transparently where permitted.
  • Data repositories can support the preservation and sharing of sequencing datasets and associated metadata. The Sequence Read Archive (SRA), European Nucleotide Archive (ENA), and DNA Data Bank of Japan (DDBJ) provide resources for archiving raw sequencing reads. Processed data, analysis scripts, workflow definitions, and supplementary files may be deposited in suitable repositories such as GitHub, Zenodo, or institutional data archives. Researchers should follow the relevant repository’s submission requirements and ensure that sample metadata, file identifiers, and links between raw and processed data are clear. Where data are restricted for privacy or ethical reasons, access conditions should be documented.
  • Reproducibility should also consider the possibility of nondeterministic computational behavior. Some tools use multithreading, randomized algorithms, or machine-learning models that may produce slightly different results under different settings. Where supported, random seeds should be recorded, thread settings should be documented, and software versions should be fixed. Researchers should distinguish exact file-level reproducibility from scientific reproducibility. Exact reproduction may not always be possible across different hardware or software environments, but the workflow should still be sufficiently documented to produce equivalent analytical results.
  • A robust preprocessing documentation strategy should therefore preserve raw data, verify file integrity, record sample and sequencing metadata, specify software versions, save exact commands and parameters, retain quality-control reports, document filtering outcomes, and maintain workflow and environment files. These records allow researchers to trace how each processed dataset was generated and understand how preprocessing decisions may have influenced downstream results.
  • Documentation and reproducibility are not merely administrative tasks; they are fundamental aspects of scientific quality in bioinformatics. Preprocessing decisions can influence which biological signals are retained, which are removed, and how confidently the resulting data can be interpreted. By maintaining transparent records, preserving original data, using version-controlled workflows, and reporting the effects of filtering and trimming, researchers can make sequencing analyses more reliable, auditable, reusable, and scientifically defensible.
Author:

Leave a Reply

Your email address will not be published. Required fields are marked *