bluecellulab 2.3.7__py3-none-any.whl → 2.4.1__py3-none-any.whl

bluecellulab/__init__.py

@@ -9,6 +9,7 @@ except ImportError:
 
 from .importer import *  # NOQA
 from .tools import *  # NOQA
+from .verbosity import *
 from .cell import Cell, create_ball_stick  # NOQA
 from .connection import Connection  # NOQA
 from .plotwindow import PlotWindow  # NOQA

bluecellulab/analysis/inject_sequence.py

@@ -0,0 +1,130 @@
+"""Module for injecting a sequence of protocols to the cell."""
+from __future__ import annotations
+from enum import Enum, auto
+from typing import NamedTuple, Sequence, Dict
+
+import neuron
+import numpy as np
+from bluecellulab.cell.core import Cell
+from bluecellulab.cell.template import TemplateParams
+from bluecellulab.simulation.simulation import Simulation
+from bluecellulab.stimulus.factory import Stimulus, StimulusFactory
+from bluecellulab.utils import IsolatedProcess
+
+
+class StimulusName(Enum):
+    """Allowed values for the StimulusName."""
+    AP_WAVEFORM = auto()
+    IDREST = auto()
+    IV = auto()
+    FIRE_PATTERN = auto()
+
+
+class Recording(NamedTuple):
+    """A tuple of the current, voltage and time recordings."""
+    current: np.ndarray
+    voltage: np.ndarray
+    time: np.ndarray
+
+
+StimulusRecordings = Dict[str, Recording]
+
+
+def run_stimulus(
+    template_params: TemplateParams,
+    stimulus: Stimulus,
+    section: str,
+    segment: float,
+    duration: float,
+) -> Recording:
+    """Creates a cell and stimulates it with a given stimulus.
+
+    Args:
+        template_params: The parameters to create the cell from a template.
+        stimulus: The input stimulus to inject into the cell.
+        section: Name of the section of cell where the stimulus is to be injected.
+        segment: The segment of the section where the stimulus is to be injected.
+        duration: The duration for which the simulation is to be run.
+
+    Returns:
+        The voltage-time recording at the specified location.
+
+    Raises:
+        ValueError: If the time and voltage arrays are not the same length.
+    """
+    cell = Cell.from_template_parameters(template_params)
+    neuron_section = cell.sections[section]
+    cell.add_voltage_recording(neuron_section, segment)
+    iclamp, _ = cell.inject_current_waveform(
+        stimulus.time, stimulus.current, section=neuron_section, segx=segment
+    )
+    current_vector = neuron.h.Vector()
+    current_vector.record(iclamp._ref_i)
+    simulation = Simulation(cell)
+    simulation.run(duration)
+    current = np.array(current_vector.to_python())
+    voltage = cell.get_voltage_recording(neuron_section, segment)
+    time = cell.get_time()
+    if len(time) != len(voltage) or len(time) != len(current):
+        raise ValueError("Time, current and voltage arrays are not the same length")
+    return Recording(current, voltage, time)
+
+
+def apply_multiple_step_stimuli(
+    cell: Cell,
+    stimulus_name: StimulusName,
+    amplitudes: Sequence[float],
+    duration: float,
+    section_name: str | None = None,
+    segment: float = 0.5,
+    n_processes: int | None = None,
+) -> StimulusRecordings:
+    """Apply multiple stimuli to the cell on isolated processes.
+
+    Args:
+        cell: The cell to which the stimuli are applied.
+        stimulus_name: The name of the stimulus to apply.
+        amplitudes: The amplitudes of the stimuli to apply.
+        duration: The duration for which each stimulus is applied.
+        section_name: Section name of the cell where the stimuli are applied.
+          If None, the stimuli are applied at the soma[0] of the cell.
+        segment: The segment of the section where the stimuli are applied.
+        n_processes: The number of processes to use for running the stimuli.
+
+    Returns:
+        A dictionary where the keys are the names of the stimuli and the values
+        are the recordings of the cell's response to each stimulus.
+
+    Raises:
+        ValueError: If the stimulus name is not recognized.
+    """
+    res: StimulusRecordings = {}
+    stim_factory = StimulusFactory(dt=1.0)
+    task_args = []
+    section_name = section_name if section_name is not None else "soma[0]"
+
+    # Prepare arguments for each stimulus
+    for amplitude in amplitudes:
+        if stimulus_name == StimulusName.AP_WAVEFORM:
+            stimulus = stim_factory.ap_waveform(threshold_current=cell.threshold, threshold_percentage=amplitude)
+        elif stimulus_name == StimulusName.IDREST:
+            stimulus = stim_factory.idrest(threshold_current=cell.threshold, threshold_percentage=amplitude)
+        elif stimulus_name == StimulusName.IV:
+            stimulus = stim_factory.iv(threshold_current=cell.threshold, threshold_percentage=amplitude)
+        elif stimulus_name == StimulusName.FIRE_PATTERN:
+            stimulus = stim_factory.fire_pattern(threshold_current=cell.threshold, threshold_percentage=amplitude)
+        else:
+            raise ValueError("Unknown stimulus name.")
+
+        task_args.append((cell.template_params, stimulus, section_name, segment, duration))
+
+    with IsolatedProcess(processes=n_processes) as pool:
+        # Map expects a function and a list of argument tuples
+        results = pool.starmap(run_stimulus, task_args)
+
+    # Associate each result with a key
+    for amplitude, result in zip(amplitudes, results):
+        key = f"{stimulus_name}_{amplitude}"
+        res[key] = result
+
+    return res

