oxDNA UTILS Documentation

oxDNA_UTILS Documentation

Marco Wong

Oct 01, 2021

Contents:

1 Tutorial 1

2 generate 3

3 ligation 5

4 modify_topology 7

5 mutual_traps 9

6 output_bonds 11

7 pulling_force 13

8 set_seq_strand 15

9 set_seq_vh_vb 17

10 Tutorial 19

11 Scripts 21

12 Modules 2312.1 base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312.2 generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2812.3 origami_utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2912.4 readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

13 Index 43

Python Module Index 45

Index 47

i

ii

CHAPTER 1

Tutorial

Before you use any scripts or modules, please put this line in your .bashrc file, and put in the path to your oxDNAUTILS:

export PYTHONPATH="$PYTHONPATH:/path/to/your/oxDNA/UTILS/"

Remember to do

. ~/.bashrc

Throughout the documentation, you will often see something called vh and vb. These are the virtual helix index andvirtual base index in cadnano. You can get these numbers by hovering your mouse over a nucleotide in cadnano, andthe two indices will show up at the lower left corner.

To use the scripts, simply follow the instructions given in their respective documentation pages. Note that some scriptsare new and not included in the oxDNA package. You can download the missing scripts here.

To use the modules, here is an example code:

import origami_utils as oruimport readers

# Read the configuration file 'prova.conf' and topology file 'prova.top'l = readers.LorenzoReader('prova.conf', 'prova.top')

# Get a base.System object from the readers = l.get_system()

# Initialise an Origami object from the System# The 'virt2nuc' file can be generated from cadnano_interface.py with a cadnano json→˓fileo = oru.Origami(system = s, cad2cuda_file = 'virt2nuc')

"""All code below are optional"""

"""(continues on next page)

1

https://github.com/mckwxp/oxDNA_UTILS/tree/master/new_scripts


(continued from previous page)

If you need to know which nucleotides are interacting with which...Note: you don't have to run this unless you want to use class methods which require→˓this list."""# Get a list of interactions between nucleotides# 'input' is a normal simulation input file, but it's only for the DNAnalysis program→˓and it won't run a simulationo.get_h_bond_list('input')

"""If you want to get the oxDNA nucleotide index from the virtual helix and virtual base→˓in cadnano..."""vh = 1 # virtual helix index (just an example)vb = 2 # virtual base index (just an example)scaf_id = o.get_nucleotides(vh, vb, type = "scaf") # get the scaffold nucleotide idstap_id = o.get_nucleotides(vh, vb, type = "stap") # get the staple nucleotide id

2 Chapter 1. Tutorial

CHAPTER 2

generate

Generates oxDNA configuration and topology files.

Usage:

python generate.py filename box_side

Args:

• filename: path to text file with a format described below

• box_side: length of box side

Reads a text file with the following format:

• Each line contains the sequence for a single strand (A,C,T,G). The nucleotides can be specified by (case insen-sitive) letter (A, C, G, T), random (X), strong (S) and weak (W).

• Options: DOUBLE, CIRCULAR, DOUBLE CIRCULAR

Example:

• Two ssDNA (single stranded DNA):

ATATATA

GCGCGCG

• Two strands, one double stranded, the other single stranded:

DOUBLE AGGGCT

CCTGTA

• One dsDNA that frays only on one side:

DOUBLE SSXXXXXXWW

• One dsDNA that frays very little but has TATA in the middle:

DOUBLE SSXXXXTATAXXXXSS

3


• Two strands, one double stranded circular, the other single stranded circular:

DOUBLE CIRCULAR AGAGGTAGGAGGATTTGCTTGAGCTTCGAGAGCTTCGA-GATTCGATCAGGGCT

CIRCULAR CCTGTAAGGAGATCGGAGAGATTCGAGAGGATCTGAGAGCTTAGCT

4 Chapter 2. generate

CHAPTER 3

ligation

You can download the script here.

Ligates two strands in an origami and prints out the new configuration and topology file.

Usage:

python ligation.py conf_file top_file virt2nuc ligate_file

Args:

• conf_file: configuration file

• top_file: topology file

• virt2nuc: virt2nuc file (can be generated from cadnano_interface.py with a cadnano json file)

• ligate_file: file containing which nucleotide to ligate (details described below)

Notes: This script works for multiple ligations in a single structure, but none of the ligations should be performed onthe same strand, otherwise the script does not give correct results.

If you want to connect the 5’ end nucleotide of strand 1 to the 3’ end nucleotide of strand 2, you should put theformer nucleotide before the latter in the ligate_file.

An example ligate_file is shown below:

1 16 stap 0 39 scaf

1 31 scaf 1 31 stap

This ligates the staple nucleotide at (vh, vb) = (1, 16) to the scaffold nucleotide at (vh, vb) = (0, 39), as wellas the scaffold nucleotide at (vh, vb) = (1, 31) to the staple nucleotide at (1, 31). vh and vb stands for virtualbase index and virtual helix index in cadnano. (Apparently this does not make any sense. It only serves as anexample.)

5



6 Chapter 3. ligation

CHAPTER 4

modify_topology


Primarily used for changing sequences to poly-T in an origami and prints out the new topology file. Can also be usedto change sequences for other parts, but set_seq scripts should be better.

Usage:

python modify_topology.py conf_file top_file virt2nuc seq_file

Args:




• seq_file: file containing which base to change (details described below)

Notes: An example seq_file is shown below:

T: 0-25,70-71,stap 0-6,296-297,stap 8-23,392-393,stap 24-25,232-233,stap

This will change all the nucleotides for the specified (vh, vb, type) to T. vh and vb stands for virtual base indexand virtual helix index in cadnano, and type is either stap (staple) or scaf (scaffold).

7



8 Chapter 4. modify_topology

CHAPTER 5

mutual_traps


Used for making mutual trap external force file.

Usage:

python mutual_traps.py monomer_conf_file monomer_top_file virt2nuc polymer_conf_file→˓polymer_top_file

Args:

• monomer_conf_file: monomer configuration file

• monomer_top_file: monomer topology file


• polymer_conf_file: polymer configuration file

• polymer_top_file: polymer topology file

Notes: You can change the pairs variable at line 20 to select the pairs to apply traps as needed.

9



10 Chapter 5. mutual_traps

