REVNANO

REVNANO is a computational tool that reverse engineers a schematic diagram for a nucleic acid origami nanostructure, given just the the raw scaffold and staple sequences for that nanostructure. Written in Python, the code is available as an open source repository on Bitbucket under a MIT Licence.

Image showing origami scaffold and staple sequences being converted to an origami geometric guide schematic

REVNANO works with DNA origami shapes, RNA origami shapes or hybrid origami shapes (e.g. RNA scaffold, DNA staples) in both 2-dimensions and 3-dimensions.

Input to the solver is a simple plain text sequence file like this, and output is an interactive HTML page showing an approximate ‘guide schematic’ of the origami nanostructure like this.

While all current software for DNA origami nanostructure design implements the forward problem of converting a geometric schematic to sequences, REVNANO solves the inverse of this problem.

Reverse engineering an (approximate) origami guide schematic from scaffold and staple sequences is generally useful for the following reasons:

Most DNA origami designs are published as raw sequences only in supplementary materials: this is the de facto standard of origami design exchange. Typically, no electronic origami design files are provided. The interactive guide schematic produced from sequences can assist in entering a DNA origami design back into a DNA origami CAD tool, hence recovering an electronic schematic file for the origami
The guide schematic allows examination of features of the origami in greater detail than is typically provided in a publication
Reversing sequences back to a guide schematic can provide a double-check that there are no sequence errors in the sequence lists
If a publication is vague about scaffold sequence, the staple set provided can be reversed against different scaffold sequences until the correct scaffold that makes the origami is found
Ease of reversing sequences back to a guide schematic is likely to be crudely correlated with lack of kinetic traps in the physical self-assembly of an origami nanostructure

REVNANO is written in Python and can be run from the command line or as part of a JupyterLab notebook on a single computer. Typical running times on a modern single computer ranges from a few seconds, up to around 5 minutes for larger origami designs based on e.g. M13 scaffold.

The REVNANO solver is described in more detail and benchmarked on a test set of 36 origamis in our 2023 paper in Computational and Structural Biotechnology Journal. If REVNANO is useful in your work, please consider citing our paper. See How to Cite Our Paper.

Image showing 3D capabilities of origami guide schematic

Finally, REVNANO makes use of a newly developed Nucleic Acid Origami Contact Map Format which is worth a look in its own right, as it has many useful features for creating, converting and modifying origami staple-scaffold contact maps.

Below is described how to install and run REVNANO. Also check out the Paper Examples page where there are sequence input files for all 36 origamis in our paper, to test out for yourself.

Installation

The following instructions should work for both MacOS and Linux systems. Windows users are encouraged to install the Windows Subsystem for Linux (WSL) and then install the software inside Ubuntu Linux.

Make a directory origami/ somewhere on your computer, and change to it:
```
mkdir origami
cd origami
```

Get the source code for the revnano Python module:

git clone https://bitbucket.org/engineering-data-structure-organoids/revnano.git

Note

Running the git command on MacOS may require you to download developer tools. If these are not installed, a dialog box should prompt you to install them.

Important: Rename the revnano repository to be upper case:
```
mv revnano REVNANO
```

Get the source code for the contactmap Python module (this is a required helper module):

git clone https://bitbucket.org/engineering-data-structure-organoids/contactmap.git

Make a python3 virtual environment and enable it:

python3 -m venv venv
source venv/bin/activate
pip3 install --upgrade pip

Install the following libraries in the new Python 3 virtual environment you just set up:

pip3 install networkx
pip3 install scipy
pip3 install matplotlib
pip3 install jupyterlab

When you have finished, your origami/ directory should contain three sub-directories:

contactmap/ REVNANO/ venv/

It is important that the REVNANO directory name is in upper case letters.

Now, REVNANO can be run either as a JupyterLab Python notebook (easiest and recommended) or from the command line. See Running as JupyterLab Notebook page or Running from Command Line page.

