Bowtie 2 utilities

ASOkai wraps the external bowtie2, bowtie2-build, and bowtie2-inspect executables. Install them through the supplied Conda environment or provide explicit executable paths. The wrappers run commands without a shell and raise Bowtie2ExecutionError on failure. Their named parameters cover selected Bowtie 2 CLI options; they do not mirror the full command-line interfaces. Use additional_args for other options.

Bowtie2Build creates an index from a FASTA file. The output argument is a basename: Bowtie 2 writes six files with that basename and either .bt2 or .bt2l suffixes. Bowtie2 accepts that basename to align unpaired or paired reads to SAM. Bowtie2Inspect reports reference names or index metadata.

from ASOkai.Utils import Bowtie2, Bowtie2Build, Bowtie2Inspect

Bowtie2Build().run("genome.fa.gz", "indexes/genome", threads=8)
Bowtie2().run(
    "indexes/genome", "alignments.sam",
    reads="queries.fa", read_format="fasta", threads=8,
    seed_length=16, all_alignments=True,
)
names = Bowtie2Inspect().run("indexes/genome", names=True).stdout

Bowtie 2’s default seed length targets longer reads. Choose an appropriate seed_length and scoring policy when searching short oligonucleotides. The wrappers do not infer a safe sensitivity setting for short queries. all_alignments=True asks Bowtie 2 to report all alignments it finds; its heuristic search does not guarantee every possible match. Use an exact sequence search when a complete count of short repeats is required.

Bowtie2IndexDirectory validates a directory of six index files. Pass its index_base(index_directory) result to Bowtie2.run when using an index directory produced by ASOkai.

The pipeline’s build-bowtie2-index utility step builds this directory from any plain FASTA.

Bowtie 2 is third-party GPLv3 software. ASOkai invokes its executables without distributing or linking against them.

class ASOkai.Utils.Bowtie2(executable='bowtie2')[source]

Bases: _Bowtie2Command

Run bowtie2 with selected CLI options against an index prefix.

Parameters:

executable (str)

run(index_base, sam_output, *, reads=None, mate1=None, mate2=None, read_format='fastq', threads=None, local=False, seed_length=None, seed_mismatches=None, max_alignments=None, all_alignments=False, score_min=None, additional_args=(), debug=False, check=True, cwd=None)[source]

Align unpaired or paired reads and write SAM output.

Short candidate sequences need an explicit seed length and scoring policy; Bowtie 2’s presets target longer sequencing reads.

Parameters:

  • index_base (str | Path)

  • sam_output (str | Path)

  • reads (str | Path | None)

  • mate1 (str | Path | None)

  • mate2 (str | Path | None)

  • read_format (Literal['fastq', 'fasta', 'raw'])

  • threads (int | None)

  • local (bool)

  • seed_length (int | None)

  • seed_mismatches (int | None)

  • max_alignments (int | None)

  • all_alignments (bool)

  • score_min (str | None)

  • additional_args (Sequence[str])

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

class ASOkai.Utils.Bowtie2Build(executable='bowtie2-build')[source]

Bases: _Bowtie2Command

Run bowtie2-build with selected CLI options to create an index.

Parameters:

executable (str)

run(reference, index_base, *, threads=None, large_index=False, offrate=None, packed=False, quiet=False, additional_args=(), debug=False, check=True, cwd=None)[source]

Build an index from a FASTA file, optionally gzipped.

index_base is a prefix, not one of the resulting .bt2 files. Bowtie 2 chooses .bt2 or .bt2l according to index size.

Parameters:

  • reference (str | Path)

  • index_base (str | Path)

  • threads (int | None)

  • large_index (bool)

  • offrate (int | None)

  • packed (bool)

  • quiet (bool)

  • additional_args (Sequence[str])

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

class ASOkai.Utils.Bowtie2Inspect(executable='bowtie2-inspect')[source]

Bases: _Bowtie2Command

Run bowtie2-inspect with selected CLI options on an index.

Parameters:

executable (str)

run(index_base, *, names=False, summary=False, output=None, additional_args=(), debug=False, check=True, cwd=None)[source]

Return reference names, a summary, or reconstructed FASTA.

Parameters:

  • index_base (str | Path)

  • names (bool)

  • summary (bool)

  • output (str | Path | None)

  • additional_args (Sequence[str])

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

exception ASOkai.Utils.Bowtie2ExecutionError(message, *, returncode, cmd, stdout=None, stderr=None)[source]

Bases: RuntimeError

A Bowtie 2 executable returned a nonzero exit status.

Parameters:

  • message (str)

  • returncode (int)

  • cmd (list[str])

  • stdout (str | None)

  • stderr (str | None)

Return type:

None

class ASOkai.Utils.ReferenceSequence(id, sequence)[source]

Bases: object

A named sequence to include in a sequence-search index.

Parameters:

  • id (str)

  • sequence (Seq)

id: str
sequence: Seq
ASOkai.Utils.write_reference_fasta(references, path)[source]

Write named sequences as a FASTA for an external index builder.

Parameters:
Return type:

Path