Metadata-Version: 2.4
Name: seqsplit
Version: 0.1.0
Summary: Splits DNA sequences at optimal ligation sites for synthesis
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.7; extra == "analysis"
Requires-Dist: statsmodels>=0.14; extra == "analysis"
Requires-Dist: scipy>=1.10; extra == "analysis"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# seqsplit

**Splitting DNA sequences at optimal ligation sites for synthesis.**

`seqsplit` takes a set of long sequences and splits them into fragments by
selecting overhang positions that maximize assembly fidelity. These overhangs
are selected using a beam search guided by an empirical ligation frequency
table (e.g. from Potapov *et al.*, 2018).

---

## Installation

```bash
pip install seqsplit
```

**Requirements:** Python ≥ 3.10, NumPy ≥ 1.24, pandas ≥ 2.0.

---

## Quick start

### Command line

```bash
# Beam search guided by greedy heuristic (fast, good default)
seqsplit my_sequences.fna --table potapov2018_T4_18h_25C

# Beam search guided by rollout-based heuristic (slower, generally not recommended)
seqsplit my_sequences.fna --table potapov2018_T4_18h_25C \
    --mode rollout --rollout-samples 50

# More pessimistic rollout heuristic (take fidelity at 98th percentile of rollout sample instead of max)
seqsplit my_sequences.fna --table potapov2018_T4_18h_25C \
    --mode rollout --rollout-samples 100 --heuristic-percentile 98

# Input custom ligation table (see docs/ligation_freq_table_format.md for formatting)
seqsplit my_sequences.fna --table-path my_conditions.csv

# List bundled ligation frequency tables
seqsplit --list-tables
```

Results are written to `my_sequences.seqsplit_results.csv` by default (use `-o`
to change).

---

## Parameters

| CLI flag | API argument | Default | Description |
|---|---|---|---|
| *(positional)* | `fna_path` | — | Input FASTA / FNA file of sequences to split |
| `--table NAME` | — | — | Bundled ligation table name |
| `--table-path CSV` | `table` | — | Custom ligation table CSV |
| `--max-oligo-len` | `max_oligo_len` | 250 | Max oligo/fragment length (nt) |
| `--region-len` | `region_len` | 20 | Candidate overhang region width (nt) |
| `--overhang-len` | `overhang_len` | 4 | Overhang length (nt); must match selected/provided ligation frequencies table |
| `--beam-width` | `beam_width` | 100 | Beam width for the search |
| `--seed` | `seed` | 42 | Random seed |
| `--mode` | `mode` | `greedy` | `greedy` or `rollout` |
| `--rollout-samples` | `rollout_samples` | 100 | Number of random path completions per candidate (rollout mode only) |
| `--heuristic-percentile` | `heuristic_percentile` | 100 | Percentile of rollout fidelity scores to use as heuristic (rollout mode only) |

### Search modes

**`greedy`** (default)
Each candidate prefix is scored by the fidelity of its overhangs alone.
There is no lookahead component.

**`rollout`**
Each candidate prefix is randomly extended to a complete path
`--rollout-samples` times; the heuristic score is the maximum (or N-th
percentile) of those complete-path fidelities.

### Output CSV columns

| Column | Description |
|--------|-------------|
| `seq_header` | FASTA header |
| `seq_len_nt` | Sequence length (nt) |
| `num_fragments` | Number of fragments produced |
| `best_log_fidelity` | Log of assembly fidelity |
| `best_fidelity` | Assembly fidelity (0–1) |
| `overhangs` | List of selected overhang sequences |
| `overhang_start_coords` | List of 0-indexed overhang start positions |
| `runtime_s` | Wall-clock time per sequence (seconds) |

---

## Citation

If you use the bundled ligation frequency data from Potapov *et al.*, please cite:

> Potapov V, *et al.* (2018). Comprehensive Profiling of Four Base Overhang
> Ligation Fidelity by T4 DNA Ligase and Application to DNA Assembly.
> *ACS Synthetic Biology*, 7(11), 2665–2674.
> https://doi.org/10.1021/acssynbio.8b00333