Note

For Raspberry Pi Linux, additional steps have to be taken to install the scipy library: sudo apt install libatlas-base-dev; sudo pip3 install pybind11; pip3 install scipy

Running as JupyterLab Notebook

Running REVNANO as a JupyterLab notebook is likely the easiest way to use the program:

Change to the origami/ directory where you installed REVNANO, and activate the Python 3 virtual environment (if not already active):
```
cd origami
source venv/bin/activate
```
Change to the REVNANO/ directory, and start JupyterLab:
```
cd REVNANO
jupyter-lab
```
Open the notebook file Reverse Engineer an Origami Guide Schematic.ipynb in the file viewer on the left hand side. Simply follow the step-by-step instructions at the top of the notebook to reverse engineer an origami guide schematic.

Note

Be patient :) The notebook can sometimes take minutes to complete for larger origamis.

See the Guide Schematic Views page, for an explanation of what the different views of the guide schematic mean.

Finally, note that the notebook calls REVNANO through API functions. These API functions can also be called by your own Python scripts.

Running from Command Line

REVNANO can also be run from the command line. First, the origami contact map is reconstructed from sequences by the REVNANO solver. Second, the contact map is copied to the contactmap module which creates a geometric guide schematic of the contact map, as an interactive HTML page.

Reconstruct Origami Contact Map

Change to the origami/ directory where you installed REVNANO, and activate the Python 3 virtual environment (if not already active):
```
cd origami
source venv/bin/activate
```
Put the origami sequence input file in the REVNANO/_assets directory. We will use the origami test and the sequence input for this origami is already supplied at REVNANO/_assets/test.rev.
Call REVNANO to reverse engineer the origami contact map. This uses the default algorithm parameters in parameters.py:
```
cd REVNANO
python3 revnano.py test
```

Note

Be patient. This step can take a few minutes to complete for larger origamis.

The REVNANO solver will produce output like this:

-----------------------------------------------------------
REVNANO Constraint Programming Solver v1.1
Origami Staple/Scaffold Sequences ----> Origami Contact Map
-----------------------------------------------------------

Origami to reverse engineer:
test

Algorithm main parameters:
MU_MIN:		6 bp
SIGMA:		4 bp
BETA:		0.30

Deterministic staple placement?:
YES - staples polled in order of ascending staple id

-----------------------------------------------------------

REVNANO STAGE 0 (Build staple routing trees)               

-----------------------------------------------------------

Finding definite 1-route staples... [SIGMA_1ROUTE = 10, MU_MIN = 6]
--> 1-route: staple 0
--> 1-route: staple 2
--> 1-route: staple 3
--> 1-route: staple 4
--> 1-route: staple 5
--> 1-route: staple 8
--> 1-route: staple 14
--> 1-route: staple 15
--> 1-route: staple 16
--> 1-route: staple 19
--> 1-route: staple 21
--> 1-route: staple 22
--> 1-route: staple 28
--> 1-route: staple 29
--> 1-route: staple 30
--> 1-route: staple 36
--> 1-route: staple 37
--> 1-route: staple 38
--> 1-route: staple 40
--> 1-route: staple 41
--> 1-route: staple 47
--> 1-route: staple 55
--> 1-route: staple 59
--> 1-route: staple 64
--> 1-route: staple 65
--> 1-route: staple 66
--> 1-route: staple 70
--> 1-route: staple 71
--> 1-route: staple 75
--> 1-route: staple 77
--> 1-route: staple 78
--> 1-route: staple 80
--> 1-route: staple 81
--> 1-route: staple 85
--> 1-route: staple 87
[Done]