CHAPTER 6

output_bonds

Prints out all interactions in the system.

Usage:

python output_bonds.py input_file trajectory_file [confid]

Args:

• input_file: path to input file used for simulation

• trajectory_file: path to trajectory file generated from simulation

• confid: configuration id in the trajectory (defaults to 0, i.e. the first configuration)

Notes: This script is only suitable for analysing a few configurations in a trajectory.

If you want to analyse the whole trajectory, you should use the DNAnalysis program directly. It can be found inthe same place as the oxDNA executable.

11


12 Chapter 6. output_bonds

CHAPTER 7

pulling_force


Used for making pulling external force file.

Usage:

python pulling_force.py conf_file top_file virt2nuc

Args:




Notes: You can change the variables in lines 63-68 to select the nucleotides to apply traps as needed.

13



14 Chapter 7. pulling_force

CHAPTER 8

set_seq_strand


Used for changing sequences of whole strands in an origami and prints out the new topology file.

Remember: oxDNA sequences run 3’-5’ (opposite to the usual way of 5’-3’)!

Usage:

python set_seq_strand.py conf_file top_file virt2nuc seq_file

Args:




• seq_file: file containing strand sequences (details described below)


0 16 stap AAAAAAAAAAAAAAAA

This will change the sequence for the strand containing the specified nucleotide at (vh, vb, type) toAAAAAAAAAAAAAAAA. vh and vb stands for virtual base index and virtual helix index in cadnano, andtype is either stap (staple) or scaf (scaffold).

15



16 Chapter 8. set_seq_strand

CHAPTER 9

set_seq_vh_vb


Used for changing sequences in an origami, particularly making sticky ends, and prints out the new topology file.

Usage:

python set_seq_vh_vb.py conf_file top_file virt2nuc seq_file

Args:




• seq_file: file containing which base to change (details described below)


0 16-23 stap ATCGATCG

This will change the sequence for the specified (vh, vb, type) to ATCGATCG. vh and vb stands for virtual baseindex and virtual helix index in cadnano, and type is either stap (staple) or scaf (scaffold).

17



18 Chapter 9. set_seq_vh_vb

CHAPTER 10

Tutorial

Tutorial

19


20 Chapter 10. Tutorial

CHAPTER 11

Scripts

generate Generates oxDNA configuration and topology files.ligation Ligates two strands in an origami.modify_topology Changes sequences to poly-T in an origami.mutual_traps Makes a mutual trap external force file.output_bonds Prints out all interactions in the system.pulling_force Makes a pulling external force file.set_seq_strand Changes sequences of whole strands in an origami.set_seq_vh_vb Changes sequences in an origami, e.g. sticky ends.

21


22 Chapter 11. Scripts

CHAPTER 12

Modules

base Utility functions for oxDNA systems, strands and nu-cleotides.

generators Generates simple DNA structures.origami_utils Utility functions for DNA origamis designed in cadnano

and simulated in oxDNA.readers Reads oxDNA configuration and topology files.

12.1 base

Utility functions for oxDNA systems, strands and nucleotides.

base.py includes the classes: System, Strand, Nucleotide

class base.Nucleotide(cm_pos, a1, a3, base, btype=None, L=<mynumpy.mynumpy_core.array ob-ject>, v=<mynumpy.mynumpy_core.array object>, n3=-1)

Nucleotides compose Strands.

Parameters

• cm_pos – Center of mass position, e.g. [0, 0, 0]

• a1 – Unit vector indicating orientation of backbone with respect to base, e.g. [1, 0, 0]

• a3 – Unit vector indicating orientation (tilting) of base with respect to backbone, e.g. [0, 0,1]

• base – Identity of base, which must be designated with either numbers or letters (this iscalled type in the c++ code). Confusingly enough, this is similar to Particle.btype in oxDNA.

Number: {0,1,2,3} or any number in between (-inf,-7) and (10, inf). To use specific se-quences (or an alphabet large than four) one should start from the complementary pair 10and -7. Complementary pairs are such that base_1 + base_2 = 3

Letter: {A,G,T,C} (these will be translated to {0, 1, 3, 2}). These are set in the dictionaries:number_to_base, base_to_number

23


• btype – Identity of base. Unused at the moment.

• L – Angular velocity

• v – Velocity

cm_posPosition of the center of mass.

indexIndex of the nucleotide.

pos_backPosition of the backbone centroid.

pos_basePosition of the base centroid.

pos_stackPosition of the stacking site centroid.

copy(disp=None, rot=None)Returns a copy of the nucleotide, with optional translation and/or rotation.

Parameters

• disp – displacement vector to translate the copied nucleotide

• rot – rotation matrix to rotate the copied nucleotide

distance(other, PBC=True, box=None)Returns the distance to another nucleotide.

Parameters

• other – the other Nucleotide object

• PBC – boolean. If true, considers periodic boundary conditions and returns the minimumimage distance.

• box – box dimensions in a numpy array

get_base()Returns the base id. If the base is in [“A”, “G”, “C”, “T”, 0, 1, 2, 3], returns a string containing the letterof the base id. Otherwise, returns a string containing the number of the base id.

get_pos_back_rel()Returns the position of the backbone centroid relative to the centre of mass, i.e. it will be a vector pointingfrom the c.o.m. to the backbone.

rotate(R, origin=None)Rotates the nucleotide.

Parameters

• R – rotation matrix to rotate the nucleotide

• origin – the point around which the nucleotide rotates; defaults to be self.cm_pos

translate(disp)Translates the nucleotide.

Parameters disp – displacement vector to translate the nucleotide

24 Chapter 12. Modules


class base.StrandStrands are composed of Nucleotides. Access nucleotide objects of Strand strand1 bystrand1._nucleotides[nucleotide_index]. Strands can be contained in a System.

NLength of the strand (i.e. the number of nucleotides).

sequenceSequence of the strand.

cm_posCenter of mass of the strand.

indexIndex of the strand.

add_nucleotide(n)Adds a nucleotide to the strand.

Parameters n – Nucleotide object to be added.

append(other)Returns an extended strand which is formed by appending another strand to the current strand. Note thatthe current strand is not changed.

Parameters other – the other Strand object

bring_in_box_nucleotides(box)Brings nucleotides of the strand back into the box.

Parameters box – box dimensions in a numpy array

