Skip to main content

Automated Multi-Locus Sequence Analysis tool

Project description

Made with science GitHub version PyPI package version GitHub Release Date Maintained? Yes Made with python Language grade: Python Latest commit GitHub commits since latest release (by date) Downloads per month Lines of code Black format Checked with mypy GitHub issues GitHub forks GitHub stars

Who might want this software?

The intended audience is scientific researchers, computational biologists, and bioinformaticians who are interested in exploring phylogenetic and phylogenomic relationships between genes and organisms. The general idea is to allow the input of sequence data along with marker genes and output a robust phylogenetic tree. I’ve implemented commands to help with the installation of external dependencies, and I hope the software is easy to use.

If you have feature requests or otherwise have ideas about how to make this software better, please submit an issue with your ideas!

PhD/Masters students and undergraduates are especially encouraged to submit issues if they are having trouble using this software.

Windows users, please install WSL to make use of this software. Using a Linux distribution will make your life as a computational researcher significantly easier.


automlsa2 is distributed on PyPI as a universal wheel and is available on Linux/macOS and Windows (untested) and supports Python 3.7+ and PyPy.

$ python3 -m pip install -U automlsa2

While I will do my best to keep the git version usable, stick to a release and/or pypi install for the most stable experience.

git version install:

$ git clone
$ cd automlsa2
$ python3 -m pip install -r requirements.txt
$ python3 -m pip install -U .

for developers, clone as above, then:

$ python3 -m pip install -e . --no-use-pep517


Python modules:

  1. pandas

  2. numpy

  3. biopython

  4. rich

  5. packaging

  6. psutil

See requirements.txt for more info.

External programs:

  1. NCBI BLAST+ >= 2.10.0

  2. mafft >= 7.471

  3. IQ-TREE COVID-19 release >= 2.1.1

You can install external programs using the automlsa2 --install_deps command. These will be installed to ${HOME}/.local/external unless otherwise specified.

Just tell me how to run it

$ automlsa2 --files Genus_species_1.fna Genus_species_2.fna ... \
  Genus_species_N.fna --query queries.fasta -t THREADS -- runID


$ automlsa2 --dir path/to/genomes --query queries.fasta -t THREADS \
  -- runID


automlsa2 is a re-imagination of

The entire codebase has been re-written in python. While the general algorithm produces similar output, and several steps are shared, there are many updates and differences between the two programs, which will be covered later.

The general overview can be summarized here:

  1. Input is a set of marker genes as queries, and a set of target genome FASTA files.

  2. BLAST databases are generated for each target genome, and each query gene is extracted from the input query FASTA files.

  3. BLAST searches are done with the extracted sequences and genomes.

  4. Per genome hits are calculated pending the cut-offs, and genomes are filtered from the analysis.

  5. Sequences are extracted from the BLAST results as unaligned multi-FASTAs.

  6. Unaligned sequences are aligned using mafft.

  7. A nexus file is generated pointing to all aligned sequences.

  8. A phylogenetic tree is generated using the nexus file as input.

BLAST searches are threaded, or, optionally, written to a file to be submitted to a compute cluster. mafft alignment commands can also be written to a file for submission to a compute cluster.

Input query files and genome directories are scanned for updates - if sequences are added, removed, or changed, the analysis is re-done.

Multiple queries targeting the same gene sequence can be used to improve coverage of disparate gene sequences, e.g. attempting to cover an entire phylum with multiple reference genomes being used.


$ automlsa2 -h
usage: automlsa2 [-h] [--query QUERY [QUERY ...]] [--files FILES [FILES ...]]
             [--dir DIR [DIR ...]] [-e EVALUE] [-c COVERAGE] [-i IDENTITY]
             [-p {blastn,tblastn}] [--config CONFIG] [--missing_check]
             [-t THREADS] [--dups] [--allow_missing ALLOW_MISSING]
             [--outgroup OUTGROUP] [--protect]
             [--checkpoint {validate,preblast,filtering,prealign,postalign,nexus,none}]
             [--install_deps [INSTALL_DEPS]] [--external EXTERNAL]
             [--mafft MAFFT] [--iqtree IQTREE] [--debug] [--version]

This is a rewrite of Generates automated multi-locus sequence analyses.

