stepwise 0.40.0

Wetlab protocols that follow the Unix philosophy.

Stepwise is a program for authoring, planning, executing, and sharing scientific protocols. There are two main benefits it seeks to provide:

1. 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.

2. 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.

Example

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
 1. 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

 2. 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

 3. Run the following thermocycler protocol:

    - 98°C for 30s
    - Repeat 35x:
      - 98°C for 10s
      - 63°C for 20s
      - 72°C for 4 min
    - 72°C for 2 min
    - 4°C hold

 4. Label the product: f169

 5. 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.

 6. 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

 7. Incubate at 50°C for 15 min.

 8. Label the products: p216, p217

 9. Transform the following plasmids: p216, p217 [7]

    - Pre-warm 2 LB+Carb plates.
    - 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.

10. Sequence the following plasmids:

    Plasmid  Primers
    ────────────────
    p216     o266
    p217     o266

11. 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

[6] https://tinyurl.com/ychbvkra

[7] https://tinyurl.com/2cesd2hv

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.

Installation

Install stepwise from pip:

$ pip install stepwise

You may also want to install some related packages. First is Stepwise — Molecular Biology, 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

Getting started

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