bluecellulab 2.6.66__py3-none-any.whl → 2.6.68__py3-none-any.whl

bluecellulab/cell/core.py

@@ -47,6 +47,7 @@ from bluecellulab.stimulus.circuit_stimulus_definitions import SynapseReplay
 from bluecellulab.synapse import SynapseFactory, Synapse
 from bluecellulab.synapse.synapse_types import SynapseID
 from bluecellulab.type_aliases import HocObjectType, NeuronSection, SectionMapping
+from bluecellulab.cell.section_tools import currents_vars, section_to_variable_recording_str
 
 logger = logging.getLogger(__name__)
 
@@ -250,6 +251,10 @@ class Cell(InjectableMixin, PlottableMixin):
         else:
             self._default_disable_ttx()
 
+    @property
+    def ttx_enabled(self):
+        return getattr(self, "_ttx_enabled", False)
+
     def _default_enable_ttx(self) -> None:
         """Default enable_ttx implementation."""
         for section in self.sections.values():
@@ -316,6 +321,7 @@ class Cell(InjectableMixin, PlottableMixin):
         """Adds recording to AIS."""
         self.add_recording("self.axonal[1](0.5)._ref_v", dt=dt)
 
+    @deprecated("Use add_variable_recording('v', ...) instead.")
     def add_voltage_recording(
         self, section: Optional[NeuronSection] = None, segx: float = 0.5, dt: Optional[float] = None
     ) -> None:
@@ -334,6 +340,7 @@ class Cell(InjectableMixin, PlottableMixin):
         var_name = section_to_voltage_recording_str(section, segx)
         self.add_recording(var_name, dt)
 
+    @deprecated("Use get_variable_recording('v', ...) instead.")
     def get_voltage_recording(
         self, section: Optional[NeuronSection] = None, segx: float = 0.5
     ) -> np.ndarray:
@@ -760,17 +767,66 @@ class Cell(InjectableMixin, PlottableMixin):
         """Get a vector of AIS voltage."""
         return self.get_recording('self.axonal[1](0.5)._ref_v')
 
-    def add_variable_recording(self, variable: str, section, segx):
-        if variable == "v":
-            self.add_voltage_recording(section, segx)
-        else:
-            raise ValueError(f"Unsupported variable for recording: {variable}")
+    def add_variable_recording(
+        self,
+        variable: str,
+        section: Optional[NeuronSection] = None,
+        segx: float = 0.5,
+        dt: Optional[float] = None
+    ) -> None:
+        """Add a recording of any NEURON RANGE variable (e.g., gna, gk, ina)
+        from a given section and segment.
+
+        Args:
+            variable: The NEURON variable name to record (e.g., "gna").
+            section: The section to record from (defaults to soma).
+            segx: Segment position between 0 and 1.
+            dt: Optional recording time step.
+        """
 
-    def get_variable_recording(self, variable: str, section, segx) -> np.ndarray:
-        if variable == "v":
-            return self.get_voltage_recording(section=section, segx=segx)
+        if section is None:
+            section = self.soma
+
+        # validate before constructing the string
+        seg = section(segx)
+        if "." in variable:
+            mech, var = variable.split(".", 1)
+            mobj = getattr(seg, mech, None)
+            if mobj is None or not hasattr(mobj, f"_ref_{var}"):
+                raise ValueError(
+                    f"'{variable}' not recordable at {section.name()}({segx}). "
+                    f"Mechanisms here: {list(section.psection()['density_mechs'].keys())}"
+                )
         else:
-            raise ValueError(f"Unsupported variable '{variable}'")
+            if not hasattr(seg, f"_ref_{variable}"):
+                raise ValueError(
+                    f"'{variable}' not recordable at {section.name()}({segx}). "
+                    f"(Top-level vars are typically v/ina/ik/ica)"
+                )
+
+        var_name = section_to_variable_recording_str(section, segx, variable)
+        self.add_recording(var_name, dt)
+
+    def get_variable_recording(
+        self, variable: str, section: Optional[NeuronSection], segx: float
+    ) -> np.ndarray:
+        """Get a recording of any variable recorded from a section and segment.
+
+        Args:
+            variable: The name of the recorded variable (e.g., 'v', 'gna').
+            section: The NEURON section object.
+            segx: Segment location from 0 to 1.
+
+        Returns:
+            NumPy array of recorded values.
+
+        Raises:
+            ValueError: If the recording is not found.
+        """
+        if section is None:
+            section = self.soma
+        recording_name = section_to_variable_recording_str(section, segx, variable)
+        return self.get_recording(recording_name)
 
     @property
     def n_segments(self) -> int:
@@ -843,3 +899,42 @@ class Cell(InjectableMixin, PlottableMixin):
 
     def __del__(self):
         self.delete()
