Changing the docs of the starting guide (#770)

* change docs * complete with nm fetching * complete with nm fetching * Apply suggestions from code review Co-authored-by: Robin De Schepper <robin.deschepper93@gmail.com> * Update include_morphos.rst Add proposed changes. * shuffling docs around a bit * add yaml example, fix line numbers * add moved configs back to git --------- Co-authored-by: Robin De Schepper <robin.deschepper93@gmail.com>
dbbs-lab · Nov 30, 2023 · 2f5477b · 2f5477b
1 parent 7d0df7f
commit 2f5477b
Show file tree

Hide file tree

Showing 22 changed files with 349 additions and 235 deletions.
diff --git a/README.md b/README.md
@@ -63,7 +63,7 @@ and connections:
 bsb compile -p
 ```
 
-This creates a [network file](bsb.readthedocs.io/guides/networks.html) and plots the network.
+This creates a [network file](bsb.readthedocs.io/getting-started/networks.html) and plots the network.
 
 ### Simulating a network
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,2 +1,3 @@
 !dev
+!getting-started
 _build/
diff --git a/docs/conf.py b/docs/conf.py
@@ -87,9 +87,9 @@
     "_build",
     "Thumbs.db",
     ".DS_Store",
-    "guides/labels.rst",
-    "guides/blender.rst",
-    "guides/layer.rst",
+    "getting-started/labels.rst",
+    "getting-started/blender.rst",
+    "getting-started/layer.rst",
 ]
 
 

diff --git a/docs/examples/networks/data.rst b/docs/examples/networks/data.rst
@@ -28,4 +28,8 @@ interface. This example shows how to access the cell positions of each populatio
 
 .. todo::
 
-   Document best ways to interact with the morphology data
+   Document best practices for the morphology data
+
+.. todo::
+
+   Document best practices for the connectivity data
diff --git a/docs/getting-started/basics.rst b/docs/getting-started/basics.rst
@@ -0,0 +1,12 @@
+==================================
+Creating networks and reading data
+==================================
+
+Greetings traveller, it seems you've created a network. Here are some examples to help
+you on your way.
+
+.. include:: /examples/networks/create.rst
+
+.. include:: /examples/networks/load.rst
+
+.. include:: /examples/networks/data.rst
diff --git a/docs/usage/getting-started.json → docs/getting-started/getting-started.json b/docs/usage/getting-started.json → docs/getting-started/getting-started.json
diff --git a/docs/usage/getting-started.rst → docs/getting-started/getting-started.rst b/docs/usage/getting-started.rst → docs/getting-started/getting-started.rst
@@ -1,10 +1,10 @@
 .. _get-started:
 
-###############
-Getting Started
-###############
+##################
+Your first network
+##################
 
-Follow the :doc:`/usage/installation`:
+Follow the :doc:`/getting-started/installation`:
 
 * Set up a new environment
 * Install the software into the environment
@@ -174,7 +174,7 @@ cells and connections in place, you're ready to move to the :ref:`simulations` s
 	    :link: include_morphos
 	    :link-type: ref
 
-	    Follow the rest of the guides and learn how to include morphologies.
+	    Follow the next chapter and learn how to include morphologies.
 
     .. grid-item-card:: :octicon:`tools;1em;sd-text-warning` Components
 	    :link: components
@@ -201,7 +201,7 @@ cells and connections in place, you're ready to move to the :ref:`simulations` s
 	    Learn to package your code for others to use!
 
     .. grid-item-card:: :octicon:`mark-github;1em;sd-text-warning` Contributing
-	    :link: https://github.com/dbbs-lab/bsb
+	    :link: https://github.com/dbbs-lab/bsb-core
 
 	    Help out the project by contributing code.
 

diff --git a/docs/usage/getting_started.py → docs/getting-started/getting_started.py b/docs/usage/getting_started.py → docs/getting-started/getting_started.py
diff --git a/docs/guides/include_morphos.json → docs/getting-started/include_morphos.json b/docs/guides/include_morphos.json → docs/getting-started/include_morphos.json
@@ -9,6 +9,17 @@
     "y": 600.0,
     "z": 400.0
   },
+  "morphologies": [
+    "neuron_A.swc",
+    {
+      "name": "neuron_B",
+      "file": "neuron2.swc"
+    },
+    {
+       "name": "neuron_NM",
+       "file": "nm://cell005_GroundTruth"
+    }
+  ],
   "regions": {
     "brain_region": {
       "type": "stack",
@@ -33,11 +44,7 @@
         "radius": 2,
         "density": 1e-3,
         "morphologies": [
-          {
-            "names": [
-              "my_neuron"
-            ]
-          }
+          "neuron_A"
         ]
       }
     },
@@ -46,14 +53,8 @@
         "radius": 7,
         "count": 10,
         "morphologies": [
-          {
-            "select": "from_neuromorpho",
-            "names": [
-              "cell005_GroundTruth",
-              "DD13-10-c8-3",
-              "10_666-GM9-He-Ctl-Chow-BNL16A-CA1Finished2e"
-            ]
-          }
+          "neuron_B",
+          "neuron_NM"
         ]
       }
     }

diff --git a/docs/guides/include_morphos.py → docs/getting-started/include_morphos.py b/docs/guides/include_morphos.py → docs/getting-started/include_morphos.py
@@ -1,7 +1,7 @@
 from bsb.core import Scaffold
 from bsb.config import from_json
 from bsb.topology import Stack
-from bsb.plotting import plot_network
+from bsb_plotting import plot_network
 import bsb.options
 
 bsb.options.verbosity = 3
@@ -14,26 +14,23 @@
         "top_layer",
     ]
 )
-config.cell_types.base_type.spatial.morphologies = [
-    dict(
-        names=["my_neuron"],
-    )
+config.morphologies = [
+    "neuron_A.swc",
+    {"name": "neuron_B", "file": "neuron2.swc"},
 ]
+
+config.cell_types.base_type.spatial.morphologies = ["neuron_A"]
+
+config.morphologies.append(
+    {"name": "neuron_NM", "file": "nm://cell005_GroundTruth"},
+)
+
 config.cell_types.add(
     "top_type",
     spatial=dict(
         radius=7,
         count=10,
-        morphologies=[
-            dict(
-                select="from_neuromorpho",
-                names=[
-                    "cell005_GroundTruth",
-                    "DD13-10-c8-3",
-                    "10_666-GM9-He-Ctl-Chow-BNL16A-CA1Finished2e",
-                ],
-            )
-        ],
+        morphologies=["neuron_B", "neuron_NM"],
     ),
 )
 config.placement.add(
@@ -50,5 +47,6 @@
 )
 
 network = Scaffold(config)
+
 network.compile()
 plot_network(network)
diff --git a/docs/getting-started/include_morphos.rst b/docs/getting-started/include_morphos.rst
@@ -0,0 +1,198 @@
+.. _include_morphos:
+
+Adding morphologies
+===================
+
+.. note::
+
+    This guide is a continuation of the |:books:| :doc:`Getting Started guide </getting-started/getting-started>`.
+
+.. hint::
+
+    To follow along, download 2 morphologies from
+    `NeuroMorpho <https://neuromorpho.org/>`_ and save them as ``neuron_A.swc`` and
+    ``neuron2.swc`` locally.
+
+Previously we constructed a stacked double layer topology, with 2 cell types. We then
+connected them in an all-to-all fashion. The next step assigns
+:doc:`morphologies </morphologies/intro>` to our cells, and connects the cells based on
+the intersection of their morphologies!
+
+Morphologies can be loaded from local files or to fetch from remote sources, like NeuroMorpho.
+
+Using local files
+-----------------
+
+You can declare source morphologies in the root :guilabel:`morphologies` list:
+
+.. tab-set-code::
+
+  .. literalinclude:: include_morphos.yaml
+    :language: yaml
+    :lines: 9-10
+
+  .. code-block:: json
+
+       "morphologies": [
+         "neuron_A"
+       ],
+
+  .. literalinclude:: include_morphos.py
+    :language: python
+    :lines: 17,18,20
+
+In this case a morphology is created from ``neuron_A.swc`` and given the name ``"neuron_A"``.
+As a second step, we associate this morphology to the ``base_type`` by referencing it by name
+in :guilabel:`cell_types.base_type.spatial.morphologies`:
+
+.. tab-set-code::
+
+  .. literalinclude:: include_morphos.yaml
+    :language: yaml
+    :lines: 30-36
+    :emphasize-lines: 6-7
+
+  .. literalinclude:: include_morphos.json
+    :language: json
+    :lines: 41-50
+    :emphasize-lines: 6-8
+
+  .. literalinclude:: include_morphos.py
+    :language: python
+    :lines: 22
+
+
+By default the name assigned to the morphology is the file name without its extension (here ``.swc``). To
+change the name we can use a node with a :guilabel:`name` and :guilabel:`file`:
+
+.. tab-set-code::
+
+  .. literalinclude:: include_morphos.yaml
+    :language: yaml
+    :lines: 9-12
+    :emphasize-lines: 3-4
+
+  .. literalinclude:: include_morphos.json
+    :language: json
+    :lines: 12-17
+    :emphasize-lines: 4-5
+
+  .. literalinclude:: include_morphos.py
+    :language: python
+    :lines: 17-20
+    :emphasize-lines: 3
+
+It is also possible to add a pipeline to perform transformations on the loaded
+morphology. Pipelines can be added by adding a :guilabel`pipeline` list to the morphology node.
+Each item in the list may either be a string reference to an importable function or a method of
+the :class:`~bsb.morphologies.Morphology` class. To pass parameters, use a node with the
+function reference placed in the guilabel:`func` attribute, and a :guilabel:`parameters` list.
+Here is an example what that would look like:
+
+.. tab-set-code::
+
+  .. code-block:: yaml
+
+    morphologies:
+      - file: my_neuron.swc
+        pipeline:
+          - center
+          - my_module.add_axon
+          - func: rotate
+            parameters:
+              - [20, 0, 20]
+
+  .. code-block:: json
+
+    "morphologies": [
+      {
+        "file": "my_neuron.swc",
+        "pipeline": [
+          "center",
+          "my_module.add_axon",
+          {
+            "func": "rotate",
+            "parameters": [
+              [20, 0, 20]
+            ]
+          },
+        ],
+      }
+    ]
+
+.. note::
+
+  Parameters are passed positionally, keyword arguments must be passed in the order they appear
+  in in the signature. If your target function has a complicated signature or keyword-only
+  arguments, create a wrapping function and target that instead.
+
+Fetching with alternative URI schemes
+-------------------------------------
+
+The framework uses URI schemes to define the path of the sources that are loaded. By
+default it tries to load from the project local folder, using the``file`` URI scheme (``"file://"``).
+It is possible to fetch morphologies directly from `neuromorpho.org
+<https://neuromorpho.org>`_ using the NeuroMorpho scheme (``"nm://"``). You can refer to
+NeuroMorpho morphologies by their morphology name:
+
+.. figure:: /images/nm_what.png
+  :figwidth: 450px
+  :align: center
+
+.. tab-set-code::
+
+  .. literalinclude:: include_morphos.yaml
+    :language: yaml
+    :lines: 9-12
+    :emphasize-lines: 3-4
+
+  .. literalinclude:: include_morphos.json
+    :language: json
+    :lines: 12-22,41-61
+    :emphasize-lines: 7-10,27-30
+
+  .. literalinclude:: include_morphos.py
+    :language: python
+    :lines: 24-35
+    :emphasize-lines: 2,10
+
+
+Morphology intersection
+-----------------------
+
+Now that we have assigned morphologies to our cell types, we can use morphology-based
+connection strategies such as :class:`~.connectivity.detailed.voxel_intersection.VoxelIntersection`:
+
+.. tab-set-code::
+
+  .. literalinclude:: include_morphos.yaml
+    :language: yaml
+    :lines: 56-64
+
+  .. literalinclude:: include_morphos.json
+    :language: json
+    :lines: 74-84
+
+  .. literalinclude:: include_morphos.py
+    :language: python
+    :lines: 42-47
+
+.. note::
+
+  If there's multiple morphologies per cell type, they'll be assigned randomly, unless you
+  specify a :class:`~.placement.distributor.MorphologyDistributor`.
+
+
+Recap
+-----
+
+.. tab-set-code::
+
+  .. literalinclude:: include_morphos.yaml
+    :language: yaml
+
+  .. literalinclude:: include_morphos.json
+    :language: json
+
+  .. literalinclude:: include_morphos.py
+    :language: python