========================
Introduction
========================

:Author: Kota Kasahara

------------------------------------
What is mDCC?
------------------------------------

The multi-modal dynamic cross correlation (mDCC) is a method for analyzing trajectories generated by molecular dynamics (MD) simulations. 
The mDCC was developed by KASAHARA Kota, FUKUDA Ikuo, and NAKAMURA Haruki, at Institute for Protein Reasearch, Osaka University.
See the original manuscript for details: A Novel Approach of Dynamic Cross Correlation Analysis on Molecular Dynamics Simulations and Its Application to Ets1 Dimer-DNA Complex. 2014 PLoS ONE 9:e112419 [Kasahara_2014]_.

.. [Kasahara_2014] Kasahara, K., Fukuda, I., & Nakamura, H. (2014). A Novel Approach of Dynamic Cross Correlation Analysis on Molecular Dynamics Simulations and Its Application to Ets1 Dimer-DNA Complex. PLoS ONE, 9(11), e112419. http://doi.org/10.1371/journal.pone.0112419

------------------------------------
mDCC tools
------------------------------------

This tool kit includes ...

- Programs

  - mdcc_learn

    - Detection of modes of atomic motions

  - mdcc_assign

    - Calculation of probability density functions for each atom at each time step

  - python scripts
   
- This document

- Sample files for the tutorial

  - A trajectory file written in the Gromacs .trr format
  - .bash files to execute analysis programs
  - Configuration files as input of the programs

------------------------------------
Installation
------------------------------------

The path to the home directory of the mDCC tools should be set as the shell variable ${MDCCTOOLS}.
For example,::

  export MDCCTOOLS=${HOME}/local/mdcctools

This tool kit includes two C++ programs (*mdcc_learn* and *mdcc_assign*) and some python scripts. 
The C++ programs need to be compiled.

The additional information of installation of dependencies are described in the Appendix.

mdcc_learn
------------------

*mdcc_learn* program performs a pattern recognition on a spatial distribution of atomic coordinates in a trajectory.

The source codes of *mdcc_learn* are placed in ${MDCCTOOLS}/src/mdcc_learn directory.

*mdcc_learn* requires LAPACK library. 
The name of LAPACK library and path to the library file should be specified in the Makefile.

  PATH_LAPACKLIB = ${HOME}/lib
  
  LAPACKLIB = -llapack

To build *mdcc_learn*, execute the *make* command and move the generated binary to ${MDCCTOOLS}/bin directory::

  make
  mv mdcc_learn ../../bin

mdcc_assign
--------------------

*mdcc_assign* program calculates the probability density for each data point of atomic coordinates in a trajectory on the basis of the results of *mdcc_learn* program.

This program requires LAPACK and BOOST libraries. The name and path of LAPACK library file and the path of BOOST include files should be specified in the Makefile::

  PATH_LAPACKLIB = ${HOME}/lib
  LAPACKLIB = -llapack
  BOOSTINC = $(HOME)/include

To build *mdcc_assign*, execute the *make* command and move the generated binary to ${MDCCTOOLS}/bin directory::

  make
  mv mdcc_assign ../../bin

Python scripts
--------------------------

Many python scripts are located in ${MDCCTOOLS}/bin directory. They are written for python2.7 and requires the libraries:

* numpy
* scipy
* mdanalysis
* networkx

They should be installed in paths in ${PYTHONPATH} environment variable.

All these libraries can be obtained by using *easy_install* command. 

Other programs for tutorial
-----------------------------

mDCC tools output the results as tab-separated text or binary files. In order to visualize the data, some analyses tools are useful.
In the tutorial, SQLite3, R, and Cytoscape are used. However, users can apply any other software, such as gnuplot and graphvis.

* https://www.sqlite.org/
* http://www.r-project.org/
* http://www.cytoscape.org/

For R software, the three libraries are used.

* reshape
* ggplot
* plyr

They can be installed with install.packages() command in the R shell.

------------------------------------
License
------------------------------------

mDCC_tools is distributed under GPL ver.3 liscense.