splicecraft 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- splicecraft-0.2.0/.gitignore +19 -0
- splicecraft-0.2.0/CHANGELOG.md +76 -0
- splicecraft-0.2.0/LICENSE +21 -0
- splicecraft-0.2.0/PKG-INFO +310 -0
- splicecraft-0.2.0/README.md +255 -0
- splicecraft-0.2.0/pyproject.toml +76 -0
- splicecraft-0.2.0/screenshot.jpg +0 -0
- splicecraft-0.2.0/splicecraft.py +7090 -0
- splicecraft-0.2.0/tests/__init__.py +0 -0
- splicecraft-0.2.0/tests/conftest.py +131 -0
- splicecraft-0.2.0/tests/test_circular_math.py +144 -0
- splicecraft-0.2.0/tests/test_data_safety.py +327 -0
- splicecraft-0.2.0/tests/test_dna_sanity.py +477 -0
- splicecraft-0.2.0/tests/test_domesticator.py +248 -0
- splicecraft-0.2.0/tests/test_genbank_io.py +150 -0
- splicecraft-0.2.0/tests/test_performance.py +256 -0
- splicecraft-0.2.0/tests/test_plannotate.py +401 -0
- splicecraft-0.2.0/tests/test_primers.py +238 -0
- splicecraft-0.2.0/tests/test_smoke.py +747 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# pytest
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
|
|
9
|
+
# User-local runtime data (library is user-specific; seeded on first run)
|
|
10
|
+
plasmid_library.json
|
|
11
|
+
parts_bin.json
|
|
12
|
+
primers.json
|
|
13
|
+
*.json.bak
|
|
14
|
+
|
|
15
|
+
# Editor / OS
|
|
16
|
+
.vscode/
|
|
17
|
+
.idea/
|
|
18
|
+
*.swp
|
|
19
|
+
.DS_Store
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# SpliceCraft Changelog
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Feature deletion** — press `Delete` to remove the selected feature (annotation only,
|
|
10
|
+
sequence is untouched); fully undo/redo-able with `Ctrl+Z` / `Ctrl+Shift+Z`.
|
|
11
|
+
|
|
12
|
+
- **Toggleable linear map view** — press `v` to switch the circular map panel between
|
|
13
|
+
circular and horizontal linear views. Linear view uses the same braille-pixel rendering
|
|
14
|
+
with per-strand feature bars, arrowheads, lane stacking, and feature labels.
|
|
15
|
+
|
|
16
|
+
- **Strand-aware DNA sequence panel layout** — forward-strand features always appear
|
|
17
|
+
*above* the DNA sequence line; reverse-strand features always appear *below*, making
|
|
18
|
+
strand identity immediately apparent. Overlapping features on the same strand stack
|
|
19
|
+
into additional lanes on their respective side.
|
|
20
|
+
|
|
21
|
+
- **Braille feature bars in sequence panel** — annotation bars now use solid braille
|
|
22
|
+
block characters (`⣿`) matching the aesthetic of the map viewer, with `▶`/`◀`
|
|
23
|
+
arrowheads at the true start/end of each feature.
|
|
24
|
+
|
|
25
|
+
- **Single-bp feature triangles** — features that are one base-pair wide render as `▼`
|
|
26
|
+
(above DNA) or `▲` (below DNA), pointing inward toward the sequence line.
|
|
27
|
+
|
|
28
|
+
- **Label-above / label-below layout** — feature names appear outside the bar (above the
|
|
29
|
+
bar for forward features, below for reverse), keeping the braille bar itself clean.
|
|
30
|
+
Multiple non-overlapping features share a single horizontal row pair.
|
|
31
|
+
|
|
32
|
+
- **Feature connector lines** (`l` key toggle) — draws a `┊` connector between each
|
|
33
|
+
feature label and its braille bar in the sequence panel, and a dotted radial leader
|
|
34
|
+
line from the arc to the label in the circular map. Both panels respond to the same
|
|
35
|
+
toggle.
|
|
36
|
+
|
|
37
|
+
- **Full NEB restriction enzyme catalog** — ~200 enzymes from New England Biolabs,
|
|
38
|
+
including Type IIS (BsaI, BsmBI, BbsI, …) with non-palindromic cut sites. Each hit
|
|
39
|
+
is visualized as two distinct overlays:
|
|
40
|
+
- **Recognition sequence bar** (`resite`) — thin braille arc outside the backbone for
|
|
41
|
+
forward-strand hits, inside for reverse-strand hits; same strand-above/below layout
|
|
42
|
+
in the sequence panel.
|
|
43
|
+
- **Cut site marker** (`recut`) — `↓` (forward) or `↑` (reverse) arrow in the
|
|
44
|
+
sequence panel; radial `┼` tick on the circular and linear map at the exact cut
|
|
45
|
+
position. Type IIS cut sites appear displaced from the recognition sequence as
|
|
46
|
+
expected.
|
|
47
|
+
- Recognition sequence IUPAC codes (R, Y, W, S, M, K, B, D, H, V, N) are handled
|
|
48
|
+
via regex; both strands are scanned. Enzyme labels appear in the circular map
|
|
49
|
+
alongside regular feature labels using the same proximity placement algorithm.
|
|
50
|
+
|
|
51
|
+
- **Circular map: inside tick marks** — bp graduation marks and labels now sit *inside*
|
|
52
|
+
the backbone ring rather than outside, keeping the outer ring clean for feature labels.
|
|
53
|
+
Two constants (`TICK_DR_MARK`, `TICK_DR_LABEL`) control the inset depth and scale
|
|
54
|
+
automatically with the `,` / `.` aspect-ratio keys.
|
|
55
|
+
|
|
56
|
+
- **Circular map: full-length feature labels** — removed the 16-character truncation;
|
|
57
|
+
labels now display their full name.
|
|
58
|
+
|
|
59
|
+
- **Circular map: proximity label placement** — labels are placed as close to the arc as
|
|
60
|
+
possible, greedy-stepping radially outward only when a label would overlap an
|
|
61
|
+
already-placed one. `LABEL_DR_MIN` (default `9`) sets the minimum clearance.
|
|
62
|
+
|
|
63
|
+
- **Default library entry** — MW463917.1 (pACYC184) is fetched and added to the library
|
|
64
|
+
automatically on first launch. The NCBI fetch dialog pre-fills with this accession.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## [0.1.0] — 2026-03-23
|
|
69
|
+
|
|
70
|
+
### Added
|
|
71
|
+
|
|
72
|
+
- Initial release: braille-canvas circular plasmid map, NCBI live fetch, local `.gb`
|
|
73
|
+
file loading, persistent plasmid library, feature sidebar with CDS translation,
|
|
74
|
+
sequence panel with click-to-cursor, drag selection, undo/redo, and restriction-site
|
|
75
|
+
overlay.
|
|
76
|
+
- ASCII logo and README.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Binomica Labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: splicecraft
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Terminal-based circular plasmid map viewer, sequence editor, and Primer3/Golden Braid primer design workbench
|
|
5
|
+
Project-URL: Homepage, https://github.com/Binomica-Labs/SpliceCraft
|
|
6
|
+
Project-URL: Repository, https://github.com/Binomica-Labs/SpliceCraft
|
|
7
|
+
Project-URL: Issues, https://github.com/Binomica-Labs/SpliceCraft/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/Binomica-Labs/SpliceCraft/blob/master/CHANGELOG.md
|
|
9
|
+
Author: Binomica Labs
|
|
10
|
+
License: MIT License
|
|
11
|
+
|
|
12
|
+
Copyright (c) 2026 Binomica Labs
|
|
13
|
+
|
|
14
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
15
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
16
|
+
in the Software without restriction, including without limitation the rights
|
|
17
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
18
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
19
|
+
furnished to do so, subject to the following conditions:
|
|
20
|
+
|
|
21
|
+
The above copyright notice and this permission notice shall be included in all
|
|
22
|
+
copies or substantial portions of the Software.
|
|
23
|
+
|
|
24
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
25
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
26
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
27
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
28
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
29
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
30
|
+
SOFTWARE.
|
|
31
|
+
License-File: LICENSE
|
|
32
|
+
Keywords: bioinformatics,cloning,genbank,golden-braid,molecular-biology,plasmid,primer3,terminal,tui
|
|
33
|
+
Classifier: Development Status :: 4 - Beta
|
|
34
|
+
Classifier: Environment :: Console
|
|
35
|
+
Classifier: Intended Audience :: Science/Research
|
|
36
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
37
|
+
Classifier: Operating System :: OS Independent
|
|
38
|
+
Classifier: Programming Language :: Python :: 3
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
42
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
43
|
+
Classifier: Topic :: Terminals
|
|
44
|
+
Requires-Python: >=3.10
|
|
45
|
+
Requires-Dist: biopython>=1.87
|
|
46
|
+
Requires-Dist: platformdirs>=4.2
|
|
47
|
+
Requires-Dist: primer3-py>=2.3.0
|
|
48
|
+
Requires-Dist: textual>=8.2.3
|
|
49
|
+
Provides-Extra: dev
|
|
50
|
+
Requires-Dist: build; extra == 'dev'
|
|
51
|
+
Requires-Dist: pytest-asyncio>=1.3; extra == 'dev'
|
|
52
|
+
Requires-Dist: pytest>=9.0; extra == 'dev'
|
|
53
|
+
Requires-Dist: twine; extra == 'dev'
|
|
54
|
+
Description-Content-Type: text/markdown
|
|
55
|
+
|
|
56
|
+
# SpliceCraft
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
╔═══════════════════════════════════════════════════════════════════════════════╗
|
|
60
|
+
║ ⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶ ║
|
|
61
|
+
║ ║
|
|
62
|
+
║ ________ __________ _________ ____________ ║
|
|
63
|
+
║ __ ___/__________ /__(_)____________ ____/____________ ___ __/_ /_ ║
|
|
64
|
+
║ _____ \___ __ \_ /__ /_ ___/ _ \ / __ ___/ __ `/_ /_ _ __/ ║
|
|
65
|
+
║ ____/ /__ /_/ / / _ / / /__ / __/ /___ _ / / /_/ /_ __/ / /_ ║
|
|
66
|
+
║ /____/ _ .___//_/ /_/ \___/ \___/\____/ /_/ \__,_/ /_/ \__/ ║
|
|
67
|
+
║ /_/ ║
|
|
68
|
+
║ ║
|
|
69
|
+
║ · I n - T e r m i n a l P l a s m i d W o r k b e n c h · ║
|
|
70
|
+
║ ║
|
|
71
|
+
║ ⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶ ║
|
|
72
|
+
╚═══════════════════════════════════════════════════════════════════════════════╝
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
A terminal-based circular plasmid map viewer, sequence editor, **primer design
|
|
78
|
+
workbench**, and **Golden Braid parts domesticator** — rendered entirely in your
|
|
79
|
+
shell. Fetch any GenBank record by accession, load local files, annotate features
|
|
80
|
+
with pLannotate, design diagnostic / cloning / Golden Braid primers with Primer3,
|
|
81
|
+
and edit sequences — without ever leaving the terminal.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Features
|
|
86
|
+
|
|
87
|
+
### Core visualization & editing
|
|
88
|
+
- **Braille dot-matrix circular map** — plasmids rendered as crisp Unicode braille
|
|
89
|
+
rings with per-strand feature arcs, directional arrowheads, and proximity-placed
|
|
90
|
+
labels
|
|
91
|
+
- **Linear map view** — toggle with `v` for a horizontal strip layout
|
|
92
|
+
- **Dithered sequence panel** — per-base DNA viewer with feature bars, restriction
|
|
93
|
+
site overlays, and double-stranded display
|
|
94
|
+
- **Live NCBI fetch** — pull any GenBank record by accession number on demand
|
|
95
|
+
- **Local file support** — open `.gb` / `.gbk` files directly from disk
|
|
96
|
+
- **Free rotation** — spin the origin left or right with `[` / `]`
|
|
97
|
+
- **Restriction enzyme overlay** — 200+ NEB enzymes including Type IIS
|
|
98
|
+
(BsaI, BsmBI, BbsI, SapI) with visible recognition arcs + cut markers
|
|
99
|
+
|
|
100
|
+
### Libraries (all persist to JSON)
|
|
101
|
+
- **Plasmid library** — SnapGene-style collection, auto-saves on import, survives
|
|
102
|
+
restarts, supports rename and handslip-protected delete
|
|
103
|
+
- **Parts Bin** — Golden Braid L0 parts catalog with user-domesticated parts
|
|
104
|
+
including sequences and primer pairs
|
|
105
|
+
- **Primer library** — all designed primers with Tm, length, date, status
|
|
106
|
+
(Designed / Ordered / Validated), multi-select for batch operations
|
|
107
|
+
|
|
108
|
+
### Primer design (Primer3)
|
|
109
|
+
- **Detection primers** — diagnostic PCR; Primer3 picks the ideal pair within
|
|
110
|
+
a selected region, 450-550 bp product by default (configurable)
|
|
111
|
+
- **Cloning primers** — RE-site tails + GCGC padding; 30+ common enzymes or
|
|
112
|
+
type a custom recognition sequence
|
|
113
|
+
- **Golden Braid primers** — BsaI domestication for all L0 positions
|
|
114
|
+
(Promoter, 5' UTR, CDS, CDS-NS, C-tag, Terminator)
|
|
115
|
+
- **Generic primers** — simple binding primers, no tails
|
|
116
|
+
- Primers can be added to the plasmid map as `primer_bind` features
|
|
117
|
+
- Scrollable `TextArea` for custom sequence input; highlighted text = target
|
|
118
|
+
|
|
119
|
+
### Annotation
|
|
120
|
+
- **pLannotate integration** — press `Shift+A` (or use the `◈` library button)
|
|
121
|
+
to auto-annotate a plasmid against pLannotate's curated feature database.
|
|
122
|
+
Optional — see install notes below
|
|
123
|
+
|
|
124
|
+
### Feature operations
|
|
125
|
+
- **Feature sidebar** — click a row to highlight on map; click the map to
|
|
126
|
+
select the feature under the cursor
|
|
127
|
+
- **Undo/redo** — 50-deep snapshot stack for all sequence edits
|
|
128
|
+
- **Delete protection** — focus-aware Delete key; confirmation modal (default
|
|
129
|
+
focus = No) for library entries
|
|
130
|
+
- **Clipboard** — OSC-52 copy works in Windows Terminal, iTerm2, modern WSL
|
|
131
|
+
|
|
132
|
+
### Data safety
|
|
133
|
+
- **Atomic saves** — all JSON files written via tempfile + `os.replace`
|
|
134
|
+
- **Automatic backups** — every save writes `*.json.bak` before overwriting
|
|
135
|
+
- **Corrupt-file recovery** — missing files don't crash; corrupt files auto-
|
|
136
|
+
restore from `.bak` with a warning notification on startup
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Installation
|
|
141
|
+
|
|
142
|
+
Requires **Python 3.10+**.
|
|
143
|
+
|
|
144
|
+
### From PyPI (recommended)
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
pip install splicecraft
|
|
148
|
+
splicecraft # empty canvas
|
|
149
|
+
splicecraft L09137 # fetch pUC19 from NCBI
|
|
150
|
+
splicecraft myplasmid.gb # open a local GenBank file
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
All required dependencies (`textual`, `biopython`, `primer3-py`, `platformdirs`)
|
|
154
|
+
are pulled in automatically. User data (library, parts bin, primers) lives in
|
|
155
|
+
the platform-appropriate data directory:
|
|
156
|
+
|
|
157
|
+
| Platform | Path |
|
|
158
|
+
|---|---|
|
|
159
|
+
| Linux | `~/.local/share/splicecraft/` |
|
|
160
|
+
| macOS | `~/Library/Application Support/splicecraft/` |
|
|
161
|
+
| Windows | `%APPDATA%\splicecraft\` |
|
|
162
|
+
|
|
163
|
+
Override with `SPLICECRAFT_DATA_DIR=/path/to/dir splicecraft`.
|
|
164
|
+
|
|
165
|
+
### From source
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
git clone https://github.com/Binomica-Labs/SpliceCraft.git
|
|
169
|
+
cd SpliceCraft
|
|
170
|
+
pip install -e .
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Optional dependencies
|
|
174
|
+
|
|
175
|
+
**pLannotate** (for automatic plasmid annotation via `Shift+A`) — requires conda:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
conda create -n plannotate -c conda-forge -c bioconda plannotate
|
|
179
|
+
conda activate plannotate
|
|
180
|
+
plannotate setupdb # one-time ~500 MB BLAST database download
|
|
181
|
+
# then run SpliceCraft from the same conda env
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
SpliceCraft runs fine without pLannotate — the annotation feature just
|
|
185
|
+
notifies the user how to install it if pressed.
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Usage
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
# After pip install:
|
|
193
|
+
splicecraft # empty canvas
|
|
194
|
+
splicecraft L09137 # fetch pUC19 from NCBI on launch
|
|
195
|
+
splicecraft myplasmid.gb # open a local GenBank file
|
|
196
|
+
splicecraft --version # print version
|
|
197
|
+
splicecraft --help # quick usage hint
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
If running from a git clone (`pip install -e .`), the same commands work;
|
|
201
|
+
you can also still run `python3 splicecraft.py` directly.
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## Key Bindings
|
|
206
|
+
|
|
207
|
+
### Main screen
|
|
208
|
+
|
|
209
|
+
| Key | Description |
|
|
210
|
+
|----------------|----------------------------------------|
|
|
211
|
+
| `[` / `]` | Rotate map origin left / right |
|
|
212
|
+
| `Shift+[/]` | Rotate coarse (10× step) |
|
|
213
|
+
| `Home` | Reset origin to 0 |
|
|
214
|
+
| `,` / `.` | Circular map aspect wider / taller |
|
|
215
|
+
| `v` | Toggle circular ↔ linear map |
|
|
216
|
+
| `l` | Toggle feature label connector lines |
|
|
217
|
+
| `r` | Toggle restriction-site overlay |
|
|
218
|
+
| `f` | Fetch a record from NCBI by accession |
|
|
219
|
+
| `o` | Open a `.gb` file from disk |
|
|
220
|
+
| `a` | Add current plasmid to the library |
|
|
221
|
+
| `Shift+A` | Annotate plasmid with pLannotate |
|
|
222
|
+
| `Shift+E` | Enter sequence editor mode |
|
|
223
|
+
| `Shift+S` | Save edits to file |
|
|
224
|
+
| `Delete` | Context-aware delete (feature or library entry) |
|
|
225
|
+
| `Ctrl+Z` | Undo |
|
|
226
|
+
| `Ctrl+Shift+Z` | Redo |
|
|
227
|
+
| `Ctrl+C` | Copy selection to clipboard |
|
|
228
|
+
| `q` | Quit |
|
|
229
|
+
|
|
230
|
+
### Primer Design screen
|
|
231
|
+
|
|
232
|
+
| Key | Description |
|
|
233
|
+
|-------|------------------------------------------------|
|
|
234
|
+
| `esc` | Close primer screen |
|
|
235
|
+
| `m` | Mark / unmark primer under cursor (`★`) |
|
|
236
|
+
| `M` | Mark / unmark all primers |
|
|
237
|
+
| `S` | Cycle status: Designed → Ordered → Validated |
|
|
238
|
+
| `Tab` | Cycle focus between fields |
|
|
239
|
+
|
|
240
|
+
### Mouse
|
|
241
|
+
|
|
242
|
+
| Action | Description |
|
|
243
|
+
|----------------|---------------------------------------------|
|
|
244
|
+
| Click | Place cursor / select feature under pointer |
|
|
245
|
+
| Double-click | Select full feature span |
|
|
246
|
+
| Drag | Select a sequence range |
|
|
247
|
+
| Scroll wheel | Rotate map (when over map panel) |
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## Menus
|
|
252
|
+
|
|
253
|
+
| Menu | Items |
|
|
254
|
+
|------------|--------------------------------------------------------------------|
|
|
255
|
+
| File | Open .gb file · Fetch from NCBI · Add to Library · Save · Quit |
|
|
256
|
+
| Edit | Edit Sequence · Undo · Redo · Delete Feature |
|
|
257
|
+
| Enzymes | Show RE sites · Unique cutters · 6+/4+ bp sites · Connectors |
|
|
258
|
+
| Features | Add Feature · Delete Feature · Annotate with pLannotate |
|
|
259
|
+
| Primers | Opens the full-screen Primer Design workbench |
|
|
260
|
+
| Parts | Opens the Parts Bin (Golden Braid L0 parts catalog) |
|
|
261
|
+
| Constructor| Opens the Assembly Constructor for TU building |
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## Requirements
|
|
266
|
+
|
|
267
|
+
| Package | Version | Purpose |
|
|
268
|
+
|-------------------|-------------------|----------------------------------------------|
|
|
269
|
+
| Python | ≥ 3.10 | Runtime |
|
|
270
|
+
| Textual | ≥ 8.2.3 | TUI framework and rendering engine |
|
|
271
|
+
| Rich | ≥ 14.0 | Terminal rendering (Textual dependency) |
|
|
272
|
+
| Biopython | ≥ 1.87 | GenBank parsing and NCBI Entrez fetch |
|
|
273
|
+
| primer3-py | ≥ 2.3.0 | Primer design (Tm, thermodynamic screening) |
|
|
274
|
+
| pytest | ≥ 9.0 | Test suite (dev only) |
|
|
275
|
+
| pytest-asyncio | ≥ 1.3 | Async test support (dev only) |
|
|
276
|
+
| **pLannotate** | optional, conda | Automatic plasmid annotation (`Shift+A`) |
|
|
277
|
+
| **BLAST+** | optional, conda | Required by pLannotate |
|
|
278
|
+
| **Primer3 CLI** | optional, `apt` | Not used directly — primer3-py bundles it |
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## Data files
|
|
283
|
+
|
|
284
|
+
All user data persists as human-readable JSON in the repo directory:
|
|
285
|
+
|
|
286
|
+
| File | Purpose |
|
|
287
|
+
|-----------------------|---------------------------------------------|
|
|
288
|
+
| `plasmid_library.json`| Saved plasmid collection (GenBank + metadata) |
|
|
289
|
+
| `parts_bin.json` | User-domesticated Golden Braid parts |
|
|
290
|
+
| `primers.json` | Designed primer library |
|
|
291
|
+
| `*.json.bak` | Automatic backup — written before each save |
|
|
292
|
+
|
|
293
|
+
These files are in `.gitignore` — they're user-local data, not repo content.
|
|
294
|
+
A manual backup rotation happens on every save so accidental data loss is
|
|
295
|
+
always recoverable via the `.bak` file.
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Tests
|
|
300
|
+
|
|
301
|
+
```bash
|
|
302
|
+
python3 -m pytest -q # full suite (246 tests, ~45 s)
|
|
303
|
+
python3 -m pytest tests/test_dna_sanity.py # biology correctness only (< 1s)
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## License
|
|
309
|
+
|
|
310
|
+
MIT
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
# SpliceCraft
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
╔═══════════════════════════════════════════════════════════════════════════════╗
|
|
5
|
+
║ ⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶ ║
|
|
6
|
+
║ ║
|
|
7
|
+
║ ________ __________ _________ ____________ ║
|
|
8
|
+
║ __ ___/__________ /__(_)____________ ____/____________ ___ __/_ /_ ║
|
|
9
|
+
║ _____ \___ __ \_ /__ /_ ___/ _ \ / __ ___/ __ `/_ /_ _ __/ ║
|
|
10
|
+
║ ____/ /__ /_/ / / _ / / /__ / __/ /___ _ / / /_/ /_ __/ / /_ ║
|
|
11
|
+
║ /____/ _ .___//_/ /_/ \___/ \___/\____/ /_/ \__,_/ /_/ \__/ ║
|
|
12
|
+
║ /_/ ║
|
|
13
|
+
║ ║
|
|
14
|
+
║ · I n - T e r m i n a l P l a s m i d W o r k b e n c h · ║
|
|
15
|
+
║ ║
|
|
16
|
+
║ ⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶⠶ ║
|
|
17
|
+
╚═══════════════════════════════════════════════════════════════════════════════╝
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
A terminal-based circular plasmid map viewer, sequence editor, **primer design
|
|
23
|
+
workbench**, and **Golden Braid parts domesticator** — rendered entirely in your
|
|
24
|
+
shell. Fetch any GenBank record by accession, load local files, annotate features
|
|
25
|
+
with pLannotate, design diagnostic / cloning / Golden Braid primers with Primer3,
|
|
26
|
+
and edit sequences — without ever leaving the terminal.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Features
|
|
31
|
+
|
|
32
|
+
### Core visualization & editing
|
|
33
|
+
- **Braille dot-matrix circular map** — plasmids rendered as crisp Unicode braille
|
|
34
|
+
rings with per-strand feature arcs, directional arrowheads, and proximity-placed
|
|
35
|
+
labels
|
|
36
|
+
- **Linear map view** — toggle with `v` for a horizontal strip layout
|
|
37
|
+
- **Dithered sequence panel** — per-base DNA viewer with feature bars, restriction
|
|
38
|
+
site overlays, and double-stranded display
|
|
39
|
+
- **Live NCBI fetch** — pull any GenBank record by accession number on demand
|
|
40
|
+
- **Local file support** — open `.gb` / `.gbk` files directly from disk
|
|
41
|
+
- **Free rotation** — spin the origin left or right with `[` / `]`
|
|
42
|
+
- **Restriction enzyme overlay** — 200+ NEB enzymes including Type IIS
|
|
43
|
+
(BsaI, BsmBI, BbsI, SapI) with visible recognition arcs + cut markers
|
|
44
|
+
|
|
45
|
+
### Libraries (all persist to JSON)
|
|
46
|
+
- **Plasmid library** — SnapGene-style collection, auto-saves on import, survives
|
|
47
|
+
restarts, supports rename and handslip-protected delete
|
|
48
|
+
- **Parts Bin** — Golden Braid L0 parts catalog with user-domesticated parts
|
|
49
|
+
including sequences and primer pairs
|
|
50
|
+
- **Primer library** — all designed primers with Tm, length, date, status
|
|
51
|
+
(Designed / Ordered / Validated), multi-select for batch operations
|
|
52
|
+
|
|
53
|
+
### Primer design (Primer3)
|
|
54
|
+
- **Detection primers** — diagnostic PCR; Primer3 picks the ideal pair within
|
|
55
|
+
a selected region, 450-550 bp product by default (configurable)
|
|
56
|
+
- **Cloning primers** — RE-site tails + GCGC padding; 30+ common enzymes or
|
|
57
|
+
type a custom recognition sequence
|
|
58
|
+
- **Golden Braid primers** — BsaI domestication for all L0 positions
|
|
59
|
+
(Promoter, 5' UTR, CDS, CDS-NS, C-tag, Terminator)
|
|
60
|
+
- **Generic primers** — simple binding primers, no tails
|
|
61
|
+
- Primers can be added to the plasmid map as `primer_bind` features
|
|
62
|
+
- Scrollable `TextArea` for custom sequence input; highlighted text = target
|
|
63
|
+
|
|
64
|
+
### Annotation
|
|
65
|
+
- **pLannotate integration** — press `Shift+A` (or use the `◈` library button)
|
|
66
|
+
to auto-annotate a plasmid against pLannotate's curated feature database.
|
|
67
|
+
Optional — see install notes below
|
|
68
|
+
|
|
69
|
+
### Feature operations
|
|
70
|
+
- **Feature sidebar** — click a row to highlight on map; click the map to
|
|
71
|
+
select the feature under the cursor
|
|
72
|
+
- **Undo/redo** — 50-deep snapshot stack for all sequence edits
|
|
73
|
+
- **Delete protection** — focus-aware Delete key; confirmation modal (default
|
|
74
|
+
focus = No) for library entries
|
|
75
|
+
- **Clipboard** — OSC-52 copy works in Windows Terminal, iTerm2, modern WSL
|
|
76
|
+
|
|
77
|
+
### Data safety
|
|
78
|
+
- **Atomic saves** — all JSON files written via tempfile + `os.replace`
|
|
79
|
+
- **Automatic backups** — every save writes `*.json.bak` before overwriting
|
|
80
|
+
- **Corrupt-file recovery** — missing files don't crash; corrupt files auto-
|
|
81
|
+
restore from `.bak` with a warning notification on startup
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Installation
|
|
86
|
+
|
|
87
|
+
Requires **Python 3.10+**.
|
|
88
|
+
|
|
89
|
+
### From PyPI (recommended)
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pip install splicecraft
|
|
93
|
+
splicecraft # empty canvas
|
|
94
|
+
splicecraft L09137 # fetch pUC19 from NCBI
|
|
95
|
+
splicecraft myplasmid.gb # open a local GenBank file
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
All required dependencies (`textual`, `biopython`, `primer3-py`, `platformdirs`)
|
|
99
|
+
are pulled in automatically. User data (library, parts bin, primers) lives in
|
|
100
|
+
the platform-appropriate data directory:
|
|
101
|
+
|
|
102
|
+
| Platform | Path |
|
|
103
|
+
|---|---|
|
|
104
|
+
| Linux | `~/.local/share/splicecraft/` |
|
|
105
|
+
| macOS | `~/Library/Application Support/splicecraft/` |
|
|
106
|
+
| Windows | `%APPDATA%\splicecraft\` |
|
|
107
|
+
|
|
108
|
+
Override with `SPLICECRAFT_DATA_DIR=/path/to/dir splicecraft`.
|
|
109
|
+
|
|
110
|
+
### From source
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
git clone https://github.com/Binomica-Labs/SpliceCraft.git
|
|
114
|
+
cd SpliceCraft
|
|
115
|
+
pip install -e .
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Optional dependencies
|
|
119
|
+
|
|
120
|
+
**pLannotate** (for automatic plasmid annotation via `Shift+A`) — requires conda:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
conda create -n plannotate -c conda-forge -c bioconda plannotate
|
|
124
|
+
conda activate plannotate
|
|
125
|
+
plannotate setupdb # one-time ~500 MB BLAST database download
|
|
126
|
+
# then run SpliceCraft from the same conda env
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
SpliceCraft runs fine without pLannotate — the annotation feature just
|
|
130
|
+
notifies the user how to install it if pressed.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Usage
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
# After pip install:
|
|
138
|
+
splicecraft # empty canvas
|
|
139
|
+
splicecraft L09137 # fetch pUC19 from NCBI on launch
|
|
140
|
+
splicecraft myplasmid.gb # open a local GenBank file
|
|
141
|
+
splicecraft --version # print version
|
|
142
|
+
splicecraft --help # quick usage hint
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
If running from a git clone (`pip install -e .`), the same commands work;
|
|
146
|
+
you can also still run `python3 splicecraft.py` directly.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Key Bindings
|
|
151
|
+
|
|
152
|
+
### Main screen
|
|
153
|
+
|
|
154
|
+
| Key | Description |
|
|
155
|
+
|----------------|----------------------------------------|
|
|
156
|
+
| `[` / `]` | Rotate map origin left / right |
|
|
157
|
+
| `Shift+[/]` | Rotate coarse (10× step) |
|
|
158
|
+
| `Home` | Reset origin to 0 |
|
|
159
|
+
| `,` / `.` | Circular map aspect wider / taller |
|
|
160
|
+
| `v` | Toggle circular ↔ linear map |
|
|
161
|
+
| `l` | Toggle feature label connector lines |
|
|
162
|
+
| `r` | Toggle restriction-site overlay |
|
|
163
|
+
| `f` | Fetch a record from NCBI by accession |
|
|
164
|
+
| `o` | Open a `.gb` file from disk |
|
|
165
|
+
| `a` | Add current plasmid to the library |
|
|
166
|
+
| `Shift+A` | Annotate plasmid with pLannotate |
|
|
167
|
+
| `Shift+E` | Enter sequence editor mode |
|
|
168
|
+
| `Shift+S` | Save edits to file |
|
|
169
|
+
| `Delete` | Context-aware delete (feature or library entry) |
|
|
170
|
+
| `Ctrl+Z` | Undo |
|
|
171
|
+
| `Ctrl+Shift+Z` | Redo |
|
|
172
|
+
| `Ctrl+C` | Copy selection to clipboard |
|
|
173
|
+
| `q` | Quit |
|
|
174
|
+
|
|
175
|
+
### Primer Design screen
|
|
176
|
+
|
|
177
|
+
| Key | Description |
|
|
178
|
+
|-------|------------------------------------------------|
|
|
179
|
+
| `esc` | Close primer screen |
|
|
180
|
+
| `m` | Mark / unmark primer under cursor (`★`) |
|
|
181
|
+
| `M` | Mark / unmark all primers |
|
|
182
|
+
| `S` | Cycle status: Designed → Ordered → Validated |
|
|
183
|
+
| `Tab` | Cycle focus between fields |
|
|
184
|
+
|
|
185
|
+
### Mouse
|
|
186
|
+
|
|
187
|
+
| Action | Description |
|
|
188
|
+
|----------------|---------------------------------------------|
|
|
189
|
+
| Click | Place cursor / select feature under pointer |
|
|
190
|
+
| Double-click | Select full feature span |
|
|
191
|
+
| Drag | Select a sequence range |
|
|
192
|
+
| Scroll wheel | Rotate map (when over map panel) |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Menus
|
|
197
|
+
|
|
198
|
+
| Menu | Items |
|
|
199
|
+
|------------|--------------------------------------------------------------------|
|
|
200
|
+
| File | Open .gb file · Fetch from NCBI · Add to Library · Save · Quit |
|
|
201
|
+
| Edit | Edit Sequence · Undo · Redo · Delete Feature |
|
|
202
|
+
| Enzymes | Show RE sites · Unique cutters · 6+/4+ bp sites · Connectors |
|
|
203
|
+
| Features | Add Feature · Delete Feature · Annotate with pLannotate |
|
|
204
|
+
| Primers | Opens the full-screen Primer Design workbench |
|
|
205
|
+
| Parts | Opens the Parts Bin (Golden Braid L0 parts catalog) |
|
|
206
|
+
| Constructor| Opens the Assembly Constructor for TU building |
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Requirements
|
|
211
|
+
|
|
212
|
+
| Package | Version | Purpose |
|
|
213
|
+
|-------------------|-------------------|----------------------------------------------|
|
|
214
|
+
| Python | ≥ 3.10 | Runtime |
|
|
215
|
+
| Textual | ≥ 8.2.3 | TUI framework and rendering engine |
|
|
216
|
+
| Rich | ≥ 14.0 | Terminal rendering (Textual dependency) |
|
|
217
|
+
| Biopython | ≥ 1.87 | GenBank parsing and NCBI Entrez fetch |
|
|
218
|
+
| primer3-py | ≥ 2.3.0 | Primer design (Tm, thermodynamic screening) |
|
|
219
|
+
| pytest | ≥ 9.0 | Test suite (dev only) |
|
|
220
|
+
| pytest-asyncio | ≥ 1.3 | Async test support (dev only) |
|
|
221
|
+
| **pLannotate** | optional, conda | Automatic plasmid annotation (`Shift+A`) |
|
|
222
|
+
| **BLAST+** | optional, conda | Required by pLannotate |
|
|
223
|
+
| **Primer3 CLI** | optional, `apt` | Not used directly — primer3-py bundles it |
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Data files
|
|
228
|
+
|
|
229
|
+
All user data persists as human-readable JSON in the repo directory:
|
|
230
|
+
|
|
231
|
+
| File | Purpose |
|
|
232
|
+
|-----------------------|---------------------------------------------|
|
|
233
|
+
| `plasmid_library.json`| Saved plasmid collection (GenBank + metadata) |
|
|
234
|
+
| `parts_bin.json` | User-domesticated Golden Braid parts |
|
|
235
|
+
| `primers.json` | Designed primer library |
|
|
236
|
+
| `*.json.bak` | Automatic backup — written before each save |
|
|
237
|
+
|
|
238
|
+
These files are in `.gitignore` — they're user-local data, not repo content.
|
|
239
|
+
A manual backup rotation happens on every save so accidental data loss is
|
|
240
|
+
always recoverable via the `.bak` file.
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## Tests
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
python3 -m pytest -q # full suite (246 tests, ~45 s)
|
|
248
|
+
python3 -m pytest tests/test_dna_sanity.py # biology correctness only (< 1s)
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## License
|
|
254
|
+
|
|
255
|
+
MIT
|