copy()Returns a copy of the strand.

get_slice(start=0, end=None)Returns a slice of the strand.

Parameters

• start – starting point of the slice (default is 0)

• end – ending point of the slice (default is end of strand)

make_circular(check_join_len=False)Connect the ends of the strand to make it circular.

Parameters check_join_len – boolean. If true, checks whether the ends of the strand areclose enough.

make_noncircular()Disconnect the ends of a circular strand.

overlaps_with(other, box)Returns True if this strand overlaps with the other strand, False otherwise.

Parameters

• other – the other Strand object


rotate(R, origin=None)Rotates the strand.

Parameters

12.1. base 25


• R – rotation matrix to rotate the system

• origin – the point around which the strand rotates; defaults to be self.cm_pos (NB thisdoes not exist at the moment, perhaps a bug)

set_cm_pos(new_pos)Sets the center of mass of the strand to a new position by moving all the nucleotides.

Parameters new_pos – new center of mass position

set_sequence(seq)Sets the sequence of the strand.

Parameters seq – either a string of letters (A,T,C,G), or a list of ints (0,1,2,3). Should have thesame length as the strand.

translate(amount)Translates the strand.

Parameters amount – displacement vector to translate the strand

class base.System(box, time=0, E_pot=0, E_kin=0)Object representing an oxDNA system. Contains strands. Access strand objects of System system1 by sys-tem1._strands[strand_index].

Parameters

• box – Box size of the system, e.g. box = [50, 50, 50]

• time – Time of the system

• E_pot – Potential energy

• E_kin – Kinetic energy

NNumber of nucleotides in the system.

N_strandsNumber of strands in the system.

E_potPotential energy

E_kinKinetic energy

E_totTotal energy

add_strand(s, check_overlap=True)Adds a Strand to the System. Returns True if non-overlapping, False otherwise.

Parameters

• s – Strand object to be added

• check_overlap – boolean. If true, checks for overlap. Defaults to be true.

add_strands(ss, check_overlap=True)Adds multiple Strands to the System. Returns True if non-overlapping, False otherwise.

Parameters

• ss – List of Strand objects to be added

• check_overlap – boolean. If true, checks for overlap. Defaults to be true.



contains_overlaps()Returns True if the system contains strand overlaps, False otherwise.

copy()Returns a copy of the system.

get_nucleotide_list()Returns a list of Nucleotide objects in the system.

get_reduced(according_to, bbox=None, check_overlap=False)Returns a reduced copy of the system with only strands set to be visible in the visibility file.

Parameters

• according_to – path to visibility file

• bbox – box size of the reduced system

• check_overlap – boolean. If true, checks for strand overlap.

get_sequences()Returns the sequence of the system as a list of lists containing strand sequences.

get_unique_seq()Returns the unique sequences in the system.

join(other, box=None)Returns a system formed by joining this system with another system.

Parameters

• other – the other System object

• box – box size in a numpy array

map_nucleotides_to_strands()Fills the nucl_id -> strand_id array self._nucleotide_to_strand

print_lorenzo_output(conf_name, top_name, visibility=None)Outputs oxDNA configuration and topology files for the system.

Parameters

• conf_name – configuration file name

• top_name – topology file name

• visibility – path to visibility file (default is None - everything is visible)

rotate(amount, origin=None)Rotates the system.

Parameters

• amount – rotation matrix

• origin – the point around which the system rotates

set_visibility(arg=None)Sets visibility according to a visibility file.

Parameters arg – visibility file

translate(amount)Translates the system.

Parameters amount – displacement vector to translate the system

12.1. base 27


12.2 generators

Generates simple DNA structures.

class generators.StrandGeneratorStrand generator object.

generate(bp, sequence=None, start_pos=<mynumpy.mynumpy_core.array object>,dir=<mynumpy.mynumpy_core.array object>, perp=None, rot=0.0, double=True, cir-cular=False, DELTA_LK=0, BP_PER_TURN=10.34, ds_start=None, ds_end=None,force_helicity=False)

Returns one (for single strand) or two (for duplex) base.Strand object(s).

• linear / circular (circular)

• ssDNA / dsDNA (double)

• Combination of ss/dsDNA (ds_start, ds_end)

Parameters

• bp – Integer number of bp/nt (required)

• sequence – Array of integers or strings. Should be same length as bp (default None).Default (None) generates a random sequence.

Ex: [0,1,2,3,0]

Ex: “AGCTA”

See dictionary base.base_to_number for int/char conversion {0:’A’}

• start_pos – Location to begin building the strand (default np.array([0, 0, 0]))

• dir – a3 vector, orientation of the base (default np.array([0, 0, 1]))

• perp – Sets a1 vector, the orientation of the backbone. (default False)

Must be perpendicular to dir (as a1 must be perpendicular to a3)

If perp is None or False, perp is set to a random orthogonal angle

• rot – Rotation of first bp (default 0.)

• double – Generate dsDNA (default True)

• circular – Generate closed circular DNA (defalt False)

Limitations: For ssDNA (double=False): bp >= 4; For dsDNA (double=True) : bp >= 30

Will throw warnings. Allowed, but use at your own risk.

• DELTA_LK – Integer change in linking number from Lk0 (default 0). Only valid if circu-lar==True

• BP_PER_TURN – Base pairs per complete 2*pi helix turn. (default 10.34). Only valid ifcircular==True

• ds_start – Index (from 0) to begin double stranded region (default None)

• ds_end – Index (from 0) to end double stranded region (default None)

Default is None, which is entirely dsDNA; sets ds_start = 0, ds_end=bp

Ex: ds_start=0, ds_end=10 will create a double stranded region on bases range(0,10):[0,1,2,3,4,5,6,7,8,9]



Note: To generate a nicked circular dsDNA, manually change state with{Strand}.make_noncircular()

• force_helicity – Force generation of helical strands. Use helicity by default for bp> 30. Warns from 18 to 29. Will crash oxDNA below 18. (default False)

Notes

Minimuim circular duplex is 18. Shorter circular strands disobey FENE. For shorter strands, circularssDNA is generated in a circle instead of having imposed helicity.

Examples:

• Generate ssDNA:

generate(bp=4, sequence=[0,1,2,3], double=False, circular=False)

• Generate circular dsDNA with +2 Linking number:

generate(bp=45, double=True, circular=True, DELTA_LK=2)

• Generate a circular ssDNA (45nt) with ssDNA (25nt) annealed to indices 0 to 24:

generate(bp=45, double=True, circular=True, ds_start=0, ds_end=25)

12.3 origami_utils

Utility functions for DNA origamis designed in cadnano and simulated in oxDNA.

origami_utils.py includes the class: Origami

class origami_utils.Origami(system=False, cad2cuda_file=False, visibility=False)Origami object.

Parameters

• system – base.System object. Can be obtained from readers.LorenzoReader.get_system

• cad2cuda_file – path to virt2nuc file. Can be obtained from cadnano_interface.py

• visibility – path to visibility file

base_to_vbase(vhelix, base)Not used right now.

check_branch_migration_strict(vh1, vb1, vh2, vb2)Check for branch migration using strict definition; returns true if there is branch migration, false otherwise.

Strict definition: at least one of the 4 junction base pairs is missing.

self.interaction_list must be filled using get_h_bond_list.

The two virtual helices and two virtual bases that define the junction’s position are given as the fourarguments.

Parameters

• vh1 – first virtual helix index in cadnano

• vb1 – first virtual base index in cadnano

• vh2 – second virtual helix index in cadnano

• vb2 – second virtual base index in cadnano

12.3. origami_utils 29


compute_vh_midpoints()Computes the base pair midpoints for each virtual helix just once to save time

corrug_angle(xpos, bbms1, bbms2, id1, id2, av_axis, ref_intra_in_plane)Computes the corrugation angle as the dot product of the intra-strand vector at xpos with the referencevector, after both have been projected into the plane perpendicular to the average helix axis at the junction.

corrugation(hj, span=16)Returns the corrugation a distance span around the junction hj. The corrugation pattern is quantified as theangle from the dot product between the average of the two intra-helix vectors at the junction and each ofthe other intra-helix vectors.

Run compute_vh_midpoints() first.

Parameters

• hj – should come from hjs[ii] where hjs=origami.get_holliday_junctions().

• span – distance span around Holliday junction

get_1d_vecs(discard_unbonded=True)Returns orthonormal vectors based on the orientation of the strand. The returned vectors are “invariant”co-ordinates x’, y’, z’. x’: along double helix; yy: average backbone-base vector for the 0th strand; z’: x’cross yy; y’: z’ cross x’

Parameters discard_unbonded – boolean. If true, discard broken base pairs in the calcu-lation. NB: it is not currently implemented in this function.

get_3d_twist(f_edge_vh, vhelix_extent=False, discard_unbonded=True)Returns the 3d global twist (top-bottom and left-right). Run get_h_bond_list first.

Parameters

• f_edge_vh – path to vh_edge file (see the function parse_vh_edge)

• vhelix_extent – 2-element array including the beginning and end of the virtual helixindices that you want to use

• discard_unbonded – boolean. If true, discard broken base pairs in the calculation.

get_3d_vecs(vhelix_extent=False, discard_unbonded=True)Returns orthonormal vectors based on the orientation of the origami.

vhelix_extent currently unused. . . . uses extent of double helices (assuming there is one duplex per virtualhelix). NB: the author of this documentation believes that it is actually used. Perhaps the author of thecode did not update the comments after vhelix_extent was implemented.

Assumes the skips are lined up across vhelices - in particular it will presumably break if there is a vb witha skip adjacent (in vhelix dimension) to a vb that represents the end of a double helix.

Parameters


• discard_unbonded – boolean. If true, discard broken base pairs in the calculation.Run get_h_bond_list first.

get_alignment(trim, period)Returns the alignment of a pair of nucleotides, i.e. to see if ones that are supposed to line up do. Assumesno skip/loop / insertion/deletion

Parameters

• trim – number of base pairs to trim at the ends



• period – separation of pairs of base pairs

get_arm_vec(vhc, vbc, vbn)This function was not documented when it was written. The author of this documentation believes that itreturns a vector along an arm of a Holliday junction, or more generally, a vector pointing along a virtualhelix.

Parameters

• vhc – virtual helix index in cadnano

• vbc – starting virtual base index in cadnano

• vbn – ending virtual base index in cadnano

get_av_helix_axis(vhelix_extent=False, discard_unbonded=True)Returns the average helix axis. Optionally discard unbonded (but designed) ‘base-pairs’, and ignore theregions outside the ‘vhelix_extent’. Run get_h_bond_list first.

Parameters


• discard_unbonded – boolean. If true, discard broken base pairs in the calculation.

get_backback_midpoint(n_index)Returns the midpoint of 2 backbone vectors corresponding to nucleotides that are hybridised according tocadnano scheme.

Parameters n_index – nucleotide index

get_backback_vec(n_index)Returns the vector between 2 backbones corresponding to nucleotides that are hybridised according tocadnano scheme.


get_bb_midpoint(n_index, pbc=True)Returns the midpoint of 2 base vectors corresponding to nucleotides that are hybridised according to cad-nano scheme.

Parameters

• n_index – nucleotide index

• pbc – boolean. If true, use the minimum image: i.e. make sure we get a sensible answerif the

• r1 and r2 correspond to nucleotides which were put atopposite (positions) –

• of the box due to pbc's. (ends) –

get_bb_vec(n_index)Returns the vector between 2 bases corresponding to nucleotides that are hybridised according to cadnanoscheme.


get_bpwise_weave(vh_id, vvib_id)Returns the weave for a pair of base pairs located at (vh_id, vvib_id) and (vh_id + 1, vvib_id). Assumesno skip/loop.

Parameters



• vh_id – virtual helix index in vhelix_indices

• vvib_id – virtual base index in vvib

get_cad2cudadna(infile, visibility=False)This function was not documented when it was written. The author of this documentation believes that itis used for parsing the virt2nuc file when initialising an origami object. Users should not use this functiondirectly.

Parameters

• infile – path to virt2nuc file

• visibility – path to visibility file

get_com()Not currently used. Unsupported/may no longer work - e.g. take care in using self.width andget_bb_midpoint.

get_corners()This function was not documented when it was written. The author of this documentation believes that itreturns the indices of the nucleotides in the four corners of the origami.

