feat/report header (#36)

* feat(report parser): Detect a header line in the report file and skip.

If the first line of a kraken report is all strings and 6 fields - assume its a header line and skip with a warning.

* feat(report parser): More informative error messages

Adds line number and line context to errors

bumps version to 3.1.0

* docs: update readme and changelog with 3.1.0 features

* build: update kractor version to 3.1.0

Author: Sam-Sims

CHANGELOG.md

@@ -5,118 +5,160 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2025-12-12
+
+### Added
+
+- Attempt to detect headers in kraken report files and skip if it looks like a header. It does this by checking if there
+  are 6 fields that are all strings (or more precisely if each field returns an error when parsing into an int/float).
+  If so,
+  it is assumed that this line is a header and is skipped. A warning message is printed in this case.
+- `--no-header-detect` flag to force parsing Kraken reports from the first line without auto-skipping headers, disabling
+  the new header detection behaviour described above
+
+### Changed
+
+- Kraken report/output parsing errors now include the line number and o line for easier debugging.
+
 ## [3.0.1] - 2025-10-16
 
 ### Fixed
+
 - Prevent a panic when writing to output paths without an extension.
 
 ## [3.0.0] - 2025-09-26
 
 ### Added
-- Able to specifiy taxon ids that are not present, without kractor stopping. These are instead logged to stderr with a warning. This may be useful when running kractor in a wrapper script for several fastq files and just want to extract a set of taxonids from them all - without caring if they are present or not.
+
+- Able to specifiy taxon ids that are not present, without kractor stopping. These are instead logged to stderr with a
+  warning. This may be useful when running kractor in a wrapper script for several fastq files and just want to extract
+  a set of taxonids from them all - without caring if they are present or not.
 - Include a new field `missing_taxon_ids` in the summary output.
 
 ### Changed
-- Under the hood refactoring, introducing structs for the processed kraken outputs and processed kraken trees to simplify the returned data.
+
+- Under the hood refactoring, introducing structs for the processed kraken outputs and processed kraken trees to
+  simplify the returned data.
 
 ### Fixed
-- Unclassified reads being skipped in the tree building stage, meaning they were unable to be extracted 
+
+- Unclassified reads being skipped in the tree building stage, meaning they were unable to be extracted
 
 ## [2.0.0] - 2025-08-12
 
 ### Added
+
 - Added a `reads_extracted_per_taxon` field to to summary report (#28)
 - Added a `proportion_extracted` field to summary report (#28)
 - Added the version to summary report (#28)
 - Added an output format (`fasta` or `fastq`) field to the summary report (#28)
 - Added a `--verbose` flag (in addition to the existing `-v`)
 
 ### Changed
+
 - Removed `-O` for compression type, now uses `--compression-format` for clarity.
 - Removed `-l` for compression level, now uses `--compression-level` for clarity.
 - Renamed `--json-report` to `--summary`
-- Improved the JSON report format to make it easier to read by removing `Paired` and `Single` fields and instead having a simple `total_reads_in` and `total_reads_out` field.
+- Improved the JSON report format to make it easier to read by removing `Paired` and `Single` fields and instead having
+  a simple `total_reads_in` and `total_reads_out` field.
 
 ### Fixed
+
 - Removed duplicate log message for taxon IDs identified
 - Clippy warnings
 
 ## [1.0.1] - 2025-06-28
 
 ### Fixed
+
 - Create subdirectories specified in output path if they don't exist (#24)
 - Add output validation to prevent overwriting existing files (#25)
 
 ## [1.0.0] - 2025-04-16
 
 ### Added
+
 - Better error handling with color-eyre (#16)
 - Proper panic handling (#16)
 - Tests for most functions
 - JSON report with accurate read count information (#15)
 
 ### Changed
+
 - Keep fastq parsing in bytes instead of converting to String (#17)
 - Optimized functions to take `&str` instead of `String` (#21)
 - Migrated to crossbeam scoped channels and refactored threading code
 - Refactored JSON output and removed lazy_static dependency
 
 ### Fixed
+
 - Root node no longer added to tree twice (#22)
 
 ## [0.4.0] - 2023-10-06
 
 ### Added
+
 - JSON report included in stdout upon successful completion (can be disabled with `--no-json`)
 
 ### Changed
+
 - Project renamed
 
 ## [0.3.0] - 2023-09-22
 
 ### Added
+
 - Support for paired-end files
 - Output FASTA file with `--output-fasta` option
 
 ### Changed
+
 - Major refactor to use Noodles for fastq parsing
 - Switched to Niffler for compression handling
 - Streamlined arguments related to compression types/level
 
 ### Improved
+
 - Logging functionality
 
 ## [0.2.3] - 2023-09-02
 
 ### Changed
+
 - Code optimizations
 
 ## [0.2.2]
 
 ### Added
+
 - `--no-compress` flag to output standard plaintext fastq files
 - `--exclude` option to exclude specified reads (works with `--children` and `--parents`)
 - Internal documentation (docstrings)
 
 ### Improved
+
 - Increased verbosity of user outputs
 
 ## [0.2.1]
 
 ### Fixed
+
 - Reduced memory usage
 
 ## [0.2.0]
 
 ### Added
+
 - Automatic detection and handling of gz and plain files
 - `--compression` argument to select compression type
 - `--children` and `--parents` options to save children and parents based on kraken report
 
 ### Changed
+
 - Integrated zlib-ng for faster gzip handling
 
 ## [0.1.0]
 
 ### Added
+
 - Initial release

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "kractor"
-version = "3.0.1"
+version = "3.1.0"
 edition = "2021"
 authors = ["Samuel Sims"]
 description = "Extract reads from a FASTQ file based on taxonomic classification via Kraken2."

Cargo.toml

@@ -10,25 +10,29 @@
 
 **kra**ken extr**actor**
 
-Kractor extracts reads from fastq `[.gz/.bz2]` files using taxonomic classifications obtained via Kraken2. 
-It supports single or paired-end reads, can optionally include taxonomic parents or children, and uses minimal memory (~4.5 MB for a 17 GB FASTQ file).
+Kractor extracts reads from fastq `[.gz/.bz2]` files using taxonomic classifications obtained via Kraken2.
+It supports single or paired-end reads, can optionally include taxonomic parents or children, and uses minimal memory (~
+4.5 MB for a 17 GB FASTQ file).
 
 The end result is a `fast[q/a]` file containing all reads classified as the specified taxon(s).
 
 Kractor significantly enhances processing speed compared to KrakenTools for both paired and unpaired reads.
 
 Performance vs KrakenTools:
-- Paired compressed FASTQ: ~21× faster 
-- Paired uncompressed FASTQ: ~10× faster 
+
+- Paired compressed FASTQ: ~21× faster
+- Paired uncompressed FASTQ: ~10× faster
 - Unpaired: ~4× faster (compressed or uncompressed)
 
 For additional details, refer to the [benchmarks](benchmarks/benchmarks.md)
 
 ## Motivation
 
-Provides similar functionality to the [KrakenTools](https://github.com/jenniferlu717/KrakenTools) `extract_kraken_reads` python script.
+Provides similar functionality to the [KrakenTools](https://github.com/jenniferlu717/KrakenTools) `extract_kraken_reads`
+python script.
 
-However the main motivation was to enhance speed when processing multiple, large FASTQ files - and as a way to learn Rust.
+However the main motivation was to enhance speed when processing multiple, large FASTQ files - and as a way to learn
+Rust.
 
 ## Installation
 
@@ -115,6 +119,8 @@ Options:
           Output results in FASTA format
       --summary
           Enable a JSON summary output written to stdout
+      --no-header-detect
+          Disable detection and skipping of header lines in the Kraken2 report
   -v, --verbose
           Enable verbose output
   -h, --help
@@ -146,7 +152,9 @@ kractor -i sample.fastq -o extracted.fasta -k kraken_output.txt -t 562 --output-
 ```
 
 ### Summary statistics
+
 Use `--summary` to get summary statistics (output to stdout on completion)
+
 ```json
 {
   "total_taxon_count": 2,
@@ -162,7 +170,7 @@ Use `--summary` to get summary statistics (output to stdout on completion)
   "proportion_extracted": 0.2140419091180432,
   "input_format": "single",
   "output_format": "fastq",
-  "kractor_version": "2.0.0"
+  "kractor_version": "3.1.0"
 }
 ```
 
@@ -174,7 +182,7 @@ Use `--summary` to get summary statistics (output to stdout on completion)
 
 `-i, --input`
 
-Specifies one or two input FASTQ files to extract reads from. Files may be uncompressed or compressed (`gz`, `bz2`). 
+Specifies one or two input FASTQ files to extract reads from. Files may be uncompressed or compressed (`gz`, `bz2`).
 Paired end reads can be specified by:
 
 Using `--input` twice: `-i <R1_fastq_file> -i <R2_fastq_file>`
@@ -185,47 +193,53 @@ Using `--input` once but passing both files: `-i <R1_fastq_file> <R2_fastq_file>
 
 `-o, --output`
 
-Specifies the output file(s) for extracted reads, matching the order of the input files. 
+Specifies the output file(s) for extracted reads, matching the order of the input files.
 Compression type is inferred from the file extension (.gz, .bz2). If not recognised, output will be uncompressed.
 
 #### Kraken Output
 
 `-k, --kraken`
 
-Path to the [Standard Kraken Output Format file](https://github.com/DerrickWood/kraken2/wiki/Manual#standard-kraken-output-format), containing taxonomic classification of read IDs.
+Path to
+the [Standard Kraken Output Format file](https://github.com/DerrickWood/kraken2/wiki/Manual#standard-kraken-output-format),
+containing taxonomic classification of read IDs.
 
 #### Taxid
 
 `-t, --taxid`
 
-One or more taxonomic IDs to extract. 
+One or more taxonomic IDs to extract.
 
 For example: `-t 1 2 10`
 
 Each taxonomic id is affected by `--exclude`, `--parents`, and `--children` if those options are used.
 
-Taxonomic ids do not need to be present in a given report. This may be useful when running kractor in a wrapper script for several fastq files and just want to extract a set of taxon ids from them all - without caring if they are present or not.
+Taxonomic ids do not need to be present in a given report. This may be useful when running kractor in a wrapper script
+for several fastq files and just want to extract a set of taxon ids from them all - without caring if they are present
+or not.
 
 ### Optional:
 
 #### Output type
 
 `--compression-format`
 
-Manually set output compression format, overriding what is inferred from file names. 
+Manually set output compression format, overriding what is inferred from file names.
 
 Valid values:
-- `gz` – gzip compression 
-- `bz2` – bzip2 compression 
+
+- `gz` – gzip compression
+- `bz2` – bzip2 compression
 - `none` – no compression
 
 #### Compression level
 
 `--compression-level`
 
-Set compression level (1–9). 
-- 1 = fastest, largest file 
-- 9 = slowest, smallest file 
+Set compression level (1–9).
+
+- 1 = fastest, largest file
+- 9 = slowest, smallest file
 
 Default: 2 (balance of speed and size)
 
@@ -239,7 +253,12 @@ Output sequences in FASTA format instead of FASTQ.
 
 `-r, --report`
 
-Path to the [Kraken2 report file](https://github.com/DerrickWood/kraken2/wiki/Manual#sample-report-output-format). Required if using `--parents` or `--children`.
+Path to the [Kraken2 report file](https://github.com/DerrickWood/kraken2/wiki/Manual#sample-report-output-format).
+Required if using `--parents` or `--children`.
+
+The first line is automatically treated as a header if it looks non-numeric; use `--no-header-detect` to force parsing
+from the very first line. Parsing errors will include the report line number and offending line to help spot format
+issues.
 
 #### Parents
 
@@ -265,8 +284,10 @@ Extract all reads except those matching the given taxids. Can be combined with `
 
 Write a JSON report to stdout after processing.
 
-## Citation 
+## Citation
+
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15761837.svg)](https://doi.org/10.5281/zenodo.15761837)
+
 ```
 Sam Sims. (2025). Sam-Sims/kractor. Zenodo. https://doi.org/10.5281/zenodo.15761837
-```
+```

README.md

@@ -48,6 +48,9 @@ pub struct Cli {
     /// Enable a JSON summary output written to stdout.
     #[arg(long = "summary")]
     pub summary: bool,
+    /// Disable detection and skipping of any header lines in the Kraken2 report.
+    #[arg(long = "no-header-detect", action)]
+    pub no_report_header_detect: bool,
     /// Enable verbose output.
     #[arg(short, long)]
     pub verbose: bool,