seqcounter 1.0.2

Documentation and validation, and one fix to the per-sample report. The counts are unchanged: 1.0.2 and 1.0.1 count identically.

• A Tutorial: counting IS6110 in three public M. tuberculosis read sets, from installing to reading the reports and normalizing the counts, with the real output of every command.
• A Validation page, which bash validation/run_validation.sh reproduces from public data in a few minutes. What it establishes: the counts are identical, read for read, to an independent exact k-mer scan over 200,000 reads and 77 references; a reference is counted once per sequence of a fasta file, even at 16 copies; with even coverage the counts follow the model to a median of 1.00 and recover a 16-copy element as 16.1 copies; a sequence absent from the genome stays at zero everywhere; and -m 1 adds reads from near-matches elsewhere in the genome for 22 of 77 references, by nothing at the median window and up to +43%.
• Three figures, drawn from those same results by validation/make_figures.py: the counts against the model, the spread of real coverage, and a circular map of the H37Rv chromosome showing its 16 IS6110 copies, the 75 single-copy references and the copy number of every kilobase of the genome.
• Fix: refseqcounts_samples.tsv is always one line of eight fields per sample. A tab in an error message (Seal's output is tab aligned, and the message carries the last ten lines of it) or in a file name is replaced by a space, instead of shifting the columns of that row.
• The logo is drawn as outlines rather than text, so it renders without the font it was designed in.

pip install seqcounter   # needs BBTools: conda install -c bioconda bbmap

The full changelog, and the 1.0.0 release for what changed against the first version.

seqcounter 1.0.1

The default branch becomes main, and the Zenodo DOI of the archived releases is recorded. No change to the code: 1.0.1 and 1.0.0 count identically.

• The default branch is now main. The links that named the branch follow it: the logo in the README, which raw.githubusercontent.com serves per branch and does not redirect after a rename, and the blob/ links from the wiki. Releasing the rename, rather than leaving it on the branch, is what puts a README with working links on the PyPI project page.
• The citation is now a DOI: 10.5281/zenodo.23826933, which resolves to the latest version, with the version DOI of each release beside it in CITATION.cff.

pip install seqcounter   # needs BBTools: conda install -c bioconda bbmap

See the 1.0.0 release for what changed against the first version, and the changelog.

seqcounter 1.0.0

seqcounter becomes an installable, tested package. Everything the first version did, it still does, with the same flags and the same refseqcounts.tsv; what changed is around that.

conda create -n seqcounter -c conda-forge -c bioconda bbmap python">=3.10"
conda activate seqcounter
pip install seqcounter
seqcounter -ref refs.fasta -i samples/ -o results/

python seqcounter.py still works from a clone, with the same arguments, so existing scripts keep working.

Packaging and interface

• A seqcounter command and python -m seqcounter, installable from PyPI (and bioconda shortly).
• No Python dependency at all: pandas and psutil are gone. Only BBTools and Java are needed, as before.
• The counts table is printed to standard output, with the messages on standard error, so seqcounter ... > counts.tsv works.
• Two new reports beside refseqcounts.tsv: refseqcounts_samples.tsv (reads, bases, matched reads and the error per sample) and refseqcounts.json (parameters, software versions, references and counts).
• New options: -s/--sample, --memory, --verbose, and -j/--jobs as another name for -p/--parallel. -v still prints the version.

Counts that can be trusted

• A single fastq file is never read as interleaved: Seal guesses interleaving from the read names, and where it guessed wrong the counts were halved.
• The reference file is checked before anything runs: a sequence shorter than -k (which Seal cannot find at all, and which used to be reported as a zero count), an empty sequence, two sequences whose first word is the same (their counts were added together), a file that is not fasta.
• Sample name collisions are reported instead of being resolved silently: two files reducing to the same name used to be mixed into one entry and passed to Seal as a bogus pair.
• File names Seal cannot be given safely (spaces, quotes, $, ;, &, parentheses, commas, or xmx/xms) are linked under a neutral name; such a name could previously make the run fail, or run a command.
• Formats are recognized from the content, not only the extension, and the quality encoding is forced (qin=33).
• Seal's memory is bounded: the Java heap is sized from the reference sequences and capped at 85% of the machine divided by the parallel jobs. Before, each job reserved most of the free memory, so -p 2 could put the machine into swap.
• One sample failing no longer stops the run: its column is left empty, its error is reported, and the exit code is 1.
• The column order is deterministic, where it used to depend on which sample finished first.

Development

• 105 tests, 100% coverage, end to end on synthetic references, genomes and reads with known counts.
• GitHub Actions: tests on Python 3.10, 3.12 and 3.14 with ruff and Codecov, PyPI publishing on release, and the wiki published from wiki/.
• A wiki, a bioconda recipe, a CITATION.cff, and examples/run_example.sh, which generates its own data and counts it.

Full details in the changelog.

seqcounter 0.1

The original clone-and-run version of seqcounter: seqcounter.py plus seqcounter_methods.py, counting occurrences of reference sequences in fastq or fasta input with Seal from BBTools.

Install by cloning the repository, as the README describes:

conda create -n seqcounter -y -c bioconda bbmap pandas psutil
conda activate seqcounter
git clone https://github.com/duceppemo/seqcounter
cd seqcounter
python seqcounter.py -h

This release marks the last state before the repository is packaged, so work that depends on the clone-and-run layout has a fixed point to refer to.