.. _faq:

FAQs
====


**How should I get started?**

#. If you have a lot of data, use a subset of it to get started.  You will
   be able to iterate much more quickly and explore the impact of different
   modeling and parameter choices running on your laptop. Once you've got a
   sense for what works, start to scale your analysis up to a full MD
   dataset.

#. Use the :ref:`Anaconda scientific python distribution<installation>` and
   its `conda <http://conda.pydata.org/docs/>`_ package manager to install
   python packages.

#. `Get involved on the github issue tracker
   <https://github.com/msmbuilder/msmbuilder/issues>`_.


**How do I report a bug?**

Post a note on the `github issue tracker
<https://github.com/msmbuilder/msmbuilder/issues>`_.


**How do I contribute a new feature?**

File a pull request on `github
<https://github.com/msmbuilder/msmbuilder/>`_. If you're not familiar
with github, there are some instructions on the scikit-learn site `here
<http://scikit-learn.org/stable/developers/index.html#how-to-contribute>`_.


**Where should I start with the MSM literature?**

Some of the key PIs involved in research on Markov modeling of biomolecular
conformational dynamics include
`Hans Andersen <http://scholar.google.com/scholar?hl=en&q=Hans+C.+Andersen&btnG=&as_sdt=1%2C5&as_sdtp=>`_, 
`Robert Best <http://www.niddk.nih.gov/about-niddk/staff-directory/intramural/robert-barrington-best/pages/research-summary.aspx>`_,
`Greg Bowman <http://scholar.google.com/citations?user=zXobc4MAAAAJ&hl=en>`_,
`Amedeo Caflisch <http://scholar.google.com/citations?user=aq2vRkIAAAAJ&hl=en>`_,
`John Chodera <http://scholar.google.com/citations?user=nnEg7_8AAAAJ&hl=en>`_,
`Peter Deuflhard <http://scholar.google.com/citations?user=xsx-ru4AAAAJ&hl=en>`_,
`Ken Dill <http://scholar.google.com/citations?user=t3u4Y3EAAAAJ&hl=en&oi=ao>`_,
`Gianni De Fabritiis <http://scholar.google.com/citations?user=-_kX4kMAAAAJ&hl=en&oi=ao>`_,
`Helmut Grubmuller <http://scholar.google.com/scholar?oi=bibs&hl=en&q=Helmut+Grubmuller>`_,
`Xuhui Huang <http://scholar.google.com/citations?user=cDpFo0oAAAAJ&hl=en&oi=ao>`_,
`Ronald Levy <http://scholar.google.com/citations?user=df7O5IkAAAAJ&hl=en>`_,
`Frank Noe <http://scholar.google.com/citations?user=QGiLc_cAAAAJ&hl=en&oi=ao>`_,
`Vijay Pande <http://scholar.google.com/citations?user=cWe_xpUAAAAJ&hl=en&oi=ao>`_,
`Jed Pitera <http://scholar.google.com/scholar?oi=bibs&hl=en&q=Jed+Pitera>`_,
`Benoit Roux <http://scholar.google.com/citations?user=hoGTGlMAAAAJ&hl=en>`_,
`Christof Schutte <http://scholar.google.com/scholar?q=Christof+Sch%C3%BCtte&btnG=&hl=en&as_sdt=0%2C5>`_,
`Bill Swope <http://scholar.google.de/citations?user=pclnAzsAAAAJ&hl=de>`_,
`Eric Vanden-Eijnden <http://scholar.google.com/citations?user=OZfliS4AAAAJ&hl=en&oi=ao>`_, and
`Marcus Weber <http://scholar.google.de/citations?user=gBwM5-gAAAAJ>`_.

In 2014, Greg Bowman, Vijay Pande, and Frank Noe edited the book
`An Introduction to Markov State Models and Their Application to Long Timescale
Molecular Simulation <http://dx.doi.org/10.1007/978-94-007-7606-7>`_,
which features contributions from many of the authors above.

Two outstanding reviews (the first is somewhat old, but still very much worth
reading) of the field are

- Noe, F, and S. Fischer. `Transition networks for modeling the 
  kinetics of conformational change in macromolecules.
  <http://dx.doi.org/10.1016/j.sbi.2008.01.008>`_
  Curr. Opin. Struct. Biol. 18.2 (2008): 154-162.