Generating routing trees for other staples... [SIGMA = 4, MU_MIN = 6]
--> Making routing tree for staple 1
--> Making routing tree for staple 6
--> Making routing tree for staple 7
--> Making routing tree for staple 9
--> Making routing tree for staple 10
--> Making routing tree for staple 11
--> Making routing tree for staple 12
--> Making routing tree for staple 13
--> Making routing tree for staple 17
--> Making routing tree for staple 18
--> Making routing tree for staple 20
--> Making routing tree for staple 23
--> Making routing tree for staple 24
--> Making routing tree for staple 25
--> Making routing tree for staple 26
--> Making routing tree for staple 27
--> Making routing tree for staple 31
--> Making routing tree for staple 32
--> Making routing tree for staple 33
--> Making routing tree for staple 34
--> Making routing tree for staple 35
--> Making routing tree for staple 39
--> Making routing tree for staple 42
--> Making routing tree for staple 43
--> Making routing tree for staple 44
--> Making routing tree for staple 45
--> Making routing tree for staple 46
--> Making routing tree for staple 48
--> Making routing tree for staple 49
--> Making routing tree for staple 50
--> Making routing tree for staple 51
--> Making routing tree for staple 52
--> Making routing tree for staple 53
--> Making routing tree for staple 54
--> Making routing tree for staple 56
--> Making routing tree for staple 57
--> Making routing tree for staple 58
--> Making routing tree for staple 60
--> Making routing tree for staple 61
--> Making routing tree for staple 62
--> Making routing tree for staple 63
--> Making routing tree for staple 67
--> Making routing tree for staple 68
--> Making routing tree for staple 69
--> Making routing tree for staple 72
--> Making routing tree for staple 73
--> Making routing tree for staple 74
--> Making routing tree for staple 76
--> Making routing tree for staple 79
--> Making routing tree for staple 82
--> Making routing tree for staple 83
--> Making routing tree for staple 84
--> Making routing tree for staple 86
--> Making routing tree for staple 88
--> Making routing tree for staple 89
[Done]

The 90 staples have status:
- No tree: 	0	
- 1 route: 	90
- >1 routes: 	0
	Average number of routes on >1 route staples: 	0.00
	Maximum number of routes on >1 route staples: 	0

-----------------------------------------------------------

REVNANO STAGE 1 (Place staples by propagating constraints) 

-----------------------------------------------------------

951 bases already claimed by definite 1-route staples

Crystallising staple footprints...
--> Iteration 1
	2623 scaffold bases now claimed (+1672 since prev)
--> Iteration 2
	2623 scaffold bases now claimed (+0 since prev)
[Done]

The 90 staples have status:
- No tree: 	0	
- 0 routes: 	0	
- 1 route: 	90
- >1 routes: 	0
	Average number of routes on >1 route staples: 	0.00
	Maximum number of routes on >1 route staples: 	0


 ** All staples placed on origami ** 

-----------------------------------------------------------

REVNANO STAGE 2 (Place remaining staples by shortest path) 

-----------------------------------------------------------

No staples of >1 route exist to be placed.
(Stage 2 skipped)

-----------------------------------------------------------

REVNANO STAGE 3 (Resolve staple-staple overlaps)           

-----------------------------------------------------------

Resolving staple-staple overlaps...
Iteration 1
	Overlapped bases fixed: 23
Iteration 2
	Overlapped bases fixed: 0
[Done]


 ** All staple-staple overlaps resolved ** 

-----------------------------------------------------------

REVNANO STAGE 4 (Re-compose staples and make contact map)  

-----------------------------------------------------------

Creating origami contact map...
[Done]

Re-composing staples with loopouts and dangles...
[Done]

*********** FINAL SUMMARY ***********
Origami: test
90 of 90 staples placed (100.0%)
2646 of 2646 scaffold bases hybridised

Reverse engineered origami contact map saved to --> _assets/test.csv
*************************************


[REVNANO running time 1.30 seconds]

If REVNANO does not return an error (see the Errors page), an origami contact map will be created at REVNANO/_assets/test.csv.

More than one contact map may be created if single base domains exist on the scaffold strand (check the output messages).

