fix: third round on feedback implementation

bsb/connectivity/strategy.py

@@ -168,7 +168,7 @@ def connect(self, presyn_collection, postsyn_collection):
         Central method of each connection strategy. Given a pair of
         ``HemitypeCollection`` (one for each connection side), should connect
         cell population using the scaffold's (available as ``self.scaffold``)
-        :func:`~bsb.core.Scaffold.connect_cells` method.
+        :meth:`bsb.core.Scaffold.connect_cells` method.
 
         :param bsb.connectivity.strategy.HemitypeCollection presyn_collection:
           presynaptic filtered cell population.

docs/cells/intro.rst

@@ -2,21 +2,18 @@
 Cell Types
 ==========
 
-A cell types contains information about cell populations. There are 2 categories: cells,
-and entities. A cell has a position, while an entity does not. Cells can also have
-morphologies and orientations associated with them. On top of that, both cells and
-entities support additional arbitrary properties.
-
-A cell type is an abstract description of the population. During placement, the concrete
-data is generated in the form of a :doc:`PlacementSet </placement/placement-set>`. These can
-then be connected together into :class:`ConnectivitySets
+A cell type is an abstract description of a cell population. Cell populations are
+placed within `Partitions` according to :doc:`placement indications </placement/placement-indicators>`.
+You can also attach morphologies and orientations to them.
+During placement, the cell positions are generated in the form of a :doc:`PlacementSet </placement/placement-set>`.
+These can then be connected together into :class:`ConnectivitySets
 <.storage.interfaces.ConnectivitySet>`. Furthermore, during simulation, cell types are
 represented by **cell models**.
 
 .. rubric:: Basic configuration
 
-The :guilabel:`radius` and :guilabel:`density` are the 2 most basic :doc:`placement
-indications </placement/placement-indicators>`: they specify how large and dense the cells in the population generally are.
+The :guilabel:`radius` and :guilabel:`density` are the 2 most basic :doc:`placement indications </placement/placement-indicators>`:
+they specify how large and dense the cells in the population generally are.
 The :guilabel:`plotting` block allows you to specify formatting details.
 
 .. tab-set-code::
@@ -47,10 +44,12 @@ The :guilabel:`plotting` block allows you to specify formatting details.
 
 .. rubric:: Specifying spatial density
 
-You can set the spatial distribution for each cell type present in an
-:ref:`NrrdVoxels <voxel-partition>` partition.
+In the previous example, we were setting the number of cells to place within each partition
+based on a single density value. Let's imagine now that you want to describe the spatial
+distribution of the cell type spatial density for each voxel within your partition.
+This can be achieved with the :ref:`NrrdVoxels <voxel-partition>` partition.
 
-To do so, you should first attach your nrrd volumetric density file(s) to the partition with either
+To do so, you should first attach your NRRD volumetric density file(s) to the partition with either
 the :guilabel:`source` or :guilabel:`sources` blocks.
 Then, label the file(s) with the :guilabel:`keys` list block and refer to the :guilabel:`keys`
 in the :guilabel:`cell_types` with :guilabel:`density_key`:
@@ -124,10 +123,11 @@ in the :guilabel:`cell_types` with :guilabel:`density_key`:
 The NRRD files should contain voxel based volumetric density in unit of cells / voxel volume,
 where the voxel volume is in cubic unit of :guilabel:`voxel_size`.
 i.e., if :guilabel:`voxel_size` is in µm then the density file is in cells/µm^3.
+This implementation corresponds to an atlas-based reconstruction and you can find an example of
+a BSB configuration using the Allen Atlas in :doc:`this section </examples/atlas/atlas_placement>` .
 
 .. rubric:: Specifying morphologies
 
-
 The easiest way to associate a morphology to a cell type is by referencing the name it is stored under.
 There are more advanced ways as well, covered in our guide on :ref:`Morphology Selectors <morphology_selector>` .
 
@@ -162,4 +162,5 @@ There are more advanced ways as well, covered in our guide on :ref:`Morphology S
         )
 
 In this case we add two different morphologies labels:
-:guilabel:`cell_B_2` add the morphology with this name, :guilabel:`cells_A_*` add all the stored morphologies with name starting with ``cells_A_`` prefix.
+:guilabel:`cell_B_2` add the morphology with this name, :guilabel:`cells_A_*` add all the stored morphologies with name starting with ``cells_A_`` prefix.
+You can also apply transformation to your cell morphologies as discussed in :ref:`this section<transform>`.

docs/components/components.rst

@@ -12,7 +12,7 @@ If you want to read a step by step tutorial on how to make your own component, c
 
 For each component, the BSB provides interfaces, each with a set of functions that you must
 implement. By implementing these functions, the framework can seamlessly integrate your
-custom components.
+custom components into a BSB workflow. Neat!
 
 Here is how you do it (theoretically):
 

docs/getting-started/simulations/toc_point_neurons.rst

@@ -1,4 +1,4 @@
-Guides on Point-neurons simulation
+Guides on Point-neuron simulations
 ==================================
 
 .. toctree::

docs/getting-started/top-level-guide.rst

@@ -63,7 +63,10 @@ simulate the network. The ones that you will probably employ the most are:
   (and attach :guilabel:`Morphologies` when needed),
 * :guilabel:`Placement` places cells,
 * :guilabel:`Connectivity` connect cells,
-* :guilabel:`Simulation` simulates the resulting network.
+* :guilabel:`Simulation` simulates the resulting network. Each simulation consists of:
+    * :guilabel:`Cell Models` describe how to simulate a cell.
+    * :guilabel:`Connection Models` describe how to simulate cellular connections such as synapses and gap junctions.
+    * :guilabel:`Devices` describe the experimental setup by ways of input stimuli, recording devices, LFP probes, etc.
 
 Assembled together these components form a linear workflow that will build your network from scratch.