Add Bulding Workflow Documentation

.pylintrc

@@ -1,5 +1,5 @@
 [MESSAGES CONTROL]
-disable=fixme,invalid-name,len-as-condition,no-else-return,no-member,empty-docstring
+disable=fixme,invalid-name,len-as-condition,no-else-return,no-member,empty-docstring,too-many-positional-arguments
 
 [FORMAT]
 # Regexp for a line that is allowed to be longer than the limit.

bbp_workflow/generation/workflow.py

@@ -11,7 +11,18 @@
 
 @luigi.util.inherits(KgCfg, RemoteHostCfg)
 class SBOWorkflow(luigi.WrapperTask):
- """Workflow class."""
+ """Generator Workflow class for building detailed circuits.
+
+ Args:
+ output_dir (Path): Output directory to write generated data.
+ config_url (str): ModelBuildingConfig NEXUS resource id.
+ account (str): Project account.
+ isolated (bool):
+ Whether the workflow will run in isolated mode. Isolated mode ignores activities from
+ previous executions.
+ target (str): The target generator execute. The workflow will run all tasks up until the
+ target task.
+ """
 
  output_dir = luigi.PathParameter(
  significant=True,
@@ -45,7 +56,7 @@ def host_config(self) -> dict:
  return self.clone(RemoteHostCfg).param_kwargs
 
  def requires(self):
-
+ """Return required leaf task in the workflow DAG, determined by the `target` argument."""
  generator_class = get_class_from_config_name(self.target)
 
  return generator_class(

doc/source/api.rst

@@ -10,3 +10,4 @@ API Documentation
  bbp_workflow.simulation.util
  bbp_workflow.target
  bbp_workflow.task
+ bbp_workflow.generation.workflow

doc/source/index.rst

@@ -34,5 +34,6 @@ Overview of the tasks available in the workflow engine:
 
  Home <self>
  api
+ workflow
  dependencies
  changelog

doc/source/workflow.rst

@@ -0,0 +1,9 @@
+The Building Workflow
+=====================
+
+.. toctree::
+
+ workflow_components/quickstart.rst
+ workflow_components/overview.rst
+ workflow_components/generator_hierarchy.rst
+ workflow_components/generator_definitions.rst

doc/source/workflow_components/generator_definitions.rst

@@ -0,0 +1,324 @@
+Generator Definitions
+======================
+
+.. _cell_composition_generator:
+
+CellCompositionGenerator
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Config: `CellCompositionConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#cellcompositionconfig>`_
+
+The ``CellCompositionGenerator`` is responsible for manipulating an input CellComposition in terms of density.
+
+
+The final resource generated by the generator is a new CellComposition incorporating the changes listed in overrides.
+
+
+.. _cell_position_generator:
+
+CellPositionGenerator
+~~~~~~~~~~~~~~~~~~~~~
+
+Config: `CellPositionConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#cellpositionconfig>`_
+
+The ``CellPositionGenerator`` consumes the upstream CellComposition registered by :ref`CellCompositionGenerator <cell_composition_generator>` and places cell somata, along with properties such as mtypes, and etype.
+
+The final resource generated by the generator is a partial ``DetailedCircuit`` with a circuit config as follows:
+
+.. code-block:: json
+
+ {
+ "version": 2,
+ "manifest": {
+ "$BASE_DIR": "."
+ },
+ "node_sets_file": "path/to/nodesets/json",
+ "networks": {
+ "nodes": [
+ {
+ "nodes_file": "path/to/nodes/h5",
+ "populations": {
+ "root__neurons": {
+ "type": "biophysical",
+ }
+ }
+ }
+ ],
+ "edges": []
+ },
+ "metadata": {
+ "status": "partial"
+ }
+ }
+
+where the node population has the following properties:
+
+.. code-block:: text
+
+ etype
+ hemisphere
+ morph_class
+ mtype
+ region
+ subregion
+ synapse_class
+ x
+ y
+ z
+
+See `SONATA documentation <https://sonata-extension.readthedocs.io/en/latest/sonata_tech.html#fields-for-biophysically-detailed-neurons-model-type-biophysical>`__ for column definitions.
+
+.. _mmodel_generator:
+
+MorphologyAssignmentGenerator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Config: `MorphologyAssignmentConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#morphologyassignmentconfig>`_
+
+The ``MorphologyAssignmentGenerator`` takes the ``DetailedCircuit`` from :ref:`CellPositionGenerator <cell_position_generator>` and depending on the configuration assigns or/and synthesizes morphologies for each cell in the node population.
+
+The final resource generated by the generator is a partial ``DetailedCircuit`` with a circuit config as follows:
+
+.. code-block:: json
+
+ {
+ "version": 2,
+ "manifest": {
+ "$BASE_DIR": "."
+ },
+ "metadata": {
+ "status": "partial"
+ },
+ "node_sets_file": "path/to/nodests/json",
+ "networks": {
+ "nodes": [
+ {
+ "nodes_file": "path/to/nodes/h5",
+ "populations": {
+ "root__neurons": {
+ "type": "biophysical",
+ "alternate_morphologies": {
+ "h5v1": "$BASE_DIR/morphologies",
+ "neurolucida-asc": "$BASE_DIR/morphologies"
+ }
+ }
+ }
+ }
+ ],
+ "edges": []
+ }
+ }
+
+where the node population has the following properties:
+
+.. code-block:: text
+
+ etype
+ hemisphere
+ morph_class
+ morphology
+ morphology_producer
+ mtype
+ orientation_w
+ orientation_x
+ orientation_y
+ orientation_z
+ region
+ subregion
+ synapse_class
+ x
+ y
+ z
+
+See `SONATA documentation <https://sonata-extension.readthedocs.io/en/latest/sonata_tech.html#fields-for-biophysically-detailed-neurons-model-type-biophysical>`__ for column definitions.
+
+
+.. _me_model_generator:
+
+MEModelGenerator
+~~~~~~~~~~~~~~~~
+
+Config: `MEModelConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#memodelconfig>`_
+
+The ``MEModelGenerator`` takes the ``DetailedCircuit`` from :ref:`MorphologyAssignmentGenerator <mmodel_generator>` and assigns emodels and emodel properties.
+
+The final resource generated by the generator is a partial ``DetailedCircuit`` with a circuit config as follows:
+
+.. code-block:: json
+
+ {
+ "version": 2,
+ "manifest": {
+ "$BASE_DIR": "."
+ },
+ "node_sets_file": "path/to/nodesets/json",
+ "networks": {
+ "nodes": [
+ {
+ "nodes_file": "path/to/nodes/h5",
+ "populations": {
+ "root__neurons": {
+ "type": "biophysical",
+ "partial": [
+ "cell-properties",
+ "morphologies"
+ ],
+ "alternate_morphologies": {
+ "h5v1": "path/to/morphologies/dir",
+ "neurolucida-asc": "path/to/morphologies/dir"
+ },
+ "biophysical_neuron_models_dir": "path/to/hoc/dir"
+ }
+ }
+ }
+ ],
+ "edges": []
+ },
+ "metadata": {
+ "status": "partial"
+ }
+ }
+
+where the node population has the following properties:
+
+.. _me_model_properties:
+
+.. code-block:: text
+
+ dynamics_params/AIS_scaler
+ dynamics_params/holding_current
+ dynamics_params/input_resistance
+ dynamics_params/resting_potential
+ dynamics_params/soma_scaler
+ dynamics_params/threshold_current
+ etype
+ hemisphere
+ model_template
+ morph_class
+ morphology
+ morphology_producer
+ mtype
+ orientation_w
+ orientation_x
+ orientation_y
+ orientation_z
+ region
+ subregion
+ synapse_class
+ x
+ y
+ z
+
+See `SONATA documentation <https://sonata-extension.readthedocs.io/en/latest/sonata_tech.html#fields-for-biophysically-detailed-neurons-model-type-biophysical>`__ for column definitions.
+
+.. _macro_generator:
+
+MacroConnectomeGenerator
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Config: `MacroConnectomeConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#macroconnectomeconfig>`_
+
+The ``MacroConnectomeGenerator`` is a :ref:`relay generator <generator_types>` that propagates its config downstream to :ref:`MicroConnectomeGenerator <micro_generator>`.
+
+The final resource of `MacroConnectomeGenerator` is a clone of its input config.
+
+
+.. _micro_generator:
+
+MicroConnectomeGenerator
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Config: `MicroConnectomeConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#microconnectomeconfig>`_
+
+The ``MicroConnectomeGenerator`` takes as an input the `MacroConnectomeConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#macroconnectomeconfig>`_ from :ref:`MacroConnectomeGenerator <macro_generator>` and the ``DetailedCircuit`` from :ref:`MEModelGenerator <me_model_generator>` and establishes the connectivity of the node population.
+
+
+The final resource generated by the generator is a partial ``DetailedCircuit`` with a circuit config as follows:
+
+.. code-block:: json
+
+ {
+ "version": 2,
+ "manifest": {
+ "$BASE_DIR": "."
+ },
+ "node_sets_file": "path/to/nodesets/json",
+ "networks": {
+ "nodes": [
+ {
+ "nodes_file": "path/to/nodes/h5",
+ "populations": {
+ "root__neurons": {
+ "type": "biophysical",
+ "alternate_morphologies": {
+ "h5v1": "path/to/morphologies/dir",
+ "neurolucida-asc": "path/to/morphologies/dir"
+ },
+ "biophysical_neuron_models_dir": "path/to/hoc/dir"
+ }
+ }
+ }
+ ],
+ "edges": [
+ {
+ "edges_file": "path/to/edges/h5",
+ "populations": {
+ "root__neurons__root__neurons__chemical": {
+ "type": "chemical"
+ }
+ }
+ }
+ ]
+ },
+ "metadata": {
+ "status": "partial"
+ }
+ }
+
+where the nodes file has the same properties as in the :ref:`MEModelGenerator ones <me_model_properties>` and the edges file has the following properties:
+
+
+.. code-block:: text
+
+ afferent_center_x
+ afferent_center_y
+ afferent_center_z
+ afferent_section_id
+ afferent_section_pos
+ afferent_section_type
+ delay
+ syn_type_id
+
+See `SONATA documentation <https://sonata-extension.readthedocs.io/en/latest/sonata_tech.html#fields-for-chemical-connection-type-edges>`__ for column definitions.
+
+
+ConnectomeFilteringGenerator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Config: `SynapseConfig <https://entity-management.readthedocs.io/en/latest/building_entities.html#synapseconfig>`_
+
+The ``ConnectomeFilteringGenerator`` takes the ``DetailedCircuit`` from :ref:`MicroConnectomeGenerator <micro_generator>` and filters the according to the configuration.
+
+The final resource is a simulation-ready ``DetailedCircuit`` where the where the nodes file has the same properties as in the :ref:`MEModelGenerator ones <me_model_properties>` and the edges file has the following properties:
+
+.. code-block:: text
+
+ afferent_center_x
+ afferent_center_y
+ afferent_center_z
+ afferent_section_id
+ afferent_section_pos
+ afferent_section_type
+ conductance
+ conductance_scale_factor
+ decay_time
+ delay
+ depression_time
+ facilitation_time
+ n_rrp_vesicles
+ syn_property_rule
+ syn_type_id
+ u_hill_coefficient
+ u_syn
+
+See `SONATA documentation <https://sonata-extension.readthedocs.io/en/latest/sonata_tech.html#fields-for-chemical-connection-type-edges>`__ for column definitions.