brucellaid 1.0.0__tar.gz

brucellaid-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Marc-Olivier Duceppe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brucellaid-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include brucellaid/data *
+recursive-include tests *.py

brucellaid-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: brucellaid
+Version: 1.0.0
+Summary: Identify the Brucella species of a read set with MASH, and type it with MLST
+Author-email: Marc-Olivier Duceppe <marc-olivier.duceppe@inspection.gc.ca>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/duceppemo/BrucellaID
+Project-URL: Documentation, https://github.com/duceppemo/BrucellaID/wiki
+Project-URL: Changelog, https://github.com/duceppemo/BrucellaID/wiki/Changelog
+Project-URL: Issues, https://github.com/duceppemo/BrucellaID/issues
+Keywords: bioinformatics,brucella,species identification,MLST,MASH,BBTools,Seal,fastq,wgs
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: xlsx
+Requires-Dist: xlsxwriter>=3; extra == "xlsx"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: xlsxwriter>=3; extra == "test"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/duceppemo/BrucellaID/main/assets/logo_dark.svg">
+    <img src="https://raw.githubusercontent.com/duceppemo/BrucellaID/main/assets/logo.svg" width="520" alt="BrucellaID: Brucella species identification and MLST from reads">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://github.com/duceppemo/BrucellaID/actions/workflows/tests.yml"><img src="https://github.com/duceppemo/BrucellaID/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://codecov.io/gh/duceppemo/BrucellaID"><img src="https://codecov.io/gh/duceppemo/BrucellaID/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/duceppemo/BrucellaID/releases/latest"><img src="https://img.shields.io/github/v/release/duceppemo/BrucellaID?cacheSeconds=3600" alt="Release"></a>
+  <a href="https://pypi.org/project/brucellaid/"><img src="https://img.shields.io/pypi/v/brucellaid?cacheSeconds=3600" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-3.10%E2%80%933.14-blue" alt="Python 3.10–3.14">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/duceppemo/BrucellaID" alt="License"></a>
+  <a href="https://github.com/duceppemo/BrucellaID/wiki"><img src="https://img.shields.io/badge/docs-wiki-informational" alt="Documentation"></a>
+</p>
+
+Identify the *Brucella* species of a fastq sample by its [MASH](https://github.com/marbl/mash) distance to 16
+reference genomes, and type it with the nine-locus
+[Whatmore MLST scheme](https://doi.org/10.1186/1471-2180-7-34), whose alleles are called from the reads with
+[Seal](https://sourceforge.net/projects/bbmap/) from BBTools. Point it at a sample, or a folder of samples.
+
+```
+$ brucellaid -r1 sample_R1.fastq.gz -r2 sample_R2.fastq.gz -o results/
+Sample  Species           Biovar  ClosestReference           MashDistance  SharedHashes  SequenceType  AlleleProfile
+sample  Brucella abortus  1       NC_006932-NC_006933.fasta  0.000024      999/1000      1             2-1-1-2-1-3-1-1-1
+```
+
+Both the reference sketch and the MLST database come with the package: nothing to download, index or
+configure.
+
+## Features
+* **Two independent answers**: the species, from the closest of 16 *Brucella* reference genomes, and the
+  sequence type, from the nine MLST alleles. Neither call corrects the other, and both come with the
+  numbers they rest on.
+* **Nothing is hidden**: the distance to every reference, the reads behind every allele call and the
+  runner-up that call had to beat, a note when a second reference was nearly as close, and a tie reported as
+  a tie rather than broken by a coin toss.
+* **Batch mode**: point it at a folder; fastq files are found recursively, R1/R2 paired, and several samples
+  run at a time. A sample that fails leaves the others readable.
+* **Current reference data**: the MLST database is PubMLST's, 309 alleles and 122 sequence types, rebuilt by
+  a script in the repository. The sketch is vSNP's 16 *Brucella* genomes, with the species, biovar, strain
+  and accession of each.
+* **Backwards compatible where it counts**: the species identification is vSNP's, down to the threshold of
+  150 shared hashes, and `--xlsx` still writes the `stat_alignment_summary_<date>.xlsx` of the first
+  version.
+* **Nothing to configure**: only the Python standard library, plus MASH and BBTools.
+* **Tested**: 194 tests, 100% coverage, end to end on a synthetic genome and on reads tiled over the real
+  MLST alleles.
+* **Validated** on 16 genomes with a known answer: every species, biovar and closest reference right, and
+  all 14 sequence types the one the genome carries — read off the assembly by exact match, which shares no
+  code with the read-based caller. The nearest neighbouring species shares 4 of 1000 hashes and comes back
+  as not identified ([Validation](https://github.com/duceppemo/BrucellaID/wiki/Validation)).
+
+## Installation
+```
+conda create -n brucellaid -c conda-forge -c bioconda brucellaid
+conda activate brucellaid
+```
+MASH and BBTools (which provides `seal.sh`) are not on PyPI, so they come from bioconda; BrucellaID itself
+needs nothing else. See [Installation](https://github.com/duceppemo/BrucellaID/wiki/Installation) for pip
+and for running it from a clone.
+
+## Quick start
+```
+brucellaid -r1 sample_R1.fastq.gz -r2 sample_R2.fastq.gz -o results/  # Paired-end reads
+brucellaid -r1 sample.fastq.gz -o results/                            # Single-end reads
+brucellaid -i reads/ -o results/ -p 4                                 # A folder, 4 samples at a time
+brucellaid -i reads/ -o results/ --no-mlst                            # Species only
+```
+The results are printed and saved in `results/`: one row per sample, one row per locus, every MASH distance,
+and a JSON report. To see it work on data with a known answer, run `bash examples/run_example.sh`, which
+builds its own reads from the alleles of a sequence type.
+
+**What the two answers mean**: the species is the species of the closest reference genome, and the biovar is
+that reference's biovar, which is not the same as a biovar call — the *Brucella* biovar references differ by
+very little. The sequence type is `new` when the nine alleles are called but the combination is not in the
+table, and `ND` when a locus could not be called. See
+[How it works](https://github.com/duceppemo/BrucellaID/wiki/How-it-works).
+
+## Documentation
+The **[wiki](https://github.com/duceppemo/BrucellaID/wiki)** covers
+[installation](https://github.com/duceppemo/BrucellaID/wiki/Installation), a
+[tutorial](https://github.com/duceppemo/BrucellaID/wiki/Tutorial) on public read sets,
+[usage and options](https://github.com/duceppemo/BrucellaID/wiki/Usage),
+[output files](https://github.com/duceppemo/BrucellaID/wiki/Output-files),
+[how it works](https://github.com/duceppemo/BrucellaID/wiki/How-it-works),
+[validation](https://github.com/duceppemo/BrucellaID/wiki/Validation),
+[troubleshooting](https://github.com/duceppemo/BrucellaID/wiki/Troubleshooting) and the
+[FAQ](https://github.com/duceppemo/BrucellaID/wiki/FAQ).
+
+## Citing
+If you use BrucellaID, please cite it together with the tools and the data it rests on:
+
+> Duceppe M-O. BrucellaID: *Brucella* species identification and MLST from sequencing reads.
+> https://github.com/duceppemo/BrucellaID
+
+> Ondov BD, Treangen TJ, Melsted P, et al. Mash: fast genome and metagenome distance estimation using
+> MinHash. *Genome Biology* 2016;17:132. https://doi.org/10.1186/s13059-016-0997-x
+
+> Bushnell B. BBTools. https://sourceforge.net/projects/bbmap/
+
+> Whatmore AM, Perrett LL, MacMillan AP. Characterisation of the genetic diversity of *Brucella* by
+> multilocus sequencing. *BMC Microbiology* 2007;7:34. https://doi.org/10.1186/1471-2180-7-34
+
+> Jolley KA, Bray JE, Maiden MCJ. Open-access bacterial population genomics: BIGSdb software, the
+> PubMLST.org website and their applications. *Wellcome Open Research* 2018;3:124.
+> https://doi.org/10.12688/wellcomeopenres.14826.1
+
+GitHub's **"Cite this repository"** button gives the citation in APA and BibTeX formats, from
+[`CITATION.cff`](CITATION.cff).
+
+## Related
+* [brucetyper](https://github.com/duceppemo/brucetyper) — *in silico* Bruce-ladder, Suis-ladder, AMOS and
+  RB51 junction PCR for *Brucella*, from assemblies. Where BrucellaID gives the species from a distance and
+  the sequence type from the alleles, brucetyper reads the assays a laboratory would run on a gel.
+* [seqcounter](https://github.com/duceppemo/seqcounter) — count the occurrences of any reference sequences
+  in reads or assemblies.
+* [spoligotyper](https://github.com/duceppemo/spoligotyper) — *in silico* spoligotyping of the
+  *M. tuberculosis* complex.
+
+## Contributing
+Bug reports, questions and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Author
+Marc-Olivier Duceppe, Canadian Food Inspection Agency (CFIA): marc-olivier.duceppe@inspection.gc.ca
+
+## License
+[MIT](LICENSE)

brucellaid-1.0.0/README.md

@@ -0,0 +1,129 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/duceppemo/BrucellaID/main/assets/logo_dark.svg">
+    <img src="https://raw.githubusercontent.com/duceppemo/BrucellaID/main/assets/logo.svg" width="520" alt="BrucellaID: Brucella species identification and MLST from reads">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://github.com/duceppemo/BrucellaID/actions/workflows/tests.yml"><img src="https://github.com/duceppemo/BrucellaID/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://codecov.io/gh/duceppemo/BrucellaID"><img src="https://codecov.io/gh/duceppemo/BrucellaID/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/duceppemo/BrucellaID/releases/latest"><img src="https://img.shields.io/github/v/release/duceppemo/BrucellaID?cacheSeconds=3600" alt="Release"></a>
+  <a href="https://pypi.org/project/brucellaid/"><img src="https://img.shields.io/pypi/v/brucellaid?cacheSeconds=3600" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-3.10%E2%80%933.14-blue" alt="Python 3.10–3.14">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/duceppemo/BrucellaID" alt="License"></a>
+  <a href="https://github.com/duceppemo/BrucellaID/wiki"><img src="https://img.shields.io/badge/docs-wiki-informational" alt="Documentation"></a>
+</p>
+
+Identify the *Brucella* species of a fastq sample by its [MASH](https://github.com/marbl/mash) distance to 16
+reference genomes, and type it with the nine-locus
+[Whatmore MLST scheme](https://doi.org/10.1186/1471-2180-7-34), whose alleles are called from the reads with
+[Seal](https://sourceforge.net/projects/bbmap/) from BBTools. Point it at a sample, or a folder of samples.
+
+```
+$ brucellaid -r1 sample_R1.fastq.gz -r2 sample_R2.fastq.gz -o results/
+Sample  Species           Biovar  ClosestReference           MashDistance  SharedHashes  SequenceType  AlleleProfile
+sample  Brucella abortus  1       NC_006932-NC_006933.fasta  0.000024      999/1000      1             2-1-1-2-1-3-1-1-1
+```
+
+Both the reference sketch and the MLST database come with the package: nothing to download, index or
+configure.
+
+## Features
+* **Two independent answers**: the species, from the closest of 16 *Brucella* reference genomes, and the
+  sequence type, from the nine MLST alleles. Neither call corrects the other, and both come with the
+  numbers they rest on.
+* **Nothing is hidden**: the distance to every reference, the reads behind every allele call and the
+  runner-up that call had to beat, a note when a second reference was nearly as close, and a tie reported as
+  a tie rather than broken by a coin toss.
+* **Batch mode**: point it at a folder; fastq files are found recursively, R1/R2 paired, and several samples
+  run at a time. A sample that fails leaves the others readable.
+* **Current reference data**: the MLST database is PubMLST's, 309 alleles and 122 sequence types, rebuilt by
+  a script in the repository. The sketch is vSNP's 16 *Brucella* genomes, with the species, biovar, strain
+  and accession of each.
+* **Backwards compatible where it counts**: the species identification is vSNP's, down to the threshold of
+  150 shared hashes, and `--xlsx` still writes the `stat_alignment_summary_<date>.xlsx` of the first
+  version.
+* **Nothing to configure**: only the Python standard library, plus MASH and BBTools.
+* **Tested**: 194 tests, 100% coverage, end to end on a synthetic genome and on reads tiled over the real
+  MLST alleles.
+* **Validated** on 16 genomes with a known answer: every species, biovar and closest reference right, and
+  all 14 sequence types the one the genome carries — read off the assembly by exact match, which shares no
+  code with the read-based caller. The nearest neighbouring species shares 4 of 1000 hashes and comes back
+  as not identified ([Validation](https://github.com/duceppemo/BrucellaID/wiki/Validation)).
+
+## Installation
+```
+conda create -n brucellaid -c conda-forge -c bioconda brucellaid
+conda activate brucellaid
+```
+MASH and BBTools (which provides `seal.sh`) are not on PyPI, so they come from bioconda; BrucellaID itself
+needs nothing else. See [Installation](https://github.com/duceppemo/BrucellaID/wiki/Installation) for pip
+and for running it from a clone.
+
+## Quick start
+```
+brucellaid -r1 sample_R1.fastq.gz -r2 sample_R2.fastq.gz -o results/  # Paired-end reads
+brucellaid -r1 sample.fastq.gz -o results/                            # Single-end reads
+brucellaid -i reads/ -o results/ -p 4                                 # A folder, 4 samples at a time
+brucellaid -i reads/ -o results/ --no-mlst                            # Species only
+```
+The results are printed and saved in `results/`: one row per sample, one row per locus, every MASH distance,
+and a JSON report. To see it work on data with a known answer, run `bash examples/run_example.sh`, which
+builds its own reads from the alleles of a sequence type.
+
+**What the two answers mean**: the species is the species of the closest reference genome, and the biovar is
+that reference's biovar, which is not the same as a biovar call — the *Brucella* biovar references differ by
+very little. The sequence type is `new` when the nine alleles are called but the combination is not in the
+table, and `ND` when a locus could not be called. See
+[How it works](https://github.com/duceppemo/BrucellaID/wiki/How-it-works).
+
+## Documentation
+The **[wiki](https://github.com/duceppemo/BrucellaID/wiki)** covers
+[installation](https://github.com/duceppemo/BrucellaID/wiki/Installation), a
+[tutorial](https://github.com/duceppemo/BrucellaID/wiki/Tutorial) on public read sets,
+[usage and options](https://github.com/duceppemo/BrucellaID/wiki/Usage),
+[output files](https://github.com/duceppemo/BrucellaID/wiki/Output-files),
+[how it works](https://github.com/duceppemo/BrucellaID/wiki/How-it-works),
+[validation](https://github.com/duceppemo/BrucellaID/wiki/Validation),
+[troubleshooting](https://github.com/duceppemo/BrucellaID/wiki/Troubleshooting) and the
+[FAQ](https://github.com/duceppemo/BrucellaID/wiki/FAQ).
+
+## Citing
+If you use BrucellaID, please cite it together with the tools and the data it rests on:
+
+> Duceppe M-O. BrucellaID: *Brucella* species identification and MLST from sequencing reads.
+> https://github.com/duceppemo/BrucellaID
+
+> Ondov BD, Treangen TJ, Melsted P, et al. Mash: fast genome and metagenome distance estimation using
+> MinHash. *Genome Biology* 2016;17:132. https://doi.org/10.1186/s13059-016-0997-x
+
+> Bushnell B. BBTools. https://sourceforge.net/projects/bbmap/
+
+> Whatmore AM, Perrett LL, MacMillan AP. Characterisation of the genetic diversity of *Brucella* by
+> multilocus sequencing. *BMC Microbiology* 2007;7:34. https://doi.org/10.1186/1471-2180-7-34
+
+> Jolley KA, Bray JE, Maiden MCJ. Open-access bacterial population genomics: BIGSdb software, the
+> PubMLST.org website and their applications. *Wellcome Open Research* 2018;3:124.
+> https://doi.org/10.12688/wellcomeopenres.14826.1
+
+GitHub's **"Cite this repository"** button gives the citation in APA and BibTeX formats, from
+[`CITATION.cff`](CITATION.cff).
+
+## Related
+* [brucetyper](https://github.com/duceppemo/brucetyper) — *in silico* Bruce-ladder, Suis-ladder, AMOS and
+  RB51 junction PCR for *Brucella*, from assemblies. Where BrucellaID gives the species from a distance and
+  the sequence type from the alleles, brucetyper reads the assays a laboratory would run on a gel.
+* [seqcounter](https://github.com/duceppemo/seqcounter) — count the occurrences of any reference sequences
+  in reads or assemblies.
+* [spoligotyper](https://github.com/duceppemo/spoligotyper) — *in silico* spoligotyping of the
+  *M. tuberculosis* complex.
+
+## Contributing
+Bug reports, questions and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Author
+Marc-Olivier Duceppe, Canadian Food Inspection Agency (CFIA): marc-olivier.duceppe@inspection.gc.ca
+
+## License
+[MIT](LICENSE)

brucellaid-1.0.0/brucellaid/__init__.py

@@ -0,0 +1,3 @@
+"""Identify the Brucella species of a read set with MASH, and type it with MLST."""
+
+__version__ = '1.0.0'

brucellaid-1.0.0/brucellaid/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the command with "python -m brucellaid"."""
+
+from .cli import main
+
+if __name__ == '__main__':
+    main()

brucellaid-1.0.0/brucellaid/cli.py

@@ -0,0 +1,233 @@
+"""Command line entry point."""
+
+import logging
+import os
+import re
+import shlex
+import sys
+import time
+from argparse import ArgumentParser, ArgumentTypeError, RawDescriptionHelpFormatter
+from datetime import datetime
+from pathlib import Path
+
+from . import __version__
+from .errors import BrucellaIDError
+from .mash import DEFAULT_MIN_HASHES, check_mash, sketch_references
+from .mlst import DEFAULT_MIN_READS, alleles_fasta, load_profiles
+from .pipeline import analyse_samples
+from .references import compare_with_sketch, load_references, reference_sketch
+from .report import print_table, run_info, write_reports
+from .samples import find_samples, single_sample
+from .seal import DEFAULT_KMER_SIZE, DEFAULT_MISMATCHES, auto_memory, check_seal
+
+log = logging.getLogger('brucellaid')
+
+# Expected errors are reported without a traceback
+USER_ERRORS = (BrucellaIDError, OSError)
+
+EPILOG = '''examples:
+  brucellaid -r1 sample_R1.fastq.gz -r2 sample_R2.fastq.gz -o results/
+  brucellaid -r1 sample.fastq.gz -o results/
+  brucellaid -i folder_of_fastq/ -o results/
+  brucellaid -i folder_of_fastq/ -o results/ -p 4 -t 16 --xlsx
+
+documentation: https://github.com/duceppemo/BrucellaID/wiki'''
+
+
+def setup_logging(verbose=False):
+    """Configure the package logger only, so importing brucellaid never alters the root logger."""
+    for handler in list(log.handlers):
+        log.removeHandler(handler)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter('%(asctime)s %(levelname)-7s %(message)s', datefmt='%H:%M:%S'))
+    log.addHandler(handler)
+    log.setLevel(logging.DEBUG if verbose else logging.INFO)
+
+
+def positive_int(value):
+    try:
+        value = int(value)
+    except ValueError:
+        raise ArgumentTypeError('"{}" is not an integer'.format(value)) from None
+    if value < 1:
+        raise ArgumentTypeError('must be >= 1')
+    return value
+
+
+def java_memory(value):
+    if not value[:-1].isdigit() or value[-1].lower() not in 'mg':
+        raise ArgumentTypeError('"{}" is not a Java memory size such as 500m or 2g'.format(value))
+    return value
+
+
+def available_cpus():
+    try:
+        return len(os.sched_getaffinity(0))  # Respects cgroup/taskset limits on Linux (e.g. SLURM jobs)
+    except AttributeError:
+        return os.cpu_count() or 1
+
+
+def format_elapsed(seconds):
+    """A readable duration: "1h2m3s"."""
+    minutes, seconds = divmod(int(round(seconds)), 60)
+    hours, minutes = divmod(minutes, 60)
+    days, hours = divmod(hours, 24)
+    periods = [('d', days), ('h', hours), ('m', minutes), ('s', seconds)]
+    return ''.join('{}{}'.format(value, name) for name, value in periods if value) or '0s'
+
+
+def build_parser():
+    max_cpu = available_cpus()
+    parser = ArgumentParser(prog='brucellaid', formatter_class=RawDescriptionHelpFormatter, epilog=EPILOG,
+                            description='Identify the Brucella species of sequencing reads by their MASH distance\n'
+                                        'to 16 reference genomes, and type them with the nine-locus MLST scheme.')
+    inputs = parser.add_argument_group('input (one sample with -r1, or a folder of samples with -i)')
+    source = inputs.add_mutually_exclusive_group(required=True)
+    source.add_argument('-r1', '--r1', metavar='FILE',
+                        help='Reads: single-end, or R1 of paired-end. fastq, gzipped or not.')
+    source.add_argument('-i', '--input', metavar='FOLDER',
+                        help='Folder of fastq files, searched recursively. Each single-end fastq file or pair of '
+                             'R1/R2 fastq files is a sample.')
+    inputs.add_argument('-r2', '--r2', metavar='FILE',
+                        help='R2 reads, for paired-end fastq files.')
+    inputs.add_argument('-s', '--sample', metavar='NAME',
+                        help='With -r1: sample name used in the reports. Default: the input file name, without '
+                             'extension and read suffix (_R1, _1, ...).')
+
+    output = parser.add_argument_group('output')
+    output.add_argument('-o', '--output', metavar='FOLDER', required=True,
+                        help='Folder to hold the reports. Created if needed.')
+    output.add_argument('--xlsx', action='store_true',
+                        help='Also write the legacy vSNP-style report, stat_alignment_summary_<date>.xlsx. Needs '
+                             'the xlsxwriter package.')
+
+    calling = parser.add_argument_group('identification and typing')
+    calling.add_argument('--min-hashes', metavar='N', type=int, default=DEFAULT_MIN_HASHES,
+                         help='Minimum number of the reference\'s 1000 min-hashes the reads must share for a '
+                              'species to be reported. Default: {}.'.format(DEFAULT_MIN_HASHES))
+    calling.add_argument('--min-reads', metavar='N', type=int, default=DEFAULT_MIN_READS,
+                         help='Minimum number of reads assigned to an MLST allele for the allele to be called. '
+                              'Default: {}.'.format(DEFAULT_MIN_READS))
+    calling.add_argument('--no-mlst', action='store_true',
+                         help='Identify the species only, and skip the MLST typing.')
+    calling.add_argument('-k', '--kmer-size', metavar='N', type=positive_int, default=DEFAULT_KMER_SIZE,
+                         help='K-mer size used to assign the reads to the MLST alleles. '
+                              'Default: {}.'.format(DEFAULT_KMER_SIZE))
+    calling.add_argument('-m', '--mismatch', metavar='N', type=int, default=DEFAULT_MISMATCHES,
+                         help='Mismatches allowed between an allele k-mer and a read (maximum Hamming distance). '
+                              'Default: {}, as the alleles of a locus differ by a few bases.'
+                              .format(DEFAULT_MISMATCHES))
+
+    data = parser.add_argument_group('reference data (the package ships all three)')
+    data.add_argument('--sketch', metavar='FILE',
+                      help='MASH sketch of the reference genomes, instead of the one of the package.')
+    data.add_argument('--references', metavar='FILE', dest='references',
+                      help='Table of the reference genomes and their species, instead of the one of the package.')
+    data.add_argument('--alleles', metavar='FILE',
+                      help='Fasta file of the MLST alleles, instead of the one of the package.')
+    data.add_argument('--profiles', metavar='FILE',
+                      help='Table of the MLST profiles, instead of the one of the package.')
+
+    other = parser.add_argument_group('performance and other options')
+    other.add_argument('-t', '--threads', metavar='N', type=positive_int, default=max_cpu,
+                       help='Number of threads. Default: all available ({}).'.format(max_cpu))
+    other.add_argument('-p', '-j', '--parallel', '--jobs', metavar='N', type=positive_int, default=1, dest='parallel',
+                       help='With -i: number of samples analysed at the same time, sharing the threads. Default: 1.')
+    other.add_argument('--memory', metavar='SIZE', type=java_memory,
+                       help='Memory for Seal (Java heap size), per job, e.g. 2g. Default: from the size of the '
+                            'allele file, within 85%% of the machine.')
+    other.add_argument('--verbose', action='store_true', help='Show debug messages, including the commands run.')
+    other.add_argument('-v', '--version', action='version', version='%(prog)s ' + __version__)
+    return parser
+
+
+def check_arguments(parser, args):
+    if args.input and (args.r2 or args.sample):
+        parser.error('-r2 and --sample are only used with -r1')
+    if args.r1 and args.parallel > 1:
+        parser.error('--parallel is only used with -i')
+    if args.min_hashes < 1:
+        parser.error('--min-hashes must be >= 1')
+    if args.min_reads < 1:
+        parser.error('--min-reads must be >= 1')
+    if args.mismatch < 0:
+        parser.error('--mismatch cannot be negative')
+    if args.mismatch >= args.kmer_size:
+        parser.error('--mismatch ({}) must be smaller than --kmer-size ({})'.format(args.mismatch, args.kmer_size))
+    if args.sample is not None and (not args.sample.strip() or '/' in args.sample or args.sample in ('.', '..')):
+        parser.error('--sample must be a name, not a path: "{}"'.format(args.sample))
+    if args.sample is not None and re.search(r'[\t\r\n]', args.sample):
+        parser.error('--sample cannot contain tabs or line breaks (they would break the table)')
+
+
+def file_bases(path):
+    """Rough number of bases in a fasta file: its size, which is close enough to size the Seal heap."""
+    try:
+        return Path(path).stat().st_size
+    except OSError:
+        return 0
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    check_arguments(parser, args)
+    setup_logging(args.verbose)
+    command = shlex.join([parser.prog, *(sys.argv[1:] if argv is None else argv)])
+    log.debug('brucellaid %s: %s', __version__, command)
+    started = datetime.now().astimezone()
+    start = time.monotonic()
+    output = Path(args.output).expanduser()
+    mlst = not args.no_mlst
+    try:
+        check_mash()
+        if mlst:
+            check_seal()
+        sketch = reference_sketch(args.sketch)
+        references = load_references(args.references)
+        alleles = alleles_fasta(args.alleles)
+        loci = load_profiles(args.profiles)[0] if mlst else ()
+        log.info('%d reference genome(s) in %s', len(sketch_references(sketch)), sketch)
+        for message in compare_with_sketch(sketch_references(sketch), references):
+            log.warning('%s', message)
+        if mlst:
+            log.info('%d MLST locus/loci: %s', len(loci), ', '.join(loci))
+        if args.input:
+            samples = find_samples(args.input, exclude=[output])
+            log.info('%d sample(s) found in %s', len(samples), args.input)
+        else:
+            samples = [single_sample(args.r1, args.r2, name=args.sample)]
+        jobs = min(args.parallel, len(samples))
+        memory = args.memory or auto_memory(file_bases(alleles), jobs=jobs)
+        results = analyse_samples(samples, jobs=jobs, threads=args.threads, sketch=sketch, references=references,
+                                  min_hashes=args.min_hashes, min_reads=args.min_reads, kmer_size=args.kmer_size,
+                                  mismatch=args.mismatch, memory=memory, alleles=args.alleles,
+                                  profiles=args.profiles, mlst=mlst)
+        run = run_info(command, {'Input': ' '.join(os.path.abspath(f) for f in (args.input, args.r1, args.r2) if f),
+                                 'Output folder': str(output.resolve()),
+                                 'Reference sketch': os.path.abspath(sketch),
+                                 'MLST alleles': os.path.abspath(alleles) if mlst else None,
+                                 'Minimum shared hashes': args.min_hashes,
+                                 'Minimum reads per allele': args.min_reads if mlst else None,
+                                 'K-mer size': args.kmer_size, 'Mismatches': args.mismatch,
+                                 'MLST': mlst, 'Threads': args.threads, 'Parallel samples': jobs,
+                                 'Seal memory': memory}, started)
+        rows, reports = write_reports(results, references, output, started, command=command, run=run,
+                                      xlsx=args.xlsx)
+    except USER_ERRORS as e:
+        log.error('%s', e)
+        log.debug('Traceback:', exc_info=True)  # Shown with --verbose
+        sys.exit(1)
+    except KeyboardInterrupt:
+        log.error('Interrupted')
+        sys.exit(130)
+
+    # The results go to stdout, the messages to stderr: "brucellaid ... > results.tsv" works
+    print_table(rows)
+    for report in reports:
+        log.info('Report saved in %s', report)
+    log.info('Done in %s', format_elapsed(time.monotonic() - start))
+    failed = [r.sample for r in results if r.error]
+    if failed:
+        log.error('%d of %d sample(s) failed: %s', len(failed), len(results), ', '.join(failed))
+        sys.exit(1)

brucellaid-1.0.0/brucellaid/data/README.md

@@ -0,0 +1,34 @@
+# Reference data
+
+Four files, about 290 kB. `brucellaid --sketch/--references/--alleles/--profiles` take files of your own
+instead of these.
+
+| File | What it is | Where it comes from |
+| --- | --- | --- |
+| `references.msh` | MASH sketch of 16 *Brucella* reference genomes (k = 21, 1000 hashes) | The *Brucella* part of [vSNP](https://github.com/USDA-VS/vsnp)'s reference set, as `vsnp_reference.msh` |
+| `references.tsv` | What each genome of the sketch is: vSNP species code, species, biovar, strain, NCBI accessions | Written for BrucellaID, from the sketch and vSNP's `species_accessions.csv` |
+| `mlst_alleles.fasta` | 309 alleles of the nine MLST loci | [PubMLST](https://pubmlst.org/organisms/brucella-spp), "MLST (9 locus)", downloaded 2026-10-31 |
+| `mlst_profiles.tsv` | 122 sequence types | The same scheme, the same day |
+
+The sketch ID of a genome is the name of the file it was built from, which is what `mash dist` reports and
+what `references.tsv` keys on.
+
+Two genomes of the sketch, `Bceti1Cudo.fasta` (*B. ceti* strain Cudo) and `B-REF-BS4-40.fasta` (*B. suis*
+bv. 4 strain 40), are distributed by vSNP under its own names rather than as accessions, so their
+`accessions` column is empty and `scripts/make_reference_data.py` cannot download them.
+
+## Rebuilding
+```bash
+python3 scripts/make_mlst_data.py                                   # the two MLST files, from PubMLST
+python3 scripts/make_reference_data.py --genomes /tmp/refs --out /tmp/references.msh   # the sketch
+```
+PubMLST serves the data submitted up to a cut-off date unless you authenticate; the script prints the date
+it was given. The MLST data here was downloaded on 2026-10-31, with data submitted up to 2024-12-31.
+
+The scheme is Whatmore, Perrett and MacMillan (2007),
+[doi:10.1186/1471-2180-7-34](https://doi.org/10.1186/1471-2180-7-34). PubMLST is maintained at the
+University of Oxford; publications using its data should cite Jolley, Bray and Maiden (2018),
+[doi:10.12688/wellcomeopenres.14826.1](https://doi.org/10.12688/wellcomeopenres.14826.1).
+
+A sketch must keep MASH's defaults (k = 21, 1000 hashes): the threshold of 150 shared hashes
+(`--min-hashes`) is read against that sketch size.