Skip to content

Commit

Permalink
Update tutorial
Browse files Browse the repository at this point in the history
  • Loading branch information
@ondrej33
ondrej33 committed Oct 22, 2023
1 parent 50f3a4e commit 65e8f3f
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 36 deletions.
Binary file added tutorial/images/2_3.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
109 changes: 73 additions & 36 deletions tutorial/tutorial.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,18 @@
}
},
"source": [
"This notebook illustrates the workflow of BNClassifier. We present the workflow on a case study using a PSBN model of MAPK pathway, as described in Section 6.1 of the paper.\n",
"This notebook illustrates the workflow of `BNClassifier`. We present the workflow on a case study using a PSBN model of the MAPK pathway, as described in Section 6.1 of the paper.\n",
"\n",
"We give a step-by-step guide how to replicate the results and observations. In the first part, we show how to run the classification and explore its inputs/outputs by executing Python cells of this notebook. In the second part, we continue by illustrating the GUI capabilities, providing screen-shots and commentaries."
"We give a step-by-step guide on how to replicate the results and observations. In the first part, we show how to run the classification and explore its inputs/outputs by executing the Python cells of this notebook. In the second part, we illustrate the GUI capabilities, providing animation, screenshots and commentaries. Please refer to the enclosed `Manual` for more information on the tool."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"First, please read the installation instructions in the provided README.\n",
"First, please read the installation instructions provided in the main README.\n",
"\n",
"After everything is successfully set up , start executing the following cells, one by one, to run the classification process."
"After everything is successfully set up, start executing the following cells, one by one, to run the classification process."
]
},
{
Expand Down Expand Up @@ -60,12 +60,12 @@
"source": [
"## Exploring the input\n",
"\n",
"We first demonstrate how the input for the HCTL classification looks like. It is essentially a combination of:\n",
"We first demonstrate what the input for the HCTL classification looks like. It is essentially a combination of:\n",
"- A partially specified Boolean network and corresponding influences.\n",
"- Required properties (HCTL formulae) which restrict the set of valid model interpretations.\n",
"- Classification properties (HCTL formulae) that are used to classify the valid models.\n",
"\n",
"We can explore the PSBN model and the properties:"
"We can explore the PSBN model and its properties:"
]
},
{
Expand Down Expand Up @@ -134,7 +134,17 @@
}
},
"source": [
"We see that required properties are given as simple HCTL formulae (in our case a single formula). On the other hand, classification properties also have names, which are used in post-processing of the classification results (as we'll see later)."
"The required properties are given as plain HCTL formulae (in our case, it is a single formula). On the other hand, classification properties also have names, which are used in the post-processing of the classification results (as we'll see later). The format of the input is further described in the tool's Manual.iour)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To reiterate, these properties mean the following:\n",
"- `p1`: Every attractor state is a fixed point with Apoptosis active (the system always converges to programmed cell death; \"healthy\" behaviour).\n",
"- `p2`, `p3`: Growth Arrest (`p2`) or Proliferation (`p3`) remain active in some attractor (programmed cell death may not be achieved; possibly \"problematic\" behaviour).\n",
"- `p4`: Proliferation and Apoptosis are simultaneously active in an attractor state (biologically \"unrealistic\" behaviour)."
]
},
{
Expand All @@ -145,7 +155,7 @@
}
},
"source": [
"## Running the classification procedure"
"## Running the classification engine"
]
},
{
Expand All @@ -156,11 +166,11 @@
}
},
"source": [
"The classifier categorizes PSBN interpretations to classes based on properties they satisfy. First, only the interpretations satisfying all required properties are computed. The set of remaining interpretations is decomposed into categories, where each class contains interpretations that (universally) satisfy the same set of properties.\n",
"The classifier categorizes PSBN interpretations into classes based on the properties they satisfy. First, only the interpretations satisfying all required properties are computed. The set of remaining interpretations is decomposed into categories, where each class contains interpretations that (universally) satisfy the same set of properties.\n",
"\n",
"It is fairly straightforward to run the classification. You just provide a path to the input file with annotated model, and a path for the result bundle. Everything else is handled internally.\n",
"It is fairly straightforward to run the classification from Jupyter notebooks. You provide a path to the input file with an annotated model and a path for the result bundle. Everything else is handled internally.\n",
"\n",
"Note that this step might take few minutes. The time depends on the machine, but should be around 2-3 minutes."
"Note that this step might take a few minutes. The time depends on the machine, but it should generally be around 1-3 minutes."
]
},
{
Expand Down Expand Up @@ -200,7 +210,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The result is a zip archive with:\n",
"The result is a `zip-archive` with:\n",
"- A text report regarding the whole classification procedure.\n",
"- Raw BDD files encoding each non-empty class.\n",
"- The original annotated input model (to reconstruct the results if needed)."
Expand All @@ -214,7 +224,7 @@
}
},
"source": [
"Before loading the output bundle into our interactive GUI explorer, we show how to obtain some general information about the results directly. We can load the dictionary with all categories - a map of `string -> color set` pairs (colors representing individual interpretations). The string \"key\" represents a binary encoding of which properties are satisfied by the particular class (in this encoding, properties are ordered alphabetically)."
"Before loading the output bundle into our interactive GUI explorer, we show how to directly obtain general information about the results. We can load the dictionary with all categories - a map of `string -> color set` pairs (colors representing individual interpretations). The string \"key\" represents a binary encoding of which properties are satisfied by the particular class (in this encoding, properties are ordered alphabetically). We can further analyse the results in Python, but that is out of the scope of this tutorial."
]
},
{
Expand All @@ -230,7 +240,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
"{'0001': ColorSet(cardinality=3), '0100': ColorSet(cardinality=3), '1100': ColorSet(cardinality=9)}\n"
"{'1100': ColorSet(cardinality=9), '0001': ColorSet(cardinality=3), '0100': ColorSet(cardinality=3)}\n"
]
}
],
Expand Down Expand Up @@ -265,7 +275,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Let's analyze the results in the Decision Tree Explorer GUI. Before starting the GUI, you can watch a summary of all the steps (that we'll go through later) in the following GIF animation. Once it finishes (less than 1min), feel free to follow the step-by-step guide with commentary below it. Note that the animation loops."
"Let's analyze the results in the Decision Tree Explorer GUI. Before starting the GUI, you can watch a summary of all the steps (that we'll go through later) in the following GIF animation. Once it finishes (less than 1 minute), feel free to follow the step-by-step guide with commentary below it. Note that the animation loops."
]
},
{
Expand All @@ -279,7 +289,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"To start the GUI, please execute the following cell. It executes the provided binary."
"To start the GUI, please run the following cell. It executes the provided binary."
]
},
{
Expand All @@ -295,7 +305,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"You should see the following screen with simple navigation instructions. At the same time, a File Dialog should open. Select the results bundle `classification-archive.zip` that we generated in previous section."
"You should see the following screen with simple navigation instructions. At the same time, a File Dialog should open. Select the results bundle `classification-archive.zip` that we generated in the previous section."
]
},
{
Expand All @@ -320,12 +330,24 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The tree's root node with the text `Mixed outcomes (3 types)` should appear. By scrolling, you can zoom it out. You can move the node across the screen by dragging (at the empty space). \n",
"\n",
"The tree's root node with the text `Mixed outcomes (3 types)` should appear. By scrolling, you can zoom it out. You can move the node across the screen by dragging (at the empty space). "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"![Loaded-root](images/2_3.png)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Once you adjust the node's size and position, click on the node. On the left, a panel describing the node should appear (see following image). In this panel, you can see: \n",
"\n",
"- TODO\n",
"- TODO..."
"- The root node represents interpretations of three different classes. For each class (\"behaviour\"), we see which properties it corresponds to, how many interpretations (witnesses) it represents, and what percentage of total number of interpretations it is. Particularly, nine interpretations satisfy properties `p1` and `p2`, three satisfy only `p2`, and three only `p4` (as we have seen before).\n",
"- Property `p3` is `universally invalid` in the whole tree - no interpretation satisfies it."
]
},
{
Expand All @@ -339,7 +361,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The tool offers two ways to expand the node - manually and automatically. To first try out the manual expanding, click on the `Make decision` button. Several possible `Decision Attributes` appear. Select the second item, `DNA_damage`."
"The tool offers two ways to expand the node - automatically and manually. First, to try out the manual expanding, click on the `Make decision` button. Several possible `Decision Attributes` appear."
]
},
{
Expand All @@ -349,6 +371,13 @@
"![Click-manual-expand](images/4.png)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Decision attributes can be sorted by several metrics. More on that in the Manual. Select the second item, `DNA_damage`."
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand All @@ -367,9 +396,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that the tree layout algorithm is non-deterministic, and therefore, the side of the branches may be switched. We thus refer to child nodes as \"positive\" (the one to which the green arrow points) and \"negative\" (the one to which the red arrow points). Sometimes, the child nodes switch positions during tree expansion to allow for a better layout.\n",
"We refer to child nodes as \"positive\" (the one to which the green arrow points) and \"negative\" (the one to which the red arrow points). The positive child node represents interpretations where the parameter `DNA_damage` is set to `True`.\n",
"Note that the tree layout algorithm is non-deterministic, and therefore, the side of the branches may be switched.\n",
"Sometimes, the child nodes switch positions during tree expansion to allow for a better layout.\n",
"\n",
"Let's now expand the negative `Mixed` child node (on a \"red path\" from the root). Select the node. On the left, a different panel should appear again."
"Let's focus on the negative `Mixed` child node (on a \"red path\" from the root). Select the node."
]
},
{
Expand All @@ -383,7 +414,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Click on the button `Auto expand (1 level)`, which automatically chooses a decision for this node."
"On the left, a different panel should appear again. We see that this node now represents only two different classes. Thus, when `DNA_damage` is set to `False`, we can no longer reach a class where `p2` is satisfied and `p1` is not.\n",
"\n",
"Click on the button `Auto expand (1 level)`, automatically choosing a decision attribute for this node and expanding it."
]
},
{
Expand All @@ -397,9 +430,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The tree should expand - the selected node becomes a `decision node` labelled by `TGFBR_stimulus`, and two new nodes appear. \n",
"The tree should again expand - the selected node becomes a `decision node` labelled by `TGFBR_stimulus`, and two new nodes appear. \n",
"\n",
"The new nodes are both leaf nodes. They each represent a subset of interpretations of a single class. To see more, click on the leaf node labelled by `p4 (3)`. This node represents three interpretations that satisfy a single classification property p4. A panel on the left should appear, as shown below.\n"
"The new nodes are both leaf nodes. They each represent a subset of interpretations of a single class. To see more, click on the leaf node labelled by `p4 (3)`. From the node's label, we see that it represents three interpretations that satisfy a single classification property `p4`. "
]
},
{
Expand All @@ -413,7 +446,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"In a leaf node, you can generate `witness networks`. TODO"
"A different panel on the left should appear, as shown below. There, we see a set of `Necessary conditions` to reach the node. These correspond to the path from the root node. In particular, both `TGFBR_stimulus` and `DNA_damage` must be set to `False` (denoted by the red colour).\n",
"\n",
"Properties satisfied in the node are also highlighted. In this case, all three BN instances represented by the node admit attractors where `Apoptosis` and `Proliferation` are active at the same time.\n",
"\n",
"In a leaf node, you can generate `witness networks` (BN instances). Click on `Generate network(s)` button to export a particular BN instance. A `File save dialog` should appear."
]
},
{
Expand All @@ -427,7 +464,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, let's expand the rest of the tree. Click on the remaining `Mixed outcomes` node. In the panel that appears (see below), change the depth of `Automatic tree expansion` to 3 using the `Depth` toggle. That will expand the tree fully."
"Now, let's automatically expand the rest of the tree. Click on the remaining `Mixed outcomes` node. In the panel that appears (see below), change the depth of `Automatic tree expansion` to 3 using the `Depth` toggle (there is a maximum of 3 remaining decision attributes)."
]
},
{
Expand All @@ -441,7 +478,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
" Click on the button `Auto expand (3 levels)`. The tree expands, as shown below (note that some branches might be mirrored, as discussed above)."
" Click on the button `Auto expand (3 levels)`."
]
},
{
Expand All @@ -455,42 +492,42 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"![Fully-expanded-tree](images/12.png)"
"The tree fully expands, as shown below (note that some branches might potentially be mirrored, as discussed above)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"TODO: something about the tree."
"![Fully-expanded-tree](images/12.png)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also export the current tree in the `dot` format. TODO"
"We can now explore the conditions leading to the validity of individual properties. In particular, we see that the property `p4` occurs if and only if both `DNA_damage` and `TGFBR_stimulus` are inactive. The decision tree also guides us towards conditions that ensure proper programmed cell death (`p1`). For example, we see that the presence of `TGFBR_stimulus` is a sufficient condition for `p1`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"![Export](images/13.png)"
"We can also export the current tree in the `dot` format. Click on the `Export decision tree` button in the lower left corner. A `File save dialog` should appear."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"TODO: loading it back here (either the results, or prepared version)"
"![Export](images/13.png)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"TODO: reverting decisions?"
"And this concludes the Tutorial. The tool's `Manual` gives further information on the GUI details."
]
},
{
Expand Down

0 comments on commit 65e8f3f

Please sign in to comment.