bluecellulab/cell/core.py

@@ -27,12 +27,13 @@ import numpy as np
 import pandas as pd
 
 import bluecellulab
+from bluecellulab.cell.recording import section_to_voltage_recording_str
 from bluecellulab.psection import PSection, init_psections
 from bluecellulab.cell.injector import InjectableMixin
 from bluecellulab.cell.plotting import PlottableMixin
 from bluecellulab.cell.section_distance import EuclideanSectionDistance
 from bluecellulab.cell.sonata_proxy import SonataProxy
-from bluecellulab.cell.template import NeuronTemplate, public_hoc_cell
+from bluecellulab.cell.template import NeuronTemplate, TemplateParams, public_hoc_cell
 from bluecellulab.circuit.config.sections import Conditions
 from bluecellulab.circuit import EmodelProperties, SynapseProperty
 from bluecellulab.circuit.node_id import CellId
@@ -44,7 +45,7 @@ from bluecellulab.rngsettings import RNGSettings
 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
+from bluecellulab.type_aliases import HocObjectType, NeuronSection, SectionMapping
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +55,24 @@ class Cell(InjectableMixin, PlottableMixin):
 
     last_id = 0
 
+    @classmethod
+    def from_template_parameters(
+        cls, template_params: TemplateParams, cell_id: Optional[CellId] = None,
+        record_dt: Optional[float] = None
+    ) -> Cell:
+        """Create a cell from a TemplateParams object.
+
+        Useful in isolating runs.
+        """
+        return cls(
+            template_path=template_params.template_filepath,
+            morphology_path=template_params.morph_filepath,
+            cell_id=cell_id,
+            record_dt=record_dt,
+            template_format=template_params.template_format,
+            emodel_properties=template_params.emodel_properties,
+        )
+
     @load_hoc_and_mod_files
     def __init__(self,
                  template_path: str | Path,
@@ -61,48 +80,52 @@ class Cell(InjectableMixin, PlottableMixin):
                  cell_id: Optional[CellId] = None,
                  record_dt: Optional[float] = None,
                  template_format: str = "v5",
-                 emodel_properties: Optional[EmodelProperties] = None,
-                 rng_settings: Optional[RNGSettings] = None) -> None:
+                 emodel_properties: Optional[EmodelProperties] = None) -> None:
         """Initializes a Cell object.
 
         Args:
-            template_path: Full path to hoc template file.
+            template_path: Path to hoc template file.
             morphology_path: Path to morphology file.
-            gid: ID of the cell, used in RNG seeds. Defaults to 0.
+            cell_id: ID of the cell, used in RNG seeds.
             record_dt: Timestep for the recordings.
-                If not provided, a default is used. Defaults to None.
-            template_format: Cell template format such as 'v5'
-                or 'v6_air_scaler'. Defaults to "v5".
-            emodel_properties: Properties such as
-                threshold_current, holding_current. Defaults to None.
-            rng_settings: Random number generation setting
-                object used by the Cell. Defaults to None.
+            template_format: Cell template format such as 'v5' or 'v6_air_scaler'.
+            emodel_properties: Template specific emodel properties.
         """
         super().__init__()
