From fa9525143da4cfebe188c55f9496ba03929b70c6 Mon Sep 17 00:00:00 2001 From: drodarie Date: Tue, 7 Jan 2025 19:02:52 +0100 Subject: [PATCH] fix: second round of feedback implementation. --- README.md | 18 ++++++++++----- docs/cells/intro.rst | 22 +++++++++---------- docs/cli/commands.rst | 2 +- docs/cli/intro.rst | 1 - docs/components/components.rst | 4 ++-- .../simulations/guide_nest.rst | 2 +- .../simulations/toc_point_neurons.rst | 4 ++-- docs/getting-started/top-level-guide.rst | 21 +++++++++++++----- docs/morphologies/intro.rst | 2 ++ 9 files changed, 47 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index ab38c910..84594599 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ # BSB: A component framework for neural modelling Developed by the Department of Brain and Behavioral Sciences at the University of Pavia, -the BSB is a component framework for neural modelling, which focusses on component +the BSB is a component framework for neural modelling, which focuses on component declarations to piece together a model. The component declarations can be made in any supported configuration language, or using the library functions in Python. It offers parallel reconstruction and simulation of any network topology, placement and/or @@ -29,7 +29,7 @@ pip install "bsb" ``` Advanced users looking to control install an unconventional combination of plugins might -be better of installing just this package, and the desired plugins: +be better off installing just this package, and the desired plugins: ``` pip install "bsb-core" @@ -65,20 +65,28 @@ bsb new my_model --quickstart cd my_model ``` +This will create a `my_model` folder for you with some starter files. It should contain: + +- `network_configuration.yaml`: A configuration file in which your network will be described. +- A `pyproject.toml` file: This file uses the TOML syntax to set configuration values for the BSB. +- A `placement.py` and `connectome.py` files if you want to make your own components. + ### Reconstructing a network -You can use your project to create reconstructions of your model, generating cell positions +Within your project folder, you can create reconstructions of your model, generating cell positions and connections: ``` bsb compile ``` -This creates a network file. +The `compile` command should produce a network file located in your project +folder based on your configuration file. ### Simulating a network -The default project currently contains no simulation config. +The starter project contains no simulation configuration but the documentation provides tutorials +for the neural simulators supported by the BSB. # Contributing diff --git a/docs/cells/intro.rst b/docs/cells/intro.rst index ed83a834..948f9811 100644 --- a/docs/cells/intro.rst +++ b/docs/cells/intro.rst @@ -16,7 +16,7 @@ represented by **cell models**. .. rubric:: Basic configuration The :guilabel:`radius` and :guilabel:`density` are the 2 most basic :doc:`placement -indications `, they specify how large and dense the cells in the population generally are. +indications `: 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,7 +47,7 @@ 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 a +You can set the spatial distribution for each cell type present in an :ref:`NrrdVoxels ` partition. To do so, you should first attach your nrrd volumetric density file(s) to the partition with either @@ -111,25 +111,25 @@ in the :guilabel:`cell_types` with :guilabel:`density_key`: ) config.cell_types.add( - "first_cell_type", - spatial=dict(radius=10, density_key="first_cell_type_density") - plotting=dict(display_name="First Cell Type", color="pink",opacity="1.0") + "first_cell_type", + spatial=dict(radius=10, density_key="first_cell_type_density") + plotting=dict(display_name="First Cell Type", color="pink",opacity="1.0") ) config.cell_types.add( - "second_cell_type", - spatial=dict(radius=10, density_key="second_cell_type_density") - plotting=dict(display_name="First Cell Type", color="#0000FF",opacity="0.5") + "second_cell_type", + spatial=dict(radius=10, density_key="second_cell_type_density") + plotting=dict(display_name="First Cell Type", color="#0000FF",opacity="0.5") ) -The nrrd files should contain voxel based volumetric density in unit of cells / voxel volume, +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. .. rubric:: Specifying morphologies -To associate a cell type with a specific morphology, add the desired morphology to the cells by referencing -the corresponding name stored in the :doc:`morphology repository `. +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 ` . .. tab-set-code:: diff --git a/docs/cli/commands.rst b/docs/cli/commands.rst index bcf99be3..a43b41b0 100644 --- a/docs/cli/commands.rst +++ b/docs/cli/commands.rst @@ -27,7 +27,7 @@ project settings. * ``quickstart``: Generates an exemplary project with basic config that can be compiled. * ``exists``: With this flag, it is not an error for the ``parent-folder`` to exist. * ``json``: With this flag, the configuration file will be written in the JSON format - instead of YAML format used by default. + instead of the default YAML format. .. _bsb_make_config: diff --git a/docs/cli/intro.rst b/docs/cli/intro.rst index d8c2a7f3..5357f7cb 100644 --- a/docs/cli/intro.rst +++ b/docs/cli/intro.rst @@ -4,7 +4,6 @@ Introduction ############ -The command line interface is composed of a collection of pluggable commands. Open up your favorite terminal and enter the ``bsb --help`` command to verify you correctly installed the software. diff --git a/docs/components/components.rst b/docs/components/components.rst index 31279ec3..02d6837c 100644 --- a/docs/components/components.rst +++ b/docs/components/components.rst @@ -11,8 +11,8 @@ If you want to read a step by step tutorial on how to make your own component, c :doc:`page ` For each component, the BSB provides interfaces, each with a set of functions that you must -implement. By implementing these functions are present, the framework can seamlessly integrate -your custom components. +implement. By implementing these functions, the framework can seamlessly integrate your +custom components. Here is how you do it (theoretically): diff --git a/docs/getting-started/simulations/guide_nest.rst b/docs/getting-started/simulations/guide_nest.rst index d021154e..14d5f462 100644 --- a/docs/getting-started/simulations/guide_nest.rst +++ b/docs/getting-started/simulations/guide_nest.rst @@ -326,7 +326,7 @@ You can now run your simulation: The results of the simulation will be stored in the ``"simulation-results"`` folder. .. note:: - If you run the simulation with the command line interface, the name of the output nio file is randomized by BSB. + If you run the simulation with the command line interface, the name of the output nio file is randomized by the BSB. For more detailed information about simulation modules, please refer to the :doc:`simulation section `. diff --git a/docs/getting-started/simulations/toc_point_neurons.rst b/docs/getting-started/simulations/toc_point_neurons.rst index d53a0672..b7c785e4 100644 --- a/docs/getting-started/simulations/toc_point_neurons.rst +++ b/docs/getting-started/simulations/toc_point_neurons.rst @@ -1,9 +1,9 @@ -Guides on Point neurons simulation +Guides on Point-neurons simulation ================================== .. toctree:: :maxdepth: 2 - :caption: Point neuron simulations + :caption: Point-neuron simulations guide_nest analyze_spikes \ No newline at end of file diff --git a/docs/getting-started/top-level-guide.rst b/docs/getting-started/top-level-guide.rst index b70dba4f..ee390a1b 100644 --- a/docs/getting-started/top-level-guide.rst +++ b/docs/getting-started/top-level-guide.rst @@ -20,7 +20,7 @@ A typical workflow of the BSB works as follows: 1. The user provides a configuration that describes the network they want to reconstruct and simulate. - It is interpreted by BSB as a list of tasks to perform. + It is interpreted by the BSB as a series of tasks to perform. 2. The BSB creates the topology of the network (i.e., its shape and size). 3. The BSB places cells within the network, following a defined strategy. 4. The BSB connects the aforementioned cells according to connectivity rules. @@ -55,7 +55,7 @@ storage object full of neuroscience. To do so, the configuration leverages configurable objects to describe the underlying neural network, called **components**. Components define which methods and parameters should be used to reconstruct and -simulate the network. The ones that you would probably employ the most are: +simulate the network. The ones that you will probably employ the most are: * :guilabel:`Topology` defines the shape and volume of your network, (it is composed of :guilabel:`Regions` and :guilabel:`Partitions`), @@ -78,9 +78,18 @@ Configuration ============= The ``Configuration`` object is organized as a hierarchical tree. -From the root, the main blocks branch off, consisting of nine main components: :guilabel:`network`, -:guilabel:`storage`, :guilabel:`regions`, :guilabel:`partitions`, :guilabel:`morphologies`, :guilabel:`cell_types`, -:guilabel:`placement`, :guilabel:`connectivity`, and :guilabel:`simulation`. +From the root, the main blocks branch off, consisting of nine main components: + +* :guilabel:`network` +* :guilabel:`storage` +* :guilabel:`regions` +* :guilabel:`partitions` +* :guilabel:`morphologies` +* :guilabel:`cell_types` +* :guilabel:`placement` +* :guilabel:`connectivity` +* :guilabel:`simulation` + These blocks contain nested sub-blocks that form the network. Additionally, there are two optional components: :guilabel:`after_placement` and :guilabel:`after_connectivity`, where users can define specific hooks to run within the workflow. @@ -96,7 +105,7 @@ All these components will be described in more detail in the following sections. The configuration object contains only the description of the model, not its implementation (python code) nor its data (stored in the storage object). -It can therefore be stored in a separate file (usually Json or Yaml) that can be easily interpreted by BSB. +It can therefore be stored in a separate file (usually Json or Yaml) that can be easily interpreted by the BSB. What is next? ============= diff --git a/docs/morphologies/intro.rst b/docs/morphologies/intro.rst index b965cd90..f7c7efa5 100644 --- a/docs/morphologies/intro.rst +++ b/docs/morphologies/intro.rst @@ -378,6 +378,8 @@ passed around in the framework as :class:`StoredMorphologies :class:`~.morphologies.Morphology` object from storage and a :meth:`~.storage.interfaces.StoredMorphology.get_meta` method to return the metadata. +.. _morphology_selector: + Morphology selectors --------------------