Metadata-Version: 2.4
Name: OrthoEvol
Version: 1.0.0
Summary: This package aids in the analysis of orthologous genes.
Author-email: Rob Gilmore <robgilmore127@gmail.com>, "Shaurita D. Hutchins" <sdhutchins@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/datasnakes/OrthoEvolution
Project-URL: Documentation, https://orthoevolution.readthedocs.io/
Project-URL: Repository, https://github.com/datasnakes/OrthoEvolution
Project-URL: Bug Reports, https://github.com/datasnakes/OrthoEvolution/issues
Project-URL: Releases, https://github.com/datasnakes/OrthoEvolution/releases
Keywords: bioinformatics,science,evolution,orthology,psychiatry,genetics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Flask
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: tqdm==4.66.3
Requires-Dist: ete3==3.0.0b35
Requires-Dist: pandas>=0.25.3
Requires-Dist: openpyxl>=2.5.0
Requires-Dist: pexpect==4.4.0
Requires-Dist: slacker==0.9.42
Requires-Dist: biopython<1.84,>=1.79
Requires-Dist: tablib>=0.11.5
Requires-Dist: mygene>=3.0.0
Requires-Dist: cookiecutter
Requires-Dist: Flask<4,>=3.1.3
Requires-Dist: Flask-Login
Requires-Dist: Flask-Mail
Requires-Dist: Flask-SQLAlchemy
Requires-Dist: Flask-WTF
Requires-Dist: treelib==1.3.5
Requires-Dist: psutil>=5.6.7
Requires-Dist: logzero>=1.5.0
Requires-Dist: xmltodict>=0.11.0
Requires-Dist: plotly>=3.10.0
Requires-Dist: pyyaml>=3.12
Requires-Dist: werkzeug>=3.1.6
Provides-Extra: test
Requires-Dist: pytest<10,>=9.1.1; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-runner; extra == "test"
Dynamic: license-file

# OrthoEvolution

