primer-finder 1.0.0__tar.gz

primer_finder-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 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.

primer_finder-1.0.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: primer-finder
+Version: 1.0.0
+Summary: Find group-specific kmers to design selective qPCR assays.
+Author: Marc-Olivier Duceppe
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/duceppemo/primer-finder
+Project-URL: Documentation, https://github.com/duceppemo/primer-finder/wiki
+Project-URL: Changelog, https://github.com/duceppemo/primer-finder/blob/master/CHANGELOG.md
+Keywords: bioinformatics,qPCR,primer design,kmer,diagnostics
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: pre-commit; extra == "test"
+Dynamic: license-file
+
+# primer-finder
+
+<p align="center">
+  <a href="https://github.com/duceppemo/primer-finder/actions/workflows/ci.yml"><img src="https://github.com/duceppemo/primer-finder/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/duceppemo/primer-finder"><img src="https://codecov.io/gh/duceppemo/primer-finder/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/duceppemo/primer-finder/releases/latest"><img src="https://img.shields.io/github/v/release/duceppemo/primer-finder?label=release&cacheSeconds=3600" alt="Latest release"></a>
+  <a href="https://anaconda.org/bioconda/primer-finder"><img src="https://img.shields.io/conda/vn/bioconda/primer-finder?label=bioconda" alt="Bioconda"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/duceppemo/primer-finder" alt="License: MIT"></a>
+  <a href="https://github.com/duceppemo/primer-finder/wiki"><img src="https://img.shields.io/badge/docs-wiki-informational" alt="Documentation"></a>
+  <a href="https://zenodo.org/badge/latestdoi/222737677"><img src="https://zenodo.org/badge/222737677.svg" alt="DOI"></a>
+</p>
+
+primer-finder finds the sequences that tell one group of genomes from another, so that a selective (q)PCR
+assay can be designed on them. Give it two folders of assembled genomes — the ones the assay should amplify
+(inclusion) and the ones it must not (exclusion) — and it reports the regions that every inclusion genome
+carries, that no exclusion genome carries, and whose differences are close enough together to sit in one
+primer or probe.
+
+```
+inclusion/ ──┐                                                   ┌──► 1. kmers shared by all inclusion genomes (KMC)
+             ├──► kmers ──► subtract ──► assemble ──► map ──► blast
+exclusion/ ──┘              (KMC)       (SKESA or   (minimap2)  (every genome)
+                                         SPAdes)
+                                                                 └──► final_kmers.fasta: the candidate regions,
+                                                                      with the specific bases in lower case
+```
+
+## Quick start
+
+```bash
+conda create -n primer-finder -c conda-forge -c bioconda primer-finder
+conda activate primer-finder
+
+primer-finder -i inclusion/ -e exclusion/ -o results/
+```
+
+`inclusion/` and `exclusion/` hold one assembled genome per file (`.fasta`, `.fna`, `.fa`, gzipped or not;
+subfolders and symbolic links are followed). The answer is `results/final_kmers.fasta`: one record per
+candidate region, the specific bases in lower case and their positions in the header, the most promising
+first. `results/run_info.json` records the parameters, the genomes and the version of every program used.
+
+To install from the source code instead, see
+[Installation](https://github.com/duceppemo/primer-finder/wiki/Installation).
+
+primer-finder only keeps perfect matches: a kmer must be in **all** the inclusion genomes with no mismatch,
+and in **none** of the exclusion genomes. It is therefore very sensitive to the quality of the assemblies and
+to how the genomes were assigned to the two groups. Curate the input genomes;
+[genome_comparator](https://github.com/duceppemo/genome_comparator) helps with that.
+
+To check an installation, run the bundled example (simulated genomes with a known answer, a few seconds).
+It is in the repository, not in the conda package:
+
+```bash
+curl -sL https://github.com/duceppemo/primer-finder/archive/refs/tags/v1.0.0.tar.gz | tar -xz --strip-components=1 primer-finder-1.0.0/example
+bash example/run_example.sh
+```
+
+## Ordering the assays
+
+Once an assay has been designed from a candidate region and ordered, `primer-finder idt` turns the IDT order
+sheet into a fasta file of oligos, one record per primer and probe:
+
+```bash
+primer-finder idt order.xlsx assays.fasta my_target
+```
+
+## Documentation
+
+Everything else is in the [wiki](https://github.com/duceppemo/primer-finder/wiki), whose sources are
+maintained in [`docs/wiki`](docs/wiki):
+
+| Page | Contents |
+|---|---|
+| [Installation](https://github.com/duceppemo/primer-finder/wiki/Installation) | conda, bioconda, from source, checking the installation |
+| [Usage](https://github.com/duceppemo/primer-finder/wiki/Usage) | inputs, every option, choosing the two groups, performance |
+| [Methods](https://github.com/duceppemo/primer-finder/wiki/Methods) | what each step does, the filtering rules, limits |
+| [Outputs](https://github.com/duceppemo/primer-finder/wiki/Outputs) | every file and field |
+| [Example](https://github.com/duceppemo/primer-finder/wiki/Example) | the simulated dataset and its expected result |
+| [FAQ](https://github.com/duceppemo/primer-finder/wiki/FAQ) | troubleshooting, "no contig passed" |
+| [Development](https://github.com/duceppemo/primer-finder/wiki/Development) | tests, continuous integration, releases |
+
+## Citation
+
+If primer-finder helped your work, please cite it (see [CITATION.cff](CITATION.cff)) together with the
+programs it runs: [KMC](https://github.com/refresh-bio/KMC),
+[SKESA](https://github.com/ncbi/SKESA) or [SPAdes](https://github.com/ablab/spades),
+[minimap2](https://github.com/lh3/minimap2) and [BLAST](https://blast.ncbi.nlm.nih.gov/).
+
+## License
+
+[MIT](LICENSE)

primer_finder-1.0.0/README.md

@@ -0,0 +1,92 @@
+# primer-finder
+
+<p align="center">
+  <a href="https://github.com/duceppemo/primer-finder/actions/workflows/ci.yml"><img src="https://github.com/duceppemo/primer-finder/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/duceppemo/primer-finder"><img src="https://codecov.io/gh/duceppemo/primer-finder/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/duceppemo/primer-finder/releases/latest"><img src="https://img.shields.io/github/v/release/duceppemo/primer-finder?label=release&cacheSeconds=3600" alt="Latest release"></a>
+  <a href="https://anaconda.org/bioconda/primer-finder"><img src="https://img.shields.io/conda/vn/bioconda/primer-finder?label=bioconda" alt="Bioconda"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/duceppemo/primer-finder" alt="License: MIT"></a>
+  <a href="https://github.com/duceppemo/primer-finder/wiki"><img src="https://img.shields.io/badge/docs-wiki-informational" alt="Documentation"></a>
+  <a href="https://zenodo.org/badge/latestdoi/222737677"><img src="https://zenodo.org/badge/222737677.svg" alt="DOI"></a>
+</p>
+
+primer-finder finds the sequences that tell one group of genomes from another, so that a selective (q)PCR
+assay can be designed on them. Give it two folders of assembled genomes — the ones the assay should amplify
+(inclusion) and the ones it must not (exclusion) — and it reports the regions that every inclusion genome
+carries, that no exclusion genome carries, and whose differences are close enough together to sit in one
+primer or probe.
+
+```
+inclusion/ ──┐                                                   ┌──► 1. kmers shared by all inclusion genomes (KMC)
+             ├──► kmers ──► subtract ──► assemble ──► map ──► blast
+exclusion/ ──┘              (KMC)       (SKESA or   (minimap2)  (every genome)
+                                         SPAdes)
+                                                                 └──► final_kmers.fasta: the candidate regions,
+                                                                      with the specific bases in lower case
+```
+
+## Quick start
+
+```bash
+conda create -n primer-finder -c conda-forge -c bioconda primer-finder
+conda activate primer-finder
+
+primer-finder -i inclusion/ -e exclusion/ -o results/
+```
+
+`inclusion/` and `exclusion/` hold one assembled genome per file (`.fasta`, `.fna`, `.fa`, gzipped or not;
+subfolders and symbolic links are followed). The answer is `results/final_kmers.fasta`: one record per
+candidate region, the specific bases in lower case and their positions in the header, the most promising
+first. `results/run_info.json` records the parameters, the genomes and the version of every program used.
+
+To install from the source code instead, see
+[Installation](https://github.com/duceppemo/primer-finder/wiki/Installation).
+
+primer-finder only keeps perfect matches: a kmer must be in **all** the inclusion genomes with no mismatch,
+and in **none** of the exclusion genomes. It is therefore very sensitive to the quality of the assemblies and
+to how the genomes were assigned to the two groups. Curate the input genomes;
+[genome_comparator](https://github.com/duceppemo/genome_comparator) helps with that.
+
+To check an installation, run the bundled example (simulated genomes with a known answer, a few seconds).
+It is in the repository, not in the conda package:
+
+```bash
+curl -sL https://github.com/duceppemo/primer-finder/archive/refs/tags/v1.0.0.tar.gz | tar -xz --strip-components=1 primer-finder-1.0.0/example
+bash example/run_example.sh
+```
+
+## Ordering the assays
+
+Once an assay has been designed from a candidate region and ordered, `primer-finder idt` turns the IDT order
+sheet into a fasta file of oligos, one record per primer and probe:
+
+```bash
+primer-finder idt order.xlsx assays.fasta my_target
+```
+
+## Documentation
+
+Everything else is in the [wiki](https://github.com/duceppemo/primer-finder/wiki), whose sources are
+maintained in [`docs/wiki`](docs/wiki):
+
+| Page | Contents |
+|---|---|
+| [Installation](https://github.com/duceppemo/primer-finder/wiki/Installation) | conda, bioconda, from source, checking the installation |
+| [Usage](https://github.com/duceppemo/primer-finder/wiki/Usage) | inputs, every option, choosing the two groups, performance |
+| [Methods](https://github.com/duceppemo/primer-finder/wiki/Methods) | what each step does, the filtering rules, limits |
+| [Outputs](https://github.com/duceppemo/primer-finder/wiki/Outputs) | every file and field |
+| [Example](https://github.com/duceppemo/primer-finder/wiki/Example) | the simulated dataset and its expected result |
+| [FAQ](https://github.com/duceppemo/primer-finder/wiki/FAQ) | troubleshooting, "no contig passed" |
+| [Development](https://github.com/duceppemo/primer-finder/wiki/Development) | tests, continuous integration, releases |
+
+## Citation
+
+If primer-finder helped your work, please cite it (see [CITATION.cff](CITATION.cff)) together with the
+programs it runs: [KMC](https://github.com/refresh-bio/KMC),
+[SKESA](https://github.com/ncbi/SKESA) or [SPAdes](https://github.com/ablab/spades),
+[minimap2](https://github.com/lh3/minimap2) and [BLAST](https://blast.ncbi.nlm.nih.gov/).
+
+## License
+
+[MIT](LICENSE)

primer_finder-1.0.0/primer_finder/__init__.py

@@ -0,0 +1,8 @@
+"""primer-finder: find group-specific kmers to design selective qPCR assays."""
+
+__version__ = "1.0.0"
+__author__ = "Marc-Olivier Duceppe"
+
+
+class PrimerFinderError(Exception):
+    """A user-facing error: bad input, a missing program, or a failed external command."""

primer_finder-1.0.0/primer_finder/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from primer_finder.cli import main
+
+sys.exit(main())

primer_finder-1.0.0/primer_finder/assemble.py

@@ -0,0 +1,58 @@
+"""Assembling the inclusion-specific kmers into contigs, with SKESA or SPAdes."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+
+from primer_finder import PrimerFinderError, tools
+
+log = logging.getLogger(__name__)
+
+ASSEMBLERS = ("skesa", "spades")
+PROGRAMS = {"skesa": "skesa", "spades": "spades.py"}
+
+
+def assemble(kmer_fasta: Path, output: Path, assembler: str, threads: int, memory_gb: int) -> Path:
+    """Assemble a fasta file of kmers into `output`. Returns `output`."""
+    if assembler == "skesa":
+        _skesa(kmer_fasta, output, threads, memory_gb)
+    elif assembler == "spades":
+        _spades(kmer_fasta, output, threads, memory_gb)
+    else:  # pragma: no cover - the command line only accepts the two
+        raise PrimerFinderError(f'Unknown assembler "{assembler}". Choose one of: {", ".join(ASSEMBLERS)}')
+    if not output.exists() or output.stat().st_size == 0:
+        raise PrimerFinderError(
+            f"{assembler} could not assemble the inclusion-specific kmers into contigs. "
+            "There may be too few of them; a smaller kmer size (-k) may help."
+        )
+    return output
+
+
+def _skesa(kmer_fasta: Path, output: Path, threads: int, memory_gb: int) -> None:
+    tools.run([
+        "skesa",
+        "--cores", str(threads),
+        "--mem", str(memory_gb),
+        "--fasta", kmer_fasta,
+        "--contigs_out", output,
+    ])
+
+
+def _spades(kmer_fasta: Path, output: Path, threads: int, memory_gb: int) -> None:
+    work_dir = output.parent / "spades"
+    tools.run([
+        "spades.py",
+        "--s", "1", kmer_fasta,
+        "--isolate",
+        "--only-assembler",  # The kmers carry no quality values: there is nothing to correct
+        "--threads", str(threads),
+        "--memory", str(memory_gb),
+        "-o", work_dir,
+    ])
+    contigs = work_dir / "contigs.fasta"
+    if not contigs.exists():
+        raise PrimerFinderError(f"SPAdes wrote no contigs ({contigs} missing)")
+    shutil.move(str(contigs), output)
+    shutil.rmtree(work_dir, ignore_errors=True)

primer_finder-1.0.0/primer_finder/blast.py

@@ -0,0 +1,238 @@
+"""Checking the candidate contigs against every inclusion and exclusion genome with blast."""
+
+from __future__ import annotations
+
+import gzip
+import logging
+import os
+import shutil
+from collections.abc import Iterable, Sequence
+from concurrent import futures
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from primer_finder import tools
+from primer_finder.mapping import PRIMER_LENGTH
+from primer_finder.seqio import base_name, iter_records
+
+log = logging.getLogger(__name__)
+
+# A hit has to be at least this good to count as "the contig is there".
+MAX_EVALUE = 1e-10
+# A variant position is kept when it differs in at least this fraction of the exclusion genomes that hold
+# the region: a few exclusion genomes may carry the inclusion allele without making the assay useless.
+MIN_EXCLUSION_FRACTION = 0.90
+
+PRESENCE_FIELDS = ("qseqid", "evalue")
+ALIGNMENT_FIELDS = ("qseqid", "qstart", "qend", "evalue", "qseq", "sseq")
+
+# BLAST splits its path arguments on whitespace, so it is never given a path that could hold a space: each
+# genome is linked into its own folder under these fixed names, and blast runs in that folder.
+LOCAL_FASTA = "genome.fasta"
+DB_NAME = "db"
+HITS_NAME = "hits.tsv"
+
+
+@dataclass
+class Hit:
+    """One blast high-scoring pair, with the aligned query and subject sequences."""
+
+    query: str
+    qstart: int
+    qend: int
+    evalue: float
+    qseq: str = ""
+    sseq: str = ""
+
+
+@dataclass
+class Alignments:
+    """What one exclusion genome holds of one contig: every part of the contig it aligns, and where each
+    of those alignments differs from it."""
+
+    spans: list[tuple[int, int, set[int]]] = field(default_factory=list)  # start, end (0-based), variants
+
+    def add(self, hit: Hit) -> None:
+        self.spans.append((hit.qstart - 1, hit.qend, set(variant_positions(hit))))
+
+    def covers(self, position: int) -> bool:
+        return any(start <= position < end for start, end, _ in self.spans)
+
+    def differs_at(self, position: int) -> bool:
+        """True when every copy of this region in the genome differs from the contig at this position. One
+        matching copy is enough for an assay to amplify the genome, so one is enough to say no."""
+        covering = [(start, end, variants) for start, end, variants in self.spans if start <= position < end]
+        return bool(covering) and all(position in variants for _, _, variants in covering)
+
+    @property
+    def variants(self) -> set[int]:
+        return {position for _, _, variants in self.spans for position in variants}
+
+
+@dataclass
+class ExclusionResult:
+    """What the exclusion genomes say about one contig: one entry per genome that holds any part of it."""
+
+    genomes: list[Alignments] = field(default_factory=list)
+
+    @property
+    def genomes_hit(self) -> int:
+        return len(self.genomes)
+
+
+def make_db(genome: Path, work_dir: Path) -> Path:
+    """Make a blast database for one genome, inside `work_dir` so that the input folders are left alone.
+
+    The genome is linked into `work_dir` under a fixed name (a gzipped one is decompressed: makeblastdb does
+    not read gzip), and makeblastdb runs there with relative paths, so neither a space in the path nor two
+    genomes with the same file name can reach BLAST.
+    """
+    work_dir.mkdir(parents=True, exist_ok=True)
+    local = work_dir / LOCAL_FASTA
+    if local.exists() or local.is_symlink():
+        local.unlink()
+    if genome.name.endswith(".gz"):
+        with gzip.open(genome, "rb") as src, local.open("wb") as dst:
+            shutil.copyfileobj(src, dst)
+    else:
+        try:
+            local.symlink_to(genome.resolve())
+        except OSError:  # pragma: no cover - a filesystem without symbolic links
+            shutil.copyfile(genome, local)
+    tools.run(["makeblastdb", "-in", LOCAL_FASTA, "-dbtype", "nucl", "-out", DB_NAME], cwd=work_dir)
+    return work_dir / DB_NAME
+
+
+def blastn(db: Path, query: Path, out_file: Path, fields: Sequence[str], max_targets: int = 10) -> Path:
+    """Run blastn in the database's folder, writing the chosen tabular fields to `out_file`."""
+    work_dir = db.parent
+    tools.run([
+        "blastn",
+        "-db", db.name,
+        "-query", os.path.relpath(query, work_dir),
+        "-out", os.path.relpath(out_file, work_dir),
+        "-evalue", str(MAX_EVALUE),
+        "-max_target_seqs", str(max_targets),
+        "-num_threads", "1",
+        "-outfmt", "6 " + " ".join(fields),
+    ], cwd=work_dir)
+    return out_file
+
+
+def parse_hits(out_file: Path, fields: Sequence[str]) -> list[Hit]:
+    """Read a tabular blast output written with `fields`."""
+    hits: list[Hit] = []
+    index = {name: position for position, name in enumerate(fields)}
+    with out_file.open() as fh:
+        for line in fh:
+            values = line.rstrip("\n").split("\t")
+            if len(values) != len(fields):
+                continue
+            hits.append(Hit(
+                query=values[index["qseqid"]],
+                qstart=int(values[index["qstart"]]) if "qstart" in index else 0,
+                qend=int(values[index["qend"]]) if "qend" in index else 0,
+                evalue=float(values[index["evalue"]]),
+                qseq=values[index["qseq"]] if "qseq" in index else "",
+                sseq=values[index["sseq"]] if "sseq" in index else "",
+            ))
+    return hits
+
+
+def variant_positions(hit: Hit) -> list[int]:
+    """The positions of the contig (0-based) that differ from this exclusion sequence: mismatches, inserted
+    bases, and the base next to a deletion."""
+    positions: list[int] = []
+    position = hit.qstart - 1
+    for query_base, subject_base in zip(hit.qseq, hit.sseq, strict=False):
+        if query_base == "-":  # The exclusion genome has bases the contig does not: mark where they fit in
+            positions.append(position)
+            continue
+        if subject_base == "-" or query_base.upper() != subject_base.upper():
+            positions.append(position)
+        position += 1
+    return sorted(set(positions))
+
+
+def has_close_variants(positions: Sequence[int], window: int = PRIMER_LENGTH) -> bool:
+    """True if at least two of these positions are less than `window` bases apart."""
+    return any(second - first < window for first, second in zip(positions, positions[1:], strict=False))
+
+
+def _parallel(work: Iterable[tuple], function, threads: int) -> list:
+    """Run `function(*arguments)` for every item, at most `threads` at a time, keeping the input order."""
+    work = list(work)
+    if not work:
+        return []
+    with futures.ThreadPoolExecutor(max_workers=max(1, min(threads, len(work)))) as executor:
+        return list(executor.map(lambda arguments: function(*arguments), work))
+
+
+def genome_folder(work_dir: Path, index: int, genome: Path) -> Path:
+    """A folder of its own for each genome: two genomes in different subfolders can have the same file
+    name, so the position in the list is what makes it unique."""
+    return work_dir / f"{index:04d}_{base_name(genome)}"
+
+
+def presence_in_genomes(
+    query: Path, genomes: Sequence[Path], work_dir: Path, threads: int
+) -> dict[str, dict[str, bool]]:
+    """For every contig of `query`, whether it is present in each genome. Keyed by contig, then by the
+    genome's path, which is what tells two genomes with the same file name apart."""
+    def one(index: int, genome: Path) -> set[str]:
+        folder = genome_folder(work_dir, index, genome)
+        db = make_db(genome, folder)
+        hits = parse_hits(blastn(db, query, folder / HITS_NAME, PRESENCE_FIELDS, max_targets=1),
+                          PRESENCE_FIELDS)
+        return {hit.query for hit in hits if hit.evalue <= MAX_EVALUE}
+
+    found = _parallel(enumerate(genomes), one, threads)
+    contigs = _query_names(query)
+    presence: dict[str, dict[str, bool]] = {contig: {} for contig in contigs}
+    for genome, hits in zip(genomes, found, strict=True):
+        for contig in contigs:
+            presence[contig][str(genome)] = contig in hits
+    return presence
+
+
+def _query_names(query: Path) -> list[str]:
+    """The names of the contigs in a fasta file, in file order."""
+    return [record.name for record in iter_records(query)]
+
+
+def exclusion_variants(
+    query: Path, genomes: Sequence[Path], work_dir: Path, threads: int
+) -> dict[str, ExclusionResult]:
+    """For every contig of `query`, what each exclusion genome that holds part of it looks like there."""
+    def one(index: int, genome: Path) -> list[Hit]:
+        folder = genome_folder(work_dir, index, genome)
+        db = make_db(genome, folder)
+        return parse_hits(blastn(db, query, folder / HITS_NAME, ALIGNMENT_FIELDS), ALIGNMENT_FIELDS)
+
+    results: dict[str, ExclusionResult] = {name: ExclusionResult() for name in _query_names(query)}
+    for hits in _parallel(enumerate(genomes), one, threads):
+        per_contig: dict[str, Alignments] = {}
+        for hit in hits:
+            if hit.evalue > MAX_EVALUE:
+                continue
+            per_contig.setdefault(hit.query, Alignments()).add(hit)
+        for contig, alignments in per_contig.items():
+            results.setdefault(contig, ExclusionResult()).genomes.append(alignments)
+    return results
+
+
+def shared_variants(result: ExclusionResult, fraction: float = MIN_EXCLUSION_FRACTION) -> list[int]:
+    """The contig positions worth designing a primer on: those that differ from at least `fraction` of the
+    exclusion genomes that hold that part of the contig.
+
+    A genome that does not align a position says nothing about it — it does not hold that region, which only
+    makes the assay more selective — so it is left out of the count rather than counted as identical.
+    """
+    kept: list[int] = []
+    candidates = {position for alignments in result.genomes for position in alignments.variants}
+    for position in sorted(candidates):
+        covering = [alignments for alignments in result.genomes if alignments.covers(position)]
+        differing = [alignments for alignments in covering if alignments.differs_at(position)]
+        if covering and len(differing) >= fraction * len(covering):
+            kept.append(position)
+    return kept