seqsplit 0.1.0

Splits DNA sequences at optimal ligation sites for synthesis

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

pip install seqsplit

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

---

Quick start

Command line

# 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