Metadata-Version: 2.4
Name: bioseqkits
Version: 0.1.0
Summary: Lightweight Python toolkit for FASTA/FASTQ parsing and bioinformatics sequence analysis.
Author: Ouyang Qinglang, Lin Yushu, Liu Yijun
Author-email: Ouyang Qinglang <ouyang725@sjtu.edu.cn>, Lin Yushu <benzi0228@sjtu.edu.cn>, Liu Yijun <liu_yijun@sjtu.edu.cn>
License: MIT
Project-URL: Homepage, https://github.com/Neuromancer-P/bioseqkits
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: notebook
Requires-Dist: matplotlib>=3.5; extra == "notebook"
Requires-Dist: seaborn>=0.11; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Dynamic: author
Dynamic: requires-python

# bioseqkits

A lightweight modular Python toolkit for FASTA/FASTQ parsing and sequence analysis, implemented from scratch with pure Python.

## Project Overview

`bioseqkits` is a teaching-oriented toolkit that recreates core FASTA/FASTQ parsing and sequence analysis logic without relying on `Bio.SeqIO` or other sequence parsing libraries. It uses Python generators to parse sequence files in a streaming fashion, supports plain and gzip-compressed input, and exposes common bioinformatics operations through both a Python API and a command-line interface.

This repository currently includes:
- `src/bioseqkits/` package with parser, sequence model, operations, stats, and CLI modules
- pytest-based unit tests under `tests/`
- Jupyter notebooks for interactive sequence analysis and validation

## Key Features

### 1. FASTA / FASTQ Parsing
- Pure Python parser for FASTA and FASTQ files
- Supports both plain and gzip-compressed files
- Generator-based streaming parsing for low memory usage
- Handles multi-line sequences, blank lines, and common FASTQ formatting edge cases

### 2. Sequence Operations
- `reverse_complement` for DNA reverse complement computation
- `dna_to_rna` and `rna_to_dna` conversion
- `translate` for frame-specific translation
- `six_frame_translation` for all six reading frames
- `kmer_frequency` and `top_k_kmers` for k-mer analysis

### 3. Sequence Statistics
- Per-record sequence length
- GC content calculation
- N base ratio calculation
- Base composition percentages for A/C/G/T/N
- Convenience functions like `calculate_sequence_stats`

### 4. Command-Line Interface (CLI)
Supported subcommands:
- `stats` — sequence statistics table output
- `revcomp` — reverse complement sequence generation
- `translate` — protein translation of input sequences

### 5. Testing and Notebooks
- `pytest` test suite for parser and algorithm edge cases
- Notebook examples for FASTA analysis and validation
- Current notebook file: `analysis_sequence_fasta.ipynb`

## Installation

### Clone repository
```bash
git clone https://github.com/Neuromancer-P/bioseqkit.git
cd bioseqkit
```

### Install package
```bash
pip install .
```

### Install development dependencies
```bash
pip install -e .[dev]
```

## Quick Start

### Python API example
```python
from bioseqkits.parser import parse_fasta
from bioseqkits.operations import reverse_complement, dna_to_rna
from bioseqkits.stats import calculate_sequence_stats

with open('tests/data/sequence.fasta') as fh:
    for record in parse_fasta(fh):
        stats = calculate_sequence_stats(record)
        rc = reverse_complement(record.seq)
        rna = dna_to_rna(record.seq)
        print(record.id, stats['length'], stats['gc_content'], rc[:20], rna[:20])
```

### Run CLI commands
```bash
bioseqkits stats tests/data/sequence.fasta
bioseqkits revcomp tests/data/sequence.fasta -o output_revcomp.fasta
bioseqkits translate tests/data/sequence.fasta --frame 0
```

### Run tests
```bash
pytest tests/ -v
```

## Project Structure

```
src/bioseqkits/
├── cli.py
├── models.py
├── operations.py
├── parser.py
├── stats.py
├── utils.py
├── __init__.py
tests/
├── __init__.py
├── conftest.py
├── test_bioseqkit.py
├── data/
│   └── sequence.fasta
analysis_sequence_fasta.ipynb
bioseqkit_test.ipynb
pyproject.toml
README.md
setup.py
```

## Packaging

This project is configured with `pyproject.toml` and uses `setuptools` for packaging. The package exposes a console script named `bioseqkits` that points to `bioseqkits.cli:main`.

## License

MIT License
