docs: update docs on NMODL, read_morphology (#520)

Author: bgmeulem

docs/bibliography.bib

@@ -114,3 +114,6 @@ @Inbook{COBYLA
 doi="10.1007/978-94-015-8330-5_4",
 url="https://doi.org/10.1007/978-94-015-8330-5_4"
 }
+
+
+@article{MODL, title={A block organized model builder}, volume={19}, ISSN={0895-7177}, DOI={10.1016/0895-7177(94)90190-2}, abstractNote={A new language has been developed for defining simulation models for biomedical science and implemented as a preprocessor for SCoP1 (Simulation Control Program) written by the National Biomedical Simulation Resource. The preprocessor creates a C program by translation of statements in a model definition file. The language defines variables and equations in labelled blocks of statements which are either mathematical equations or English phrases. The availability of several kinds of equation definition blocks simplifies the description of the corresponding classes of equations. Sub-blocks are provided for some special operations, such as logical tests. Algebraic logical operators are included. Special statements called directives instruct the preprocessor to create specific variables or generate code to call specific numerical methods routines from SCoP’s library. Models may be decomposed into sub-models stored on separate model definition files and automatically assembled by the preprocessor in hierarchical fashion. The model description language has been implemented in the C language by generating machine independent code with the Unix lex and yacc programs. An example of the use of the model description language, including hierarchical assembly, is illustrated by a model of the human ovulatory cycle.}, number={6}, journal={Mathematical and Computer Modelling}, author={Kohn, M. C. and Hines, M. L. and Kootsey, J. M. and Feezor, M. D.}, year={1994}, month=mar, pages={75–97} }

docs/file_formats.rst

@@ -100,9 +100,10 @@ Note that the mechanism name in :ref:`mod_file_format` files are defined in the
 .. seealso::
    The :ref:`mod_file_format` file documentation for how these files are structured.
 
-Each range mechanism must have the key ``spatial``, and its value must match one of the supported spatial profiles in ISF. All spatial profiles except for ``"uniform"`` require additional parameters that need to be defined for a given range mechanism. E.g. the exponential profile expects the parameters ``offset``, ``linScale``, ``_lambda``, ``xOffset``. Distances for these spatial profiles are calculated in terms of distance to soma.
+Each range mechanism must have the key ``spatial``, and its value must match one of the supported spatial profiles in ISF. All spatial profiles except for ``"uniform"`` require additional parameters that need to be defined for a given range mechanism. E.g. the exponential profile expects the parameters ``offset``, ``linScale``, ``_lambda``, ``xOffset``. 
+Distances for these spatial profiles are calculated in terms of distance to soma.
 If ``"distance": "relative"`` is passed for a range mechanism, the distance dependency is scaled by the maximum distance of all sections with the same label. E.g. for a simple dendrite, this means that all distance metrics are scaled with the length of the longest dendrite. This is useful for setting scaling parameters without necessarily having to worry about the exact dimensions of the neurites beforehand.
-Spatial profiles are evaluated on a segment-by-segment basis: the segment center is used as the distance dependency of each spatial profile, and channels are uniform within a single segment.
+Spatial profiles are evaluated on a segment-by-segment basis: the segment center is used as the distance dependency of each spatial profile, and neuron parameters are uniform within a single segment.
 
 .. seealso::
    :meth:`~single_cell_parser.cell_parser.CellParser.insert_range_mechanisms` for an overview of the available spatial profiles for range mechanisms.
@@ -897,21 +898,21 @@ Example::
 
 .mod
 ****
-``MODL`` is a file format Used to define dynamical systems as simply as reasonably possible.
-NEURON :cite:t:`hines2001neuron` provides an extension to this format called ``NMODL``, in this
-case to define channel and synapse dynamics for use in NEURON simulations.
-NEURON translates these files to ``C`` (and to ``C++`` since NEURON 9.0), to be compiled to machine code on the host machine.
+``MODL`` ("MOdel Description Language") is a file format developed at the National Biomedical Simulation Resource, intended to define physical systems as simultaneous algebraic equations :cite:`MODL`.
+NEURON :cite:`hines2001neuron` provides an extension to this format called ``NMODL`` ("Neuron MODL"), in this
+case to define channel and synapse dynamics per neuronal compartment for use in NEURON simulations.
+The NEURON simulation environment provides translators and compilers (``nrnivmodl`` for UNIX, ``nrnmkdll`` for Windows) to translate these files to ``C`` (and to ``C++`` since NEURON 9.0), and to compile the resulting C/C++ to machine code on the host machine.
 
-``NMODL`` files are categorized in blocks. 
+``MODL``/``NMODL`` files are categorized in blocks. 
 We highlight some important ones below:
 
 .. list-table::
 
   * - NEURON
-    - NEURON :cite:t:`hines2001neuron` specific specification, such as ``READ`` and ``WRITE`` statements, 
-      defining which global variables this particular mechanism needs access to (e.g. intracellular :math:`Ca^{2+}` for :math:`Ca^{2+}`-activated channels).
+    - NEURON :cite:`hines2001neuron` specific specification, such as ``READ`` and ``WRITE`` statements, 
+      defining which segment-wide shared variables this particular mechanism needs access to (e.g. :math:`Ca^{2+}`-activated channels and buffers both need access to the intracellular :math:`Ca^{2+}` concentration).
       The mechanism's name is defined as either a ``SUFFIX`` or ``POINTPROCESS`` in this block.
-      This is the name that will be accessible by the user, and how NEURON will register it in the NEURON or Python namespace.
+      This is the name that will be accessible by the user in :ref:`cell_parameters_format`, and how NEURON will register it in the NEURON or Python namespace.
   * - PARAMETER
     - Free parameters used in this mechanism. 
       These are the parameters the user has direct access to, and can be tweaked during optimization or exploration.
@@ -1025,11 +1026,6 @@ Example:
    if they exist in the NEURON namespace.
 
 
-
-
-
-
-
 .. _am_file_format:
 
 .am

single_cell_parser/io/morphology/__init__.py

@@ -19,11 +19,7 @@
 This module specifies converters between :ref:`swc_file_format` and :ref:`hoc_file_format` morphologies.
 """
 from __future__ import annotations
-from typing import List, Dict, Any
-import numpy as np
-from data_base.dbopen import dbopen
 from config.isf_logging import get_isf_logger
-from typing import Optional
 from .hoc import read_hoc, write_hoc
 from .swc import read_swc
 from pathlib import Path
@@ -36,10 +32,13 @@ def read_morphology(
     ):
     """Read a morphology in :ref:`hoc_file_format` or :ref:`swc_file_format` format.
     
-    This function is a simply strategy pattern to decide which reader to use.
+    This function is simply a strategy pattern to decide which reader to use:
+
+    - :meth:`~single_cell_parser.io.morphology.hoc.read_hoc`
+    - :meth:`~single_cell_parser.io.morphology.swc.read_swc`
 
     Args:
-        fn (str|:class:`~Path`): Name of the morphology file.
+        fn (str | :class:`~pathlib.Path`): Name of the morphology file.
 
     Returns:
        List[_Edge]: List of :class:`~_Edge` objects for further parsing, usually by :meth:`~CellParser.spatialgraph_to_cell`