HelixMC Reference

Date:May 13, 2016

This reference document details functions, modules, and objects included in HelixMC, describing what they are and what they do. For learning how to use HelixMC, see also HelixMC Tutorial.

Code Organization

HelixMC is coded in Python in an object-oriented fashion, allowing easy usage and extension. Here we briefly summarizes the organization of the code.

First, HelixPose object stores all information of the current helix conformation. Various properties, e.g. coordinates, twist, writhe, etc. can be directly accessed from the object. The object also contains functions that allow one to update the conformation and to plot the helix.

Second, RandomStep are used to generate random samples of base-pair step parameters. RandomStepSimple takes in a list of database parameter sets, and can randomly emit one of input parameter set, or construct a multivariate Gaussian and emit samples from the distribution, upon the choice of the user. RandomStepAgg aggregates multiple RandomStep objects into one, allow easy handling of sequence-dependent sampling (by aggregating several RandomStepSimple for different sequences). The user can also create their own RandomStep objects by inheriting from RandomStepBase.

Third, Score objects take a HelixPose and scores it. The scoring can then be used to decide whether a Monte-Carlo move should be accepted. Currently we have 3 simple score terms ScoreExt, ScoreTorsionTrap and ScoreXyTrap, which scores a HelixPose under Z-extension, torsional trap and xy horizontal trap respectively. These 3 score terms are summarized into ScoreTweezers, which is a sub-class of ScoreAgg, an aggregator class that combines multiple score functions. ScoreTweezers is the workhorse score functions currently in used. The user can also define their own scoring by inheriting from ScoreBase.

Last, the util module contains useful functions for evaluating twist and writhe, for conversion between bp-step parameters and cartesian translation and rotation operation, and so on. The fitfxn module is a standalone module that contains a few widely used analytical fitting functions based on the elastic rod model.

Constant Random Seed

constant_seed([seed]) Set constant random seed.

Helix Pose

pose.HelixPose(params[, frame0, compute_tw_wr]) Pose object storing the state info of the helix.

Random Base-pair Steps Generators

random_step.RandomStepBase() Base class for Random bp-step generator, for inheritence only.
random_step.RandomStepSimple([params, ...]) Simple random bp-step generator.
random_step.RandomStepAgg([data_file, ...]) Random bp-step generator by aggregating multiple independent simple bp-step generators.

Score Functions

score.ScoreBase() Base class for scoring fucntion, for inheritence only.
score.ScoreExt(force) Score function for force-extension along Z-axis.
score.ScoreTorsionTrap(stiffness, target_link) Score function for torsional trap.
score.ScoreXyTrap(stiffness) Score function for xy trap.
score.ScoreAgg([score_list]) Score function aggregates of multiple score terms.
score.ScoreTweezers([force, ...]) Score function for tweezers experiments.

Utility Functions

Rotation Matrices

util.Rz(theta) Return z-rotation matrices with rotational angle theta.
util.Rx(theta) Return x-rotation matrices with rotational angle theta.
util.Ry(theta) Return y-rotation matrices with rotational angle theta.
util.R_axis(theta, axis) Return rotation matrices with rotational angle theta along an arbitary rotation axis.

Twist and Writhe

util.ribbon_twist(dr, rb_vec[, ...]) Compute the ribbon-twist (supercoiling twist) of a helix.
util.writhe_exact(dr) Compute the writhe of the helix using the exact Gauss double integral.
util.writhe_fuller(dr[, return_val_only]) Compute the writhe using the Fuller’s approximated single integral.

Useful Conversions

util.params2coords(params) Convert base-pair step parameters to bp-center coordinates and rotation matrix.
util.coords2params(o2, R2) Convert bp-center coordinates and rotation matrix to base-pair step parameters.
util.dr2coords(dr) Convert delta-r vectors to coordinates.
util.coords2dr(coord) Convert xyz coordinates of axis curve to delta-r vectors.
util.params2data(params[, frame0]) Convert step parameters to delta-r vectors and frames.
util.data2params(dr, frames) Convert delta-r vectors and frames to step parameters.
util.params_join(params) Convert consequtive bp-params to the params between 1st and last bp.
util.frames2params(o1, o2, f1, f2) Convert bp coordinates and frames to step parameters.
util.frames2params_3dna(o1, o2, f1, f2) Convert bp coordinates and frames in 3DNA format to step parameters.

Other Functions

util.unitarize(R) Enforce unitarity of the input matrix using Gram-Schmidt process.
util.circmean(arr[, axis]) Circular mean of angles.
util.MC_acpt_rej(score_old, score_new[, kT]) Decide whether to accept a Monte-Carlo move.
util.read_seq_from_fasta(fasta) Read the sequence from a fasta file.
util.locate_data_file(data_file) Search for the input data_file.

Useful Fitting Functions

fitfxn.wlc_odijk(F, A, L, S[, kT]) Worm-like chain fitting formula described in Odijk 1995 paper.
fitfxn.wlc_bouchiat(A, L, z[, kT]) Worm-like chain fitting formula described in Bouchiat et al.
fitfxn.wlc_bouchiat_impl(A, L, S, z, F[, kT]) Implicit worm-like chain formula described in Bouchiat et al.
fitfxn.f_wlc_bouchiat_impl(A, L, S, z[, kT]) Approximately solve the force from implicit wlc model by grid search.
fitfxn.moroz_3rd(A, C, F[, kT]) 3rd order Moroz-Nelson function for effective torsional persistence.
fitfxn.moroz_1st(A, C, F[, kT]) 1st order Moroz-Nelson function for effective torsional persistence.