Metadata-Version: 2.4
Name: zehramsa
Version: 1.0.2
Summary: Multiple Sequence Alignment via Dynamic Programming
Requires-Python: >=3.9
Description-Content-Type: text/markdown

**Dil / Language:** [🇹🇷 Türkçe](#türkçe) · [🇬🇧 English](#english)

---

<a name="türkçe"></a>

# zehramsa — Çoklu Dizi Hizalama Kütüphanesi

zehramsa, Needleman-Wunsch dinamik programlama algoritması, Center Star Alignment ve k boyutlu saf DP yaklaşımını kullanarak birden fazla DNA dizisini hizalayan, saf Python ile yazılmış bir kütüphanedir. Harici bağımlılık gerektirmez; pip ile kurulabilir.

---

## Teknolojiler

- **Python 3.9+**
- **Needleman-Wunsch** — global pairwise hizalama (dinamik programlama)
- **Center Star Alignment** — çoklu dizi birleştirme stratejisi
- **k Boyutlu DP MSA** — optimal Sum-of-Pairs garantili çoklu hizalama
- **pyproject.toml** — pip kurulum desteği

---

## Özellikler

- İkili dizi hizalama (Needleman-Wunsch DP)
- 3+ dizi için Center Star tabanlı MSA
- 3+ dizi için k boyutlu saf DP tabanlı optimal MSA
- Özelleştirilebilir puanlama (match / mismatch / gap)
- Hizalama skoru ve kimlik yüzdesi hesaplama
- Tip ve girdi doğrulama ile açık hata mesajları

---

## Kurulum

```bash
pip install zehramsa
```

---

## Kullanım

### Center Star ile hizalama
```python
from zehramsa import align, SimpleScoring

result = align(["GATTACA", "GCATGCU", "GAGTACA"])
print(result)

result = align(["ACGT", "ACCT", "AGGT"], scoring=SimpleScoring(match=2.0, mismatch=-1.0, gap=-2.0))
print(result.center_sequence)
```

### k Boyutlu DP ile optimal hizalama
```python
from zehramsa import dp_align

result = dp_align(["GAT", "GCT", "GTT"])
print(result)

result = dp_align(["ACGT", "AGT", "ACT"], scoring=SimpleScoring(match=2.0, mismatch=-1.0, gap=-2.0))
print(result.score)
```

---

## Algoritmalar

| Fonksiyon | Yöntem | Karmaşıklık | Optimal |
|---|---|---|---|
| `align()` | Center Star + NW | O(k·n²) | ❌ yaklaşık |
| `dp_align()` | k boyutlu DP | O(nᵏ·2ᵏ) | ✅ garantili |

---

## Süreç

Proje, dinamik programlama ile çoklu dizi hizalamasının sıfırdan uygulanmasına odaklanır. Önce Needleman-Wunsch algoritması ayrı bir modül olarak kuruldu; ardından 3+ dizi için Center Star stratejisi entegre edildi. Son olarak k boyutlu saf DP tabanlı optimal MSA eklendi. Tüm çiftler için NW tek seferde çalıştırılıp cache'lenerek gereksiz hesaplama tekrarı engellendi.

---

---

<a name="english"></a>

# zehramsa — Multiple Sequence Alignment Library

zehramsa is a pure Python library that aligns multiple DNA sequences using the Needleman-Wunsch dynamic programming algorithm, Center Star Alignment, and k-dimensional pure DP approach. No external dependencies required; installable via pip.

---

## Technologies

- **Python 3.9+**
- **Needleman-Wunsch** — global pairwise alignment (dynamic programming)
- **Center Star Alignment** — multi-sequence merging strategy
- **k-Dimensional DP MSA** — optimal Sum-of-Pairs guaranteed alignment
- **pyproject.toml** — pip installation support

---

## Features

- Pairwise sequence alignment (Needleman-Wunsch DP)
- MSA for 3+ sequences via Center Star approach
- MSA for 3+ sequences via k-dimensional pure DP (optimal)
- Customizable scoring (match / mismatch / gap)
- Alignment score and identity percentage calculation
- Type and input validation with clear error messages

---

## Installation

```bash
pip install zehramsa
```

---

## Usage

### Align with Center Star
```python
from zehramsa import align, SimpleScoring

result = align(["GATTACA", "GCATGCU", "GAGTACA"])
print(result)

result = align(["ACGT", "ACCT", "AGGT"], scoring=SimpleScoring(match=2.0, mismatch=-1.0, gap=-2.0))
print(result.center_sequence)
```

### Align with k-dimensional DP (optimal)
```python
from zehramsa import dp_align

result = dp_align(["GAT", "GCT", "GTT"])
print(result)

result = dp_align(["ACGT", "AGT", "ACT"], scoring=SimpleScoring(match=2.0, mismatch=-1.0, gap=-2.0))
print(result.score)
```

---

## Algorithms

| Function | Method | Complexity | Optimal |
|---|---|---|---|
| `align()` | Center Star + NW | O(k·n²) | ❌ approximate |
| `dp_align()` | k-dimensional DP | O(nᵏ·2ᵏ) | ✅ guaranteed |

---

## The Process

The project focuses on implementing multiple sequence alignment from scratch using dynamic programming. Needleman-Wunsch was built as a standalone module first; Center Star strategy was then integrated for 3+ sequences. Finally, k-dimensional pure DP based optimal MSA was added. All pairwise NW results are computed once and cached to eliminate redundant computation.