[![CI](https://github.com/datasnakes/OrthoEvolution/actions/workflows/ci.yml/badge.svg)](https://github.com/datasnakes/OrthoEvolution/actions/workflows/ci.yml)
[![PyPI](https://badge.fury.io/py/OrthoEvol.svg)](https://pypi.org/project/OrthoEvol/)
[![Documentation](https://readthedocs.org/projects/orthoevolution/badge/?version=latest)](https://orthoevolution.readthedocs.io/en/latest/)
[![Coverage](https://codecov.io/gh/datasnakes/OrthoEvolution/branch/main/graph/badge.svg)](https://codecov.io/gh/datasnakes/OrthoEvolution)
[![DOI](https://zenodo.org/badge/88282824.svg)](https://doi.org/10.5281/zenodo.17796234)
[![Last Commit](https://badgen.net/github/last-commit/datasnakes/OrthoEvolution)](https://github.com/datasnakes/OrthoEvolution/commits/main)

OrthoEvolution is a Python package for reproducible comparative evolutionary
genetics, with a focus on ortholog inference, sequence analysis, and
phylogenetic workflows.

**Current version:** 1.0.0

## Table of Contents

- [Project Background](#project-background)
- [Core Capabilities](#core-capabilities)
- [Install & Setup](#install--setup)
- [Usage](#usage)
- [Documentation and Examples](#documentation-and-examples)
- [Testing](#testing)
- [Contributing](#contributing)
- [Citation](#citation)
- [License](#license)
- [Authors](#authors)

## Project Background

OrthoEvolution supports the inference and analysis of orthologous genes using
NCBI BLAST, multiple-sequence alignment strategies, and phylogenetic tools. It
organizes these steps into reusable workflows so researchers can manage large
comparative-genetics datasets and reproduce their analyses.

The package is organized around four major areas:

- `Orthologs` provides ortholog inference, alignment, and phylogenetic tools.
- `Manager` creates and coordinates repositories, projects, databases, and
  research datasets.
- `Tools` provides reusable utilities for data retrieval, parallel execution,
  logging, and cluster workloads.
- `Cookies` provides project and website templates.

For additional scientific context, see this
[related comparative-genetics paper](https://www.frontiersin.org/journals/neuroscience/articles/10.3389/fnins.2014.00283/full).

## Core Capabilities

- Infer candidate orthologs and generate post-BLAST reports.
- Retrieve NCBI datasets and preformatted BLAST databases.
- Prepare and filter nucleotide or protein sequence alignments.
- Support phylogenetic workflows involving PAML, PhyML, IQ-TREE, Phylip, and
  ETE.
- Create consistent directory structures for comparative-genetics projects.
- Configure local, parallel, PBS, and Slurm-oriented workloads.

Some workflows call external scientific programs or remote services. Install
the required BLAST, alignment, or phylogenetic software for the specific
workflow you intend to run.

## Install & Setup

OrthoEvolution supports Python 3.11 and 3.12. A virtual environment keeps its
dependencies separate from other Python projects.

### Install from PyPI

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install OrthoEvol
```

### Install from source

```bash
git clone https://github.com/datasnakes/OrthoEvolution.git
cd OrthoEvolution
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .
```

### Install for development

```bash
git clone https://github.com/datasnakes/OrthoEvolution.git
cd OrthoEvolution
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
```

## Usage

### Run a preconfigured local BLAST workflow

```python
from OrthoEvol.Orthologs.Blast import OrthoBlastN

gpcr_blastn = OrthoBlastN(
    project="orthology-gpcr",
    method=1,
    save_data=True,
    acc_file="gpcr.csv",
    copy_from_package=True,
)
gpcr_blastn.run()
```

This workflow requires a compatible local BLAST installation and database.

### Create a comparative-genetics project

```python
from OrthoEvol.Manager.management import ProjectManagement

project_manager = ProjectManagement(
    repo="test-repo",
    user=None,
    project="test-project",
    research=None,
    research_type="comparative_genetics",
    new_project=True,
)
```

### Download an NCBI BLAST database

```python
from pathlib import Path

from OrthoEvol.Tools.ftp import NcbiFTPClient

ncbi_ftp = NcbiFTPClient(email="researcher@example.org")
ncbi_ftp.getblastdb(
    database_name="refseq_rna",
    download_path=Path("databases"),
    v5=True,
)
```

NCBI database downloads require network access and can use substantial disk
space. Choose the destination and database deliberately before starting a
transfer.

## Documentation and Examples

- Read the
  [OrthoEvolution documentation](https://orthoevolution.readthedocs.io/en/latest/)
  for module and API details.
- Browse the [examples](examples/) for scripts, example data, and interface
  prototypes.
- Report problems or request enhancements through
  [GitHub Issues](https://github.com/datasnakes/OrthoEvolution/issues).

## Testing

Install the development dependencies and run the test suite through the active
virtual environment:

```bash
python -m pip install -e ".[test]"
python -m pytest tests/
```

The continuous-integration workflow runs the suite on Python 3.11 and 3.12.

## Contributing

Contributions are welcome. Create a focused branch, include tests and
documentation where appropriate, and review the
[contributing guidelines](CONTRIBUTING.rst) before opening a pull request.

## Citation

If you use OrthoEvolution in research, please cite the software:

> Gilmore, R., & Hutchins, S. D. (2026). *OrthoEvolution* (Version 1.0.0)
> [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17796234

OrthoEvolution builds on the work of the Biopython community. We thank its
developers and contributors and ask users to cite Biopython when it supports
their analyses:

> Cock, P. J. A., et al. (2009). Biopython: Freely available Python tools for
> computational molecular biology and bioinformatics. *Bioinformatics*,
> 25(11), 1422–1423. https://doi.org/10.1093/bioinformatics/btp163

## License

OrthoEvolution is distributed under the [MIT License](LICENSE).

## Authors

OrthoEvolution was created and is maintained by the Datasnakes:

- [Rob Gilmore](https://github.com/grabear)
- [Shaurita D. Hutchins](https://github.com/sdhutchins)
