markdown overhaul

Author: cwehmeyer

notebooks/00-pentapeptide-showcase.ipynb

@@ -37,7 +37,10 @@
    "metadata": {},
    "source": [
     "## Case 1: preprocessed, two-dimensional data (toy model)\n",
-    "We load the two-dimensional trajectory from an archive using numpy, directly discretize the full space using $k$-means clustering, visualize the marginal and joint distributions of both components as well as the cluster centers, and show the implied timescale (ITS) convergence:"
+    "We load the two-dimensional trajectory from an archive using numpy,\n",
+    "directly discretize the full space using $k$-means clustering,\n",
+    "visualize the marginal and joint distributions of both components as well as the cluster centers,\n",
+    "and show the implied timescale (ITS) convergence:"
    ]
   },
   {
@@ -71,9 +74,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The plots show us the marginal (left panel) and joint distributions along with the cluster centers (middle panel). The implied timescales are converged (right panel). \n",
+    "The plots show us the marginal (left panel) and joint distributions along with the cluster centers (middle panel).\n",
+    "The implied timescales are converged (right panel). \n",
     "\n",
-    "Before we proceed, let's have a look at the implied timescales error bars. They were computed from a Bayesian MSM, as requested by the `errors='bayes'` argument of the `pyemma.msm.its()` function. As mentioned before, Bayesian MSMs incorporate a sample of transition matrices. Target properties such as implied timescales can now simply be computed from the individual matrices. Thereby, the posterior distributions of these properties can be estimated. The ITS plot shows a confidence interval that contains $95\\%$ of the Bayesian samples."
+    "Before we proceed, let's have a look at the implied timescales error bars.\n",
+    "They were computed from a Bayesian MSM, as requested by the `errors='bayes'` argument of the `pyemma.msm.its()` function.\n",
+    "As mentioned before, Bayesian MSMs incorporate a sample of transition matrices.\n",
+    "Target properties such as implied timescales can now simply be computed from the individual matrices.\n",
+    "Thereby, the posterior distributions of these properties can be estimated.\n",
+    "The ITS plot shows a confidence interval that contains $95\\%$ of the Bayesian samples."
    ]
   },
   {
@@ -89,7 +98,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For any PyEMMA method that derives target properties from MSMs, sample mean and confidence intervals (as defined by the function argument above) are directly accessible with  `sample_mean()` and `sample_conf()`. Further, `sample_std()` is available for computing the standard deviation. In the more general case, it might be interesting to extract the full sample of a function evaluation with `sample_f()`. The syntax is equivalent for all those functions."
+    "For any PyEMMA method that derives target properties from MSMs, sample mean and confidence intervals (as defined by the function argument above) are directly accessible with  `sample_mean()` and `sample_conf()`.\n",
+    "Further, `sample_std()` is available for computing the standard deviation.\n",
+    "In the more general case, it might be interesting to extract the full sample of a function evaluation with `sample_f()`.\n",
+    "The syntax is equivalent for all those functions."
    ]
   },
   {
@@ -111,7 +123,8 @@
    "source": [
     "Please note that sample mean and maximum likelihood estimates are not identical and generally do not provide numerically identical results.\n",
     "\n",
-    "Now, for the sake of simplicity we proceed with the analysis of a maximum likelihood MSM. We estimate it at lag time $1$ step."
+    "Now, for the sake of simplicity we proceed with the analysis of a maximum likelihood MSM.\n",
+    "We estimate it at lag time $1$ step..."
    ]
   },
   {
@@ -127,7 +140,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "and check for disconnectivity. The MSM is constructed on the largest set of discrete states that are (reversibly) connected. The `active_state_fraction` and `active_count_fraction` show us the fraction of discrete states and transition counts from our data which are part of this largest set and, thus, used for the model:"
+    "... and check for disconnectivity.\n",
+    "The MSM is constructed on the largest set of discrete states that are (reversibly) connected.\n",
+    "The `active_state_fraction` and `active_count_fraction` show us the fraction of discrete states and transition counts from our data which are part of this largest set and, thus, used for the model:"
    ]
   },
   {
@@ -146,7 +161,8 @@
    "source": [
     "The fraction is, in both cases, $1$ and, thus, we have no disconnected states (which we would have to exclude from our analysis).\n",
     "\n",
-    "If there were any disconnectivities in our data (fractions $<1$), we could access the indices of the **active states** (members of the largest connected set) via the `active_set` attribute:"
+    "If there were any disconnectivities in our data (fractions $<1$),\n",
+    "we could access the indices of the **active states** (members of the largest connected set) via the `active_set` attribute:"
    ]
   },
   {
@@ -162,7 +178,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "With this potential issue out of the way, we can extract our first (stationary/thermodynamic) property, the `stationary_distribution` or, as a shortcut, `pi`:"
+    "With this potential issue out of the way, we can extract our first (stationary/thermodynamic) property,\n",
+    "the `stationary_distribution` or, as a shortcut, `pi`:"
    ]
   },
   {
@@ -216,7 +233,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The stationary distribution can also be used to correct the `pyemma.plots.plot_free_energy()` function. This might be necessary if the data points are not sampled from global equilibrium.\n",
+    "The stationary distribution can also be used to correct the `pyemma.plots.plot_free_energy()` function.\n",
+    "This might be necessary if the data points are not sampled from global equilibrium.\n",
     "\n",
     "In this case, we assign the weight of the corresponding discrete state to each data point and pass this information to the plotting function via its `weights` parameter:"
    ]
