https://github.com/bibymaths/bio-sea-pearl
Sequence analysis and bioinformatics utilities in Python and Perl.
https://github.com/bibymaths/bio-sea-pearl
Last synced: 2 months ago
JSON representation
Sequence analysis and bioinformatics utilities in Python and Perl.
- Host: GitHub
- URL: https://github.com/bibymaths/bio-sea-pearl
- Owner: bibymaths
- License: mit
- Created: 2025-05-26T11:17:28.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-31T00:46:19.000Z (2 months ago)
- Last Synced: 2026-03-31T04:21:32.689Z (2 months ago)
- Language: Python
- Homepage: https://bibymaths.github.io/bio-sea-pearl/
- Size: 840 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
[](https://doi.org/10.5281/zenodo.19435099)
[](https://pypi.org/project/bio-sea-pearl/)
[](https://pypi.org/project/bio-sea-pearl/)
[](https://pypi.org/project/bio-sea-pearl/)
[](https://github.com/bibymaths/bio-sea-pearl/releases)
[](https://bibymaths.github.io/bio-sea-pearl/)
[](LICENSE)
[](https://github.com/bibymaths/bio-sea-pearl/actions/workflows/release.yml)
[](https://github.com/bibymaths/bio-sea-pearl/actions/workflows/docs.yml)
[](https://github.com/bibymaths/bio-sea-pearl/pkgs/container/bio-sea-pearl)
[](https://github.com/bibymaths/bio-sea-pearl/pkgs/container/bio-sea-pearl)
***
A hybrid **Python + Perl bioinformatics toolkit** for sequence alignment, Markov modeling, sequence analysis, and FM-index-based search — unified under a single Python CLI and API.
***
[Read Documentation](https://bibymaths.github.io/bio-sea-pearl/)
***
## Quick Start
Requires **Python >= 3.10** and optionally **Perl >= 5.26** (for alignment and Markov features).
### 1. Install
```bash
git clone https://github.com/bibymaths/bio-sea-pearl.git
cd bio-sea-pearl
uv pip install -e ".[dev]" # or: pip install -e ".[dev]"
```
### 2. Run
```bash
biosea --help
```
***
## CLI Usage
### Alignment
```bash
biosea align seq1.fa seq2.fa --matrix alignment/scoring/blosum62.mat --mode global
```
> Matrix filenames are case-sensitive (`blosum62.mat`, not `BLOSUM62.mat`). For a dotplot: `perl alignment/bin/dotplot.pl align.matrix.tsv dotplot.svg`
### Markov Chain
```bash
biosea markov --fasta seq1.fa --length 100 --start A --order 1 --method alias
```
> `--start` length must equal `--order` (e.g. `--order 2 --start AA`)
### Sequence Utilities
```bash
biosea seqtools hamming ACGT AGGT
biosea seqtools levenshtein kitten sitting
biosea seqtools kmer ACGTACGT --k 3
```
### BWT / FM-Index
```bash
biosea bwt search --sequence ACGTACGT --pattern CGT
```
***
## REST API
```bash
uvicorn api.server:app --reload
```
Endpoints: `POST /align`, `/markov`, `/distance`, `/kmer`, `/bwt/search`. Interactive docs at [http://localhost:8000/docs](http://localhost:8000/docs).
```bash
curl -X POST http://localhost:8000/distance \
-H "Content-Type: application/json" \
-d '{"seq1": "kitten", "seq2": "sitting", "metric": "levenshtein"}'
```
***
## Docker
```bash
./docker_up.sh # Build and start
./docker_down.sh # Stop and remove
./docker_interactive.sh # Interactive shell
```
***
## Project Structure
```
src/bio_sea_pearl/
├── cli.py # Unified CLI
├── api/ # Python API layer
├── perl_wrappers/ # Perl subprocess bridge
├── seqtools_py/ # Python algorithm ports
└── bwt/ # FM-index (pure Python)
alignment/ markov/ seqtools/ api/server.py docs/ tests/
```
The layered architecture (`CLI/API → Python layer → subprocess wrappers → Perl/Python tools`) preserves legacy code while enabling gradual migration.
***
## Build, Test & Release
```bash
pytest # Run tests
python -m build # Build wheel + sdist into dist/
git tag v0.1.0 && git push origin v0.1.0 # Trigger release CI
```
Pushing a tag runs tests, creates a GitHub release, publishes to PyPI, and pushes multi-arch Docker images to `ghcr.io/bibymaths/bio-sea-pearl`.
***
## Troubleshooting
- **Alignment fails:** verify matrix path (`alignment/scoring/blosum62.mat`) and use lowercase filenames.
- **Markov fails** (`Start state must be length N`): ensure `--start` string length equals `--order`.
- **CLI not found:** run `pip install -e .` then retry.
***
## License
[MIT License](LICENSE)
***