positional arguments:
  runid                 Name of the run directory.

optional arguments:

-h, --help

show this help message and exit

--query <QUERY [QUERY …]>

Path to file with input seq(s).

--files <FILES [FILES …]>

Path to the target genome FASTA files.

--dir <DIR [DIR …]>

Path to the target genome directory with FASTA files.

-e EVALUE, --evalue EVALUE

E-value cutoff for BLAST searches. [1e-5]

-c COVERAGE, --coverage COVERAGE

Sets the coverage cut-off threshold. [50]

-i IDENTITY, --identity IDENTITY

Sets the identity cut-off threshold. [30]

-p PROGRAM, --program PROGRAM

Which BLAST program to run. [tblastn] {tblastn, blastn}

--config CONFIG

Path to configuration json file to copy.


Use this to confirm that settings have been checked when genes are missing.

-t THREADS, --threads THREADS

Number of threads to use. [1]


Allow for duplicate query names for more sequence coverage across disparate organisms.

--allow_missing ALLOW_MISSING

Allow for N missing genes per genome. [0]

--outgroup OUTGROUP

Name of outgroup file or strain to root on.


Save files from getting overwritten. By default, as input files update, older alignments and trees are deleted.

--checkpoint CHECKPOINT

Name of stage to stop computing on. [none] {validate,preblast,filtering,prealign,postalign,nexus,none}

--install_deps <[INSTALL_DEPS]>

Install dependencies into given directory. [~/.local/external]

--external EXTERNAL

Path to installed external programs. [~/.local/external]

--mafft MAFFT

mafft settings [–localpair –maxiterate 1000 –reorder]

--iqtree IQTREE

iqtree2 settings [-m MFP -B 1000 -alrt 1000 –msub nuclear –merge rclusterf]


Turn on debugging messages.


show program’s version number and exit


Turn off progress messages.

One or more input target genome FASTA files is required, either using --files or --dir. Additionally, one or more query FASTA files containing one or more query gene sequences is necessary for analysis.

By default, protein queries are expected, and nucleotide FASTA sequence is required for the target genomes. tblastn is used to target the genome sequences using the amino acid queries. blastn is also available, targeting the genome sequences using nucleotide queries.

Threads will speed things up significantly. BLAST searches are threaded in python; submitting multiple threads to the blast executable often does not result in much speed up, so each BLAST search is run with one CPU given.

Query marker genes often come from a well-studied representative of, at most, the same genus. Intergenera phylogenies should have a representative sequence from each genus. This can be accomplished by giving all examples of a particular gene the same name in the reference FASTA file. e.g.

>Gene1 Refgenus1 refspecies ABC
<AA sequence>
>Gene1 Refgenus2 refspecies DEF
<AA sequence>
>Gene1 Refgenus3 refspecies GHI
<AA sequence>

This ^ FASTA ^ file would have three representatives of Gene1 in the analysis. The resulting alignments would have one copy of the gene, with the best hits from each target genome included.

Target genome files will be named based on the filename in the final output. Generally, one will want to have Genus_species_strain.fasta or G_species_strain.fasta as the filenames prior to analysis.

Genomes can be downloaded using my get_assemblies program, here: Locally produced genomes can be renamed as required.

Running Tests

The test data are included in a separate repository -

To download this test data, you can run git submodule update --init.

Alternatively, you can run the script and it will download the git submodule for you and run the test command.

The tests should take about 2-3 minutes with 4 CPUs.


☐ Write detailed list of intermediate files.

☐ Compare functionality of this version to prior version.

☑ Check for version numbers for external programs.


Bug reports are encouraged! Submit a github issue and I’ll be happy to take a look. Also, feel free to clone and submit merge requests.

Author Contact

Ed Davis


Special thanks for helping me test the software and get the python code packaged:

Also, thanks to these groups for supporting me through my scientific career:


automlsa2 is distributed under the terms listed in the LICENSE file. The software is free for non-commercial use.


Copyright (c) 2020 Oregon State University

All Rights Reserved.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

automlsa2-0.9.0.tar.gz (33.2 kB view hashes)

Uploaded Source

Built Distribution

automlsa2-0.9.0-py3-none-any.whl (33.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page