+        self.template_params = TemplateParams(
+            template_filepath=template_path,
+            morph_filepath=morphology_path,
+            template_format=template_format,
+            emodel_properties=emodel_properties,
+        )
         if cell_id is None:
             cell_id = CellId("", Cell.last_id)
             Cell.last_id += 1
         self.cell_id = cell_id
-        # Persistent objects, like clamps, that exist as long
-        # as the object exists
-        self.persistent: list[HocObjectType] = []
-
-        self.morphology_path = morphology_path
 
         # Load the template
-        neuron_template = NeuronTemplate(template_path, morphology_path)
+        neuron_template = NeuronTemplate(template_path, morphology_path, template_format, emodel_properties)
         self.template_id = neuron_template.template_name  # useful to map NEURON and python objects
-        self.cell = neuron_template.get_cell(template_format, self.cell_id.id, emodel_properties)
+        self.cell = neuron_template.get_cell(self.cell_id.id)
+        if template_format == 'v6':
+            if emodel_properties is None:
+                raise BluecellulabError('EmodelProperties must be provided for v6 template')
+            self.hypamp: float | None = emodel_properties.holding_current
+            self.threshold: float = emodel_properties.threshold_current
+        else:
+            try:
+                self.hypamp = self.cell.getHypAmp()
+            except AttributeError:
+                self.hypamp = None
+            try:
+                self.threshold = self.cell.getThreshold()
+            except AttributeError:
+                self.threshold = 0.0
         self.soma = public_hoc_cell(self.cell).soma[0]
         # WARNING: this finitialize 'must' be here, otherwhise the
         # diameters of the loaded morph are wrong
         neuron.h.finitialize()
 
-        if rng_settings is None:
-            self.rng_settings = RNGSettings("Random123")  # SONATA value
-        else:
-            self.rng_settings = rng_settings
-
         self.recordings: dict[str, HocObjectType] = {}
         self.synapses: dict[SynapseID, Synapse] = {}
         self.connections: dict[SynapseID, bluecellulab.Connection] = {}
@@ -121,23 +144,6 @@ class Cell(InjectableMixin, PlottableMixin):
         self.delayed_weights = queue.PriorityQueue()  # type: ignore
         self.psections, self.secname_to_psection = init_psections(public_hoc_cell(self.cell))
 
-        self.emodel_properties = emodel_properties
-        if template_format == 'v6':
-            if self.emodel_properties is None:
-                raise BluecellulabError('EmodelProperties must be provided for v6 template')
-            self.hypamp: float | None = self.emodel_properties.holding_current
-            self.threshold: float | None = self.emodel_properties.threshold_current
-        else:
-            try:
-                self.hypamp = self.cell.getHypAmp()
-            except AttributeError:
-                self.hypamp = None
-
-            try:
-                self.threshold = self.cell.getThreshold()
-            except AttributeError:
-                self.threshold = None
-
         # Keep track of when a cell is made passive by make_passive()
         # Used to know when re_init_rng() can be executed
         self.is_made_passive = False
@@ -145,6 +151,17 @@ class Cell(InjectableMixin, PlottableMixin):
         neuron.h.pop_section()  # Undoing soma push
         self.sonata_proxy: Optional[SonataProxy] = None
 
+        # Persistent objects, like clamps, that exist as long
+        # as the object exists
+        self.persistent: list[HocObjectType] = []
+
+    def _extract_sections(self, sections) -> SectionMapping:
+        res: SectionMapping = {}
+        for section in sections:
+            key_name = str(section).split(".")[-1]
+            res[key_name] = section
+        return res
+
     @property
     def somatic(self) -> list[NeuronSection]:
         return list(public_hoc_cell(self.cell).somatic)
@@ -162,8 +179,8 @@ class Cell(InjectableMixin, PlottableMixin):
         return list(public_hoc_cell(self.cell).axonal)
 
     @property