+
+    def add_currents_recordings(
+        self,
+        section,
+        segx: float = 0.5,
+        *,
+        include_nonspecific: bool = True,
+        include_point_processes: bool = False,
+        dt: float | None = None,
+    ) -> list[str]:
+        """Record all available currents (ionic + optionally nonspecific) at
+        (section, segx)."""
+
+        # discover what’s available at this site
+        available = currents_vars(section)
+        chosen: list[str] = []
+
+        for name, meta in available.items():
+            kind = meta.get("kind")
+
+            if kind == "ionic_current":
+                self.add_variable_recording(name, section=section, segx=segx, dt=dt)
+                chosen.append(name)
+
+            elif kind == "nonspecific_current":
+                if not include_nonspecific:
+                    continue
+                # density-mech nonspecific currents
+                self.add_variable_recording(name, section=section, segx=segx, dt=dt)
+                chosen.append(name)
+
+            elif kind == "point_process_current":
+                if not include_point_processes:
+                    continue
+                # point process nonspecific currents
+                self.add_variable_recording(name, section=section, segx=segx, dt=dt)
+                chosen.append(name)
+
+        return chosen

bluecellulab/cell/section_tools.py

@@ -0,0 +1,96 @@
+# Copyright 2025 Open Brain Institute
+
+# 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.
+"""NEURON section helpers for BlueCelluLab."""
+
+
+def currents_vars(section) -> dict:
+    """Return recordable currents (with units) at a given section.
+
+    - Ionic currents from the ions block (e.g. ``ina``, ``ik``, ``ica``), in mA/cm².
+    - Mechanism currents for variables ``i`` or ``ihcn``, reported as ``<var>_<mech>``
+      (e.g. ``i_pas``, ``ihcn_Ih``), in mA/cm².
+
+    Args:
+        section: NEURON Section object.
+
+    Returns:
+        dict mapping variable names to {"units": str, "kind": str}.
+    """
+    psec = section.psection()
+    out = {}
+
+    ions = psec.get("ions", {}) or {}
+    for ion, vars_dict in ions.items():
+        if ion == "ttx":
+            continue
+        name = f"i{ion}"
+        if name in vars_dict:
+            out[name] = {"units": "mA/cm²", "kind": "ionic_current"}
+
+    special_currents = {
+        ("pas", "i"): "i_pas",
+        ("Ih", "ihcn"): "ihcn_Ih",
+        ("hd", "i"): "i_hd",
+    }
+
+    for (mech, var), out_name in special_currents.items():
+        if var in (psec.get("density_mechs") or {}).get(mech, {}):
+            out[out_name] = {"units": "mA/cm²", "kind": "nonspecific_current"}
+
+    return dict(sorted(out.items()))
+
+
+def mechs_vars(section, include_point_mechs: bool = False) -> dict:
+    """Return mechanism-scoped variables at a given section.
+
+    Args:
+        section: NEURON Section object.
+        include_point_mechs: Whether to include point processes.
+    """
+    psec = section.psection()
+    dens = psec.get("density_mechs", {}) or {}
+    points = psec.get("point_mechs", {}) or {}
+    mech_map = {
+        mech: sorted(vars_dict.keys())
+        for mech, vars_dict in dens.items() if vars_dict
+    }
+    entry = {"mech": mech_map}
+    if include_point_mechs:
+        point_map = {
+            pp: sorted(vars_dict.keys())
+            for pp, vars_dict in points.items() if vars_dict
+        }
+        entry["point"] = point_map
+    return entry
+
+
+def section_to_variable_recording_str(section, segx: float, variable: str) -> str:
+    """Build an evaluable NEURON pointer string for `add_recording`.
+
+    Accepts:
+      - top-level vars: "v", "ina", "ik", ...
+      - mechanism-scoped vars: "kca.gkca", "na3.m", "na3.h", ...
+
+    Returns examples:
+      neuron.h.soma[0](0.5)._ref_v
+      neuron.h.soma[0](0.5)._ref_ina
+      neuron.h.soma[0](0.5).kca._ref_gkca
+      neuron.h.dend[3](0.7).na3._ref_m
+    """
+    sec_name = section.name()
+    if "." in variable:
+        mech, var = variable.split(".", 1)
+        return f"neuron.h.{sec_name}({segx}).{mech}._ref_{var}"
+    else:
+        return f"neuron.h.{sec_name}({segx})._ref_{variable}"