get_flat_nucs(vh)This function was not documented when it was written. The author of this documentation believes that itreturns a list of nucleotides in a given virtual helix.

Parameters vh – virtual helix index in cadnano

get_flat_units(discard_unbonded)Returns the width, height units of the origami if it had been laid out flat.

Parameters discard_unbonded – boolean. If true, discard broken base pairs in the calcu-lation. Run get_h_bond_list first.

get_h_bond_list(infile)Fill in self.interaction_list for the current system self._sys; self.interaction_list[nucid1] is a list of nu-cleotides that nucid1 has hydrogen bonds with

Parameters infile – path to input file for DNAnalysis

get_h_bond_list_output_bonds(infile, conffile, conf_num)Deprecated function, use origami_utils.Origami.get_h_bond_list instead.

The old (slow) version using output bonds.

get_hj_alignment(start, period)Find alignment of a pair of nucleotides, i.e. to see if ones that are supposed to line up do.

Assumes exactly 2 virtual helices, no skip/loop / insertion/deletion.

Parameters

• start – virtual base index of the first crossover (reading left to right)

• period – separation of the pair of base pairs

get_holliday_junctions(single=False, single_only=False)Returns a list of hjs in format (vh, vb, vh_neighbour, vb_next). Assumes no insertions/deletions whenusing cad2cudadna. If somehow there were two holliday junctions between the same pairs of vbases (onefor scaffold and one for staple strand), the 2nd would not be detected here.

Parameters



• single – boolean. If true, returns a list of all single crossovers rather than hollidayjunctions (i.e. pairs of crossovers).

• single_only – boolean. If true, returns a list of just single crossovers (doublecrossovers excluded). If single_only is true, the state of single should not matter.

get_junction_normal(hj, armlen=3)Returns the normal vector of a Holliday junction. Assumes double crossover, no skip/loop (not sure ifmatters).

Parameters hj – should come from hjs[ii] where hjs=origami.get_holliday_junctions().

get_junction_normal2(hj)Returns the normal vector of a Holliday junction. Assumes double crossover, no skip/loop (not sure ifmatters).

A similar method to get_junction_normal.

Parameters hj – should come from hjs[ii] where hjs=origami.get_holliday_junctions().

get_local_twist(vh_id, vvib_id, type, conf=False)Returns the local twist between given vhelix, vbase and the next one along. Assumes no skip/loop /insertion/deletion.

Parameters



• type – “base” for base or “back” for backbone

get_n_bp(vh)Returns the number of base pairs in a virtual helix.

Parameters vh – virtual helix index in cadnano

get_n_nicks()Returns the number of nicks (staple or scaffold) in an origami. Here a nick must be between adjacentstrands (e.g. if a nucleotide is missing that isn’t counted as a nick at all).

get_nearest_native_bonded(vhi, vb, increment, bound)Returns the nearest natively bonded base-pair. Run get_h_bond_list first.

Parameters

• vhi – virtual helix index in vhelix_indices

• vb – virtual base index in cadnano

• increment – must be +1 or -1, the amount to increment the virtual base by when search-ing for a virtual base with a native bond

• bound – if we get to this virtual base and we still haven’t found anything, we give up andthrow and error

get_nicks()Returns a list [scaffold_nicks, staple_nicks], each of which is a list of nicked neighbours in the origami.Here a nick must be between adjacent strands (e.g. if a nucleotide is missing that isn’t counted as a nick atall).

An element of each nick list has virtual helix number (NOT array index), virtual base 1, virtual base 2.

get_nucleotides(vhelix, vbase, type=’default’)Given a cadnano virtual helix index and a virtual base index, returns the nucleotide index



Parameters

• vhelix – virtual helix index in cadnano

• vbase – virtual base index in cadnano

• type – “scaf” for scaffold, “stap” for staple, “double” for both

get_plane_vecs(discard_unbonded=True)This function was not documented when it was written. The author of this documentation believes thatit sets self.vec_long and self.vec_lat for an origami_utils.Origami object. These are believed to be twovectors defining a plane of an origami.

Parameters discard_unbonded – boolean. If true, discard broken base pairs in the calcu-lation. Run get_h_bond_list first.

get_principal_axes(approxaxes, minnucs)Unsupported function. Do not use.

get_radius(vh_id, vvib_id, new_method=False)Returns the radius of a base pair (i.e. the radius of helix). Assumes no skip/loop.

Parameters



• new_method – boolean. If true, use a new method for getting the radius. It gives thesame result for an ideal configuration but a greater radius for an equilibrated configuration.

get_rise(vh_id, vvib_id)Returns the rise for a base pair. Assumes no skip/loop.

Parameters



get_vh_midpoints(vhi)Returns a list of base pair midpoints for a virtual helix. Effectively ‘flattens’ a virtual helix, dealing withany skips or loops.

Parameters vhi – virtual helix index in vhelix_indices

get_vh_spline(vh, mode=’midpoint’, vhelix_extent=False, discard_unbonded=True,force_circular=False)

Returns a cartesian spline for the base-base midpoints of a virtual helix.

Parameters

• vh – virtual helix number in cadnano

• mode – “midpoint”, which fits a spline through the midpoint between the two strands; or“both strands”, which fits two splines through each strand.


• discard_unbonded – boolean. If true, discard broken base pairs in the calculation.Run get_h_bond_list first.

• force_circular – boolean. If true, force a closed curve; the ends of the midpointcurve (which is open) will be joined together by a straight line.



get_vhelix_ds_length(vhi)Returns length of double helix. Requires one continuous double strand - otherwise how is double strandlength defined?

Parameters vhi – virtual helix index in self.vhelix_indices

get_vhelix_neighbours(type)This function was not documented when it was written. The author of this documentation believes that itreturns a neighbour list of virtual helices.

Parameters type – “sq” or “he”, corresponding to square or hexagonal lattice in cadnano

get_weave(verbose=False)Returns the weave pattern as a list of lists. Each pair of virtual helices has a list associated with it. Each ofthose lists contains the interhelical distance as a function of base-pair index along the virtual helix.

This method copes with insertions/deletions by creating a list of base- base midpoints for each virtualhelix, and assuming that each pair of virtual helices has the same number of base-base midpoints. Thisshould mean that the base pairs are fairly well lined up and results in a reasonable definition of the weavepattern.