@@ -229,7 +247,7 @@
    "source": [
     "fig, ax, misc = pyemma.plots.plot_free_energy(\n",
     "    *data.T,\n",
-    "    weights=msm.pi[cluster.dtrajs[0]],\n",
+    "    weights=np.concatenate(msm.trajectory_weights()),\n",
     "    legacy=False)\n",
     "ax.set_xlabel('$x$')\n",
     "ax.set_ylabel('$y$')\n",
@@ -336,7 +354,11 @@
    "metadata": {},
    "source": [
     "## Case 2: low-dimensional molecular dynamics data (alanine dipeptide)\n",
-    "We fetch the alanine dipeptide data set, load the backbone torsions into memory, directly discretize the full space using $k$-means clustering, visualize the margial and joint distributions of both components as well as the cluster centers, and show the ITS convergence to help selecting a suitable lag time:"
+    "\n",
+    "We fetch the alanine dipeptide data set, load the backbone torsions into memory,\n",
+    "directly discretize the full space using $k$-means clustering,\n",
+    "visualize the margial and joint distributions of both components as well as the cluster centers,\n",
+    "and show the ITS convergence to help selecting a suitable lag time:"
    ]
   },
   {
@@ -376,7 +398,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The plots show us the marginal (left panel) and joint distributions along with the cluster centers (middle panel). The implied timescales are converged (right panel). \n",
+    "The plots show us the marginal (left panel) and joint distributions along with the cluster centers (middle panel).\n",
+    "The implied timescales are converged (right panel). \n",
     "\n",
     "We then estimate an MSM at lag time $10$ ps and visualize the stationary distribution by coloring all data points according to the stationary weight of the discrete state they belong to:"
    ]
@@ -464,7 +487,10 @@
    "source": [
     "We note that four metastable states are a reasonable choice for our MSM.\n",
     "\n",
-    "In general, the number of metastable states is a modeler's choice; it is adjusted to map the kinetics to be modeled. In the current example, increasing the resolution with a higher number of metastable states or resolving only the slowest process between $2$ states would be possible. However, the number of states is not arbitrary as the observed processes in metastable state space need not be Markovian in general. A failed Chapman-Kolmogorov test can thus also hint to a bad choice of the metastable state number.\n",
+    "In general, the number of metastable states is a modeler's choice; it is adjusted to map the kinetics to be modeled.\n",
+    "In the current example, increasing the resolution with a higher number of metastable states or resolving only the slowest process between $2$ states would be possible.\n",
+    "However, the number of states is not arbitrary as the observed processes in metastable state space need not be Markovian in general.\n",
+    "A failed Chapman-Kolmogorov test can thus also hint to a bad choice of the metastable state number.\n",
     "\n",
     "In order to perform further analysis, we save the model to disk:"
    ]
@@ -738,7 +764,9 @@
    "metadata": {},
    "source": [
     "#### Exercise 5\n",
-    "Save the MSM, Bayesian MSM and Cluster objects to the same file as before. Use the model names `ala2tica_msm`, `ala2tica_bayesian_msm` and `ala2tica_cluster`, respectively. Further, include the TICA object with model name `ala2tica_tica`."
+    "Save the MSM, Bayesian MSM and Cluster objects to the same file as before.\n",
+    "Use the model names `ala2tica_msm`, `ala2tica_bayesian_msm` and `ala2tica_cluster`, respectively.\n",
+    "Further, include the TICA object with model name `ala2tica_tica`."
    ]
   },
   {