-    def all(self) -> list[NeuronSection]:
-        return list(public_hoc_cell(self.cell).all)
+    def sections(self) -> SectionMapping:
+        return self._extract_sections(public_hoc_cell(self.cell).all)
 
     def __repr__(self) -> str:
         base_info = f"Cell Object: {super().__repr__()}"
@@ -211,7 +228,7 @@ class Cell(InjectableMixin, PlottableMixin):
 
     def make_passive(self) -> None:
         """Make the cell passive by deactivating all the active channels."""
-        for section in self.all:
+        for section in self.sections.values():
             mech_names = set()
             for seg in section:
                 for mech in seg:
@@ -246,14 +263,14 @@ class Cell(InjectableMixin, PlottableMixin):
 
     def _default_enable_ttx(self) -> None:
         """Default enable_ttx implementation."""
-        for section in self.all:
+        for section in self.sections.values():
             if not neuron.h.ismembrane("TTXDynamicsSwitch"):
                 section.insert('TTXDynamicsSwitch')
             section.ttxo_level_TTXDynamicsSwitch = 1.0
 
     def _default_disable_ttx(self) -> None:
         """Default disable_ttx implementation."""
-        for section in self.all:
+        for section in self.sections.values():
             if not neuron.h.ismembrane("TTXDynamicsSwitch"):
                 section.insert('TTXDynamicsSwitch')
             section.ttxo_level_TTXDynamicsSwitch = 1e-14
@@ -261,7 +278,7 @@ class Cell(InjectableMixin, PlottableMixin):
     def area(self) -> float:
         """The total surface area of the cell."""
         area = 0.0
-        for section in self.all:
+        for section in self.sections.values():
             x_s = np.arange(1.0 / (2 * section.nseg), 1.0,
                             1.0 / (section.nseg))
             for x in x_s:
@@ -311,7 +328,7 @@ class Cell(InjectableMixin, PlottableMixin):
         self.add_recording("self.axonal[1](0.5)._ref_v", dt=dt)
 
     def add_voltage_recording(
-        self, section: "neuron.h.Section", segx: float = 0.5, dt: Optional[float] = None
+        self, section: Optional[NeuronSection] = None, segx: float = 0.5, dt: Optional[float] = None
     ) -> None:
         """Add a voltage recording to a certain section at a given segment
         (segx).
@@ -323,11 +340,13 @@ class Cell(InjectableMixin, PlottableMixin):
             dt: Recording time step. If not provided, the recording step will
                 default to the simulator's time step.
         """
-        var_name = f"neuron.h.{section.name()}({segx})._ref_v"
+        if section is None:
+            section = self.soma
+        var_name = section_to_voltage_recording_str(section, segx)
         self.add_recording(var_name, dt)
 
     def get_voltage_recording(
-        self, section: "neuron.h.Section", segx: float = 0.5
+        self, section: Optional[NeuronSection] = None, segx: float = 0.5
     ) -> np.ndarray:
         """Get a voltage recording for a certain section at a given segment
         (segx).
@@ -343,7 +362,9 @@ class Cell(InjectableMixin, PlottableMixin):
         Raises:
             BluecellulabError: If voltage recording was not added previously using add_voltage_recording.
         """
-        recording_name = f"neuron.h.{section.name()}({segx})._ref_v"
+        if section is None:
+            section = self.soma
+        recording_name = section_to_voltage_recording_str(section, segx)
         if recording_name in self.recordings:
             return self.get_recording(recording_name)
         else:
@@ -354,15 +375,13 @@ class Cell(InjectableMixin, PlottableMixin):
 
     def add_allsections_voltagerecordings(self):
         """Add a voltage recording to every section of the cell."""
-        all_sections = public_hoc_cell(self.cell).all
-        for section in all_sections:
+        for section in self.sections.values():
             self.add_voltage_recording(section, dt=self.record_dt)
 
     def get_allsections_voltagerecordings(self) -> dict[str, np.ndarray]:
         """Get all the voltage recordings from all the sections."""
         all_section_voltages = {}
-        all_sections = public_hoc_cell(self.cell).all
-        for section in all_sections:
+        for section in self.sections.values():
             recording = self.get_voltage_recording(section)
             all_section_voltages[section.name()] = recording
         return all_section_voltages
