BioSeeker

BioSeeker is a Python library and CLI tool for the analysis of codon and bicodon conservation rates across linked species.

With this project, you can calculate codon and bicodon conservation rates for a given genus. It is based on the math from Conservation of location of several specific inhibitory codon pairs in the Saccharomyces sensu stricto yeasts reveals translational selection (Ghoneim et al., 2019).

What it does

BioSeeker calculates conservation rates for single codons and codon pairs (bicodons) across three reading frames (ORF 0, 1, 2) by reading standard FASTA formats with Biopython. It automatically aggregates results from multiple alignment files and uses NumPy to speed up the math.

Beyond simple counting, it runs linear regressions, finds outliers, and computes dipeptide-based z-scores to help you isolate translational selection signals. It can also calculate the Relative Synonymous Codon Usage (RSCU) for your dataset. If you prefer to avoid installing local dependencies, there is a Docker image available.

You can read the exact mathematical definitions of these metrics in the Methodology Documentation.

Installation

From Source

Requires Python 3.11+.

git clone https://github.com/SouthernBio/BioSeeker.git
cd BioSeeker
pip install .

From PyPI

pip install bioseeker

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Usage

Command Line

BioSeeker provides a command line interface with a few subcommands. Place your aligned FASTA files in a directory (e.g., FASTA_files).

Full Analysis Pipeline: The analyze subcommand runs the full pipeline (counts, rates, regressions, and plots).

bioseeker analyze --input FASTA_files --output results --species Scer Spar Smik Skud Sbay

Key Arguments for analyze:

• --input, -i: Directory containing input alignment files (default: FASTA_files).
• --output, -o: Directory to save CSV results and plots (default: results).
• --species: Only process alignments containing all specified species (e.g., --species Scer Spar Smik Skud Sbay). Incomplete alignments are discarded.
• --reference: Reference sequence ID (default: first sequence in the file).
• --threshold: Conservation threshold (default: 1.0, meaning 100% identity required).
• --genetic-code: NCBI translation table ID (default: 1 for Standard). This is necessary because different organisms may use different translation tables (e.g., Candida uses table 12 where CTG translates to Serine instead of Leucine, and different tables have different stop codons).
• --orfs: Reading frames to analyze (default: 0 1 2).
• --sigma-threshold: Threshold (in σ) for outlier detection (default: 3.0).

RSCU Analysis

To calculate the global RSCU values across your alignments:

bioseeker rscu --input FASTA_files --output results

Docker

You can run BioSeeker without installing Python dependencies using Docker.

Build the image:

docker build -t bioseeker .

Run the container: Assuming your data is in the current directory under FASTA_files:

docker run -v $(pwd)/FASTA_files:/data/input -v $(pwd)/results:/data/output bioseeker --input /data/input --output /data/output

Output

The tool generates CSV files and plots in the output directory for each analyzed ORF (e.g., ORF0):

• codon_conservation_ORF0.csv: Raw codon counts.
• bicodon_conservation_ORF0.csv: Raw bicodon counts.
• bicodon_stats_ORF0.csv: Full metrics including ExpectedRate, FittedRate, Outlier status, NormalizedScore, and DipeptideZ.
• conservation_regression_ORF0.png: Plot of observed vs expected conservation rates.

For a full explanation of the outputs, refer to the Methodology Documentation.

License

GNU General Public License v3.0. See LICENSE.

💙 Support this project

Your contribution would help SouthernBio in improving the quality of this project and adding additional features. If you find this project useful and/or interesting, please consider offering your support on Github Sponsors, Ko-Fi or PayPal