DNA sequence designer for algorithmic self-assembly of iterated Boolean circuits
The code in this directory is shipped with the manuscript: "Diverse and robust molecular algorithms using reprogrammable DNA self-assembly". Woods*, Doty*, Myhrvold, Hui, Zhou, Yin and Winfree. (*joint first co-authors) Nature 567:366–372, 2019.
This software can be installed on Linux and MacOS machines in several ways. (Installation on Windows is not possible as a piece of software we require, namely NUPACK, is not supported on Windows.)
We strongly recommend following the Nix instructions outlined below in part A as this provides an automated install procedure that essentially creates an isolated environment with the required prerequisites and without otherwise impacting your system. The nix-installed packages can be easily removed at a later time.
We also provide alternative do-it-yourself instructions (further below in part B) for those who do not wish to install the Nix package manager, but are happy to alter the global state of their system (however, configuration via B might be trickier than A).
Example invocations of the sequence designer are given in part C.
Example usage of our sequence analysis code is given in part D.
A note on NUPACK and ViennaRNA versions: Our DNA sequence designer used nupack3.0.4 to design the 6bit IBC DNA sequences in the publication, but we include nupack3.0.6 here. We believe that choosing between either version should not affect sequence quality. We have not (yet) updated to the later versions of NUPACK than nupack3.0.6 because they would require some internal changes to our code to accommodate interface and I/O differences. We used ViennaRNA-2.1.9 in the paper, the same version used here.
A. Nix Instructions
- Install the Nix package manager by running:
curl https://nixos.org/nix/install | sh
After the install, follow any instructions given on screen. For more information on Nix, see: https://nixos.org/nix/.
- Create a directory and place the sequence design code there.
git clone https://github.com/DNA-and-Natural-Algorithms-Group/SST-sequence-designer
- That directory needs to contain the file default.nix shipped with the sequence design code. You'll need an internet connection. In that directory run the command:
This will download and install a number of dependencies, essentially in an isolated environment (i.e. not on your system path), including nupack, ViennaRNA, python3 and others. Nix should then present you a new bash shell ready for use. The dependencies required for our sequence designer are locally available to the nix/bash shell and will not be globally available on your system (nor will they interfere with your current system setup).
B. Do-it-yourself Instructions
The sequence designer is written in python and relies on the specific point versions of NUPACK and ViennaRNA; using different versions may cause an error. We recommend the sequence designer by run using Python 3 (but also works with Python 2). It requires a number of python packages including numpy and matplotlib.
Install python3 (or python2).
Install the python packages for numpy and matplotlib.
NUPACK: Install NUPACK version 3.0.6. At the time of writing, the source is publicly available by request from the authors here: http://www.nupack.org/downloads (shipped as nupack3.0.6.tar.gz). Extract and run GNU make. The pdf file doc/NUPACK-UserGuide-3.0.pdf included has helpful info on NUPACK. The unix path must be able to find NUPACK executables (e.g. pfunc, mfe), and the environment path variable NUPACKHOME must be set, as described in the NUPACK installation instructions NUPACK-UserGuide-3.0.pdf. The following URL has a mirror of the nupack source: http://www.dna.caltech.edu/SupplementaryMaterial/Algorithmic_SST/archived_software/nupack3.0.6.tar.gz
ViennaRNA: Install ViennaRNA-2.1.9. At the time of writing the source is publicly available here: https://www.tbi.univie.ac.at/RNA/download/sourcecode/2_1_x/ViennaRNA-2.1.9.tar.gz. Follow the instructions in the "INSTALL" text file. You will need to set the environment path variable VIENNARNA_PARAMS_PATH to the location of the ViennaRNA parameters (dna_mathews1999.par and dna_mathews2004.par) which on some systems can be done via (and should be made part of your shell, e.g. bash, startup routine): export VIENNARNA_PARAMS_PATH=/usr/local/share/ViennaRNA/ The following URL has a mirror of the ViennaRNA sources: http://www.dna.caltech.edu/SupplementaryMaterial/Algorithmic_SST/archived_software/ViennaRNA-2.1.9.tar.gz
C. Designing sequences -- example commands
An example command to quickly design a small demo sequence set:
python3 atam2ssts.py -p input_tilesets/demo.py -o output_DNA_sequences/demo_sequences.txt
Note that the -p (input tile set and energy thresholds) and -o (output sequence file) parameters are mandatory.
An example command to quickly design 355 sequences using loose parameters that will presumably result in worse sequences than those used in our experimental work:
python3 atam2ssts.py -p input_tilesets/IBC_6bit_loose_params.py -o output_DNA_sequences/IBC_6bit_loose_params_sequences.txt
An example command to design 355 sequences using the parameters used in our experimental work (takes a very long time and may not halt for some runs, depending on random number seed):
python3 atam2ssts.py -p input_tilesets/IBC_6bit.py -o output_DNA_sequences/IBC_6bit_sequences.txt
For help, run:
python3 atam2ssts.py --help
D. Analysing designed sequence -- example commands
Input can be taken directly from a run of sequence designer (e.g. demo_sequences.txt in the example above), or can be an idt-formatted file. The code produces a set of pdf plots that describe thermodynamic proerties of the input DNA sequences.
An example command to analyse a small demo sequence set, at a default temperature of 53.0 C:
python3 analyse_seqs.py output_DNA_sequences/demo_sequences.txt
which generates plots that are placed in /output_DNA_sequences/53.0 C/
An example command to analyse a small demo sequence set, at a temperature of 20.0 C:
python3 analyse_seqs.py output_DNA_sequences/demo_sequences.txt -T 20.0
For help, run:
python3 analyse_seqs.py --help
The license that applies to all of the code in this repository is the MIT license see the file "LICENSE". We have also included the NUPACK license (as LICENSE_NUPACK) and ViennaRNA license (as LICENSE_viennaRNA), our python code calls the executable binaries of these software packages but does not link to them directly.