Parameters verbose – boolean. If true, prints skipped virtual helix pairs.

has_full_hbond(vh, vb)Returns true if all cadnano base-pairs at this virtual base have their correct base-pairs in the configuration.Assumes self.interaction_list is already filled. Run get_h_bond_list first.

Parameters

• vh – virtual helix index in cadnano


intra_helix_autocorr()Returns the autocorrelation (i.e. the dot product) between the intra-helix vectors along each pair of virtualhelices in the origami.

This method does assume that the base pairs on adjacent virtual helices ‘line up,’ in the sense that thelist index of the closest base pair on one helix is the same as the index of the closest base pair on theneighbouring helix. A weak check for this is the condition that the lengths of the bbm lists (and so thenumber of base pairs in each virtual helix) are the same.

Note that the list this method returns is indexed by the actual virtual helix number given by cadnano, notthe ‘virtual helix index’ which indexes the self.vhelix_indices list.

Run compute_vh_midpoints() first.

is_crossover(vh, vhn, vb, strand_type)Returns a boolean of whether a crossover of type strand_type span the squares (vh, vb) and (vhn, vb).

Parameters


• vhn – another virtual helix index in cadnano


• strand_type – “scaffold” or “staple”

is_junction(vh, vb1, vb2, hjs_double, hjs_single)Returns ‘double’ if double crossover, ‘single’ if single crossover, False otherwise

Parameters




• vb1 – virtual base index in cadnano (left square)

• vb2 – virtual base index in cadnano (right square)

• hjs_double – array of holliday junctions (double crossovers). Should come fromorigami.get_holliday_junctions().

• hjs_single – array of single crossovers. Should come fromorigami.get_holliday_junctions().

is_nicked(vh, vb1, vb2)Returns true if there is a nick across vb1 and vb2, false otherwise.

Parameters


• vb1 – first virtual bsae index in cadnano

• vb2 – second virtual base index in cadnano

is_strand_end(vh, vb, strand_type)Returns string “first” or “last” for first or last nucleotide of the strand, otherwise false. Assumes we don’thave any 1-nucleotide-long strands

Parameters




map_base_to_vbase(vhelices_len, begin_bases, end_bases)Not used right now.

Returns virtual base AND the index of the nucleotide at that virtual base (ie to deal with the possiblity ofa loop).

min_distance(r1, r2)Returns the minimum image distance in going from r1 to r2, in this system’s box.

Parameters

• r1 – first vector

• r2 – second vector

old_get_corrug_weave(vh1, vh2, vb, n, norm2, corrug_signed=False)Returns distance between adjacent helices and decomposes into weave and corrugation for a pair of basepairs located at (vh1, vb) and (vh2, vb). Assumes no skip/loop.

parse_vh_edge(f_edge_vh)Returns a tuple of lists, each element corresponds to a vhelix number that is either in the top (vhelices1) orbottom (vhelices2) of the origami.

Parameters f_edge_vh – path to vh_edge file

parse_vhelix_extent_file(vhelix_extentf)Parses the vhelix_extent file and returns a list [vh_begin, vh_end], where vh_begin is a list of length<number of virtual helices> and each element being the left virtual base, and analogous for vh_end.

vhelix_extent file example: 10, 30



This function could be extended to parse a file with different vh_begin and vh_end for each virtual helix;the machinery that uses this function should be able to deal with that without modification.

Parameters vhelix_extentf – path to vhelix_extent file

prepare_principal_axes_calc()Unsupported function. Do not use.

square_contains_exactly_one_nucleotide(vh, vb, strand_type)Returns a boolean of whether the square vh, vb contains exactly one nucleotide.

Parameters




update_system(system)This function was not documented when it was written. The author of this documentation believes that itupdates the system of the origami object.

Parameters system – base.System object. Can be obtained from read-ers.LorenzoReader.get_system

vb2nuci(vhi, vb0)This function was not documented when it was written. The author of this documentation believes that itreturns the number of nucleotides corresponding to a given virtual helix and virtual base. It is not always1 because of insertions/deletions.

Parameters

• vhi – virtual helix index in self.vhelix_indices

• vb0 – virtual base index in cadnano (maybe, the author is not sure)

vb2vhelix_nucid(vh, vb, vb_nuci, mode=’default’)Given a virtual helix, a virtual base, and a nucleotide id for that virtual base, returns the index of thatnucleotide in a scheme where the leftmost (lowest virtual base index) nucleotide has index 0 and all nu-cleotides are given a unique integer index.

Parameters



• vb_nuci – index of particular nucleotide in the virtual base (if the virtual base does nothave a loop there is always exactly one nucleotide, which has index 0)

• mode – gets given to get_nucleotides as type; ‘default’ will count a vb that has either ascaffold or staple strand, while ‘double’ will only count vbs that have both a scaffold andstaple strand.

vbase_to_base(vhelix, vbase)Not used right now.

Returns base corresponding to first base at a particular virtual base i.e. taking into account skips and loops(counting from the left of a cadnano diagram).

origami_utils.angle_sense(v1, v2, axis)Returns the angle between two vectors, using a 3rd vector to determine the sense of the angle.

Parameters



• v1 – first vector

• v2 – second vector

• axis – third vector

origami_utils.array_index(mylist, myarray)Returns the index in a list mylist of a numpy array myarray.

Parameters

• mylist – list

• myarray – numpy array

origami_utils.dihedral_angle_sense(v1, v2, axis, sanity_check=False)Returns the dihedral angle between two vectors, using a 3rd vector to determine the sense of the angle and todefine the axis normal to the plane we want the vectors in

Parameters

• v1 – first vector

• v2 – second vector

• axis – third vector

• sanity_check – boolean. If true, check whether v1 and v2 are not too parallel to theaxis, and returns false if either of them is.

origami_utils.get_base_spline(strand, reverse=False)Returns a cartesian spline that represents a fit through the bases for the strand ‘strand’.

Parameters

• strand – base.Strand object

• reverse – boolean. If true, strand is reversed

origami_utils.get_bb_midpoint(system, strand, n_index, interaction_list)Deprecated function, use origami_utils.Origami.get_bb_midpoint instead.

Returns the midpoint vector between 2 hybridised bases.

origami_utils.get_nucleotide(vhelix, vbase, vhelix_indices)Deprecated function, use origami_utils.Origami.get_nucleotides instead.

