Rc0.7.2 beta (#515)

Update documentation (see #513)

Author: bgmeulem

biophysics_fitting/hay/L5tt_parameter_setup.py

@@ -522,7 +522,7 @@ def set_hot_zone(cell_param, min_=None, max_=None, outsidescale_sections=None):
         max\_ (float): The maximum distance from the soma.
         outsidescale_sections (list): 
             A list of sections not part of the hot zone, but including calcium channels nonetheless.
-            These sections will get a Ca channel density equal to the :ref:`neuron_parameters_format` key ``outside_scale``.
+            These sections will get a Ca channel density equal to the :ref:`cell_parameters_format` key ``outside_scale``.
             Usually, this is less than the hot zone density.
             See :ref:`~single_cell_parser.cell_parser.insert_range_mechanisms` for more information on channel density during neuron model creation.
         

config/__init__.py

@@ -24,6 +24,7 @@
     "udvary2022",
     # no other methods have been implemented yet
 )
+"""Which methods ISF currently implements to infer synapse locations onto a poastsynaptic neuron morphology."""
 
 
 def _read_db_settings():
@@ -98,6 +99,14 @@ def get_default_db_dumper():
 
 
 def get_meta_file_format():
+    """Check which file format to use for saving data_base meta objects.
+
+    This is either ``"msgpack"`` or ``"json"``.
+    The actual format is defined in the database settings. This functions simply reads it to check which one should be used.
+
+    Returns:
+        str: The specified file format for meta objects.
+    """
     allowed_formats = ("msgpack", "json")
     db_settings = _read_db_settings()
     meta_file_format = db_settings.get("OBJECT_META_FORMAT")['file_format']

config/file_locking.py

@@ -12,9 +12,30 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Default values for file locking.
+
+This module allows the user to set default fallback values for file locking.
+This default fallback value is only used when the env variable ``"ISF_DISTRIBUTED_LOCK_CONFIG"`` is unset.
+It is recommended to make use of this env variable when setting up your environment, especially for HPC contexts.
+
+For example, to use the zookeeper locking configuration:
+
+- launch a zookeeper server
+- write out the configuration for your session::
+
+    config = [{
+        'config': {
+            'hosts': 'ip:port'
+        },
+        'type': 'zookeeper'
+    }]
+
+- set ``"ISF_DISTRIBUTED_LOCK_CONFIG"`` to the filepath pointing to this config file.
+"""
 DEFAULT_CONFIG = [
     dict(type="file"),
     # dict(type="redis", config=dict(host="spock", port=8885, socket_timeout=1)),
     # dict(type="redis", config=dict(host="localhost", port=6379, socket_timeout=1)),
 ]
+"""Default fallback value when no file locking is configured. Defaults to file-based file locking."""
 

config/user/morphology.py

@@ -12,6 +12,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+Configure label names for :ref:`hoc_file_format` and :ref:`swc_file_format` morphology files.
+"""
 
 HOC_LABEL_MAP = {
     'soma':          'Soma',
@@ -26,4 +29,18 @@
 
 For example, if a :ref:`hoc_file_format` contains the label "DEND", "Dend", or "BasalDendrite", these will be converted in ISF to just "Dendrite".
 If a connections spreadsheet contains labels "BASAL", it will be converted to "Dendrite".
-"""
+"""
+
+SWC_LABEL_MAP = {
+    1: 'Soma', 
+    2: "AIS", 
+    3: "Dendrite", 
+    4: "ApicalDendrite", 
+    5: "Myelin"
+}
+"""Mapping between labels found in :ref:`swc_file_format` morphology files, and the label to be used internally throughout ISF.
+
+For example, if a :ref:`swc_file_format` contains the label ``3``, this will be converted in ISF to just "Dendrite".
+
+Useful for defining custom labels on a project-wide basis.
+"""

config/user/network_connectivity.py

@@ -1,8 +1,34 @@
+# In Silico Framework
+# Copyright (C) 2025  Max Planck Institute for Neurobiology of Behavior - CAESAR
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Configure the default values for synapse mapping and network connectivity workflows in ISF.
 
+This module allows the user to configure default settings for synapse mapping in ISF.
+
+In particular, it allows:
+
+- Setting a default synapse mapping strategy
+- Setting default paths for data sources for this synapse mapping strategy
+
+We generally recommend to always explicitly pass both the synapse mapping strategy and the data sources, as it makes the code more explicit. Relying too much on these default values can have the undesirable side effect that the same code may yield different results, when these values are changed.
+"""
 from pathlib import Path
 from .. import AVAILABLE_SYNAPSE_MAPPING_METHODS
 
 SELECTED_SYNAPSE_MAPPING_METHOD = "udvary2022"
+"""Which synapse mapping workflow to use for calculating synapse positions on the morphology. Default is :mod:`~singlecell_input_mapper.udvary2022`"""
 
 prefix = Path(__file__).parent.parent.parent / "barrel_cortex"
 
@@ -17,4 +43,4 @@
 
 
 assert SELECTED_SYNAPSE_MAPPING_METHOD in AVAILABLE_SYNAPSE_MAPPING_METHODS, \
-    f"The chosen synapse mapping method {SELECTED_SYNAPSE_MAPPING_METHOD} is not available. Available methods are: {AVAILABLE_SYNAPSE_MAPPING_METHODS}"
+    f"The chosen synapse mapping method {SELECTED_SYNAPSE_MAPPING_METHOD} is not available. Available methods are: {AVAILABLE_SYNAPSE_MAPPING_METHODS}"

data_base/distributed_lock.py

@@ -77,6 +77,11 @@ def _get_locking_config():
     
     This method allows for a lazy evaluation of the locking configuration, 
     and is used to set the global variable ``_CONFIG``.
+
+    If the env variable ``ISF_DISTRIBUTED_LOCK_CONFIG`` is not set, it falls back to :attr:`~DEFAULT_CONFIG`.
+
+    Returns:
+        List[dict]: List of configurations to try. Order of the list reflects priority.
     """
     global _CONFIG
 

docs/api_reference.rst

@@ -15,6 +15,7 @@ API reference
    ./api_reference/spike_analysis/index
    ./api_reference/visualize/index
    ./api_reference/mechanisms/index
+   ./api_reference/config/index
 
 .. autoapisummary::
 
@@ -27,3 +28,4 @@ API reference
    spike_analysis
    visualize
    mechanisms
+   config

docs/file_formats.rst

@@ -648,7 +648,7 @@ Parsed dataframe
 
 Writers:
 
-- :func:`~single_cell_parser.writer.write_presynaptic_spike_file` is used by :mod:`simrun` and :mod:`~single_cell_parser.analyze.synanalysis`
+- :func:`~single_cell_parser.io.activity.write_presynaptic_spike_times` is used by :mod:`simrun` and :mod:`~single_cell_parser.analyze.synanalysis`
    to write raw output data.
 - :func:`data_base.db_initializers.load_simrun_general.init` parses these files into a pandas dataframe.
 
@@ -978,7 +978,8 @@ Example:
 
   : What to calculate each time step
   BREAKPOINT {
-    : solve the DERIVATIVE block named "states" using `sympy.dsolve` and fall back to `CNEXP` method
+    : Solve the DERIVATIVE block named "states"
+    : Use `cnexp` (Crank-Nicolson, exponential)
     : For more info, see https://www.neuronsimulator.org/en/latest/nmodl/transpiler/notebooks/nmodl-sympy-solver-cnexp.html#Implementation
     SOLVE states METHOD cnexp
     : Calculate the conductance of the Im current = conductance density * gating variable

docs/installation.rst

@@ -125,9 +125,14 @@ Each ISF environment adapts the following environment variables:
 
 Configuration
 -------------
+The :mod:`config` module allows the user to configure many aspects of ISF, such as:
 
-ISF works best with a dask server for parallel computing. We provide default scripts to launch a dask server and workers
-that should work on most systems. 
+- The default file format for saving objects in a :mod:`data_base` (see :mod:`config`)
+- Which file locking method to use (see :mod:`config.file_locking`)
+- User-specific configuration for your project, such as morphology label names, cell type definitions, synapse mapping strategies, and default values for activity data (see :mod:`config.user`)
+
+ISF works best with a dask server for parallel computing, and all compute-intensive workflows in ISF work with a client for distributed computing. 
+We provide default scripts to launch a dask server and workers that should work on most systems:
 
 .. code-block:: bash
 
@@ -140,6 +145,7 @@ that should work on most systems.
 For High-Performance Computing (HPC), you may want to launch the dask server with custom configuration instead of these default scripts.
 The underlying commands for these shortcuts are configured in the ``pyproject.toml`` file.
 
+
 Usage
 -----
 
@@ -171,4 +177,4 @@ To test if all components of ISF are working as intended, you can run the test s
 
 .. container:: doc-feedback
 
-   Documentation unclear, incomplete, broken or wrong? `Let us know <https://github.com/mpinb/in_silico_framework/issues/new?template=documentation.md&labels=docs>`_
+   Documentation unclear, incomplete, broken or wrong? `Let us know <https://github.com/mpinb/in_silico_framework/issues/new?template=documentation.md&labels=docs>`_

single_cell_parser/io/morphology/swc.py

@@ -16,17 +16,13 @@
 Read and write :ref:`swc_file_format` morphologies.
 """
 from __future__ import annotations
-from typing import Any
+from config.user.morphology import SWC_LABEL_MAP
 import numpy as np
 import warnings
-from pathlib import Path
 import logging
 from ._edge import _Edge
 logger = logging.getLogger("ISF").getChild(__name__)
 
-SWC_LABEL_MAP = {'Soma': 1, "AIS": 2, "Dendrite": 3, "ApicalDendrite": 4, "Myelin": 5}
-REVERSE_SWC_LABEL_MAP = {v: k for k, v in SWC_LABEL_MAP.items()}
-
 def _get_swc_lines_per_section(
     sections, 
     skip_myelin=False, 
@@ -116,6 +112,7 @@ def _get_swc_lines_per_section(
         swc_lines_per_section.append(swc_lines_this_section)
     return swc_lines_per_section
 
+
 def _get_only_child_sections(sections):
     """Check if a cell has sections that are only children.
     
@@ -133,7 +130,7 @@ def _get_only_child_sections(sections):
         if sec.parent and len(sec.parent.children()) == 1:
             direct_desc_sections[sec_ind] = sections.index(sec.parent)
     return direct_desc_sections
-    
+
 
 def write_swc(sections, of, skip_myelin=False, remap_sections=None):
     """
@@ -174,8 +171,8 @@ def write_swc(sections, of, skip_myelin=False, remap_sections=None):
             line = [str(e) for e in line]
             f.write(' '.join(line))
             f.write('\n')  
-            
-            
+
+
 def swc_to_point_dict(swc_filepath):
     """
     Extract point coordinate information.
@@ -273,7 +270,7 @@ def _traverse(point_id, sec_name, sec_label, parent_sec_id, points_dict, section
     parent_sec_id= len(sections) - 1
     for i, child_id in enumerate(children_pt_id):
         section_type = points_dict[child_id]["type"]
-        child_sec_label = REVERSE_SWC_LABEL_MAP[section_type]
+        child_sec_label = SWC_LABEL_MAP[section_type]
         child_sec_name = f"{sec_name}_{i}"
         sections= _traverse(
             point_id=child_id, 
@@ -330,7 +327,7 @@ def build_section_directory(root_ids, points_dict):
         for child_id in points_dict[root_id]["children"]:
             if child_id <= len(sections[0].edgePts): continue  # child is soma - already added
             section_type = points_dict[child_id]["type"]
-            label = REVERSE_SWC_LABEL_MAP.get(section_type, f"type{section_type}")
+            label = SWC_LABEL_MAP.get(section_type, f"type{section_type}")
             counters[section_type] = counters.get(section_type, 0) + 1
             child_sec_name = f"{label}_{counters[section_type]}_0"
             sections = _traverse(