Performance of the REVNANO algorithm is dependent on three important parameters MU_MIN, SIGMA and BETA. When you run the algorithm as above, the default values of these parameters are taken from the parameters.py file. However, you can specify these parameters on the command line using syntax:

python3 revnano.py <origami_name> <MU_MIN> <SIGMA> <BETA>

For example:

python3 revnano.py test 6 0 0.3

Finally, if REVNANO fails with Error 2 (see Errors page), you can sometimes make the algorithm complete by lowering the GAMMA parameter in parameters.py (to e.g. 0.4).

Create Origami Guide Schematic

Change to the REVNANO/_assets directory and move the newly created contact map to the contactmap module:
```
cd _assets
mv test.csv ../../contactmap/_assets/test.csv
```
Then, change to the contactmap module directory :
```
cd ../../contactmap
```

Make the guide schematic of the origami from the contact map. The syntax is:

python3 contact2schematic.py <origami name> <layout dimension of origami> <dimension of space>

Note

Be patient. This step can take a few minutes to complete for larger origamis.

For example, this command draws our 2D origami in 2D space:

python3 contact2schematic.py test 2 2

It can also be interesting to draw our 2D origami as a rotatable 2D plane in 3D space:

python3 contact2schematic.py test 2 3

If our origami was 3D, we could display it in 3D space using:

python3 contact2schematic.py test 3 3

When the renderer has finished, open file contactmap/_assets/test.html in a web browser to to see the interactive guide schematic.
See the Guide Schematic Views page, for an explanation of what the different views of the guide schematic mean.

Sequence Input File Format

Staple and scaffold sequences are input into REVNANO using a plain text file with extension .rev.

You can see the Paper Examples page for many example sequence input files.

The sequence input file has a simple format:

Comments can be included at any point in the text file by using the symbol #. A comment occupies the entire line it is on.
A keyword LINEAR or CIRCULAR may occur on a separate line anywhere in the text file, and denotes if the scaffold is a closed loop or not. This is most conveniently placed after the scaffold sequence. If this keyword is not specified, the scaffold defaults to LINEAR.
The first nucleic acid sequence encountered in the text file is considered as the scaffold sequence, listed 5’ to 3’.
Subsequent sequences in the text file are considered as staple sequences, each listed 5’ to 3’.

Note

* pairs must be put around staple sequence regions which are dangles or interior staple loopouts (regions not designed to hybridise with the scaffold). For example: Staple *TTTT*AAATCA*TTTTT*GGTCTTTACCCTGACGATTAGAG*TTTT* has a TTTT dangle at both ends marked, and a TTTTT interior staple loopout region marked.
Sequences can written in upper or lower case, or a mixture of both
Sequences will have internal spaces automatically removed
One sequence per line: Sequences split over multiple lines are treated as separate sequences

Guide Schematic Views

On the origami guide schematic, DNA helices are represented as straight lines for simplicity. Nodes can be dragged with the mouse and the layout re-equalises in a fluid way. Alternatively, forces can be turned off. The layout leverages the excellent Force Graph and 3D Force Graph engines.

The ‘Toggle View’ button at the top of the guide schematic can be used to put the schematic in three different display modes, explained below.

Scaffold View

The Scaffold View emphasises the route taken by the (long) scaffold strand through the origami nanostructure. Arrows point in direction of scaffold 5’ to scaffold 3’ (except the grey staple crossover arrows). On hovering the mouse over a domain, the blue sequence listed in the pop-up box is the scaffold sequence (listed 3’ to 5’).

Linear scaffolds have 5’ and 3’ scaffold ends marked with purple nodes. The guide schematic below has a circular scaffold, and scaffold end nodes are not present.
Any sections of scaffold not hybridised to staples are marked as yellow domains. The guide schematic above has no ssDNA scaffold sections.

Staples View