Returns the system nucleotide index of a nucleotide given a position on the origami.

origami_utils.get_pos_midpoint(r1, r2, box)Returns the midpoint of two vectors r1 and r2.

Uses the minimum image: i.e. make sure we get a sensible answer if the positions r1 and r2 correspond tonucleotides which were put at opposite ends of the box due to periodic boundary conditions.

Parameters




origami_utils.get_sayar_twist(s1, s2, smin, smax, npoints=1000, circular=False, inte-gral_type=’simple’)

Returns the twist for a given pair of spline fits, one through the bases of each strand.

From Sayar et al. Phys. Rev. E, 81, 041916 (2010)



Just need to integrate along the contour parameter s that is common to both splines. We need the normalisedtangent vector to the spline formed by the midpoint of the two input splines t(s), the normalised normal vectorformed by the vectors between the splines u(s), and the derivative of the normalised normal vector between thesplines d/ds (u(s)). NB, the normal u(s) vector should be orthogonal to the tangent vector t(s); we ensure this byusing only the component orthogonal to t(s).

Using integral_type = ‘simple’ and npoints = 200, it will give a correct twist, or at least one that gives a conservedlinking number when combined with get_sayar_writhe.

Parameters

• s1 – list of 3 splines corresponding to 3-D spline through strand 1’s bases (e.g. useget_base_spline())

• s2 – list of 3 splines corresponding to 3-D spline through strand 2’s bases – NB the splinesshould run in the same direction, i.e. one must reverse one of the splines if they come fromget_base_spline (e.g. use get_base_spline(reverse = True))

• smin – minimum value for s, which parameterises the splines

• smax – maximum value for s, which parameterises the splines

• npoints – number of points for the discrete integration

• circular – boolean. If true, spline is circular.

• integral_type – “simple”

origami_utils.get_sayar_writhe(splines1, smin, smax, splines2=False, npoints=1000, de-bug=False, circular=False, integral_type=’simple’)

Returns the writhe for a 3D spline fit through a set of duplex midpoints.

From Sayar et al. Phys. Rev. E, 81, 041916 (2010).

Using integral_type = ‘simple’ and npoints = 200, it will give a correct writhe, or at least one that gives aconserved linking number when combined with get_sayar_twist.

Parameters

• splines1 – list of 3 splines corresponding to either (if not splines2) a 3D spline throughthe duplex or (if splines2) strand 1’s bases

• smin – minimum value for s, which parameterises the splines

• smax – maximum value for s, which parameterises the splines

• splines2 – optionally, (see splines1) list of 3 splines corresponding to a 3D spline throughstrand2’s bases

• npoints – number of points for the discrete integration

• debug – print a load of debugging information

• circular – boolean. If true, spline is circular.

• integral_type – “simple”

origami_utils.get_scaffold_index(system)Returns the index of the scaffold strand in the system.

Parameters system – base.System object. Can be obtained from read-ers.LorenzoReader.get_system.

origami_utils.get_vhelix_vis(fname)Reads the ‘virtual helix visibility’ from a text file and ignore any virtual helices set to invisible.

The syntax is the same as for the base.py visibility.



Modified from the base.py strand visibility parsing.

Parameters fname – path to visibility file

origami_utils.min_distance(r1, r2, box)Returns the minimum image distance in going from r1 to r2, in a box of size box.

Same as base.Nucleotide.distance().

Parameters




origami_utils.norm(vec)Returns a normalised vector.

Parameters vec – vector

origami_utils.open_arrow_debug_file(filename, type=’w’)This function was not documented when it was written. The author of this documentation believes that it is adebugging function for VMD.

origami_utils.open_box_debug_file(filename)This function was not documented when it was written. The author of this documentation believes that it is adebugging function for VMD.

origami_utils.parse_scanfile(infile)This function was not documented when it was written. The author of this documentation believes that it parsesa “scan file”, the format and purpose of which is unclear.

Parameters infile – path to scan file

origami_utils.parse_vh_data(filename, origami)Gets vhelices data from file - format is either <auto,[number of vhelices]>, or, if a region of an origami is to beanalysed, <[region width],[list of starting nucleotide index for the region for each vhelix]>.

Parameters

• filename – path to vhelix data file

• origami – origami_utils.Origami object

origami_utils.print_arrow_debug_line(begin, end, file)This function was not documented when it was written. The author of this documentation believes that it is adebugging function for VMD.

origami_utils.print_box_debug_line(vecs, file)This function was not documented when it was written. The author of this documentation believes that it is adebugging function for VMD.

origami_utils.vecs2spline(vecs, per)This function was not documented when it was written. The author of this documentation believes that it returnsa spline interpolating the given vectors.

Parameters

• vecs – list of vectors (arrays of length 3)

• per – boolean. If true, forces spline to be periodic.



12.4 readers

Reads oxDNA configuration and topology files.

readers.py includes the class: LorenzoReader

class readers.LorenzoReader(configuration, topology, check_overlap=False)Reader for oxDNA configurations and topologies.

Parameters

• configuration – oxDNA configuration/trajectory file

• topology – oxDNA topology file

• check_overlap – boolean. If true, check for nucleotide overlaps in the configuration.

get_system(only_strand_ends=False, N_skip=0)Returns a base.System object by reading one configuration from the given configuration/trajectory file.After reaching the end of the configuration file, returns False.

Parameters

• only_strand_ends – boolean. If true, a strand will contain only the first and the lastnucleotide.

• N_skip – number of configurations to skip in the trajectory file

12.4. readers 41



CHAPTER 13

Index

genindex

43


44 Chapter 13. Index

Python Module Index

bbase, 23

ggenerators, 28

oorigami_utils, 29

rreaders, 41

45


46 Python Module Index

Index

Aadd_nucleotide() (base.Strand method), 25add_strand() (base.System method), 26add_strands() (base.System method), 26angle_sense() (in module origami_utils), 37append() (base.Strand method), 25array_index() (in module origami_utils), 38

Bbase (module), 23base_to_vbase() (origami_utils.Origami method),

29bring_in_box_nucleotides() (base.Strand

method), 25

Ccheck_branch_migration_strict()

