seqsplit 0.1.0__tar.gz

seqsplit-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+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

seqsplit-0.1.0/README.md

@@ -0,0 +1,99 @@
+# 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

seqsplit-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seqsplit"
+version = "0.1.0"
+description = "Splits DNA sequences at optimal ligation sites for synthesis"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+]
+
+[project.optional-dependencies]
+# For extended analysis / plotting utilities
+analysis = [
+    "matplotlib>=3.7",
+    "statsmodels>=0.14",
+    "scipy>=1.10",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[project.scripts]
+seqsplit = "seqsplit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.setuptools.package-data]
+"seqsplit.data" = ["*.csv"]

seqsplit-0.1.0/seqsplit/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("seq-splitter")
+except PackageNotFoundError:
+    __version__ = "0.1.0-dev"
+
+from .api import split_fna
+
+__all__ = ["split_fna", "__version__"]

seqsplit-0.1.0/seqsplit/api.py

@@ -0,0 +1,133 @@
+"""
+Python API for seqsplit.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .tables import LigationTable
+from .sequence import get_all_possible_idx_matrices
+from .search import run_beam_search
+
+
+def split_fna(
+    fna_path: str,
+    table: LigationTable,
+    *,
+    max_oligo_len: int = 250,
+    region_len: int = 20,
+    overhang_len: int = 4,
+    beam_width: int = 100,
+    mode: str = "greedy",
+    rollout_samples: int = 100,
+    heuristic_percentile: float = 100.0,
+    seed: int = 42,
+    verbose: bool = True,
+) -> list[dict[str, Any]]:
+    """
+    Split all sequences in a FASTA/FNA file at optimal ligation sites.
+
+    Parameters
+    ----------
+    fna_path : str
+        Path to input FASTA/FNA file.
+    table : LigationTable
+        Loaded ligation frequency table. Obtain via
+        :func:`~seqsplit.tables.load_ligation_table` or
+        :func:`~seqsplit.tables.load_builtin_table`.
+    max_oligo_len : int
+        Maximum allowed oligo/fragment length in nt.
+    region_len : int
+        Width of each candidate overhang region.
+        ``region_len - overhang_len + 1`` candidate overhangs are evaluated
+        per region.
+    overhang_len : int
+        Overhang length in nt. Must match the ligation table.
+    beam_width : int
+        Number of partial paths kept alive in the beam.
+    mode : {'greedy', 'rollout'}
+        'greedy' scores by current-prefix fidelity only (fast, recommended).
+        'rollout' uses random completions as a lookahead heuristic.
+    rollout_samples : int
+        Number of random rollouts used to evaluate each candidate (rollout
+        mode only).
+    heuristic_percentile : float
+        Percentile of rollout scores used as the heuristic to guide the search.
+        100 → max (default), 98 → more pessimistic heuristic, etc.
+    seed : ints
+        NumPy random seed for reproducibility.
+    verbose : bool
+        Print per-sequence progress.
+
+    Returns
+    -------
+    list of dicts with keys:
+        * ``header``           – header string of sequence from FASTA/FNA
+        * ``seq_len``          – sequence length in nt
+        * ``num_fragments``    – number of fragments produced
+        * ``overhangs``        – list of overhang DNA strings
+        * ``oh_row_indices``   – list of ligation-table row indices
+        * ``oh_start_coords``  – list of 0-indexed overhang start positions
+        * ``log_fidelity``     – best log-fidelity
+        * ``fidelity``         – best fidelity (exp of log_fidelity)
+        * ``runtime_s``        – wall-clock time for this sequence
+    """
+    if mode not in ("greedy", "rollout"):
+        raise ValueError(f"mode must be 'greedy' or 'rollout', got '{mode}'.")
+    if overhang_len != table.overhang_len:
+        raise ValueError(
+            f"overhang_len={overhang_len} does not match the loaded table "
+            f"(table.overhang_len={table.overhang_len})."
+        )
+
+    branching_factor = region_len - overhang_len + 1
+    n_rollouts = rollout_samples if mode == "rollout" else 0
+    rng = np.random.default_rng(seed)
+
+    all_matrices = get_all_possible_idx_matrices(
+        fna_path,
+        table.kmer_enc_to_row_idx,
+        oh_region_len=region_len,
+        overhang_len=overhang_len,
+        max_oligo_len=max_oligo_len,
+    )
+
+    results = []
+    for header, (mtrx, region_starts, seq_len) in all_matrices.items():
+        oh_list, log_fid, runtime, oh_coords = run_beam_search(
+            possible_idx_matrix=mtrx,
+            branching_factor=branching_factor,
+            total_num_regions=mtrx.shape[0],
+            beam_width=beam_width,
+            rollout_samples=n_rollouts,
+            region_starts=region_starts,
+            rng=rng,
+            table=table,
+            overhang_len=overhang_len,
+            heuristic_percentile=heuristic_percentile,
+            verbose=verbose,
+        )
+
+        if oh_list is None:
+            results.append({"header": header, "error": "no solution found"})
+            continue
+
+        oh_strings = [table.row_overhangs[idx] for idx in oh_list]
+        results.append(
+            {
+                "header": header,
+                "seq_len": seq_len,
+                "num_fragments": len(oh_strings) + 1,
+                "overhangs": oh_strings,
+                "oh_row_indices": oh_list,
+                "oh_start_coords": oh_coords,
+                "log_fidelity": float(log_fid),
+                "fidelity": float(np.exp(log_fid)),
+                "runtime_s": float(runtime),
+            }
+        )
+
+    return results