refactoring the documentation

docs/README.md

@@ -33,7 +33,7 @@ Then we define some elements and generate the permutation space:
 nodes = ['A', 'B', 'C', 'D']
 permutation_space = msa.make_permutation_space(n_permutations=1000, elements=nodes)
 ```
-This results in a list of tuples, our permutation space that has 1000 permutations in it, here are the top 5 ones:
+This results in a list of tuples, our permutation space that has 1000 permutations in it, here are the first 5 lines:
 ```python
 [('D', 'C', 'A', 'B'),
  ('A', 'D', 'C', 'B'),
@@ -88,7 +88,9 @@ that is the difference of what's in the combination space in that coalition and
  ('D', 'A'),
  ('C', 'D', 'A')]
 ```
-As you can see, for example when combination is `{'D'}` the corresponding complement is `('C', 'B', 'A')`. Note the difference in types, combination space is an `OrderedSet` of `frozenset`s so the Shapley value calculations are quicker while complement space is an `OrderedSet` of `Tuples` So handling it in your objective function is easier. Speaking of, let's make the worst objective function that just produces random values regardless of what's what (see the example `on ground-truth models.ipynb` for a more elaborate version.)[(see the example `on ground-truth models.ipynb` for a more elaborate version.)](https://github.com/kuffmode/msa/blob/main/examples/on%20ground-truth%20models.ipynb)
+As you can see, for example when combination is `{'D'}` the corresponding complement is `('C', 'B', 'A')`. Note the difference in types, combination space is an `OrderedSet` of `frozenset`s so the Shapley value calculations are quicker while complement space is an `OrderedSet` of `Tuples` So handling it in your objective function is easier. Speaking of, let's make the worst objective function that just produces random values regardless of what's what (see the example `on ground-truth models.ipynb` for a more elaborate version).
+For that we use the function 'random.randit' which returns random integers. 
+[(see the example `on ground-truth models.ipynb` for a more elaborate version.)](https://github.com/kuffmode/msa/blob/main/examples/on%20ground-truth%20models.ipynb)
 ```python
 def rnd(complements):
 	return np.random.randint(1, 10)

docs/examples/brain modes.ipynb

@@ -75,6 +75,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -85,16 +86,15 @@
     "\n",
     "Each mode represents a type of interaction between two (or more) regions that causes some deficit in a cognitive/behavioral domain. Let's look at the parts describing these modes in the paper: (bolded parts are by me)\n",
     "\n",
-    "- **Unicity:** Unicity, could depict the functional contributions of **isolated nodes**, which are hardly present in the highly and intricately connected mammalian nervous systems. Thus, this mode has been theoretically hypothesized but remains to be documented clinically.\n",
+    "- **Unicity:** \"In the unicity mode, the behavioral dificit is linked to the lesion of a single brain region, hence 100% performance is obtained solely when node A is intact, irrespective of whether node B is intact or damaged.\"\n",
     "\n",
     "\n",
     "- **Equivalence:** The equivalence brain mode has been documented theoretically and also clinically. Indeed, in the original paper describing brain modes, single lesions localized at two different levels along the cortico-spinal tract were characterized as **equally responsible** for motor weakness.\n",
     "\n",
     "\n",
-    "- **Association:** The association brain mode has been identified theoretically but remains to be better documented clinically, as it requires rare-to-find patients with selective lesions damaging **multiple regions within the same network.** This mode was originally illustrated in patients with unilateral lenticulostriate lesions(Godefroy et al., 1992) showing executive function impairment **only when, additionally, they suffered an associated cortical infarct**.\n",
+    "- **Association:** \"In the association mode, the behavioral deficit is observed only when two or more brain regions are simultaneously damaged; therefore 100% performance occurs when node A or node B are intact, but not when both are lesioned.\"\n",
     "\n",
-    "\n",
-    "- **Summation:** The summation mode has been documented both theoretically and clinically. For example, in language impairments, non-fluent aphasia was associated with lesions of putamen and surrounding structures while mutism was associated with **large lesion of the three frontal gyri and putamen**.\n",
+    "- **Summation:** \"100% performance occurs only when both nodes A and B are intact; however, when either node A or node B are lesioned there is a moderate deficit; whereas when both nodes A and B are damaged, then the deficit becomes severe.\"\n",
     "\n",
     "\n",
     "- **Mutual Inhibition:** [...]multivariate CART approaches originally used for their characterization failed to identify ‘paradoxical lesion cancellation’ effects,[...] This phenomenon described the **paradoxical improvement of performance deficits caused by a circumscribed lesion** thanks to a reversible or permanent suppression of activity in a second brain area interacting with the former.\n",
@@ -259,7 +259,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3.8.12 ('msa_echoes')",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -273,11 +273,11 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.10.6 (main, Nov 14 2022, 16:10:14) [GCC 11.3.0]"
   },
   "vscode": {
    "interpreter": {
-    "hash": "246903f92a9335ee7901984aee723bcb299db318829cc3c17eaabab75a65fba4"
+    "hash": "916dbcbb3f70747c44a77c7bcd40155683ae19c65e1c03b4aa3499c5328201f1"
    }
   }
  },