@@ -440,10 +459,10 @@ class Cell(InjectableMixin, PlottableMixin):
         """
         if location == "soma":
             sec = public_hoc_cell(self.cell).soma[0]
-            source = public_hoc_cell(self.cell).soma[0](1)._ref_v
+            source = sec(1)._ref_v
         elif location == "AIS":
             sec = public_hoc_cell(self.cell).axon[1]
-            source = public_hoc_cell(self.cell).axon[1](0.5)._ref_v
+            source = sec(0.5)._ref_v
         else:
             raise ValueError("Spike detection location must be soma or AIS")
         netcon = neuron.h.NetCon(source, target, sec=sec)
@@ -486,7 +505,6 @@ class Cell(InjectableMixin, PlottableMixin):
 
         sid = synapse_id[1]
 
-        base_seed = self.rng_settings.base_seed
         weight = syn_description[SynapseProperty.G_SYNX]
         # numpy int to int
         post_sec_id = int(syn_description[SynapseProperty.POST_SECTION_ID])
@@ -526,9 +544,10 @@ class Cell(InjectableMixin, PlottableMixin):
                 # NC_SPONTMINI
                 self.syn_mini_netcons[synapse_id].weight[nc_type_param] = 1
 
-            if self.rng_settings.mode == 'Random123':
+            rng_settings = RNGSettings.get_instance()
+            if rng_settings.mode == 'Random123':
                 seed2 = source_popid * 65536 + target_popid \
-                    + self.rng_settings.minis_seed
+                    + rng_settings.minis_seed
                 self.ips[synapse_id].setRNGs(
                     sid + 200,
                     self.cell_id.id + 250,
@@ -543,25 +562,26 @@ class Cell(InjectableMixin, PlottableMixin):
                 uniformrng = neuron.h.Random()
                 self.persistent.append(uniformrng)
 
-                if self.rng_settings.mode == 'Compatibility':
+                base_seed = rng_settings.base_seed
+                if rng_settings.mode == 'Compatibility':
                     exp_seed1 = sid * 100000 + 200
                     exp_seed2 = self.cell_id.id + 250 + base_seed + \
-                        self.rng_settings.minis_seed
+                        rng_settings.minis_seed
                     uniform_seed1 = sid * 100000 + 300
                     uniform_seed2 = self.cell_id.id + 250 + base_seed + \
-                        self.rng_settings.minis_seed
-                elif self.rng_settings.mode == "UpdatedMCell":
+                        rng_settings.minis_seed
+                elif rng_settings.mode == "UpdatedMCell":
                     exp_seed1 = sid * 1000 + 200
                     exp_seed2 = source_popid * 16777216 + self.cell_id.id + 250 + \
                         base_seed + \
-                        self.rng_settings.minis_seed
+                        rng_settings.minis_seed
                     uniform_seed1 = sid * 1000 + 300
                     uniform_seed2 = source_popid * 16777216 + self.cell_id.id + 250 \
                         + base_seed + \
-                        self.rng_settings.minis_seed
+                        rng_settings.minis_seed
                 else:
                     raise ValueError(
-                        f"Cell: Unknown rng mode: {self.rng_settings.mode}")
+                        f"Cell: Unknown rng mode: {rng_settings.mode}")
 
                 exprng.MCellRan4(exp_seed1, exp_seed2)
                 exprng.negexp(1.0)
@@ -695,9 +715,10 @@ class Cell(InjectableMixin, PlottableMixin):
         """Get a vector of AIS voltage."""
         return self.get_recording('self.axonal[1](0.5)._ref_v')
 
-    def getNumberOfSegments(self) -> int:
+    @property
+    def n_segments(self) -> int:
         """Get the number of segments in the cell."""
-        return sum(section.nseg for section in self.all)
+        return sum(section.nseg for section in self.sections.values())
 
     def add_synapse_replay(
         self, stimulus: SynapseReplay, spike_threshold: float, spike_location: str

bluecellulab/cell/injector.py

@@ -27,6 +27,7 @@ from bluecellulab.cell.stimuli_generator import (
     get_relative_shotnoise_params,
 )
 from bluecellulab.exceptions import BluecellulabError
+from bluecellulab.rngsettings import RNGSettings
 from bluecellulab.stimulus.circuit_stimulus_definitions import (
     ClampMode,
     Hyperpolarizing,
@@ -191,20 +192,21 @@ class InjectableMixin:
 
     def _get_noise_step_rand(self, noisestim_count):
         """Return rng for noise step stimulus."""
-        if self.rng_settings.mode == "Compatibility":
+        rng_settings = RNGSettings.get_instance()
+        if rng_settings.mode == "Compatibility":
             rng = neuron.h.Random(self.cell_id.id + noisestim_count)
-        elif self.rng_settings.mode == "UpdatedMCell":
+        elif rng_settings.mode == "UpdatedMCell":
             rng = neuron.h.Random()
             rng.MCellRan4(
                 noisestim_count * 10000 + 100,
-                self.rng_settings.base_seed +
-                self.rng_settings.stimulus_seed +
+                rng_settings.base_seed +
+                rng_settings.stimulus_seed +
                 self.cell_id.id * 1000)
-        elif self.rng_settings.mode == "Random123":
+        elif rng_settings.mode == "Random123":
             rng = neuron.h.Random()
             rng.Random123(
                 noisestim_count + 100,
-                self.rng_settings.stimulus_seed + 500,
+                rng_settings.stimulus_seed + 500,
                 self.cell_id.id + 300)
 
         self.persistent.append(rng)
@@ -268,9 +270,10 @@ class InjectableMixin:
 
     def _get_ornstein_uhlenbeck_rand(self, stim_count, seed):
         """Return rng for ornstein_uhlenbeck simulation."""
-        if self.rng_settings.mode == "Random123":
+        rng_settings = RNGSettings.get_instance()
+        if rng_settings.mode == "Random123":
             seed1 = stim_count + 2997  # stimulus block
-            seed2 = self.rng_settings.stimulus_seed + 291204  # stimulus type
+            seed2 = rng_settings.stimulus_seed + 291204  # stimulus type
             seed3 = self.cell_id.id + 123 if seed is None else seed  # GID
             logger.debug("Using ornstein_uhlenbeck process seeds %d %d %d" %
                          (seed1, seed2, seed3))
@@ -284,9 +287,10 @@ class InjectableMixin:
 
     def _get_shotnoise_step_rand(self, shotnoise_stim_count, seed=None):
         """Return rng for shot noise step stimulus."""
-        if self.rng_settings.mode == "Random123":
+        rng_settings = RNGSettings.get_instance()
+        if rng_settings.mode == "Random123":
             seed1 = shotnoise_stim_count + 2997
-            seed2 = self.rng_settings.stimulus_seed + 19216
+            seed2 = rng_settings.stimulus_seed + 19216
             seed3 = self.cell_id.id + 123 if seed is None else seed
             logger.debug("Using shot noise seeds %d %d %d" %
                          (seed1, seed2, seed3))
@@ -439,14 +443,14 @@ class InjectableMixin:
         time_vector = neuron.h.Vector().from_python(t_content)
         current_vector = neuron.h.Vector().from_python(i_content)
 
-        pulse = neuron.h.IClamp(segx, sec=section)
-        self.persistent.extend([pulse, time_vector, current_vector])
+        iclamp = neuron.h.IClamp(segx, sec=section)
+        self.persistent.extend([iclamp, time_vector, current_vector])
 
-        pulse.delay = t_content[0]
-        pulse.dur = t_content[-1] - t_content[0]
-        current_vector.play(pulse._ref_amp, time_vector)
+        iclamp.delay = t_content[0]
+        iclamp.dur = t_content[-1] - t_content[0]
+        current_vector.play(iclamp._ref_amp, time_vector)
 
-        return current_vector
+        return iclamp, current_vector
 
     @deprecated("Use add_sin_current instead.")
     def addSineCurrentInject(self, start_time, stop_time, freq,

bluecellulab/cell/recording.py

@@ -0,0 +1,8 @@
+"""Neuron recordings related functions."""
+from __future__ import annotations
+from bluecellulab.type_aliases import NeuronSection
+
+
+def section_to_voltage_recording_str(section: NeuronSection, segment=0.5) -> str:
+    """Converts a section and segment to voltage recording string."""
+    return f"neuron.h.{section.name()}({segment})._ref_v"