(origami_utils.Origami method), 29cm_pos (base.Nucleotide attribute), 24cm_pos (base.Strand attribute), 25compute_vh_midpoints() (origami_utils.Origami

method), 30contains_overlaps() (base.System method), 26copy() (base.Nucleotide method), 24copy() (base.Strand method), 25copy() (base.System method), 27corrug_angle() (origami_utils.Origami method), 30corrugation() (origami_utils.Origami method), 30

Ddihedral_angle_sense() (in module

origami_utils), 38distance() (base.Nucleotide method), 24

EE_kin (base.System attribute), 26E_pot (base.System attribute), 26E_tot (base.System attribute), 26

Ggenerate() (generators.StrandGenerator method), 28generators (module), 28get_1d_vecs() (origami_utils.Origami method), 30get_3d_twist() (origami_utils.Origami method), 30get_3d_vecs() (origami_utils.Origami method), 30get_alignment() (origami_utils.Origami method),

30get_arm_vec() (origami_utils.Origami method), 31get_av_helix_axis() (origami_utils.Origami

method), 31get_backback_midpoint()

(origami_utils.Origami method), 31get_backback_vec() (origami_utils.Origami

method), 31get_base() (base.Nucleotide method), 24get_base_spline() (in module origami_utils), 38get_bb_midpoint() (in module origami_utils), 38get_bb_midpoint() (origami_utils.Origami

method), 31get_bb_vec() (origami_utils.Origami method), 31get_bpwise_weave() (origami_utils.Origami

method), 31get_cad2cudadna() (origami_utils.Origami

method), 32get_com() (origami_utils.Origami method), 32get_corners() (origami_utils.Origami method), 32get_flat_nucs() (origami_utils.Origami method),

32get_flat_units() (origami_utils.Origami method),

32get_h_bond_list() (origami_utils.Origami

method), 32get_h_bond_list_output_bonds()

(origami_utils.Origami method), 32get_hj_alignment() (origami_utils.Origami

method), 32get_holliday_junctions()

(origami_utils.Origami method), 32

47


get_junction_normal() (origami_utils.Origamimethod), 33

get_junction_normal2() (origami_utils.Origamimethod), 33

get_local_twist() (origami_utils.Origamimethod), 33

get_n_bp() (origami_utils.Origami method), 33get_n_nicks() (origami_utils.Origami method), 33get_nearest_native_bonded()

(origami_utils.Origami method), 33get_nicks() (origami_utils.Origami method), 33get_nucleotide() (in module origami_utils), 38get_nucleotide_list() (base.System method), 27get_nucleotides() (origami_utils.Origami

method), 33get_plane_vecs() (origami_utils.Origami method),

34get_pos_back_rel() (base.Nucleotide method), 24get_pos_midpoint() (in module origami_utils), 38get_principal_axes() (origami_utils.Origami

method), 34get_radius() (origami_utils.Origami method), 34get_reduced() (base.System method), 27get_rise() (origami_utils.Origami method), 34get_sayar_twist() (in module origami_utils), 38get_sayar_writhe() (in module origami_utils), 39get_scaffold_index() (in module origami_utils),

39get_sequences() (base.System method), 27get_slice() (base.Strand method), 25get_system() (readers.LorenzoReader method), 41get_unique_seq() (base.System method), 27get_vh_midpoints() (origami_utils.Origami

method), 34get_vh_spline() (origami_utils.Origami method),

34get_vhelix_ds_length() (origami_utils.Origami

method), 34get_vhelix_neighbours()

(origami_utils.Origami method), 35get_vhelix_vis() (in module origami_utils), 39get_weave() (origami_utils.Origami method), 35

Hhas_full_hbond() (origami_utils.Origami method),

35

Iindex (base.Nucleotide attribute), 24index (base.Strand attribute), 25intra_helix_autocorr() (origami_utils.Origami

method), 35is_crossover() (origami_utils.Origami method), 35is_junction() (origami_utils.Origami method), 35

is_nicked() (origami_utils.Origami method), 36is_strand_end() (origami_utils.Origami method),

36

Jjoin() (base.System method), 27

LLorenzoReader (class in readers), 41

Mmake_circular() (base.Strand method), 25make_noncircular() (base.Strand method), 25map_base_to_vbase() (origami_utils.Origami

method), 36map_nucleotides_to_strands() (base.System

method), 27min_distance() (in module origami_utils), 40min_distance() (origami_utils.Origami method), 36

NN (base.Strand attribute), 25N (base.System attribute), 26N_strands (base.System attribute), 26norm() (in module origami_utils), 40Nucleotide (class in base), 23

Oold_get_corrug_weave() (origami_utils.Origami

method), 36open_arrow_debug_file() (in module

origami_utils), 40open_box_debug_file() (in module

origami_utils), 40Origami (class in origami_utils), 29origami_utils (module), 29overlaps_with() (base.Strand method), 25

Pparse_scanfile() (in module origami_utils), 40parse_vh_data() (in module origami_utils), 40parse_vh_edge() (origami_utils.Origami method),

36parse_vhelix_extent_file()

(origami_utils.Origami method), 36pos_back (base.Nucleotide attribute), 24pos_base (base.Nucleotide attribute), 24pos_stack (base.Nucleotide attribute), 24prepare_principal_axes_calc()

(origami_utils.Origami method), 37print_arrow_debug_line() (in module

origami_utils), 40print_box_debug_line() (in module

origami_utils), 40

48 Index


print_lorenzo_output() (base.System method),27

Rreaders (module), 41rotate() (base.Nucleotide method), 24rotate() (base.Strand method), 25rotate() (base.System method), 27

Ssequence (base.Strand attribute), 25set_cm_pos() (base.Strand method), 26set_sequence() (base.Strand method), 26set_visibility() (base.System method), 27square_contains_exactly_one_nucleotide()

(origami_utils.Origami method), 37Strand (class in base), 24StrandGenerator (class in generators), 28System (class in base), 26

Ttranslate() (base.Nucleotide method), 24translate() (base.Strand method), 26translate() (base.System method), 27

Uupdate_system() (origami_utils.Origami method),

37

Vvb2nuci() (origami_utils.Origami method), 37vb2vhelix_nucid() (origami_utils.Origami

method), 37vbase_to_base() (origami_utils.Origami method),

37vecs2spline() (in module origami_utils), 40

Index 49

oxDNA UTILS Documentation

Documents