Stepwise
.. image:: https://img.shields.io/pypi/v/stepwise.svg :target: https://pypi.python.org/pypi/stepwise
.. image:: https://img.shields.io/pypi/pyversions/stepwise.svg :target: https://pypi.python.org/pypi/stepwise
.. image:: https://img.shields.io/readthedocs/stepwise.svg :target: https://stepwise.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/github/actions/workflow/status/kalekundert/stepwise/test.yml?branch=master :target: https://github.com/kalekundert/stepwise/actions
.. image:: https://img.shields.io/coveralls/kalekundert/stepwise.svg :target: https://coveralls.io/github/kalekundert/stepwise?branch=master
Stepwise is a program for authoring, planning, executing, and sharing scientific protocols. There are two main benefits it seeks to provide:
Automate tedious calculations/remembering small details. For example, calculating how to setup master mixes, remembering which antibiotics to use with which plasmids, adding fragments to a DNA assembly reaction in the ideal molar ratios, choosing annealing temperatures and extension times for PCR reactions, etc. Stepwise can automatically work out all of these details and many more like them.
Record every step of every experiment. We all know that we should keep careful notes of everything we do in lab, but having to repeatedly write down similar details for similar experiments is tedious and prone to ambiguities or inconsistencies. Stepwise helps by filling in all the little details after you specify the few important ones.
Warning: this software is still very much a work in progress!
If stepwise seems like it might be useful to you, I'd encourage you to give it
a try! I use it every day, and it's certainly functional. However, it's not
yet finished, and it's certainly not yet polished. Let me know (preferably by
opening an issue in the bug tracker_) if you have a hard time understanding
how anything is supposed to work, or if you encounter a cryptic error message,
or anything like that. I ultimately want to make this into a broadly useful
tool for as many scientists as possible, and getting feedback from other people
will really help with that.
An example makes the benefits mentioned above more clear. Here's the command for a protocol to construct two plasmids, named "p216" and "p217"::
$ sw make p216 p217
This protocol needs to know what these plasmids are, and you would provide that
information via an Excel spreadsheet or similar; see FreezerBox_ for more info.
Below are some of the relevant entries from this spreadsheet:
Plasmids and fragments:
==== ===== ==================================== ================================== Name Ready Synthesis Cleanup ==== ===== ==================================== ================================== p216 n gibson f169,f172 transform; sequence o266; miniprep p217 n gibson f169,f173 transform; sequence o266; miniprep f169 n pcr template=p186 primers=o359,sr71 spin-cleanup f172 y order vendor=IDT f173 y order vendor=IDT ==== ===== ==================================== ==================================
Oligos:
==== ==================== Name Sequence ==== ==================== o359 CAACATTTCCGTGTCGCCCT sr71 CCGGTTGTACCTATCGAGTG ==== ====================
Briefly, these tables describe how to make each construct. For example, p216 is made by doing a Gibson assembly with fragments f169 and f172. In turn, f169 is made by doing PCR with p186 as a template and o359 and sr71 as primers.
From just the names of the constructs to make, the information in these spreadsheets, and sequence information read from SnapGene or GenBank files, stepwise produces the following protocol::
$ sw make p216 p217
Prepare 10x primer mix [1]:
Reagent Stock Volume ───────────────────────── water 9.00 µL o359 100 µM 0.50 µL sr71 100 µM 0.50 µL ───────────────────────── 10.00 µL
Setup 1 PCR reaction [2,3]:
Reagent Stock Volume ───────────────────────────────── water 15.00 µL p186 20 pg/µL 5.00 µL primer mix 10x 5.00 µL Q5 master mix 2x 25.00 µL ───────────────────────────────── 50.00 µL
Run the following thermocycler protocol:
Label the product: f169
Purify using QIAquick PCR purification kit (28104) [4,5]:
Perform all spin steps at 17900g.
Add 5 volumes PB to the crude DNA.
If not yellow: Add 0.2 volumes 3M sodium acetate, pH=5.0.
Load on a QIAquick column.
Spin 30s; discard flow-through.
Add 750 µL PE.
Spin 30s; discard flow-through.
Spin 1m; discard flow-through.
Add 50 µL EB.
Wait at least 1m.
Spin 30s; keep flow-through.
Setup 2 Gibson assemblies [6]:
Reagent Stock Volume 2.2x ───────────────────────────────────────────── Gibson master mix 2x 2.50 µL 5.50 µL f169 65 ng/uL 1.60 µL 3.51 µL f172,f173 10 ng/µL 0.90 µL ───────────────────────────────────────────── 5.00 µL 4.10 µL/rxn
Incubate at 50°C for 15 min.
Label the products: p216, p217
Transform the following plasmids: p216, p217 [7]
For each transformation:
Thaw 25 µL competent MACH1 cells on ice.
Add 1 µL plasmid.
Gently flick to mix.
Plate 25 µL cells.
Incubate at 37°C for 16h.
Sequence the following plasmids:
Plasmid Primers ──────────────── p216 o266 p217 o266
Miniprep.
Notes: [1] For resuspending lyophilized primers: 100 µM = 10 µL/nmol
[2] https://tinyurl.com/y27ralt4
[3] For diluting template DNA to 20 pg/µL: Dilute 1 µL twice into 7*sqrt([DNA]) µL
[4] https://tinyurl.com/xr8ruvr9
[5] Column capacity: 10 µg
Note that we only had to specify the really meaningful details, like which constructs to make, which templates/primers to use for PCR, etc. Stepwise figured out everything else automatically, including:
Realizing that f169 needs to be made before p216 or p217.
Realizing that f172 and f173 don't need to be made, because they are marked as "ready".
Choosing all of the PCR parameters, including volumes for every reagent and a temperatures/times for every thermocycler step. Q5 polymerase is used in this example because that is what I order, but it easy to configure other vendors/mixes. The annealing temperature and extension times are based on the sequences of the template and the primers.
Realizing that both assemblies share the f169 fragment, and so it can be included in a master mix.
Estimating the concentration of the f169 fragment based on the typical yield from a PCR reaction and the typical recovery from a silica spin column.
Choosing all of the Gibson assembly parameters, most notably fragment volumes that give the recommended molar ratio of backbone to insert.
Which antibiotics to use when transforming the plasmids. This comes from searching the sequence of the plasmids for known antibiotic resistance genes.
Install stepwise from pip::
$ pip install stepwise
You may also want to install some related packages. First is Stepwise — Molecular Biology <swmb>_, which is a collection of pre-programmed protocols
relating to molecular biology, e.g. PCR, Gibson/Golden Gate assembly, in vitro
transcription, etc.::
$ pip install stepwise_mol_bio
Second is FreezerBox_, which allows you to record useful information about your DNA/protein constructs (e.g. sequence, molecular weight, cloning strategy, etc.) in a way that is accessible to stepwise::
$ pip install freezerbox
Stepwise aims to be something you can use for every single protocol you perform. However, that's a big commitment. It's easier to get started by just using stepwise for a few tasks that it really excels at:
sw make: See the example above. This command is great for routine
cloning. The basic workflow is to record your cloning steps in a spreadsheet
as you plan them, then to have stepwise generate a protocol once all of your
primers etc. have arrived. Requires FreezerBox_.
sw future/reactions: This command calculates the best way to use master
mixes to setup groups of related reactions. It really shows its worth in
complex situations that call for 3-4 master mixes. It knows how to make a
little bit extra of each mix, and can account for all sorts of complicated
reaction setups.
Quick hint: There isn't yet any online documentation for stepwise, but each
command has pretty extensive usage information if you use the -h flag. For
example::
$ sw future/reactions -h
.. _bug tracker: https://github.com/kalekundert/stepwise/issues
.. _FreezerBox: https://github.com/kalekundert/freezerbox
.. _swmb: https://github.com/kalekundert/stepwise_mol_bio