brucellaid 1.0.0__py3-none-any.whl

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/__main__.py

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

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/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.