changed src to source

vignettes/2_moon.ipynb

@@ -192,6 +192,48 @@
     "sig_input = nc.filter_input_nodes_not_in_pkn(sig_input, meta_network)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Network compression"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is one of the most important parts of this vignette. Here, we aim to remove redundant information from the network, in order to reduce its size without compromising the information contained in it. A common example would be the following:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"./img/network_compr.png\" height=\"250\" />"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here, the nodes B and C have been compressed into a single node, Parent of D. There is no loss of information because B and C regulate D in the same way (same edge sign), and A also regulates B and C the same way (same edge sign). However, in other cases, we would lose information:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"./img/network_compression_nocases.png\" height=\"250\" />"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In case 1, nodes B and C cannot be compressed because they exert opposite regulation onto D. If we compressed this situation, we would have a duplicated edge with opposite weights, which would create issues when computing the moon scores. Similarly in case 2, even B and C have the same edge signs towards D, A exert opposite regulation towards B and C. If we compressed B and C, we would have a duplicated edge between A and Parent of D, which poses similar issues as Case 1."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 11,
@@ -201,6 +243,13 @@
     "meta_network_compressed, signatures, dup_parents = nc.compress_same_children(meta_network, sig_input, metab_input) # equals R"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We clean the network again in case some self loops arose"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 12,
@@ -214,7 +263,20 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now, the network has been compressed by around a third of its original size, which increases computational efficiency without losing information.\n",
+    "## 3. MOON scoring"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now it is time to compute the MOON scores from the compressed network. The network has been compressed by around a third of its original size, which increases computational efficiency. We will use the metabolic inputs and the signalling inputs to compute the MOON scores. After each optimisation, we check the sign consistency of the MOON scores, and remove those edges that turn out to be incoherent (the real TF enrichment scores are compared against the computed MOON scores and the sign of the edge). If there are incoherent edges, the function computes the MOON scores on the reduced network. The loop continues until it reaches a maximum number of tries (in our example, 10) or there are no incoherent edges left."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "We can get now the GRN from DoRothEA, filtering by levels of confidence A and B."
    ]
   },
@@ -359,14 +421,6 @@
     "tf_regn = dc.get_dorothea(levels = ['A', 'B'])"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Now, we are ready to compute the moon scores on the compressed network, using the signalling network inputs and the metabolic measurements.\n",
-    "MOON will run iteratively until the solution converges (there are no incoherent edges), or a maximum of 10 iterations happen."
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": 14,
@@ -423,14 +477,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "the differences here arise from different floats in the original network, which is then amplified after subsequent iterations"
+    "## 4. Decompression and solution network"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now, we perform the decompression of the network, mapping the compressed nodes to their original components."
+    "Once the MOON scores are computed, we need to restore the uncompressed nodes that were compressed in section 2. For this, we will use the signatures that we obtained when we compressed the network to map back the original nodes to the compressed ones. After that, we can retrieve a solution network that contains the nodes (with the subsequent MOON scores) that are in the vicinity of the signalling input(s) and are sign consistent in terms of signed interactions."
    ]
   },
   {
@@ -442,6 +496,13 @@
     "moon_res_dec = nc.decompress_moon_result(moon_res, signatures, dup_parents, meta_network_compressed)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we perform the decompression of the network, mapping the compressed nodes to their original components."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -482,6 +543,13 @@
    "source": [
     "translated_network, att_translated = nc.translate_res(res_network, att, mapping_dict)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The resulted network can be used now for visualization purposes. Since the network is quite big, it will not be shown in this notebook."
+   ]
   }
  ],
  "metadata": {