NucDynamics
-----------
NucDynamics is a Python/Cython program for the calculation of genome structures
from single-cell Hi-C chromosome contact data using a simulated annealing
particle dynamics protocol. This software takes NCC format contact data (as
output by NucProcess) and creates 3D coordinates, which are output as N3D (a
simple tab-separated format, see below) or PDB (ProteinDataBank) format files.
If the result of the calculation is output as PDB format the structures may be
viewed in molecular graphics software such as PyMol. Further output formats will
be supported in the near future.
To run NucDynamics issue the 'nuc_dynamics' command line followed by the
name/location of an input NCC format contact file. Various options may be
specfied on the command line using flags that are prefixed with '-'. A full
listing of these is given below, but commonly -o (the output coordinate file),
-m (the number of conformational models to generate), -f (output file format)
and -s (the particle size or sizes to use) will be specified.
Parameters relating to the restraint distances are not normally changed when
calculating interphase genome structures. However, the annealing stage
temperatures and the number of temperature and dynamics steps may be adjusted
according to the amount and/or quality of the single-cell Hi-C contacts. The
default parameters are generally suitable for good data sets with at least
40,000 contacts but better results may be obtained with longer and more gentle
annealing, i.e. more temperature steps and dynamics steps.
It should be noted that obtaining high-quality whole-genome structures (with a
tight conformational bundle) is dependant on both having a good number of
contacts and having a reasonable proportion of inter-chromosomal (trans)
contacts. As a rough guide, around 40,000 total contacts with 2000 trans
contacts is about the lower limit for calculating resonable structures
(intra-bundle RMSD < 2 radii) at a 100 kb particle size. Though, having a higher
proportion of trans contacts can make up for shortfalls in the total count.
The quality of the output structure bundles naturally depends on the final
sequence resolution that is chosen, as specified by the particle size (-s
option). Though the default paramaters calculate to a final size of 100 kb, for
more sparse datasets larger sizes often give good results. Using finer sizes can
provide more detail, but will increase the number of particles that are not
restrained by at least one Hi-C derived contact, and thus the precision (RMSD)
at the particle scale will decrease. Though, with >100,000 contacts particle
sizes of 25 kb are reasonable. However, finer resolutions will naturally
increase memory requirements and calculation time.
Multiple particle sizes can be specified so that the genome structure
calculation uses a hierarchical protocol, calculating a low resolution structure
first and then basing the next, finer resolution stage on the output of the
previous stage. Hierarchical particle sizes need not be used, but they make the
calculation more robust.
Python Module Requirements
---------------------------
This software uses Python version 2 or 3 and requires that the Numpy and Cython
packages are installed and available to the Python version that runs
NucDynamics.
These modules are available in bundled Python packages like Anaconda or Canopy,
in most Linux distributions' package managers or can be installed on most
UNIX-like systems using pip:
pip install numpy
pip install cython
Installation
------------
NucDynamics does not require installation as such and may be run directly from
its download location, though all the component files must reside in the same
directory.
When first run, NucDynamics will attempt to compile the modules written in
Cython. A re-compilation may be forced by deleting the .so and .c files that
result from the compilation. The Cython code may also be compiled indepenently
using the setup_cython.py script as follows:
python setup_cython.py build_ext --inplace
Running NucDynamics
-------------------
Typical use, generating 10 conformational models in PDB format:
nuc_dynamics example_chromo_data/Cell_1_contacts.ncc -m 10 -f pdb
Specifying the particle sizes (8 Mb, 2 Mb, 1 Mb, 500 kb) and an output file
name:
nuc_dynamics example_chromo_data/Cell_1_contacts.ncc -m 10 -f pdb -o Cell_1.pdb -s 8 2 1 0.5
Example Data
------------
Example NCC format contact data to demonstrate NucDynamics is avaiable in the
example_chromo_data sub-directory, as a .tar.gz archive which must be extracted
before use.
N3D coordinate format
---------------------
The default N3D output file format for genomic 3D coordinate positions is a
simple whitespace-separated format consisting of blocks of lines for separate
chromosomes (or other named sequence segments). Each block consists of a header
line, giving the chrosome name, number of coordinates (i.e. number of particle
positions) and the number of alternative coordinate models. The subsequent
particle data lines for the chromosome contain the basebair sequence position
followed by cartesian (X, Y, Z) coordinates for each alternative model.
i.e. each block is arranged like:
chr_name num_coords num_models
seq_pos_a xa1 ya1 za1 xa2 ya2 za2 xa3 ya3 za3 ...
seq_pos_b xb1 yb1 zb1 xb2 yb2 zb2 xb3 yb3 zb3 ...
...
For example the lines for two chromosomes, each with 5 positions/coordinates and
1 model could be:
chr7 5 1
3000000 9.58282628 7.00573100 -1.83845778
3100000 9.59673638 5.97364070 -2.01971472
3200000 10.96127666 5.81146425 -1.89757439
3300000 10.62732797 4.85757116 -1.96395929
3400000 10.12147618 5.03441764 -1.01074847
chrX 5 1
3100000 -4.90378489 5.82575335 -2.68593345
3200000 -3.82554225 5.68513329 -2.78682360
3300000 -2.86136185 5.20402428 -2.68921585
3400000 -3.37860658 4.53744574 -2.09833147
3500000 -4.05993187 3.72324210 -2.17562361
Command line options for nuc_dynamics
-------------------------------------
usage: nuc_dynamics [-h] [-o OUT_FILE] [-m NUM_MODELS] [-f OUT_FORMAT]
[-s Mb_SIZE [Mb_SIZE ...]] [-iso Mb_SIZE] [-pow FLOAT]
[-lower DISTANCE] [-upper DISTANCE] [-bb_lower DISTANCE]
[-bb_upper DISTANCE] [-ran INT] [-rad DISTANCE]
[-hot TEMP_KELVIN] [-cold TEMP_KELVIN] [-temps NUM_STEPS]
[-dyns NUM_STEPS] [-time_step TIME_DELTA]
NCC_FILE
Single-cell Hi-C genome and chromosome structure calculation module for Nuc3D
and NucTools
positional arguments:
NCC_FILE Input NCC format file containing single-cell Hi-C
contact data, e.g. use the demo data at
example_chromo_data/Cell_1_contacts.ncc
optional arguments:
-h, --help show this help message and exit
-o OUT_FILE Optional name of output file for 3D coordinates in N3D
or PDB format (see -f option). If not set this will be
auto-generated from the input file name
-m NUM_MODELS Number of alternative conformations to generate from
repeat calculations with different random starting
coordinates: Default: 1
-f OUT_FORMAT File format for output 3D coordinate file. Default:
"n3d". Also available: "pdb"
-s Mb_SIZE [Mb_SIZE ...]
One or more sizes (Mb) for the hierarchical structure
calculation protocol (will be used in descending
order). Default: 8.0 4.0 2.0 0.4 0.2 0.1
-iso Mb_SIZE Contacts must be near another, within this (Mb)
separation threshold (at both ends) to be considered
supported: Default 2.0
-pow FLOAT Distance power law for combining multiple Hi-C
contacts between the same particles. Default: -0.33
-lower DISTANCE Lower limit for a contact-derived distance restraint,
as a fraction of the ideal distance. Default: 0.8
-upper DISTANCE Upper limit for a contact-derived distance restraint,
as a fraction of the ideal distance. Default: 1.2
-bb_lower DISTANCE Lower limit for sequential particle backbone
restraints, as a fraction of the ideal distance.
Default: 0.1
-bb_upper DISTANCE Upper limit for sequential particle backbone
restraints, as a fraction of the ideal distance.
Default: 1.1
-ran INT Seed for psuedo-random number generator
-rad DISTANCE Radius of sphere for random starting coordinates.
Default: 10.0
-hot TEMP_KELVIN Start annealing temperature in pseudo-Kelvin units.
Default: 5000
-cold TEMP_KELVIN End annealing temperature in pseudo-Kelvin units.
Default: 10
-temps NUM_STEPS Number of temperature steps in annealing protocol
between start and end temperature. Default: 500
-dyns NUM_STEPS Number of particle dynamics steps to apply at each
temperature in the annealing protocol. Default: 100
-time_step TIME_DELTA
Simulation time step between re-calculation of
particle velocities. Default: 0.001
Jupyter Script
--------------
In addition to the command-line tool a Jupyter notebook for Python 3 is provided
to illustrate how nuc_dynamics can be imported used within Python scripts.
Jupyter can be installed using:
pip install jupyter
And from the directory containing nuc_dynamics the notebook can be started with:
jupyter notebook
This notebook is has only been tested under Python version 3 and to run requires
the Cython code to be compiled (see Installation section above), to generate the
dyn_util.so file, and for all the modules to either be in the same directory or
on the PYTHONPATH.