- Prinz, J.-H., et al. `Markov models of molecular kinetics:
  Generation and validation. <http://dx.doi.org/10.1063/1.3565032>`_
  J. Chem. Phys. 134.17 (2011): 174105.

Methodologically, some of our favorite recent papers (2013-) include: [#f1]_

- Nuske, F., et al. `Variational approach to molecular kinetics
  <http://dx.doi.org/10.1021/ct4009156>`_ J. Chem. Theory Comput. 10.4 (2014): 1739-1752.
- Schwantes, C. R., and V. S. Pande. `Improvements in markov state
  model construction reveal many non-native interactions in the folding of
  NTL9 <http://dx.doi.org/10.1021/ct300878a>`_ J. Chem. Theory Comput. 9.4 (2013):
  2000-2009.
- Perez-Hernandez, G., et al. `Identification of slow molecular order
  parameters for Markov model construction <http://dx.doi.org/10.1063/1.4811489>`_
  J Chem. Phys. (2013): 015102.
- Noe, F., et al. `Projected and Hidden Markov Models for calculating
  kinetics and metastable states of complex molecules.
  <http://dx.doi.org/10.1063/1.4828816>`_ J. Chem. Phys. 139.18 (2013): 184114.
- McGibbon, R. T., et al. `Understanding Protein Dynamics with L1-Regularized
  Reversible Hidden Markov Models. <http://arxiv.org/abs/1405.1444>`_
  arXiv:1405.1444 (2014).

Some particularly notable recent applications of MSMs include

- Shukla, D, et al. `Activation pathway of Src kinase reveals intermediate
  states as targets for drug design. <http://dx.doi.org/10.1038/ncomms4397>`_
  Nat. Commun. 5 (2014).
- Sadiq, S. K., F. Noe, and G. De Fabritiis. `Kinetic characterization of the
  critical step in HIV-1 protease maturation.
  <http://dx.doi.org/10.1073/pnas.1210983109>`_
  Proc. Natl. Acad. Sci. U.S.A 109.50 (2012): 20449-20454.
- Kohlhoff, K. J., et al. `Cloud-based simulations on Google Exacycle
  reveal ligand modulation of GPCR activation pathways.
  <http://dx.doi.org/10.1038/nchem.1821>`_ Nat. Chem. 6.1 (2014): 15-21.


**What is the relationship between MSMBuilder and other packages?**

Another software packages that performs similar analyses is `EMMA
<http://emma-project.org>`_.  MSMBuilder inherits a lot of ideas about API
design, machine learning, and software engineering from `scikit-learn
<http://scikit-learn.org/>`_. MSMBuilder also has a number of python
dependencies. See the :ref:`installation` page for details.


**How much MD sampling do I need to build an MSM?**

There's no definitive way to answer this question -- in general reasoning
about the convergence of any stochastic sampling is very tricky. We can't
really be certain that there isn't another free energy minima that our
simulations didn't find.

An MSM (or tICA, HMM, etc) can help you answer this question. Using the
MSM, compare the slowest relaxation timescales in your model with the total
amount of aggregate sampling you have. If your system takes hundreds of
microseconds to relax to equilibrium according to your model, you probably
want at minimum hundreds of microseconds of sampling.

Another thing you can do is to split your data set into a couple (e.g.
2-10) chunks, and then repeat your analysis on subsets of the data. For
example, break your data up into 5 chunks and then build 5 MSMs, each of
which is fit using 4/5 of the data (with one chunk left out). If the 5 MSMs
are all consistent with one another, you might have very good sampling. If
they give totally different results from one another, you don't have enough
sampling.


**How can I validate an MSM?**

The gold standard is to use your MSM to make predictions about experimental
observables for a real molecular system that can be tested in the lab. The
relaxation timescales which are calculated by MSMs, tICA, HMMs, and other
types of kinetic models correspond to approximations for the relaxation
timescales that should be observed in experiments like T-jump spectroscopy.
It's best to look in the literature for this. See for example [#f2]_ and
[#f3]_ for a couple cool connections between MSMs and IR experiments.

One tricky part about validating an MSM by comparing to experiments is that
there are multiple possible reasons that an MSM could be "wrong". The MD
forcefield used for the simulations might not be a sufficiently accurate
model of reality. You might not have enough sampling. The MSM itself might
not resolve the slow degrees of freedom in the system (e.g. because of poor
clustering).

Another good idea is to build multiple MSMs, and see if they are consistent
with one another. For example, a common thing is to compare the implied
timescales of a series of MSMs built with the same clustering but with
different lag time (which should converge). See the validation section of
[#f4]_.


**How can statistical models like MSMs be used to accelerate MD?**

See Bowman, G R., D. L. Ensign, and S. S. Pande. `Enhanced modeling via 
network theory: Adaptive sampling of markov state models. <http://dx.doi.org/10.1021/ct900620b>`_
J. Chem. Theory Compt. 6.3 (2010): 787-794 and
Doerr, S., and G. De Fabritiis. `On-the-fly learning and sampling of ligand
binding by high-throughput molecular simulations. <http://dx.doi.org/10.1021/ct400919u>`_
J. Chem. Theory Comput. (2014).


**What are the tradeoffs between running a large number
of short MD simulations vs. a few long ones?**

Thats a good question.


**My simulations use replica exchange, aMD, or metadynamics.
Can I use these tools to analyze them?**

Yes, but you're going to have to be careful. Replica exchange, aMD,
meta-dynamics, and other related thermodynamic sampling methods sacrifice
physical kinetics to achieve potentially faster thermodynamic sampling.  So
you're going to need to be careful about interpreting the time-related
quantities from any models you might build using msmbuilder such as the
transition matrix of an MSM, or tICA eigenvalues. With clustering you're
fine.


**Why am I getting MemoryErrors?**

.. code-block:: guess

    Traceback (most recent call last):
      File "file.py", line 5, in <module>
        np.zeros((N, M))
    MemoryError

If you're running models in msmbuilder and you get a traceback with a
MemoryError (e.g. above), the reason is that you don't have enough RAM in
your machine to run whatever you're trying to run. One thing you can do is
just get more RAM, but his isn't going to scale very far.

To debug this kind of issue, you need really to reason about the size of
the arrays that are being created, which means thinking about the number of
data points in your dataset, the number of features, etc. Some algorithms,
like :class:`~msmbuilder.cluster.LandmarkHierarchical` let you trace off
the memory requirement against accuracy.

If you're trying to build models with thousands of features, consider
running a dimensionality reduction algorithm like
:class:`~msmbuilder.decomposition.PCA` or
:class:`~msmbuilder.decomposition.tICA` first. Or if you have milliseconds
of MD data sampled at a picosecond frequency, consider subsampling (e.g.
only analyze every 100th or 10,000th snapshot from your simulations).


**How can I cite MSMBuilder?**

Please cite `MSMBuilder2: Modeling Conformational Dynamics on the
Picosecond to Millisecond Scale
<http://pubs.acs.org/doi/abs/10.1021/ct200463m>`_ Most of the individual
methods that are implemented in MSMBuilder were also introduced in
published papers. The documentation for each class or command should have
the appropriate references listed.


References
----------

.. [#f1] Of course, this is merely an opinion
.. [#f2] Zhuang, W, et al. `Simulating the T-jump-triggered unfolding dynamics of trpzip2 peptide and its time-resolved IR and two-dimensional IR signals using the Markov state model approach. <http://pubs.acs.org/doi/abs/10.1021/jp109592b>`_ J. Phys. Chem. B 115.18 (2011): 5415-5424.
.. [#f3] Baiz, C. R., et al. `A Molecular Interpretation of 2D IR Protein Folding Experiments with Markov State Models. <http://dx.doi.org/10.1016/j.bpj.2014.02.008>`_ Biophysical journal 106.6 (2014): 1359-1370.
.. [#f4] Pande, V S., K. Beauchamp, and G. R. Bowman. `Everything you wanted to know about Markov State Models but were afraid to ask <http://dx.doi.org/10.1016/j.ymeth.2010.06.002>`_ Methods 52.1 (2010): 99-105.

.. vim: tw=75