The Staples View highlights all individual staples in different colours. Arrows on the coloured staples point in the staple 5’ to staple 3’ direction. Arrows showing scaffold nicks still show the 5’ to 3’ direction of the scaffold. On hovering the mouse over a staple section, the white sequence listed in the pop-up box is the staple sequence (listed 5’ to 3’).

Sequence-Ambiguous Junction View

The Sequence-Ambiguous Junction View shows which parts of the origami are completely constrained by sequence complementarity. It helps identify areas where REVNANO could have made errors in reconstructing the contact map (and bound those errors).

Green junctions on the origami cannot be moved without breaking sequence complementarity at some point. Hence, with certainty, green junctions are correctly placed by the REVNANO solver.
Red junctions can be moved and still retain staple-scaffold sequence complementarity. Red junctions are ambiguous and may or may not be correctly placed by the REVNANO solver.

Note

Often, it is the case that Holliday junctions (back to back staple crossovers) admit a certain amount of ‘slide’ whilst retaining staple-scaffold sequence complementarity in all positions.

Image showing Sequence-Ambiguous Junction View of origami guide schematic

More specifically, a red node on the graph corresponds to the end of a hybridised domain between a staple and the scaffold, where the hybridised domain may be made shorter or longer (and the associated local hybridisation changes propagated) without breaking local sequence complementarity between scaffold and staples.

Hovering the mouse over a red node on the graph shows a message like {ambig -1 to +1}.

This means that, from its currently displayed position, the red node can be moved 1 base position ‘back’ in the direction of the scaffold 5’ (the -1 part), which may either shorten or lengthen the hybridised domain it is part of. Or, it can be moved 1 base position ‘forwards’ toward scaffold 3’ (the +1 part), which may either lengthen or shorten the hybridised domain it is part of. Hence, the domain can be three different lengths at the red node end, without scaffold-staple sequence complementarity being broken.

Often looking at the global origami design schematic, and by using symmetry, positions of the non-ambiguous green junctions can inform where the positions of the ambiguous red junctions are in the original origami design.

An origami with all green junctions (and all staples placed) unambiguously embeds its entire staples-scaffold contact map within its sequences.

The presence of some moveable junctions may also have implications for self-assembly accuracy.

Export High Resolution Image

Export a hi-resolution screen shot of your current guide schematic view in Firefox, by pressing alt-cmd-k to open the browser Console, and then type:

:screenshot --dpr 1 --fullpage

The resolution can be increased by increasing the number 1 (decimal numbers are allowed).

Paper Examples

All DNA origami nanostructures reverse engineered in our paper are listed below. For each origami is listed the REVNANO sequence input file, the REVNANO reverse engineered contact map and the reconstructed guide schematic. Entries followed by (D) indicate that single unhybridised bases have been removed from the scaffold strand in order to permit display as a guide schematic.

You can try these examples in REVNANO yourself. See Table 1 of our paper for the REVNANO parameters (MU_MIN, SIGMA and BETA) used in each case.

Raster Origamis

	Origami	REVNANO Input	REVNANO Output
1	RNA/DNA Hybrid Triangle	`Sequence File`	`Contact Map`	`Guide Schematic`
2	M1.3 Four Finger	`Sequence File`	`Contact Map`	`Guide Schematic`
3	Brick	`Sequence File`	`Contact Map`	`Guide Schematic`
4	Mini Triangle	`Sequence File`	`Contact Map`	`Guide Schematic`
5	DeBruijn Sequence Square	`Sequence File`	`Contact Map`	`Guide Schematic`
6	puc19 Rectangle	`Sequence File`	`Contact Map`	`Guide Schematic`
7	6 Helix Bundle	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
8	Fivewell Plate	`Sequence File`	`Contact Map`	`Guide Schematic`
9	Membrane Nanopore	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
10	Single Staple Loop	`Sequence File`	`Contact Map`	`Guide Schematic`
11	DNA Frame	`Sequence File`	`Contact Map`	`Guide Schematic`
12	Rothemund Rectangle	`Sequence File`	`Contact Map`	`Guide Schematic`
13	Rectangle Variant	`Sequence File`	`Contact Map`	`Guide Schematic`
14	Small Moon	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
15	Rothemund Smiley	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
16	Rothemund Star	`Sequence File`	`Contact Map`	`Guide Schematic`
17	Capsule	`Sequence File`	–	–