{bluecellulab-2.6.66.dist-info → bluecellulab-2.6.68.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bluecellulab
-Version: 2.6.66
+Version: 2.6.68
 Summary: Biologically detailed neural network simulations and analysis.
 Author: Blue Brain Project, EPFL
 License: Apache2.0
@@ -28,6 +28,8 @@ Requires-Dist: typing-extensions>=4.8.0
 Requires-Dist: networkx>=3.1
 Requires-Dist: h5py>=3.8.0
 Requires-Dist: seaborn
+Provides-Extra: examples
+Requires-Dist: ipywidgets; extra == "examples"
 Dynamic: license-file
 
 |banner|

{bluecellulab-2.6.66.dist-info → bluecellulab-2.6.68.dist-info}/RECORD

@@ -21,12 +21,13 @@ bluecellulab/analysis/plotting.py,sha256=PqRoaZz33ULMw8A9YnZXXrxcUd84M_dwlYMTFhG
 bluecellulab/analysis/utils.py,sha256=eMirP557D11BuedgSqjripDxOq1haIldNbnYNetV1bg,121
 bluecellulab/cell/__init__.py,sha256=Sbc0QOsJ8E7tSwf3q7fsXuE_SevBN6ZmoCVyyU5zfII,208
 bluecellulab/cell/cell_dict.py,sha256=VE7pi-NsMVRSmo-PSdbiLYmolDOu0Gc6JxFBkuQpFdk,1346
-bluecellulab/cell/core.py,sha256=2dRx5ueElOJthhmnrijbBb9rH9xlJRp_hyZ73YHLGas,34478
+bluecellulab/cell/core.py,sha256=PKus_O8iREcU5-SDBjM7XbRUwromPz-K9imGo2Q11-4,37875
 bluecellulab/cell/injector.py,sha256=GB0pmyZMOHNV-lzd_t4cLoDE87S58IMbe7-qU1zBWvE,19033
 bluecellulab/cell/plotting.py,sha256=t2qDUabFtsBb-nJMkDh5UfsgW-wvQ2wfDwAVZ8-hWPo,4032
 bluecellulab/cell/random.py,sha256=pemekc11geRBKD8Ghb82tvKOZLfFWkUz1IKLc_NWg-A,1773
 bluecellulab/cell/recording.py,sha256=dekJspPb_5yrS6WR3aXtvZ6KWwMNbyhe5aIOVtNDHpY,342
 bluecellulab/cell/section_distance.py,sha256=QrNJ_avRSm-PFZfSg-FrcCqu-BNZNwcbECwMN9fY2ho,3908
+bluecellulab/cell/section_tools.py,sha256=abIxZLyy0RFl7KVC3eR6gTxssK-y0nx0_qoj6eOVArU,3201
 bluecellulab/cell/serialized_sections.py,sha256=5JfLNgrUKdyYe4mKFIH2zMnT5QohNB9JYXbe475goEg,1543
 bluecellulab/cell/sonata_proxy.py,sha256=1FsMDosS7fbffgY_shaBKVIXjkmxL5aiPLlxcgeAUsc,1529
 bluecellulab/cell/stimuli_generator.py,sha256=DwWX8Keed1KgKExwlD4u-h4WUhEXcsG7XPjJTxqfZaQ,7129
@@ -75,9 +76,9 @@ bluecellulab/synapse/__init__.py,sha256=RW8XoAMXOvK7OG1nHl_q8jSEKLj9ZN4oWf2nY9HA
 bluecellulab/synapse/synapse_factory.py,sha256=NHwRMYMrnRVm_sHmyKTJ1bdoNmWZNU4UPOGu7FCi-PE,6987
 bluecellulab/synapse/synapse_types.py,sha256=zs_yBvGTH4QrbQF3nEViidyq1WM_ZcTSFdjUxB3khW0,16871
 bluecellulab/validation/validation.py,sha256=D35LE_131CtIzeeePAPz1OFzncGjAcvF02lSIvGvL2E,21331
-bluecellulab-2.6.66.dist-info/licenses/AUTHORS.txt,sha256=EDs3H-2HXBojbma10psixk3C2rFiOCTIREi2ZAbXYNQ,179
-bluecellulab-2.6.66.dist-info/licenses/LICENSE,sha256=dAMAR2Sud4Nead1wGFleKiwTZfkTNZbzmuGfcTKb3kg,11335
-bluecellulab-2.6.66.dist-info/METADATA,sha256=Ks8Pluoya43-54yOznhJlHPFTlIRmgr8z8NGWRvvZ5o,8259
-bluecellulab-2.6.66.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-bluecellulab-2.6.66.dist-info/top_level.txt,sha256=VSyEP8w9l3pXdRkyP_goeMwiNA8KWwitfAqUkveJkdQ,13
-bluecellulab-2.6.66.dist-info/RECORD,,
+bluecellulab-2.6.68.dist-info/licenses/AUTHORS.txt,sha256=EDs3H-2HXBojbma10psixk3C2rFiOCTIREi2ZAbXYNQ,179
+bluecellulab-2.6.68.dist-info/licenses/LICENSE,sha256=dAMAR2Sud4Nead1wGFleKiwTZfkTNZbzmuGfcTKb3kg,11335
+bluecellulab-2.6.68.dist-info/METADATA,sha256=D7ekc9VkRUId673jW-Gl8zfSp9VbBfcEvGqc4ANfWN0,8331
+bluecellulab-2.6.68.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bluecellulab-2.6.68.dist-info/top_level.txt,sha256=VSyEP8w9l3pXdRkyP_goeMwiNA8KWwitfAqUkveJkdQ,13
+bluecellulab-2.6.68.dist-info/RECORD,,