Merge branch 'main' of github.com:markovmodel/ivampnets

10Cube.ipynb

@@ -111,7 +111,10 @@
    "outputs": [],
    "source": [
     "angles = np.pi / 4 * np.ones(number_subsystems//2)\n",
+    "# training data with 100000 steps\n",
     "hidden_state_traj, observable_traj = toymodel.generate_traj(100000, angles=angles, dim_noise=dim_noise)\n",
+    "\n",
+    "# validation data with 10000 steps\n",
     "hidden_state_traj_valid, observable_traj_valid = toymodel.generate_traj(10000, angles=angles, dim_noise=dim_noise)"
    ]
   },
@@ -266,7 +269,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "tensorboard_installed = True\n",
+    "tensorboard_installed = False\n",
     "if tensorboard_installed:\n",
     "    from torch.utils.tensorboard import SummaryWriter\n",
     "    writer = SummaryWriter('./runs/Cube10/')\n",
@@ -301,6 +304,16 @@
     "                     lam_trace=0, start_mask=0, end_trace=0, tb_writer=writer, clip=False).fetch_model()"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "95548c29",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# execution time (on cpu): ~ 4.5 min"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "3984d128",
@@ -341,6 +354,16 @@
     "plot_mask(mask, vmax=0.5, skip=2)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c0d74aeb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# reproduces Fig. 4c (or a permutation with respect to ivampnet state assignments)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "143348c9",
@@ -396,12 +419,14 @@
    "id": "90807a5c",
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "# reproduces Fig. 4d"
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -415,7 +440,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.8.8"
   }
  },
  "nbformat": 4,

README.md

@@ -2,17 +2,17 @@
 
 Codebase for the iVAMPnets estimator and model which includes the classes for constructing the masks for toymodels and real protein applications.
 The implemented methods allow to decompose a possible high dimensional system in its weakly coupled or independent subsystems. Thereby, the downstream estimation of the kinetic models is much more data efficient than estimating a global kinetic model which might not be feasible. The whole pipeline is an end-to-end deep learning framework which allows to define your own network architectures for the kinetics estimation of each subsystem. 
-The data for the synaptotagmin C2A system is available upon request. The code is designed to reproduce the results of our paper "A deep learning framework for the decomposition of macromolecules into independent VAMPnets" (Link will be added) and is based on the deeptime package (see https://deeptime-ml.github.io/latest/index.html). 
+The data for the synaptotagmin C2A system is available upon request. The code is designed to reproduce the results of our paper "Deep learning to decompose macromolecules into independent Markovian domains" (https://www.biorxiv.org/content/10.1101/2022.03.30.486366v1) and is based on the deeptime package (see https://deeptime-ml.github.io/latest/index.html). 
 
 The code includes:
 1. (ivampnets.py) The definition of the ivampnets estimator class, which allows to fit a given model to simulation data. The definition of the ivampnets model class - the resulting model - which can then be used to estimate transition matrices, implied timescales, eigenfunctions, etc.
 2. (masks.py) The definition of the mask modules, which can be used to give the modeler an intuition which part of the global system is assigned to which subsystem.
 3. (examples.py) Helper functions to generate the data for the toy systems and plot some results.
-4. (Toymodel_2Systems.ipynb) Notebook to reproduce the results for a simple truly independent 2D system. 
-5. (10Cube.ipynb) Notebook to reproduce the results for the 10-Cube example.
-6. (SynaptotagminC2A.ipynb) Notebook to reproduce the results for a protein example. The data of the synaptotagmin C2A domain is available upon request.
+4. (Toymodel_2Systems.ipynb) Notebook to reproduce the results for a simple truly independent 2D system. Typical runtime (cpu): 2 min
+5. (10Cube.ipynb) Notebook to reproduce the results for the 10-Cube example. Typical runtime (cpu): 5 min
+6. (SynaptotagminC2A.ipynb) Notebook to reproduce the results for a protein example. The data of the synaptotagmin C2A domain is available upon request. Typical runtime (cuda): 1.5 hours
 
-The code was executed using the following package versions:
+The code was executed using the following package versions on a linux computer (debian bullseye):
 
 ```
 python=3.6 or higher
@@ -29,3 +29,34 @@ tensorboard=2.6.0
 h5py=1.10.4
 ```
 
+## Installation instructions
+
+The software dependencies can be installed with anaconda / miniconda. If you do not have miniconda or anaconda, please follow the instructions here: https://conda.io/miniconda.html
+
+The following command can be used to create a new conda environment and install all dependencies for the ivampnets scripts. 
+```bash
+conda create -n ivampnets pytorch=1.8.0 deeptime=0.2.9 numpy=1.19.5 matplotlib=3.1.3 jupyter h5py -c conda-forge
+```
+The new conda environment can be activated with
+```bash
+conda activate ivampnets
+```
+
+
+In case you are already a conda and jupyter notebook user with various environments, you can install your environment Python kernel via
+```bash
+python -m ipykernel install --user --name ivampnets
+```
+This repository including the python scripts and jupyter notebooks can be downloaded with 
+```bash
+git clone [email protected]:markovmodel/ivampnets.git
+```
+
+The following command will start the jupyter notebook server:
+```bash
+jupyter notebook
+```
+
+Your browser should pop up pointing to a list of notebooks once you navigate into the repository directory. If it's the wrong browser, add for example `--browser=firefox` or copy and paste the URL into the browser of your choice.
+
+The typical install time ranges from 5 minutes for conda-users to 20 minutes if conda has to be set up from scratch.