Wireframe Origamis

Note: From ATHENA (except for Origami 33 from vHelix website).

	Origami	REVNANO Input	REVNANO Output
18	Triangle	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
19	Square	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
20	Pentagon	`Sequence File`	`Contact Map`	`Guide Schematic`
21	Tetrahedron	`Sequence File`	`Contact Map`	`Guide Schematic`
22	Triangle Mesh	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
23	Cube	`Sequence File`	`Contact Map`	`Guide Schematic`
24	Star Mesh	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
25	Dodecahedron	`Sequence File`	`Contact Map`	`Guide Schematic`
26	Icosahedron	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
27	Square Mesh 1	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
28	Hexagon Mesh 1	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
29	Annulus Mesh 1	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
30	Hexagonal Tile	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
31	Truncated Cube	`Sequence File`	`Contact Map`	`Guide Schematic`
32	Cross Mesh	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
33	vHelix Ball	`Sequence File`	`Contact Map`	`Guide Schematic`
34	Annulus Mesh 2	`Sequence File`	`Contact Map`	`Guide Schematic`
35	Lotus Mesh	`Sequence File`	`Contact Map` (D)	`Guide Schematic` (D)
36	Enneagonal Trapezohedron	`Sequence File`	–	–

Errors

If REVNANO cannot derive a contact map from scaffold and staple sequences, it terminates in one of four error conditions explained below.

REVNANO Error #1

Occurs at: Stage 0
Error description: A staple with a single route on the scaffold intersects the hybridisation of another single route staple too much, or has hybridised sections which fully nest (or are fully nested by) the hybridised sections of other single route staples.
Why REVNANO termination is necessary: When positions of single route staples are conflicting, the first hard constraints in the REVNANO solver cannot be established.

REVNANO Error #2

Occurs at: Stage 2
Error description: Less than 65% of staples have been assigned a single route on the scaffold in Stage 1.
Why REVNANO termination is necessary: With insufficient staples placed, shortest paths calculated in Stage 2 are not reliable since the origami graph is not well connected. Stage 2 relies on the calculation of accurate shortest paths.

REVNANO Error #3

Occurs at: Stage 3
Error description: Some base position on the scaffold has three (or more) staples overlapping.
Why REVNANO termination is necessary: Only overlaps involving two staples can be resolved. It is unclear how to deal with more complex overlap scenarios.

REVNANO Error #4

Occurs at: Stage 3
Error description: Some staple-staple overlaps (i.e. two staple overlaps) could not be resolved by moving the ends of hybridised staple sections involved in the overlap. Moving the staple section ends leads to non-complementarity between staples and scaffold.
Why REVNANO termination is necessary: If an overlap cannot be resolved, the staples involved cannot be entered into the final contact map.

Note

Staples with very large routing trees (i.e. consisting of more than 10,000 subtrees) at Stage 0 do not cause an error immediately. Rather, these staples are assigned 0 routes through the scaffold, signifying that the staple cannot be routed. However, if large numbers of staples have very large routing trees and are reduced to 0 routes, this can cause errors later (like Error 2).

How to Cite Our Paper

Shirt-Ediss, B., Connolly, J., Elezgaray, J., Torelli, E., Navarro, S. A., Bacardit, J., & Krasnogor, N. (2023). Reverse engineering DNA origami nanostructure designs from raw scaffold and staple sequence lists. Comput. Struct. Biotechnol. J. 21, 3615–3626. DOI: 10.1016/j.csbj.2023.07.011

Download citation as Bibtex.