`_
Parameters
----------
channel : str
Synaptic channel type. Available options: ``'AMPA'``, ``'NMDA'``,
- ``'GABA'``, by default ``None``
- pre : str
- A unique name to distinguish synapses of the same type coming from
- different input sources, by default ``None``
+ ``'GABA'``.
+ tag : str
+ A unique name to distinguish synapses of the same type.
g : :class:`~brian2.units.fundamentalunits.Quantity`
- Maximum synaptic conductance, by default ``None``
+ Maximum synaptic conductance
t_rise : :class:`~brian2.units.fundamentalunits.Quantity`
- Rise time constant, by default ``None``
+ Rise time constant
t_decay : :class:`~brian2.units.fundamentalunits.Quantity`
- Decay time constant, by default ``None``
+ Decay time constant
scale_g : bool, optional
Option to add a normalization factor to scale the maximum
conductance at 1 when synapses are modelled as a difference of
@@ -217,51 +268,66 @@ def synapse(self, channel: Optional[str] = None,
--------
>>> comp = Compartment('comp')
>>> # adding an AMPA synapse with instant rise & exponential decay:
- >>> comp.synapse('AMPA', g=1*nS, t_decay=5*ms, pre='X')
+ >>> comp.synapse('AMPA', tag='X', g=1*nS, t_decay=5*ms)
>>> # same channel, different conductance & source:
- >>> comp.synapse('AMPA', g=2*nS, t_decay=5*ms, pre='Y')
- >>> # different channel with both rise & decay kinetics:
- >>> comp.synapse('NMDA', g=1*nS, t_rise=5*ms, t_decay=50*ms, pre='X')
+ >>> comp.synapse('AMPA', tag='Y', g=2*nS, t_decay=5*ms)
+ >>> # different channel with both rise & decay kinetics:
+ >>> comp.synapse('NMDA', tag='X' g=1*nS, t_rise=5*ms, t_decay=50*ms)
"""
- # Make sure that the user provides a synapse source
- if not pre:
- print((f"Warning: argument missing for '{channel}' "
- f"synapse @ '{self.name}'\n"
- "Program exited.\n"))
- sys.exit()
- # Switch to rise/decay equations if t_rise & t_decay are provided
- if all([t_rise, t_decay]):
- key = f"{channel}_rd"
+ synapse_id = "_".join([channel, tag, self.name])
+
+ if self._synapses:
+ # Check if this synapse already exists
+ if synapse_id in self._synapses:
+ raise DuplicateEquationsError(
+ f"The equations of '{channel}_{tag}' have already been "
+ f"added to '{self.name}'. \nPlease use a different "
+ f"combination of [channel, tag] when calling the synapse() "
+ "method \nmultiple times on a single compartment. You might"
+ " also see this error if you are using \nJupyter/iPython "
+ "which store variable values in memory. Try cleaning all "
+ "variables or \nrestart the kernel before running your "
+ "code. If this problem persists, please report it \n"
+ "by creating a new issue here: "
+ "https://github.com/Poirazi-Lab/dendrify/issues."
+ )
else:
- key = channel
+ self._synapses = []
- current_name = f'I_{channel}_{pre}_{self.name}'
- current_eqs = library[key].format(self.name, pre)
+ # Switch to rise/decay equations if t_rise & t_decay are provided
+ key = f"{channel}_rd" if all([t_rise, t_decay]) else channel
+ current_name = f'I_{channel}_{tag}_{self.name}'
+ current_eqs = library[key].format(self.name, tag)
to_replace = f'= I_ext_{self.name}'
self._equations = self._equations.replace(
- to_replace, f'{to_replace} + {current_name}')
+ to_replace,
+ f'{to_replace} + {current_name}'
+ )
self._equations += '\n'+current_eqs
if not self._params:
self._params = {}
- weight = f"w_{channel}_{pre}_{self.name}"
- self._params[weight] = 1
+ weight = f"w_{channel}_{tag}_{self.name}"
+ self._params[weight] = 1.0
+
# If user provides a value for g, then add it to _params
if g:
- self._params[f'g_{channel}_{pre}_{self.name}'] = g
+ self._params[f'g_{channel}_{tag}_{self.name}'] = g
if t_rise:
- self._params[f't_{channel}_rise_{pre}_{self.name}'] = t_rise
+ self._params[f't_{channel}_rise_{tag}_{self.name}'] = t_rise
if t_decay:
- self._params[f't_{channel}_decay_{pre}_{self.name}'] = t_decay
+ self._params[f't_{channel}_decay_{tag}_{self.name}'] = t_decay
if scale_g:
if all([t_rise, t_decay, g]):
norm_factor = Compartment.g_norm_factor(t_rise, t_decay)
- self._params[f'g_{channel}_{pre}_{self.name}'] *= norm_factor
+ self._params[f'g_{channel}_{tag}_{self.name}'] *= norm_factor
+
+ self._synapses.append(synapse_id)
- def noise(self, tau: Quantity = 20*ms, sigma: Quantity = 3*pA,
+ def noise(self, tau: Quantity = 20*ms, sigma: Quantity = 1*pA,
mean: Quantity = 0*pA):
"""
Adds a stochastic noise current. For more information see the Noise
@@ -277,10 +343,24 @@ def noise(self, tau: Quantity = 20*ms, sigma: Quantity = 3*pA,
Mean of the Gaussian noise, by default ``0*pA``
"""
I_noise_name = f'I_noise_{self.name}'
+
+ if I_noise_name in self.equations:
+ raise DuplicateEquationsError(
+ f"The equations of '{I_noise_name}' have already been "
+ f"added to '{self.name}'. \nYou might be seeing this error if "
+ "you are using Jupyter/iPython "
+ "which store variable values \nin memory. Try cleaning all "
+ "variables or restart the kernel before running your "
+ "code. If this \nproblem persists, please report it "
+ "by creating a new issue here:\n"
+ "https://github.com/Poirazi-Lab/dendrify/issues."
+ )
noise_eqs = library['noise'].format(self.name)
to_change = f'= I_ext_{self.name}'
self._equations = self._equations.replace(
- to_change, f'{to_change} + {I_noise_name}')
+ to_change,
+ f'{to_change} + {I_noise_name}'
+ )
self._equations += '\n'+noise_eqs
# Add _params:
@@ -293,7 +373,8 @@ def noise(self, tau: Quantity = 20*ms, sigma: Quantity = 3*pA,
@property
def parameters(self) -> dict:
"""
- All parameters that have been generated for a single compartment.
+ Returns all the parameters that have been generated for a single
+ compartment.
Returns
-------
@@ -310,59 +391,42 @@ def parameters(self) -> dict:
@property
def area(self) -> Quantity:
"""
- A compartment's surface area (open cylinder) based on its length
+ Returns a compartment's surface area (open cylinder) based on its length
and diameter.
Returns
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
- try:
- return self._ephys_object.area
- except AttributeError:
- print(("Error: Missing Parameters\n"
- f"Cannot calculate the area of <{self.name}>, "
- "returned None instead.\n"))
+ return self._ephys_object.area
@property
def capacitance(self) -> Quantity:
"""
- A compartment's absolute capacitance based on its specific capacitance
- (cm) and surface area.
+ Returns a compartment's absolute capacitance.
Returns
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
- try:
- return self._ephys_object.capacitance
- except AttributeError:
- print(("Error: Missing Parameters\n"
- f"Cannot calculate the capacitance of <{self.name}>, "
- "returned None instead.\n"))
+ return self._ephys_object.capacitance
@property
def g_leakage(self) -> Quantity:
"""
- A compartment's absolute leakage conductance based on its specific
- leakage conductance (gl) and surface area.
+ A compartment's absolute leakage conductance.
Returns
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
- try:
- return self._ephys_object.g_leakage
- except AttributeError:
- print(("Error: Missing Parameters\n"
- f"Cannot calculate the g leakage of <{self.name}>, "
- "returned None instead.\n"))
+ return self._ephys_object.g_leakage
@property
def equations(self) -> str:
"""
- All differential equations that have been generated for a single
- compartment.
+ Returns all differential equations that describe a single compartment
+ and the mechanisms that have been added to it.
Returns
-------
@@ -371,7 +435,7 @@ def equations(self) -> str:
return self._equations
@property
- def _g_couples(self) -> dict:
+ def _g_couples(self) -> Union[dict, None]:
# If not _connections have been specified yet
if not self._connections:
return None
@@ -405,6 +469,17 @@ def g_norm_factor(trise: Quantity, tdecay: Quantity):
/ ms)
return 1/factor
+ @property
+ def dimensionless(self) -> bool:
+ """
+ Checks if a compartment has been flagged as dimensionless.
+
+ Returns
+ -------
+ bool
+ """
+ return True if self._ephys_object._dimensionless else False
+
class Soma(Compartment):
"""
@@ -429,48 +504,70 @@ class Soma(Compartment):
also be provided but they should be in the same formattable structure as
the library models. Available options: ``'leakyIF'`` (default),
``'adaptiveIF'``, ``'adex'``.
- kwargs : :class:`~brian2.units.fundamentalunits.Quantity`, optional
- Kwargs are used to specify important electrophysiological properties,
- such as the specific capacitance or resistance. For more information
- see: :class:`.EphysProperties`.
+ length : ~brian2.units.fundamentalunits.Quantity, optional
+ A compartment's length.
+ diameter : ~brian2.units.fundamentalunits.Quantity, optional
+ A compartment's diameter.
+ cm : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific capacitance (usually μF / cm^2).
+ gl : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific leakage conductance (usually μS / cm^2).
+ cm_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute capacitance (usually pF).
+ gl_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute leakage conductance (usually nS).
+ r_axial : ~brian2.units.fundamentalunits.Quantity, optional
+ Axial resistance (usually Ohm * cm).
+ v_rest : ~brian2.units.fundamentalunits.Quantity, optional
+ Resting membrane voltage.
+ scale_factor : float, optional
+ A global area scale factor, by default ``1.0``.
+ spine_factor : float, optional
+ A dendritic area scale factor to account for spines, by default ``1.0``.
Examples
--------
>>> # specifying equations only:
- >>> somaX = Soma('nameX', 'leakyIF')
+ >>> compX = Soma('nameX', 'leakyIF')
>>> # specifying equations and ephys properties:
- >>> somaY = Soma('nameY', 'adaptiveIF', length=100*um, diameter=1*um,
- >>> cm=1*uF/(cm**2), gl=50*uS/(cm**2))
+ >>> compY = Soma('nameY', 'adaptiveIF', length=100*um, diameter=1*um,
+ >>> cm=1*uF/(cm**2), gl=50*uS/(cm**2))
+ >>> # specifying equations and absolute ephys properties:
+ >>> compY = Soma('nameZ', 'adaptiveIF', cm_abs=100*pF, gl_abs=20*nS)
"""
- def __init__(self, name: str, model: str = 'leakyIF', **kwargs: Quantity):
-
- super().__init__(name, model, **kwargs)
- self._events = None
- self._event_actions = None
-
- def __str__(self):
- ephys_dict = self._ephys_object.__dict__
- ephys = '\n'.join([f"\u2192 {i}:\n [{ephys_dict[i]}]\n"
- for i in ephys_dict])
- equations = self.equations.replace('\n', '\n ')
-
- parameters = '\n'.join([f" '{i[0]}': {i[1]}"
- for i in self.parameters.items()
- ]) if self.parameters else ' None'
-
- msg = (f"OBJECT TYPE:\n\n {self.__class__}\n\n"
- f"{'-'*45}\n\n"
- f"USER PARAMETERS:\n\n{ephys}"
- f"\n{'-'*45}\n\n"
- "PROPERTIES: \n\n"
- f"\u2192 equations:\n {equations}\n\n"
- f"\u2192 parameters:\n{parameters}\n")
- return msg
+ def __init__(
+ self,
+ name: str,
+ model: str = 'leakyIF',
+ length: Optional[Quantity] = None,
+ diameter: Optional[Quantity] = None,
+ cm: Optional[Quantity] = None,
+ gl: Optional[Quantity] = None,
+ cm_abs: Optional[Quantity] = None,
+ gl_abs: Optional[Quantity] = None,
+ r_axial: Optional[Quantity] = None,
+ v_rest: Optional[Quantity] = None,
+ scale_factor: Optional[float] = 1.0,
+ spine_factor: Optional[float] = 1.0
+ ):
+ super().__init__(
+ name=name,
+ model=model,
+ length=length,
+ diameter=diameter,
+ cm=cm,
+ gl=gl,
+ cm_abs=cm_abs,
+ gl_abs=gl_abs,
+ r_axial=r_axial,
+ v_rest=v_rest,
+ scale_factor=scale_factor,
+ spine_factor=spine_factor
+ )
class Dendrite(Compartment):
- # TODO: restrict to passive
"""
A class that automatically generates and handles all differential equations
and parameters needed to describe a dendritic compartment, its active
@@ -491,46 +588,104 @@ class Dendrite(Compartment):
model : str, optional
A keyword for accessing Dendrify's library models. Dendritic compartments
are by default set to ``'passive'``.
+ length : ~brian2.units.fundamentalunits.Quantity, optional
+ A compartment's length.
+ diameter : ~brian2.units.fundamentalunits.Quantity, optional
+ A compartment's diameter.
+ cm : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific capacitance (usually μF / cm^2).
+ gl : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific leakage conductance (usually μS / cm^2).
+ cm_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute capacitance (usually pF).
+ gl_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute leakage conductance (usually nS).
+ r_axial : ~brian2.units.fundamentalunits.Quantity, optional
+ Axial resistance (usually Ohm * cm).
+ v_rest : ~brian2.units.fundamentalunits.Quantity, optional
+ Resting membrane voltage.
+ scale_factor : float, optional
+ A global area scale factor, by default ``1.0``.
+ spine_factor : float, optional
+ A dendritic area scale factor to account for spines, by default ``1.0``.
+
+ Examples
+ --------
+ >>> # specifying equations only:
+ >>> compX = Dendrite('nameX')
+ >>> # specifying equations and ephys properties:
+ >>> compY = Dendrite('nameY', length=100*um, diameter=1*um,
+ >>> cm=1*uF/(cm**2), gl=50*uS/(cm**2))
+ >>> # specifying equations and absolute ephys properties:
+ >>> compY = Dendrite('nameZ', cm_abs=100*pF, gl_abs=20*nS)
"""
- def __init__(self, name: str, model: str = 'passive', **kwargs: Quantity):
- super().__init__(name, model, **kwargs)
+ def __init__(
+ self,
+ name: str,
+ model: str = 'passive',
+ length: Optional[Quantity] = None,
+ diameter: Optional[Quantity] = None,
+ cm: Optional[Quantity] = None,
+ gl: Optional[Quantity] = None,
+ cm_abs: Optional[Quantity] = None,
+ gl_abs: Optional[Quantity] = None,
+ r_axial: Optional[Quantity] = None,
+ v_rest: Optional[Quantity] = None,
+ scale_factor: Optional[float] = 1.0,
+ spine_factor: Optional[float] = 1.0
+ ):
+ super().__init__(
+ name=name,
+ model=model,
+ length=length,
+ diameter=diameter,
+ cm=cm,
+ gl=gl,
+ cm_abs=cm_abs,
+ gl_abs=gl_abs,
+ r_axial=r_axial,
+ v_rest=v_rest,
+ scale_factor=scale_factor,
+ spine_factor=spine_factor
+ )
self._events = None
self._event_actions = None
+ self._dspike_params = None
def __str__(self):
- ephys_dict = self._ephys_object.__dict__
- ephys = '\n'.join([f"\u2192 {i}:\n [{ephys_dict[i]}]\n"
- for i in ephys_dict])
- equations = self.equations.replace('\n', '\n ')
- events = '\n'.join([f" '{key}': '{self.events[key]}'"
- for key in self.events
- ]) if self.events else ' None'
- parameters = '\n'.join([f" '{i[0]}': {i[1]}"
- for i in self.parameters.items()
- ]) if self.parameters else ' None'
- msg = (f"OBJECT TYPE:\n\n {self.__class__}\n\n"
- f"{'-'*45}\n\n"
- f"USER PARAMETERS:\n\n{ephys}"
- f"\n{'-'*45}\n\n"
- "PROPERTIES: \n\n"
- f"\u2192 equations:\n {equations}\n\n"
- f"\u2192 events:\n{events}\n\n"
- f"\u2192 parameters:\n{parameters}\n")
- return msg
-
- def dspikes(self, channel: str,
+ equations = self.equations
+ parameters = pp.pformat(self.parameters)
+ events = pp.pformat(self.events, width=120)
+ event_names = pp.pformat(self.event_names)
+ user = self._ephys_object.__dict__
+ user_clean = pp.pformat({k: v for k, v in user.items() if v})
+ txt = (f"\nOBJECT\n{6*'-'}\n{self.__class__}\n\n\n"
+ f"EQUATIONS\n{9*'-'}\n{equations}\n\n\n"
+ f"PARAMETERS\n{10*'-'}\n{parameters}\n\n\n"
+ f"EVENTS\n{6*'-'}\n{event_names}\n\n\n"
+ f"EVENT CONDITIONS\n{16*'-'}\n{events}\n\n\n"
+ f"USER PARAMETERS\n{15*'-'}\n{user_clean}")
+ return txt
+
+ def dspikes(self, name: str,
threshold: Optional[Quantity] = None,
g_rise: Optional[Quantity] = None,
- g_fall: Optional[Quantity] = None):
- # TODO: show error if channel does not exist.
+ g_fall: Optional[Quantity] = None,
+ duration_rise: Optional[Quantity] = None,
+ duration_fall: Optional[Quantity] = None,
+ reversal_rise: Union[Quantity, str, None] = None,
+ reversal_fall: Union[Quantity, str, None] = None,
+ offset_fall: Optional[Quantity] = None,
+ refractory: Optional[Quantity] = None
+ ):
"""
- Adds the mechanisms and parameters needed for dendritic spiking. Under
- the hood, this method creates all equations, conditions and actions to
- utilize Brian's custom events functionality. Spikes are generated through
- the sequential activation of a positive (sodium or calcium-like) and a
- negative current (potassium-like current) when a specified dSpike
- threshold is crossed.
+ Adds the ionic mechanisms and parameters needed for dendritic spiking.
+ Under the hood, this method creates the equations, conditions and
+ actions to take advantage of Brian's custom events. dSpikes are
+ generated through the sequential activation of a positive (sodium or
+ calcium-like) and a negative current (potassium-like current) when a
+ specified dSpike threshold is crossed.
.. hint::
@@ -542,152 +697,228 @@ def dspikes(self, channel: str,
within the refractory period. dSpikes cannot be generated during this
phase.
- **DEPOLARIZATION PHASE:**\n
+ **RISE PHASE:**\n
When the dendritic voltage crosses the dSpike threshold AND the
refractory period has elapsed. This triggers the instant activation
- of a positive current that enters the dendrite and then decays
- exponentially.
+ of a positive current that is deactivated after a specified amount
+ of time (``duration_rise``). Also a new refractory period begins.
- **REPOLARIZATION PHASE:**\n
- This phase starts automatically after a specified delay from the
- initiation of the dSpike. A negative current is activated instantly
- and then decays exponentially. Also a new refractory period begins.
+ **FALL PHASE:**\n
+ This phase starts automatically with a delay (``offset_fall``) after
+ the dSpike threshold is crossed. A negative current is activated
+ instantly and then is deactivated after a specified amount of time
+ (``duration_fall``).
Parameters
----------
- channel : str
- Ion channel type. Available options: ``'Na'``, ``'Ca'`` (coming soon).
- threshold : :class:`~brian2.units.fundamentalunits.Quantity`
- The membrane voltage threshold for dendritic spiking, by default
- ``None``.
- g_rise : :class:`~brian2.units.fundamentalunits.Quantity`
- The conductance of the current that is activated during the
- depolarization phase, by default ``None``.
- g_fall : :class:`~brian2.units.fundamentalunits.Quantity`
- The conductance of the current that is activated during the
- repolarization phase, by default ``None``.
+ name : str
+ A unique name to describe a single dSpike type.
+ threshold : ~brian2.units.fundamentalunits.Quantity, optional
+ The membrane voltage threshold for dendritic spiking.
+ g_rise : ~brian2.units.fundamentalunits.Quantity, optional
+ The max conductance of the channel that is activated during the rise
+ (depolarization phase).
+ g_fall : ~brian2.units.fundamentalunits.Quantity, optional
+ The max conductance of the channel that is activated during the fall
+ (repolarization phase).
+ duration_rise : ~brian2.units.fundamentalunits.Quantity, optional
+ The duration of g_rise staying open.
+ duration_fall : ~brian2.units.fundamentalunits.Quantity, optional
+ The duration of g_fall staying open.
+ reversal_rise : (~brian2.units.fundamentalunits.Quantity, str), optional
+ The reversal potential of the channel that is activated during the rise
+ (depolarization) phase.
+ reversal_fall : (~brian2.units.fundamentalunits.Quantity, str), optional
+ The reversal potential of the channel that is activated during the fall
+ (repolarization) phase.
+ offset_fall : ~brian2.units.fundamentalunits.Quantity, optional
+ The delay for the activation of g_rise.
+ refractory : ~brian2.units.fundamentalunits.Quantity, optional
+ The time interval required before dSpike can be activated again.
"""
- if channel == 'Na':
- self._Na_spikes(threshold=threshold, g_rise=g_rise, g_fall=g_fall)
- elif channel == 'Ca':
- self._Ca_spikes(threshold=threshold, g_rise=g_rise, g_fall=g_fall)
-
- def _Na_spikes(self, threshold: Optional[Quantity] = None,
- g_rise: Optional[Quantity] = None,
- g_fall: Optional[Quantity] = None):
+
# The following code creates all necessary equations for dspikes:
- name = self.name
- dspike_currents = f'I_Na_{name} + I_Kn_{name}'
+ comp = self.name
+ ID = f"{name}_{comp}"
+ event_name = f"spike_{ID}"
+
+ if self._events:
+ # Check if this event already exists
+ if event_name in self._events:
+ raise DuplicateEquationsError(
+ f"The equations for '{event_name}' have already been "
+ f"added to '{self.name}'. \nPlease use a different "
+ f"[name] when adding multiple dSpike mechanisms to "
+ " a single compartment. \nYou might"
+ " also see this error if you are using Jupyter/iPython "
+ "which store variable values in \nmemory. Try cleaning all "
+ "variables or restart the kernel before running your "
+ "code. If this \nproblem persists, please report it "
+ "by creating a new issue here: \n"
+ "https://github.com/Poirazi-Lab/dendrify/issues."
+ )
+ else:
+ self._events = {}
+
+ dspike_currents = f"I_rise_{ID} + I_fall_{ID}"
+
# Both currents take into account the reversal potential of Na/K
- I_Na_eqs = f'I_Na_{name} = g_Na_{name} * (E_Na-V_{name}) :amp'
- I_Kn_eqs = f'I_Kn_{name} = g_Kn_{name} * (E_K-V_{name}) :amp'
- # Ion conductances simply decay exponentially
- g_Na_eqs = f'dg_Na_{name}/dt = -g_Na_{name}/tau_Na :siemens'
- g_Kn_eqs = f'dg_Kn_{name}/dt = -g_Kn_{name}/tau_Kn :siemens'
- # Parameters needed for the dSpike custom events
- I_Na_check = f'allow_I_Na_{name} :boolean'
- I_Kn_check = f'allow_I_Kn_{name} :boolean'
- refractory_var = f'timer_Na_{name} :second'
+ I_rise_eqs = f"I_rise_{ID} = g_rise_{ID} * (E_rise_{name}-V_{comp}) :amp"
+ I_fall_eqs = f"I_fall_{ID} = g_fall_{ID} * (E_fall_{name}-V_{comp}) :amp"
+
+ # Ion conductances
+ g_rise_eqs = (
+ f"g_rise_{ID} = "
+ f"g_rise_max_{ID} * "
+ f"int(t_in_timesteps <= spiketime_{ID} + duration_rise_{ID}) * "
+ f"gate_{ID} "
+ ":siemens"
+ )
+ g_fall_eqs = (
+ f"g_fall_{ID} = "
+ f"g_fall_max_{ID} * "
+ f"int(t_in_timesteps <= spiketime_{ID} + offset_fall_{ID} + duration_fall_{ID}) * "
+ f"int(t_in_timesteps >= spiketime_{ID} + offset_fall_{ID}) * "
+ f"gate_{ID} "
+ ":siemens"
+ )
+ spiketime = f'spiketime_{ID} :1' # in units of timestep
+ gate = f'gate_{ID} :1' # zero or one
+
# Add equations to a compartment
- to_replace = f'= I_ext_{name}'
+ to_replace = f'= I_ext_{comp}'
self._equations = self._equations.replace(
- to_replace, f'{to_replace} + {dspike_currents}')
- self._equations += '\n'.join(['', I_Na_eqs, I_Kn_eqs, g_Na_eqs, g_Kn_eqs,
- I_Na_check, I_Kn_check, refractory_var])
- # Create all necessary custom _events for dspikes:
- condition_I_Na = library['condition_I_Na']
- condition_I_Kn = library['condition_I_Kn']
- if not self._events:
- self._events = {}
- self._events[f"activate_I_Na_{name}"] = condition_I_Na.format(name)
- self._events[f"activate_I_Kn_{name}"] = condition_I_Kn.format(name)
+ to_replace,
+ f'{to_replace} + {dspike_currents}'
+ )
+ self._equations += '\n'.join(['', I_rise_eqs, I_fall_eqs,
+ g_rise_eqs, g_fall_eqs,
+ spiketime, gate]
+ )
+
+ # Create and add custom dspike event
+ event_name = f"spike_{ID}"
+ condition = (f"V_{comp} >= Vth_{ID} and "
+ f"t_in_timesteps >= spiketime_{ID} + refractory_{ID} * gate_{ID}"
+ )
+
+ self._events[event_name] = condition
# Specify what is going to happen inside run_on_event()
+ action = {f"spike_{ID}": f"spiketime_{ID} = t_in_timesteps; gate_{ID} = 1"}
if not self._event_actions:
- self._event_actions = library['run_on_Na_spike'].format(name)
+ self._event_actions = action
else:
- self._event_actions += "\n" + \
- library['run_on_Na_spike'].format(name)
+ self._event_actions.update(action)
+
# Include params needed
- if not self._params:
- self._params = {}
- if threshold:
- self._params[f"Vth_Na_{self.name}"] = threshold
- if g_rise:
- self._params[f"g_Na_{self.name}_max"] = g_rise
- if g_fall:
- self._params[f"g_Kn_{self.name}_max"] = g_fall
-
- def _Ca_spikes(self, threshold: Quantity = None, g_rise: Quantity = None,
- g_fall: Quantity = None):
- # TODO: check that it works as expected.
+ if not self._dspike_params:
+ self._dspike_params = {}
+
+ dt = defaultclock.dt
+
+ params = [threshold,
+ g_rise,
+ g_fall,
+ self._ionic_param(reversal_rise),
+ self._ionic_param(reversal_fall),
+ self._timestep(duration_rise, dt),
+ self._timestep(duration_fall, dt),
+ self._timestep(offset_fall, dt),
+ self._timestep(refractory, dt)]
+
+ vars = [f"Vth_{ID}",
+ f"g_rise_max_{ID}",
+ f"g_fall_max_{ID}",
+ f"E_rise_{name}",
+ f"E_fall_{name}",
+ f"duration_rise_{ID}",
+ f"duration_fall_{ID}",
+ f"offset_fall_{ID}",
+ f"refractory_{ID}"]
+
+ d = dict(zip(vars, params))
+ self._dspike_params[ID] = d
+
+ def _timestep(self,
+ param: Union[Quantity, None], dt
+ ) -> Union[int, None]:
+ if not param:
+ return None
+ if isinstance(param, Quantity):
+ return timestep(param, dt)
+ else:
+ raise ValueError(
+ f"Please provide a valid time parameter for '{self.name}'."
+ )
+
+ def _ionic_param(self,
+ param: Union[str, Quantity, None],
+ ) -> Union[Quantity, None]:
+ DEFAULT_PARAMS = EphysProperties.DEFAULT_PARAMS
+ valid_params = {k: v for k, v in DEFAULT_PARAMS.items() if k[0] == 'E'}
+ if not param:
+ return None
+ if isinstance(param, Quantity):
+ return param
+ elif isinstance(param, str):
+ try:
+ return DEFAULT_PARAMS[param]
+ except KeyError:
+ raise ValueError(
+ f"Please provide a valid ionic parameter for '{self.name}'."
+ " Available options:\n"
+ f"{pp.pformat(valid_params)}"
+ )
+ else:
+ raise ValueError(
+ f"Please provide a valid ionic parameter for '{self.name}'."
+ " Available options:\n"
+ f"{pp.pformat(valid_params)}"
+ )
+
+ @property
+ def parameters(self) -> dict:
"""
- Coming soon.
+ Returns a dictionary of all parameters that have been generated for a
+ single compartment.
+
+ Returns
+ -------
+ dict
"""
- pass
-
- # # The following code creates all necessary equations for dspikes:
- # name = self.name
- # dspike_currents = f'I_Ca_{name} + I_Kc_{name}'
-
- # I_Ca_eqs = f'dI_Ca_{name}/dt = -I_Ca_{name}/tau_Ca :amp'
- # I_Kc_eqs = f'dI_Kc_{name}/dt = -I_Kc_{name}/tau_Kc :amp'
-
- # I_Ca_check = f'allow_I_Ca_{name} :boolean'
- # I_Kc_check = f'allow_I_Kc_{name} :boolean'
-
- # refractory_var = f'timer_Ca_{name} :second'
- # to_replace = f'= I_ext_{name}'
-
- # self._equations = self._equations.replace(
- # to_replace, f'{to_replace} + {dspike_currents}')
- # self._equations += '\n'.join(['', I_Ca_eqs, I_Kc_eqs, I_Ca_check,
- # I_Kc_check, refractory_var])
-
- # # Create all necessary custom _events for dspikes:
- # condition_I_Ca = library['condition_I_Ca']
- # condition_I_Kc = library['condition_I_Kc']
- # if not self._events:
- # self._events = {}
- # self._events[f"activate_I_Ca_{name}"] = condition_I_Ca.format(name)
- # self._events[f"activate_I_Kc_{name}"] = condition_I_Kc.format(name)
-
- # # Specify what is going to happen inside run_on_event()
- # if not self._event_actions:
- # self._event_actions = library['run_on_Ca_spike'].format(name)
- # else:
- # self._event_actions += "\n" + \
- # library['run_on_Ca_spike'].format(name)
- # # Include params needed
- # if not self._params:
- # self._params = {}
- # if threshold:
- # self._params[f"Vth_Ca_{self.name}"] = threshold
- # if g_rise:
- # self._params[f"g_Ca_{self.name}_max"] = g_rise
- # if g_fall:
- # self._params[f"g_Kc_{self.name}_max"] = g_fall
+ d_out = {}
+ for i in [self._params, self._g_couples]:
+ if i:
+ d_out.update(i)
+ if self._dspike_params:
+ for d in self._dspike_params.values():
+ d_out.update(d)
+ if self._ephys_object:
+ d_out.update(self._ephys_object.parameters)
+ return d_out
@property
def events(self) -> dict:
"""
- A dictionary of all dSpike events created for a single dendrite.
+ Returns a dictionary of all dSpike events created for a single dendrite.
Returns
-------
dict
Keys: event names, values: events conditions.
"""
- return self._events
+ return self._events if self._events else {}
@property
- def event_actions(self) -> str:
+ def event_names(self) -> list:
"""
- A string that is used to tell Brian how to handle the dSpike events.
+ Returns a list of all dSpike event names created for a single dendrite.
Returns
-------
- str
- Executable code that runs automatically in the background.
+ list
"""
- return self._event_actions
+ if not self._events:
+ return []
+ return list(self._events.keys())
diff --git a/dendrify/ephysproperties.py b/dendrify/ephysproperties.py
index e05a402..5f07d55 100644
--- a/dendrify/ephysproperties.py
+++ b/dendrify/ephysproperties.py
@@ -1,9 +1,37 @@
from __future__ import annotations
+import pprint as pp
from math import pi
-from typing import List, Optional, Tuple, Union
+from typing import Optional
-from brian2.units import Quantity
+from brian2.units import *
+
+from .utils import DimensionlessCompartmentError, get_logger
+
+logger = get_logger(__name__)
+
+
+def default_params() -> dict:
+ """
+ Returns the default ephys parameters.
+
+ Returns
+ -------
+ dict
+ """
+ return EphysProperties.DEFAULT_PARAMS
+
+
+def update_default_params(params: dict) -> None:
+ """
+ Updates the default ephys parameters.
+
+ Parameters
+ ----------
+ params : dict
+ A dictionary of ionic parameters
+ """
+ EphysProperties.DEFAULT_PARAMS.update(params)
class EphysProperties(object):
@@ -13,62 +41,111 @@ class EphysProperties(object):
Note
----
- An EphysProperties object is automatically created and linked to a
- :class:`.Compartment`, :class:`.Soma`, or :class:`.Dendrite` object
- during the instantiation of the latter.
+ An EphysProperties object is automatically created and linked to a
+ single compartment during the initialization of the latter.
Parameters
----------
name : str, optional
- A compartment's name, by default ``None``
+ A compartment's name.
length : ~brian2.units.fundamentalunits.Quantity, optional
- A compartment's length, by default ``None``
+ A compartment's length.
diameter : ~brian2.units.fundamentalunits.Quantity, optional
- A compartment's diameter, by default ``None``
+ A compartment's diameter.
cm : ~brian2.units.fundamentalunits.Quantity, optional
- Specific capacitance (usually μF / cm^2), by default ``None``
+ Specific capacitance (usually μF / cm^2).
gl : ~brian2.units.fundamentalunits.Quantity, optional
- Specific leakage conductance (usually μS / cm^2), by default ``None``
+ Specific leakage conductance (usually μS / cm^2).
+ cm_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute capacitance (usually pF).
+ gl_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute leakage conductance (usually nS).
r_axial : ~brian2.units.fundamentalunits.Quantity, optional
- Axial resistance (usually Ohm * cm), by default ``None``
+ Axial resistance (usually Ohm * cm).
v_rest : ~brian2.units.fundamentalunits.Quantity, optional
- Resting membrane voltage, by default ``None``
+ Resting membrane voltage.
scale_factor : float, optional
- A global area scale factor, by default ``1.0``
+ A global area scale factor, by default ``1.0``.
spine_factor : float, optional
- A dendritic area scale factor to account for spines, by default ``1.0``
+ A dendritic area scale factor to account for spines, by default ``1.0``.
"""
- def __init__(self, name: Optional[str] = None,
- length: Optional[Quantity] = None,
- diameter: Optional[Quantity] = None,
- cm: Optional[Quantity] = None,
- gl: Optional[Quantity] = None,
- r_axial: Optional[Quantity] = None,
- v_rest: Optional[Quantity] = None,
- scale_factor: float = 1.0,
- spine_factor: float = 1.0):
+ DEFAULT_PARAMS = {
+ "E_AMPA": 0 * mV,
+ "E_NMDA": 0 * mV,
+ "E_GABA": -80 * mV,
+ "E_Na": 70 * mV,
+ "E_K": -89 * mV,
+ "E_Ca": 136 * mV,
+ "Mg_con": 1.0,
+ "Alpha_NMDA": 0.062,
+ "Beta_NMDA": 3.57,
+ "Gamma_NMDA": 0
+ }
+
+ def __init__(
+ self,
+ name: Optional[str] = None,
+ length: Optional[Quantity] = None,
+ diameter: Optional[Quantity] = None,
+ cm: Optional[Quantity] = None,
+ gl: Optional[Quantity] = None,
+ cm_abs: Optional[Quantity] = None,
+ gl_abs: Optional[Quantity] = None,
+ r_axial: Optional[Quantity] = None,
+ v_rest: Optional[Quantity] = None,
+ scale_factor: Optional[float] = 1.0,
+ spine_factor: Optional[float] = 1.0
+ ):
self.name = name
self.length = length
self.diameter = diameter
self.cm = cm
self.gl = gl
+ self.cm_abs = cm_abs
+ self.gl_abs = gl_abs
self.r_axial = r_axial
self.v_rest = v_rest
- self.scale_factor = scale_factor
- self.spine_factor = spine_factor
+ self.scale_factor = scale_factor if not any([cm_abs, gl_abs]) else None
+ self.spine_factor = spine_factor if not any([cm_abs, gl_abs]) else None
+ self._dimensionless = True if any([cm_abs, gl_abs]) else False
+ self._check_dimensionless()
def __str__(self):
- attrs = self.__dict__
- details = [f"\u2192 {i}: \n{attrs[i]}\n" for i in attrs]
- msg = ("OBJECT:\n{0}\n"
- "\n=======================================================\n\n"
- "ATTRIBUTES:\n{1}")
- return msg.format(self.__class__, "\n".join(details))
+ attrs = pp.pformat(self.__dict__)
+ txt = (f"OBJECT:\n{self.__class__}\n\n"
+ f"ATTRIBUTES:\n{attrs}"
+ )
+ return txt
+
+ def _check_dimensionless(self):
+ """
+ Ensure that no redundant parameters are provided when a dimensionless
+ compartment is created (i.e., when absolute values of capacitance and
+ leakage conductance are provided).
+ """
+ not_dimensionless = [self.length, self.diameter,
+ self.cm, self.gl, self.r_axial]
+
+ if self._dimensionless and any(not_dimensionless):
+ raise DimensionlessCompartmentError(
+ ("\nRedundant or incompatible parameters were detected "
+ f"during \nthe initialization of '{self.name}'. "
+ "When absolute values of \ncapacitance [cm_abs] or leakage "
+ "conductance [gl_abs] are \nused, a dimensionless "
+ "compartment is created by default. \nTo resolve this error, "
+ "you can perform one of the following:\n\n"
+ "1. Discard these parameters [length, diameter, cm,"
+ "gl, r_axial]\n if you want to create a dimensionless "
+ "compartment.\n\n"
+ "2. Discard these parameters [cm_abs, gl_abs] if you want to\n"
+ " create a compartment with physical dimensions."
+ )
+ )
@property
- def total_area_factor(self) -> float:
+ def _total_area_factor(self) -> float:
"""
The total surface are factor.
@@ -79,91 +156,118 @@ def total_area_factor(self) -> float:
return self.scale_factor * self.spine_factor
@property
- def area(self) -> Quantity:
+ def area(self) -> Quantity | None:
"""
- A compartment's surface area (open cylinder) based on its length and
- diameter.
+ Returns compartment's surface area (open cylinder) based on its length
+ and diameter.
Returns
-------
~brian2.units.fundamentalunits.Quantity
A compartment's surface area
"""
- try:
- return pi * self.length * self.diameter * self.total_area_factor
- except TypeError:
- print(("ERROR: Missing Parameters ('length' or 'diameter')\n"
- f"Could not calculate the area of <{self.name}>, "
- "returned None instead\n"))
+ if self._dimensionless:
+ logger.warning(
+ (f"Surface area is not defined for the dimensionless "
+ f"compartment: '{self.name}'"
+ f"\nReturning None instead."
+ )
+ )
+ else:
+ try:
+ return pi * self.length * self.diameter * self._total_area_factor
+ except TypeError:
+ logger.warning(
+ (f"Missing parameters [length | diameter] for '{self.name}'."
+ f"\nCould not calculate the area of '{self.name}', "
+ "returned None."
+ )
+ )
@property
- def capacitance(self) -> Quantity:
+ def capacitance(self) -> Quantity | None:
"""
- A compartment's absolute capacitance based on its specific capacitance
- (cm) and surface area.
+ Returns a compartment's capacitance based on its specific capacitance
+ (cm) and surface area. If an absolute capacitance (cm_abs) has been
+ provided by the user, it returns this value instead.
Returns
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
- try:
- return self.area * self.cm
- except TypeError:
- print(("ERROR: Missing Parameters ('cm')\n"
- f"Could not calculate the capacitance of <{self.name}>, "
- "returned None instead"))
+ if self._dimensionless:
+ if self.cm_abs:
+ return self.cm_abs
+ else:
+ logger.warning(
+ f"Missing parameter [cm_abs] for '{self.name}', "
+ "returned None."
+ )
+ else:
+ try:
+ return self.area * self.cm
+ except TypeError:
+ logger.warning(
+ (f"Could not calculate the [capacitance] of '{self.name}', "
+ "returned None."
+ )
+ )
@property
def g_leakage(self) -> Quantity:
"""
- A compartment's absolute leakage conductance based on its specific
- leakage conductance (gl) and surface area.
+ Returns a compartment's absolute leakage conductance based on its
+ specific leakage conductance (gl) and surface area. If an absolute
+ leakage conductance (gl_abs) has been provided by the user, it returns
+ this value instead.
Returns
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
- try:
- return self.area * self.gl
- except TypeError:
- print(("ERROR: Missing Parameters ('gl')\n"
- f"Could not calculate the g_leakage of <{self.name}>, "
- "returned None instead"))
+ if self._dimensionless:
+ if self.gl_abs:
+ return self.gl_abs
+ else:
+ logger.warning(
+ f"Missing parameter [gl_abs] for '{self.name}', "
+ "returned None."
+ )
+ else:
+ try:
+ return self.area * self.gl
+ except TypeError:
+ logger.warning(
+ (f"Could not calculate the [g_leakage] of '{self.name}', "
+ "returned None."
+ )
+ )
@property
def parameters(self) -> dict:
"""
- Returns a dictionary of all electrophysiological parameters.
+ Returns a dictionary of all the major electrophysiological parameters
+ that describe a single compartment.
Returns
-------
dict
"""
- d = {}
- error = None
-
- if self.v_rest:
- d[f"EL_{self.name}"] = self.v_rest
- else:
- print(f"ERROR: Could not resolve 'EL_{self.name}'\n")
- error = True
-
- if self.capacitance:
- d[f"C_{self.name}"] = self.capacitance
- else:
- print(f"Could not resolve 'C_{self.name}'\n")
- error = True
-
- if self.g_leakage:
- d[f"gL_{self.name}"] = self.g_leakage
- else:
- print(f"Could not resolve 'gL_{self.name}'")
- error = True
+ d_out = {}
+ EL, C, gL = self.v_rest, self.capacitance, self.g_leakage
- if error:
- print("\nWARNING: One or more parameters are "
- f"missing for '{self.name}' !!!\n")
- return d
+ for value, var in zip([EL, C, gL], ['EL', 'C', 'gL']):
+ if value:
+ if self.name:
+ d_out[f"{var}_{self.name}"] = value
+ else:
+ d_out[f"{var}"] = value
+ else:
+ logger.error(
+ f"Could not resolve [{var}_{self.name}] for '{self.name}'."
+ )
+ d_out.update(self.DEFAULT_PARAMS)
+ return d_out
@property
def g_cylinder(self) -> Quantity:
@@ -177,12 +281,20 @@ def g_cylinder(self) -> Quantity:
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
+ if self._dimensionless:
+ raise DimensionlessCompartmentError(
+ f"Calculating [g_cylinder] is invalid for '{self.name}', since\n"
+ "it is a dimensionless compartment. To connect two dimensionless"
+ " compartments, an exact \nvalue for g_couple must be provided."
+ )
try:
ri = (4*self.r_axial*self.length) / (pi*self.diameter**2)
except TypeError:
- print(("ERROR: Missing Parameters \n"
- f"Could not calculate the g_cylinder of <{self.name}>, "
- "returned None instead."))
+ logger.warning(
+ (f"Could not calculate [g_cylinder] for '{self.name}'.\n"
+ "Please make sure that [length, diameter, r_axial]\n"
+ "are available.")
+ )
else:
return 1/ri
@@ -204,13 +316,28 @@ def g_couple(comp1: EphysProperties, comp2: EphysProperties) -> Quantity:
-------
:class:`~brian2.units.fundamentalunits.Quantity`
"""
+ if any([comp1._dimensionless, comp2._dimensionless]):
+ raise DimensionlessCompartmentError(
+ ("Cannot automatically calculate the coupling \nconductance of "
+ "dimensionless compartments. To resolve this error, perform\n"
+ "one of the following:\n\n"
+ f"1. Provide [length, diameter, r_axial] for both '{comp1.name}'"
+ f" and '{comp2.name}'.\n\n"
+ f"2. Turn both compartment into dimensionless by providing only"
+ " values for \n [cm_abs, gl_abs] and then connect them using "
+ "an exact coupling conductance."
+ )
+ )
try:
r1 = (4 * comp1.r_axial * comp1.length) / (pi * comp1.diameter**2)
r2 = (4 * comp2.r_axial * comp2.length) / (pi * comp2.diameter**2)
ri = (r1+r2) / 2
except TypeError:
- print(("ERROR: Missing Parameters \n"
- f"Could not calculate the g_couple of <{comp1.name}> "
- f"& <{comp2.name}>, returned None instead."))
+ logger.error(
+ (f"Could not calculate the g_couple for '{comp1.name}' and "
+ f"'{comp2.name}'.\n"
+ "Please make sure that [length, diameter, r_axial] are\n"
+ "available for both compartments.")
+ )
else:
return 1/ri
diff --git a/dendrify/equations.py b/dendrify/equations.py
index 75fbc43..eb4fd16 100644
--- a/dendrify/equations.py
+++ b/dendrify/equations.py
@@ -42,28 +42,68 @@
'ds_GABA_{1}_{0}/dt = -s_GABA_{1}_{0} / t_GABA_rise_{1}_{0} :1'),
# NMDA equations with rise and decay kinetics:
- 'NMDA': ('I_NMDA_{1}_{0} = g_NMDA_{1}_{0} * (E_NMDA-V_{0}) * s_NMDA_{1}_{0} / (1 + Mg * exp(-alpha*(V_{0}/mV+gamma)) / beta) * w_NMDA_{1}_{0} :amp\n'
+ 'NMDA': ('I_NMDA_{1}_{0} = g_NMDA_{1}_{0} * (E_NMDA-V_{0}) * s_NMDA_{1}_{0} / (1 + Mg_con * exp(-Alpha_NMDA*(V_{0}/mV+Gamma_NMDA)) / Beta_NMDA) * w_NMDA_{1}_{0} :amp\n'
'ds_NMDA_{1}_{0}/dt = -s_NMDA_{1}_{0}/t_NMDA_decay_{1}_{0} :1'),
# NMDA equations with rise and decay kinetics:
- 'NMDA_rd': ('I_NMDA_{1}_{0} = g_NMDA_{1}_{0} * (E_NMDA-V_{0}) * x_NMDA_{1}_{0} / (1 + Mg * exp(-alpha*(V_{0}/mV+gamma)) / beta) * w_NMDA_{1}_{0} :amp\n'
+ 'NMDA_rd': ('I_NMDA_{1}_{0} = g_NMDA_{1}_{0} * (E_NMDA-V_{0}) * x_NMDA_{1}_{0} / (1 + Mg_con * exp(-Alpha_NMDA*(V_{0}/mV+Gamma_NMDA)) / Beta_NMDA) * w_NMDA_{1}_{0} :amp\n'
'dx_NMDA_{1}_{0}/dt = (-x_NMDA_{1}_{0}/t_NMDA_decay_{1}_{0}) + s_NMDA_{1}_{0}/ms :1\n'
'ds_NMDA_{1}_{0}/dt = -s_NMDA_{1}_{0} / t_NMDA_rise_{1}_{0} :1'),
# Random white noise equations:
- 'noise': 'dI_noise_{0}/dt = (mean_noise_{0}-I_noise_{0}) / tau_noise_{0} + sigma_noise_{0} * (sqrt(2/(tau_noise_{0}*dt)) * randn()) :amp',
+ 'noise': 'dI_noise_{0}/dt = (mean_noise_{0}-I_noise_{0}) / tau_noise_{0} + sigma_noise_{0} * (sqrt(2/(tau_noise_{0}*dt)) * randn()) :amp'
+}
- 'condition_I_Na': 'V_{0} > Vth_Na_{0} and allow_I_Na_{0} and t > timer_Na_{0} + refractory_Na',
+library_point = {
+ # Adaptive exponential integrate & fire:
+ 'adex': ('dV/dt = (gL * (EL-V) + gL*DeltaT*exp((V-Vth)/DeltaT) + I - w) / C :volt\n'
+ 'dw/dt = (a * (V-EL) -w) / tauw :amp\n'
+ 'I = I_ext :amp\n'
+ 'I_ext :amp'),
- 'condition_I_Kn': 't > (timer_Na_{0} + offset_Kn) and allow_I_Kn_{0}',
+ # Leaky integrate and fire with adaptation:
+ 'adaptiveIF': ('dV/dt = (gL * (EL-V) + I - w) / C :volt\n'
+ 'dw/dt = (a * (V-EL) - w) / tauw :amp\n'
+ 'I = I_ext :amp\n'
+ 'I_ext :amp'),
- 'condition_I_Ca': 'V_{0} > Vth_Ca_{0} and allow_I_Ca_{0} and t > timer_Ca_{0} + refractory_Ca',
+ # Leaky integrate and fire:
+ 'leakyIF': ('dV/dt = (gL * (EL-V) + I) / C :volt\n'
+ 'I = I_ext :amp\n'
+ 'I_ext :amp'),
- 'condition_I_Kc': 't > (timer_Ca_{0} + offset_Kc) and allow_I_Kc_{0}',
+ # Leaky membrane:
+ 'passive': ('dV/dt = (gL * (EL-V) + I) / C :volt\n'
+ 'I = I_ext :amp\n'
+ 'I_ext :amp'),
- 'run_on_Na_spike': ("run_on_event('activate_I_Na_{0}', 'g_Na_{0} += g_Na_{0}_max; allow_I_Na_{0}=False; allow_I_Kn_{0}=True; timer_Na_{0} = t') \n"
- "run_on_event('activate_I_Kn_{0}', 'g_Kn_{0} += g_Kn_{0}_max; allow_I_Kn_{0}=False; allow_I_Na_{0}=True')"),
+ # AMPA equations with instant rise (only decay kinetics):
+ 'AMPA': ('I_AMPA_{0} = g_AMPA_{0} * (E_AMPA-V) * s_AMPA_{0} * w_AMPA_{0} :amp\n'
+ 'ds_AMPA_{0}/dt = -s_AMPA_{0} / t_AMPA_decay_{0} :1'),
+
+ # AMPA equations with rise and decay kinetics:
+ 'AMPA_rd': ('I_AMPA_{0} = g_AMPA_{0} * (E_AMPA-V) * x_AMPA_{0} * w_AMPA_{0} :amp\n'
+ 'dx_AMPA_{0}/dt = (-x_AMPA_{0}/t_AMPA_decay_{0}) + s_AMPA_{0}/ms :1\n'
+ 'ds_AMPA_{0}/dt = -s_AMPA_{0} / t_AMPA_rise_{0} :1'),
- 'run_on_Ca_spike': ("run_on_event('activate_I_Ca_{0}', 'g_Ca_{0} += g_Ca_{0}_max; allow_I_Ca_{0}=False; allow_I_Kc_{0}=True; timer_Ca_{0} = t') \n"
- "run_on_event('activate_I_Kc_{0}', 'g_Kc_{0} += g_Kc_{0}_max; allow_I_Kc_{0}=False; allow_I_Ca_{0}=True')")
+ # GABA equations with instant rise (only decay kinetics):
+ 'GABA': ('I_GABA_{0} = g_GABA_{0} * (E_GABA-V) * s_GABA_{0} * w_GABA_{0} :amp\n'
+ 'ds_GABA_{0}/dt = -s_GABA_{0} / t_GABA_decay_{0} :1'),
+
+ # GABA equations with rise and decay kinetics:
+ 'GABA_rd': ('I_GABA_{0} = g_GABA_{0} * (E_GABA-V) * x_GABA_{0} * w_GABA_{0} :amp\n'
+ 'dx_GABA_{0}/dt = (-x_GABA_{0}/t_GABA_decay_{0}) + s_GABA_{0}/ms :1\n'
+ 'ds_GABA_{0}/dt = -s_GABA_{0} / t_GABA_rise_{0} :1'),
+
+ # NMDA equations with rise and decay kinetics:
+ 'NMDA': ('I_NMDA_{0} = g_NMDA_{0} * (E_NMDA-V) * s_NMDA_{0} / (1 + Mg_con * exp(-Alpha_NMDA*(V/mV+Gamma_NMDA)) / Beta_NMDA) * w_NMDA_{0} :amp\n'
+ 'ds_NMDA_{0}/dt = -s_NMDA_{0}/t_NMDA_decay_{0} :1'),
+
+ # NMDA equations with rise and decay kinetics:
+ 'NMDA_rd': ('I_NMDA_{0} = g_NMDA_{0} * (E_NMDA-V) * x_NMDA_{0} / (1 + Mg_con * exp(-Alpha_NMDA*(V/mV+Gamma_NMDA)) / Beta_NMDA) * w_NMDA_{0} :amp\n'
+ 'dx_NMDA_{0}/dt = (-x_NMDA_{0}/t_NMDA_decay_{0}) + s_NMDA_{0}/ms :1\n'
+ 'ds_NMDA_{0}/dt = -s_NMDA_{0} / t_NMDA_rise_{0} :1'),
+
+ # Random white noise equations:
+ 'noise': 'dI_noise/dt = (mean_noise-I_noise) / tau_noise + sigma_noise * (sqrt(2/(tau_noise*dt)) * randn()) :amp'
}
diff --git a/dendrify/neuronmodel.py b/dendrify/neuronmodel.py
index e013cdb..efdc291 100644
--- a/dendrify/neuronmodel.py
+++ b/dendrify/neuronmodel.py
@@ -1,11 +1,18 @@
-import sys
+import pprint as pp
+from copy import deepcopy
from typing import List, Optional, Tuple, Union
-import __main__ as main
-from brian2 import NeuronGroup
-from brian2.units import Quantity, mV, mvolt
+import numpy as np
+from brian2 import NeuronGroup, Synapses, defaultclock
+from brian2.units import Quantity, ms, pA
from .compartment import Compartment, Dendrite, Soma
+from .ephysproperties import EphysProperties
+from .equations import library_point
+from .utils import (DimensionlessCompartmentError, DuplicateEquationsError,
+ get_logger)
+
+logger = get_logger(__name__)
class NeuronModel:
@@ -25,7 +32,7 @@ class NeuronModel:
substitute morphologically and biophysically detailed neuron models,
commonly used for highly-accurate, single-cell simulations. If you are
interested in the latter category of models, please see Brian's
- :doc:`SpatialNeuron
+ :doc:`SpatialNeuron
`.
Parameters
@@ -33,15 +40,23 @@ class NeuronModel:
connections : list[tuple[Compartment, Compartment, str | Quantity]]
A description of how the various compartments belonging to the same
neuron model should be connected.
- kwargs : :class:`~brian2.units.fundamentalunits.Quantity`, optional
- Kwargs are used to specify important electrophysiological properties,
- such as the specific capacitance or resistance. For all available options
- see: :class:`.EphysProperties`.
+ cm : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific capacitance (usually μF / cm^2).
+ gl : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific leakage conductance (usually μS / cm^2).
+ r_axial : ~brian2.units.fundamentalunits.Quantity, optional
+ Axial resistance (usually Ohm * cm).
+ v_rest : ~brian2.units.fundamentalunits.Quantity, optional
+ Resting membrane voltage.
+ scale_factor : float, optional
+ A global area scale factor, by default ``1.0``.
+ spine_factor : float, optional
+ A dendritic area scale factor to account for spines, by default ``1.0``.
Warning
-------
Parameters set here affect all model compartments and can override any
- compartment-specific parameters.
+ compartment-specific parameters.
Example
-------
@@ -50,174 +65,326 @@ class NeuronModel:
>>> # y -> Soma or Dendrite object other than x
>>> # z -> 'half_cylinders' or 'cylinder_ + name' or brian2.nS unit
>>> # (by default 'half_cylinders')
- >>> soma = Soma('s', ...)
- >>> prox = Dendrite('p', ...)
- >>> dist = Dendrite('d', ...)
+ >>> soma = Soma(...)
+ >>> prox = Dendrite(...)
+ >>> dist = Dendrite(...)
>>> connections = [(soma, prox, 15*nS), (prox, dist, 10*nS)]
>>> model = NeuronModel(connections)
"""
- # Default values for key ionic mechanisms
- DEFAULTS = {"E_AMPA": 0 * mV,
- "E_NMDA": 0 * mV,
- "E_GABA": -80 * mV,
- "E_Na": 70 * mV,
- "E_K": -89 * mV,
- "E_Ca": 136 * mV,
- "Mg": 1.0,
- "alpha": 0.062,
- "beta": 3.57,
- "gamma": 0}
-
- def __init__(self, connections: List[
- Tuple[Compartment, Compartment, Union[str, Quantity]]], **kwargs):
- self._namespace = None
+ def __init__(
+ self,
+ connections: List[Tuple[Compartment,
+ Compartment,
+ Union[str, Quantity, None]]],
+ cm: Optional[Quantity] = None,
+ gl: Optional[Quantity] = None,
+ r_axial: Optional[Quantity] = None,
+ v_rest: Optional[Quantity] = None,
+ scale_factor: Optional[float] = None,
+ spine_factor: Optional[float] = None,
+ ):
self._compartments = None
- self._linked_neurongroup = None
- self._varscope = None
self._extra_equations = None
self._extra_params = None
self._graph = None
self._parse_compartments(connections)
- self._set_properties(**kwargs)
+ self._set_properties(cm=cm, gl=gl,
+ r_axial=r_axial,
+ v_rest=v_rest,
+ scale_factor=scale_factor,
+ spine_factor=spine_factor)
def __str__(self):
- equations = self.equations.replace('\n', '\n ')
- if self.parameters:
- params_sorted = {key: self.parameters[key]
- for key in sorted(self.parameters)}
- parameters = '\n'.join([f" '{i[0]}': {i[1]}"
- for i in params_sorted.items()])
- else:
- parameters = ' None'
-
- if self._extra_params:
- extra_params_sorted = {key: self._extra_params[key]
- for key in sorted(self._extra_params)}
- extra_params = '\n'.join([f" '{i[0]}': {i[1]}"
- for i in extra_params_sorted.items()])
- else:
- extra_params = ' None'
-
- events = '\n'.join([f" '{key}': '{self.events[key]}'"
- for key in self.events
- ]) if self.events else ' None'
-
- msg = (f"OBJECT TYPE:\n\n {self.__class__}\n\n"
- f"{'-'*45}\n\n"
- "PROPERTIES (type): \n\n"
- f"\u2192 equations (str):\n {equations}\n\n"
- f"\u2192 parameters (dict):\n{parameters}\n\n"
- f"\u2192 events (dict):\n{events}\n"
- f"\n{'-'*45}\n\n"
- f"USEFUL ATTRIBUTES:\n\n"
- f"\u2192 _linked_neurongroup:\n {self._linked_neurongroup}\n\n"
- f"\u2192 _extra_equations:\n {self._extra_equations}\n\n"
- f"\u2192 _extra_params:\n{extra_params}\n")
- return msg
+ equations = self.equations
+ parameters = pp.pformat(self.parameters)
+ events = pp.pformat(self.events, width=120)
+ event_names = pp.pformat(self.event_names)
+ txt = (f"\nOBJECT\n{6*'-'}\n{self.__class__}\n\n\n"
+ f"EQUATIONS\n{9*'-'}\n{equations}\n\n\n"
+ f"PARAMETERS\n{10*'-'}\n{parameters}\n\n\n"
+ f"EVENTS\n{6*'-'}\n{event_names}\n\n\n"
+ f"EVENT CONDITIONS\n{16*'-'}\n{events}\n\n\n"
+ )
+ return txt
def _parse_compartments(self, comp_list):
- error_msg = (
- "\nValid format: [*(x, y, z)] \n"
- "- x -> Soma or Dendrite object\n"
- "- y -> Soma or Dendrite object other than x\n"
- "- z -> 'half_cylinders' or 'cylinder_ + name' or brian2.nS unit\n"
- " (default is 'half_cylinders' if left blank)\n\n"
- "Example:\n"
- "[(comp1, comp2), (comp2, comp3, 10*nS), "
- "(comp3, comp4, 'cylinder_c3')]\n")
-
+ # Ensure that all compartments have a unique names
+ ids, names = [], []
+ for tup in comp_list:
+ for i in tup:
+ if isinstance(i, Compartment):
+ ids.append(id(i))
+ names.append(i.name)
+ if len(set(ids)) != len(set(names)):
+ raise ValueError(
+ ("Please make sure that all compartments included to a single "
+ "NeuronModel have unique names.")
+ )
+ # Start parsing
self._compartments = []
self._graph = []
- for comp in comp_list:
- pre, post = comp[0], comp[1]
-
- # Prohibit self connections
- if pre is post:
- print(f"ERROR: Cannot connect '{pre.name}' to itself.")
- print(error_msg)
- sys.exit()
-
- # Ensure that users do not use objects that make no sense
- if not (isinstance(pre, Compartment) and
- isinstance(post, Compartment)):
- print(f"ERROR: Unknown compartment type provided.")
- print(error_msg)
- sys.exit()
-
+ # Copy compartments to avoid modifying the original objects
+ copied_list = self._copy_compartments(comp_list)
+ for tup in copied_list:
+ pre, post = tup[0], tup[1]
# Store graph-like representation for debugging or visualization
self._graph.append((pre.name, post.name))
-
# Include all compartments in a list for easy access
if pre not in self._compartments:
self._compartments.append(pre)
if post not in self._compartments:
self._compartments.append(post)
-
- # Call the connect method from the Compartment class
- if len(comp) == 2:
+ # Call the connect method from the Compartment class
+ if len(tup) == 2:
pre.connect(post)
else:
- pre.connect(post, g=comp[2])
+ pre.connect(post, g=tup[2])
+ # Check if all compartments are dimensionless or not
+ is_dimensionless = [i.dimensionless for i in self._compartments]
+ if True in is_dimensionless and False in is_dimensionless:
+ raise DimensionlessCompartmentError(
+ "When creating a NeuronModel, either all of its\n"
+ "compartments must be dimensionless or none of them. "
+ "To resolve this issue, you\n"
+ "can perform one of the following:\n\n"
+ "1. Discard these parameters [length, diameter, cm,"
+ "gl, r_axial]\n if you want to create dimensionless "
+ "compartments.\n\n"
+ "2. Discard these parameters [cm_abs, gl_abs] if you want to\n"
+ " create compartments with physical dimensions."
+ )
+
+ def _copy_compartments(self, comp_list):
+ error_msg = (
+ "\n\nValid format: [*(x, y, z)]\n"
+ f"{26*'-'}\n"
+ "x -> Soma or Dendrite object.\n"
+ "y -> Soma or Dendrite object other than x.\n"
+ "z -> 'half_cylinders' or 'cylinder_ + name' or conductance unit.\n"
+ " (default: 'half_cylinders' if left blank).\n\n"
+ "Example:\n"
+ "[(comp1, comp2), (comp2, comp3, 10*nS)] \n"
+ )
+ used = {} # Keep track of copied compartments to avoid duplicates
+ new_list = []
+ for tup in comp_list:
+ # Ensure that users provide correct format
+ if len(tup) < 2 or len(tup) > 3:
+ raise ValueError(
+ f"Invalid number of arguments provided. {error_msg}"
+ )
+ # Ensure that users do not use objects that make no sense
+ if not (isinstance(tup[0], Compartment) and
+ isinstance(tup[1], Compartment)):
+ raise TypeError(
+ f"Invalid compartment type provided. {error_msg}"
+ )
+ # Prohibit self connections
+ if tup[0] is tup[1]:
+ raise ValueError(
+ f"ERROR: Cannot connect '{tup[0].name}' to itself. "
+ f"{error_msg}"
+ )
+
+ if tup[0].name in used:
+ pre = used[tup[0].name]
+ else:
+ pre = deepcopy(tup[0])
+ used[pre.name] = pre
+ if tup[1].name in used:
+ post = used[tup[1].name]
+ else:
+ post = deepcopy(tup[1])
+ used[post.name] = post
+ if len(tup) == 2:
+ new_tup = (pre, post)
+ elif len(tup) == 3:
+ new_tup = (pre, post, tup[2])
+ new_list.append(new_tup)
+ return new_list
def _set_properties(self, cm=None, gl=None, r_axial=None, v_rest=None,
scale_factor=None, spine_factor=None):
- for i in self._compartments:
- if cm and (not i._ephys_object.cm):
- i._ephys_object.cm = cm
- if gl and (not i._ephys_object.gl):
- i._ephys_object.gl = gl
- if r_axial and (not i._ephys_object.r_axial):
- i._ephys_object.r_axial = r_axial
- if v_rest and (not i._ephys_object.v_rest):
- i._ephys_object.v_rest = v_rest
- if scale_factor:
- i._ephys_object.scale_factor = scale_factor
- if spine_factor:
- if isinstance(i, Dendrite):
- i._ephys_object.spine_factor = spine_factor
-
- def dspike_properties(self, channel: str = None,
- tau_rise: Optional[Quantity] = None,
- tau_fall: Optional[Quantity] = None,
- offset_fall: Optional[Quantity] = None,
- refractory: Optional[Quantity] = None):
- """
- Allows specifying essential dSpike properties affecting all compartments.
+
+ params = {'cm': cm, 'gl': gl, 'r_axial': r_axial,
+ 'scale_factor': scale_factor, 'spine_factor': spine_factor}
+
+ for comp in self._compartments:
+ # update v_rest for all compartments if provided
+ if v_rest:
+ comp._ephys_object.v_rest = v_rest
+ # prohibit dimensionless compartments from taking area-related params
+ if comp.dimensionless and any(params.values()):
+ raise DimensionlessCompartmentError(
+ f"The dimensionless compartment '{comp.name}' cannot take "
+ "the \nfollowing parameters: "
+ "[cm, gl, r_axial, scale_factor, spine_factor]."
+ )
+ # update all other params if provided
+ if not comp.dimensionless and any(params.values()):
+ for param, value in params.items():
+ if value:
+ setattr(comp._ephys_object, param, value)
+ # make sure to initialize area factors if not provided
+ if not value and param in ['scale_factor', 'spine_factor']:
+ setattr(comp._ephys_object, param, 1.0)
+
+
+ def config_dspikes(self, event_name: str,
+ threshold: Union[Quantity, None] = None,
+ duration_rise: Union[Quantity, None] = None,
+ duration_fall: Union[Quantity, None] = None,
+ reversal_rise: Union[Quantity, str, None] = None,
+ reversal_fall: Union[Quantity, str, None] = None,
+ offset_fall: Union[Quantity, None] = None,
+ refractory: Union[Quantity, None] = None
+ ):
+ """
+ Configure the parameters for dendritic spiking.
Parameters
----------
- channel : str
- Ion channel type. Available options: ``'Na'``, ``'Ca'`` (coming
- soon).
- tau_rise : :class:`~brian2.units.fundamentalunits.Quantity`
- The decay time constant of the current causing the dSpike's
- **depolarization** phase, by default ``None``.
- tau_fall : :class:`~brian2.units.fundamentalunits.Quantity`
- The decay time constant of the current causing the dSpike's
- **repolarization** phase, by default ``None``.
- offset_fall : :class:`~brian2.units.fundamentalunits.Quantity`
- The delay for starting the dSpike repolarization phase, by default
- ``None``.
- refractory : :class:`~brian2.units.fundamentalunits.Quantity`
- The duration of the dSpike inactive period, by default ``None``.
- """
- # Make sure user provides a valid option:
- if channel not in ['Na', 'Ca']:
- print("Please select a valid dendritic spike type ('Na' or 'Ca')")
- sys.exit()
- # Choose param names based on user input:
- if channel == 'Na':
- dspike_params = {'refractory_Na': refractory,
- 'offset_Kn': offset_fall,
- 'tau_Na': tau_rise,
- 'tau_Kn': tau_fall}
- else:
- dspike_params = {'refractory_Ca': refractory,
- 'offset_Kc': offset_fall,
- 'tau_Ca': tau_rise,
- 'tau_Kc': tau_fall}
- self.add_params(dspike_params)
+ event_name : str
+ A unique name referring to a specific dSpike type.
+ threshold : ~brian2.units.fundamentalunits.Quantity, optional
+ The membrane voltage threshold for dendritic spiking.
+ duration_rise : ~brian2.units.fundamentalunits.Quantity, optional
+ The duration of g_rise staying open.
+ duration_fall : ~brian2.units.fundamentalunits.Quantity, optional
+ The duration of g_fall staying open.
+ reversal_rise : (~brian2.units.fundamentalunits.Quantity, str), optional
+ The reversal potential of the channel that is activated during the rise
+ (depolarization) phase.
+ reversal_fall : (~brian2.units.fundamentalunits.Quantity, str), optional
+ The reversal potential of the channel that is activated during the fall
+ (repolarization) phase.
+ offset_fall : ~brian2.units.fundamentalunits.Quantity, optional
+ The delay for the activation of g_rise.
+ refractory : ~brian2.units.fundamentalunits.Quantity, optional
+ The time interval required before dSpike can be activated again.
+ """
+
+ for comp in self._compartments:
+ if isinstance(comp, Dendrite) and comp._dspike_params:
+ ID = f"{event_name}_{comp.name}"
+ dt = defaultclock.dt
+ d = {f"Vth_{ID}": threshold,
+ f"duration_rise_{ID}": comp._timestep(duration_rise, dt),
+ f"duration_fall_{ID}": comp._timestep(duration_fall, dt),
+ f"E_rise_{event_name}": comp._ionic_param(reversal_rise),
+ f"E_fall_{event_name}": comp._ionic_param(reversal_fall),
+ f"offset_fall_{ID}": comp._timestep(offset_fall, dt),
+ f"refractory_{ID}": comp._timestep(refractory, dt)}
+ comp._dspike_params[ID].update(d)
+
+ def make_neurongroup(self,
+ N: int,
+ method: str = 'euler',
+ threshold: Optional[str] = None,
+ reset: Optional[str] = None,
+ second_reset: Optional[str] = None,
+ spike_width: Optional[Quantity] = None,
+ refractory: Union[Quantity, str, bool] = False,
+ init_rest: bool = True,
+ init_events: bool = True,
+ show: bool = False,
+ **kwargs
+ ) -> Union[NeuronGroup, Tuple]:
+ """
+ Returns a Brian2 NeuronGroup object from a NeuronModel. If a second
+ reset is provided, it also returns a Synapses object to implement
+ somatic action potentials with a more realistic shape which also unlocks
+ dendritic backpropagation. This method can also take all parameters that
+ are accepted by Brian's
+ :doc:`NeuronGroup `.
+
+ Parameters
+ ----------
+ N : int
+ The number of neurons in the group.
+ method : str, optional
+ The numerical integration method. Either a string with the name of a
+ registered method (e.g. "euler") or a function that receives an
+ `Equations` object and returns the corresponding abstract code, by
+ default ``'euler'``.
+ threshold : str, optional
+ The condition which produces spikes. Should be a single line boolean
+ expression.
+ reset : str, optional
+ The (possibly multi-line) string with the code to execute on reset.
+ refractory : (Quantity, str), optional
+ Either the length of the refractory period (e.g. ``2*ms``), a string
+ expression that evaluates to the length of the refractory period
+ after each spike (e.g. ``'(1 + rand())*ms'``), or a string expression
+ evaluating to a boolean value, given the condition under which the
+ neuron stays refractory after a spike (e.g. ``'v > -20*mV'``).
+ second_reset : str, optional
+ Option to include a second reset for more realistic somatic spikes.
+ spike_width : Quantity, optional
+ The time interval between the two resets.
+ init_rest : bool, optional
+ Option to automatically initialize the voltages of all compartments
+ at the specified resting potentials, by default True.
+ init_events : bool, optional
+ Option to automatically initialize all custom events that required
+ for dendritic spiking, by default True.
+ show : bool, optional
+ Option to print the automatically initialized parameters, by default
+ False.
+ **kwargs: optional
+ All other parameters accepted by Brian's NeuronGroup.
+
+ Returns
+ -------
+ Union[NeuronGroup, Tuple]
+ If no second reset is added, it returns a NeuronGroup object.
+ Otherwise, it returns a tuple of (NeuronGroup, Synapses) objects.
+ """
+
+ group = NeuronGroup(N,
+ method=method,
+ threshold=threshold,
+ reset=reset,
+ refractory=refractory,
+ model=self.equations,
+ events=self.events,
+ namespace=self.parameters,
+ **kwargs)
+
+ if init_rest:
+ for comp in self._compartments:
+ if show:
+ print(
+ f"Setting V_{comp.name} = {comp._ephys_object.v_rest}")
+ setattr(group, f'V_{comp.name}', comp._ephys_object.v_rest)
+
+ if init_events:
+ if self.event_actions:
+ for event, action in self.event_actions.items():
+ if show:
+ print(f"Setting run_on_event('{event}', '{action}')")
+ group.run_on_event(event, action)
+
+ ap_reset = None
+ if any([second_reset, spike_width]):
+ txt = (
+ "If you wish to have a more realistic action potential shape, "
+ "please provide \nvalid values for both [second_reset] and "
+ "[spike_width]."
+ )
+ if not all([second_reset, spike_width]):
+ raise ValueError(txt)
+ try:
+ ap_reset = Synapses(group, group,
+ on_pre=second_reset,
+ delay=spike_width)
+ ap_reset.connect(j='i')
+
+ except Exception:
+ raise ValueError(txt)
+
+ return (group, ap_reset) if ap_reset else group
def add_params(self, params_dict: dict):
"""
@@ -246,95 +413,7 @@ def add_equations(self, eqs: str):
else:
self._extra_equations += f"\n{eqs}"
- def link(self, ng: NeuronGroup, automate: str = 'all',
- verbose: bool = False):
- """
- Links a NeuronModel to a
- :doc:`NeuronGroup `.
- This allows dendrify to automatically handle the initialization of
- important simulation parameters.
-
- Parameters
- ----------
- ng : brian2.NeuronGroup
- A NeuronGroup that was created using a NeuronModel.
- automate : str, optional
- What to automate. Available options: ``'all'`` (default),
- ``'v_rest'``, ``'events'``.
- verbose : bool, optional
- If ``True`` it prints all the code that was created and run in the
- background by dendrify, by default ``False``
- """
- self._namespace = ng.namespace
- self._varscope = main.__dict__
- items = main.__dict__.items()
- ng_name = [k for k, v in items if v is ng][0]
- self._linked_neurongroup = ng_name, ng
-
- if automate == 'all':
- self._set_rest(verbose)
- self._handle_events(verbose)
-
- elif automate == 'v_rest':
- self._set_rest(verbose)
-
- elif automate == 'events':
- self._handle_events(verbose)
-
- def _set_rest(self, verbose=False):
- """
- Creates and runs executable code that initialises V rest across all
- NeuronModel _compartments.
- """
- command = '{0}.V_{1} = {2}'
-
- # When model parameters are passed as dict to the NeuronGroup:
- if self._namespace:
- commands = [command.format(self._linked_neurongroup[0], i.name,
- repr(self._namespace['EL_'+i.name]))
- for i in self._compartments]
- executable = '\n'.join(commands)
- if verbose:
- print(executable)
- exec(executable, self._varscope)
-
- def _handle_events(self, verbose=False):
- """
- Creates and runs executable code that:
- a) Initializes custom event checkpoint variables.
- b) Specifies what happens during custom events.
- """
- ng_name = self._linked_neurongroup[0]
- # Find all active _compartments:
- active_comps = [i for i in self._compartments if i._events]
- if active_comps == []:
- if verbose:
- print("\n")
- return
- # Na spike vs Ca spike branches
- comps_Na = filter(lambda x: '_I_Na_' in x.event_actions, active_comps)
- comps_Ca = filter(lambda x: '_I_Ca_' in x.event_actions, active_comps)
- # Initial compditions for the custom events needed for dspikes:
- checks_Na = ('{0}.allow_I_Na_{1} = True \n'
- '{0}.allow_I_Kn_{1} = False')
- checks_Ca = ('{0}.allow_I_Ca_{1} = True \n'
- '{0}.allow_I_Kc_{1} = False')
- # Compartment specific initial compditions:
- checks_Na_comp = [checks_Na.format(ng_name, i.name) for i in comps_Na]
- checks_Ca_comp = [checks_Ca.format(ng_name, i.name) for i in comps_Ca]
- # All initial compditions and actions needed for dspikes:
- all_checks = checks_Na_comp + checks_Ca_comp
- all_actions = [i.event_actions for i in active_comps]
- # Megrge all actions and checks into a single string:
- commands = '\n'.join(all_checks + all_actions)
-
- executable = commands.replace('run_on_event',
- f'{ng_name}.run_on_event')
- if verbose:
- print(executable)
- exec(executable, self._varscope)
-
- def as_graph(self, fontsize: int = 10, fontcolor: str = 'white',
+ def as_graph(self, figsize: list = [6, 4], fontsize: int = 10, fontcolor: str = 'white',
scale_nodes: float = 1, color_soma: str = '#4C6C92',
color_dendrites: str = '#A7361C', alpha: float = 1,
scale_edges: float = 1, seed: Optional[int] = None):
@@ -380,7 +459,7 @@ def as_graph(self, fontsize: int = 10, fontcolor: str = 'white',
G.add_edges_from(self._graph)
# Visualize it
- fig, ax = plt.subplots()
+ fig, ax = plt.subplots(figsize=figsize)
for d in ['right', 'top', 'left', 'bottom']:
ax.spines[d].set_visible(False)
pos = nx.spring_layout(G, fixed=soma, pos={soma[0]: (0, 0)},
@@ -402,7 +481,7 @@ def as_graph(self, fontsize: int = 10, fontcolor: str = 'white',
@property
def equations(self) -> str:
"""
- Merges all compartments' equations into a single string.
+ Returns a string containing all model equations.
Returns
-------
@@ -417,7 +496,7 @@ def equations(self) -> str:
@property
def parameters(self) -> dict:
"""
- Merges all compartments' parameters into a dictionary.
+ Returns a dictionary containing all model parameters.
Returns
-------
@@ -427,7 +506,6 @@ def parameters(self) -> dict:
d = {}
for i in self._compartments:
d.update(i.parameters)
- d.update(self.DEFAULTS)
if self._extra_params:
d.update(self._extra_params)
return d
@@ -435,7 +513,8 @@ def parameters(self) -> dict:
@property
def events(self) -> dict:
"""
- Organizes all custom events for dendritic spiking into a dictionary.
+ Returns a dictionary containing all model custom events for dendritic
+ spiking.
Returns
-------
@@ -443,22 +522,386 @@ def events(self) -> dict:
All model custom events for dendritic spiking.
"""
d_out = {}
- all_events = [i._events for i in self._compartments
- if i._events and isinstance(i, Dendrite)]
+ dendrites = [i for i in self._compartments if isinstance(i, Dendrite)]
+ all_events = [i._events for i in dendrites if i._events]
for d in all_events:
d_out.update(d)
return d_out
@property
- def event_actions(self) -> list:
+ def event_names(self) -> list:
"""
- Creates a list of all event actions for dendritic spiking.
+ Returns a list of all event names for dendritic spiking.
+
+ Returns
+ -------
+ list
+ All event names for dendritic spiking
+ """
+ return list(self.events.keys())
+
+ @property
+ def event_actions(self) -> dict:
+ """
+ Returns a dictionary containing all event actions for dendritic
+ spiking.
Returns
-------
list
All event actions for dendritic spiking
"""
- all_actions = [i._event_actions for i in self._compartments
- if i._event_actions and isinstance(i, Dendrite)]
- return all_actions
+ d_out = {}
+ dendrites = [i for i in self._compartments if isinstance(i, Dendrite)]
+ all_actions = [i._event_actions for i in dendrites if i._event_actions]
+ for d in all_actions:
+ d_out.update(d)
+ return d_out
+
+
+class PointNeuronModel:
+ """
+ Like a :class:`.NeuronModel` but for point-neuron (single-compartment)
+ models.
+
+ Parameters
+ ----------
+ model : str, optional
+ A keyword for accessing Dendrify's library models. Custom models can
+ also be provided but they should be in the same formattable structure as
+ the library models. Available options: ``'leakyIF'`` (default),
+ ``'adaptiveIF'``, ``'adex'``.
+ length : ~brian2.units.fundamentalunits.Quantity, optional
+ The point neuron's length.
+ diameter : ~brian2.units.fundamentalunits.Quantity, optional
+ The point neuron's diameter.
+ cm : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific capacitance (usually μF / cm^2).
+ gl : ~brian2.units.fundamentalunits.Quantity, optional
+ Specific leakage conductance (usually μS / cm^2).
+ cm_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute capacitance (usually pF).
+ gl_abs : ~brian2.units.fundamentalunits.Quantity, optional
+ Absolute leakage conductance (usually nS).
+ v_rest : ~brian2.units.fundamentalunits.Quantity, optional
+ Resting membrane voltage.
+ """
+
+ def __init__(
+ self,
+ model: str = 'leakyIF',
+ length: Optional[Quantity] = None,
+ diameter: Optional[Quantity] = None,
+ cm: Optional[Quantity] = None,
+ gl: Optional[Quantity] = None,
+ cm_abs: Optional[Quantity] = None,
+ gl_abs: Optional[Quantity] = None,
+ v_rest: Optional[Quantity] = None,
+ ):
+ self._equations = None
+ self._params = None
+ self._synapses = None
+ self._extra_equations = None
+ self._extra_params = None
+ # Add membrane equations:
+ self._add_equations(model)
+ # Keep track of electrophysiological properties:
+ self._ephys_object = EphysProperties(
+ name=None,
+ length=length,
+ diameter=diameter,
+ cm=cm,
+ gl=gl,
+ cm_abs=cm_abs,
+ gl_abs=gl_abs,
+ v_rest=v_rest,
+ )
+
+ def __str__(self):
+ equations = self.equations
+ parameters = pp.pformat(self.parameters)
+ user = pp.pformat(self._ephys_object.__dict__)
+ txt = (f"\nOBJECT\n{6*'-'}\n{self.__class__}\n\n\n"
+ f"EQUATIONS\n{9*'-'}\n{equations}\n\n\n"
+ f"PARAMETERS\n{10*'-'}\n{parameters}\n\n\n"
+ f"USER PARAMETERS\n{15*'-'}\n{user}")
+ return txt
+
+ def _add_equations(self, model: str):
+ """
+ Adds equations to a compartment.
+
+ Parameters
+ ----------
+ model : str
+ """
+ # Pick a model template or provide a custom model:
+ if model in library_point:
+ self._equations = library_point[model]
+ else:
+ logger.warning(("The model you provided is not found. The default "
+ "'passive' membrane model will be used instead."))
+ self._equations = library_point['passive']
+
+ def synapse(self,
+ channel: str,
+ tag: str,
+ g: Optional[Quantity] = None,
+ t_rise: Optional[Quantity] = None,
+ t_decay: Optional[Quantity] = None,
+ scale_g: bool = False):
+ """
+ Adds synaptic currents equations and parameters. When only the decay
+ time constant ``t_decay`` is provided, the synaptic model assumes an
+ instantaneous rise of the synaptic conductance followed by an exponential
+ decay. When both the rise ``t_rise`` and decay ``t_decay`` constants are
+ provided, synapses are modelled as a sum of two exponentials. For more
+ information see:
+ `Modeling Synapses by Arnd Roth & Mark C. W. van Rossum
+ `_
+
+ Parameters
+ ----------
+ channel : str
+ Synaptic channel type. Available options: ``'AMPA'``, ``'NMDA'``,
+ ``'GABA'``.
+ tag : str
+ A unique name to distinguish synapses of the same type.
+ g : :class:`~brian2.units.fundamentalunits.Quantity`
+ Maximum synaptic conductance
+ t_rise : :class:`~brian2.units.fundamentalunits.Quantity`
+ Rise time constant
+ t_decay : :class:`~brian2.units.fundamentalunits.Quantity`
+ Decay time constant
+ scale_g : bool, optional
+ Option to add a normalization factor to scale the maximum
+ conductance at 1 when synapses are modelled as a difference of
+ exponentials (have both rise and decay kinetics), by default
+ ``False``.
+
+ Examples
+ --------
+ >>> neuron = PointNeuronModel(...)
+ >>> # adding an AMPA synapse with instant rise & exponential decay:
+ >>> neuron.synapse('AMPA', tag='X', g=1*nS, t_decay=5*ms)
+ >>> # same channel, different conductance & source:
+ >>> neuron.synapse('AMPA', tag='Y', g=2*nS, t_decay=5*ms)
+ >>> # different channel with both rise & decay kinetics:
+ >>> neuron.synapse('NMDA', tag='X' g=1*nS, t_rise=5*ms, t_decay=50*ms)
+ """
+
+ synapse_id = "_".join([channel, tag])
+
+ if self._synapses:
+ # Check if this synapse already exists
+ if synapse_id in self._synapses:
+ raise DuplicateEquationsError(
+ f"The equations of '{channel}_{tag}' have already been "
+ f"added. \nPlease use a different "
+ f"combination of [channel, tag] when calling the synapse() "
+ "method \nmultiple times on a single compartment. You might"
+ " also see this error if you are using \nJupyter/iPython "
+ "which store variable values in memory. Try cleaning all "
+ "variables or \nrestart the kernel before running your "
+ "code. If this problem persists, please report it \n"
+ "by creating a new issue here: "
+ "https://github.com/Poirazi-Lab/dendrify/issues."
+ )
+ else:
+ self._synapses = []
+
+ # Switch to rise/decay equations if t_rise & t_decay are provided
+ key = f"{channel}_rd" if all([t_rise, t_decay]) else channel
+ current_name = f'I_{channel}_{tag}'
+ current_eqs = library_point[key].format(tag)
+
+ to_replace = f'= I_ext'
+ self._equations = self._equations.replace(
+ to_replace,
+ f'{to_replace} + {current_name}'
+ )
+ self._equations += '\n'+current_eqs
+
+ if not self._params:
+ self._params = {}
+
+ weight = f"w_{channel}_{tag}"
+ self._params[weight] = 1.0
+
+ # If user provides a value for g, then add it to _params
+ if g:
+ self._params[f'g_{channel}_{tag}'] = g
+ if t_rise:
+ self._params[f't_{channel}_rise_{tag}'] = t_rise
+ if t_decay:
+ self._params[f't_{channel}_decay_{tag}'] = t_decay
+ if scale_g:
+ if all([t_rise, t_decay, g]):
+ norm_factor = Compartment.g_norm_factor(t_rise, t_decay)
+ self._params[f'g_{channel}_{tag}'] *= norm_factor
+
+ self._synapses.append(synapse_id)
+
+ def noise(self, tau: Quantity = 20*ms, sigma: Quantity = 1*pA,
+ mean: Quantity = 0*pA):
+ """
+ Adds a stochastic noise current. For more information see the Noise
+ section: of :doc:`brian2:user/models`
+
+ Parameters
+ ----------
+ tau : :class:`~brian2.units.fundamentalunits.Quantity`, optional
+ Time constant of the Gaussian noise, by default ``20*ms``
+ sigma : :class:`~brian2.units.fundamentalunits.Quantity`, optional
+ Standard deviation of the Gaussian noise, by default ``3*pA``
+ mean : :class:`~brian2.units.fundamentalunits.Quantity`, optional
+ Mean of the Gaussian noise, by default ``0*pA``
+ """
+ I_noise_name = f'I_noise'
+
+ if I_noise_name in self.equations:
+ raise DuplicateEquationsError(
+ f"The equations of '{I_noise_name}' have already been "
+ f"added to the model. \nYou might be seeing this error if "
+ "you are using Jupyter/iPython "
+ "which store variable values \nin memory. Try cleaning all "
+ "variables or restart the kernel before running your "
+ "code. If this \nproblem persists, please report it "
+ "by creating a new issue here:\n"
+ "https://github.com/Poirazi-Lab/dendrify/issues."
+ )
+ noise_eqs = library_point['noise']
+ to_change = f'= I_ext'
+ self._equations = self._equations.replace(
+ to_change,
+ f'{to_change} + {I_noise_name}'
+ )
+ self._equations = f"{self._equations}\n{noise_eqs}"
+
+ # Add _params:
+ if not self._params:
+ self._params = {}
+ self._params[f'tau_noise'] = tau
+ self._params[f'sigma_noise'] = sigma
+ self._params[f'mean_noise'] = mean
+
+
+ def make_neurongroup(self, N: int, **kwargs) -> NeuronGroup:
+ group = NeuronGroup(N, model=self.equations,
+ namespace=self.parameters,
+ **kwargs)
+ setattr(group, 'V', self._ephys_object.v_rest)
+ return group
+
+ def add_params(self, params_dict: dict):
+ """
+ Allows specifying extra/custom parameters.
+
+ Parameters
+ ----------
+ params_dict : dict
+ A dictionary of parameters.
+ """
+ if not self._extra_params:
+ self._extra_params = {}
+ self._extra_params.update(params_dict)
+
+ def add_equations(self, eqs: str):
+ """
+ Allows adding custom equations.
+
+ Parameters
+ ----------
+ eqs : str
+ A string of Brian-compatible equations.
+ """
+ if not self._extra_equations:
+ self._extra_equations = f"{eqs}"
+ else:
+ self._extra_equations += f"\n{eqs}"
+
+ @property
+ def parameters(self) -> dict:
+ """
+ Returns all the parameters that have been generated for a single
+ compartment.
+
+ Returns
+ -------
+ dict
+ """
+ d_out = {}
+ if self._params:
+ d_out.update(self._params)
+ if self._extra_params:
+ d_out.update(self._extra_params)
+ if self._ephys_object:
+ d_out.update(self._ephys_object.parameters)
+ return d_out
+
+ @property
+ def area(self) -> Quantity:
+ """
+ Returns a compartment's surface area (open cylinder) based on its length
+ and diameter.
+
+ Returns
+ -------
+ :class:`~brian2.units.fundamentalunits.Quantity`
+ """
+ return self._ephys_object.area
+
+ @property
+ def capacitance(self) -> Quantity:
+ """
+ Returns a compartment's absolute capacitance.
+
+ Returns
+ -------
+ :class:`~brian2.units.fundamentalunits.Quantity`
+ """
+ return self._ephys_object.capacitance
+
+ @property
+ def g_leakage(self) -> Quantity:
+ """
+ A compartment's absolute leakage conductance.
+
+ Returns
+ -------
+ :class:`~brian2.units.fundamentalunits.Quantity`
+ """
+ return self._ephys_object.g_leakage
+
+ @property
+ def equations(self) -> str:
+ """
+ Returns all differential equations that describe a single compartment
+ and the mechanisms that have been added to it.
+
+ Returns
+ -------
+ str
+ """
+ if self._extra_equations:
+ return f"{self._equations}\n\n{self._extra_equations}"
+ return self._equations
+
+ @staticmethod
+ def g_norm_factor(trise: Quantity, tdecay: Quantity):
+ tpeak = (tdecay*trise / (tdecay-trise)) * np.log(tdecay/trise)
+ factor = (((tdecay*trise) / (tdecay-trise))
+ * (-np.exp(-tpeak/trise) + np.exp(-tpeak/tdecay))
+ / ms)
+ return 1/factor
+
+ @property
+ def dimensionless(self) -> bool:
+ """
+ Checks if a compartment has been flagged as dimensionless.
+
+ Returns
+ -------
+ bool
+ """
+ return True if self._ephys_object._dimensionless else False
diff --git a/dendrify/tests/simple_test.py b/dendrify/tests/simple_test.py
new file mode 100644
index 0000000..924a820
--- /dev/null
+++ b/dendrify/tests/simple_test.py
@@ -0,0 +1,7 @@
+# content of test_sample.py
+def func(x):
+ return x + 1
+
+
+def test_answer():
+ assert func(5) == 6
\ No newline at end of file
diff --git a/dendrify/utils.py b/dendrify/utils.py
new file mode 100644
index 0000000..aa9511c
--- /dev/null
+++ b/dendrify/utils.py
@@ -0,0 +1,41 @@
+import logging
+
+
+def get_logger(name):
+ """A simple function that returns a logger
+
+ Parameters
+ ----------
+ name : str
+ The name used for logging, should normally be the module name as
+ returned by ``__name__``.
+
+ Returns
+ -------
+ logger : logging.Logger
+ Used for nicely displaying error, warnings etc.
+ """
+ logger = logging.getLogger(name)
+ logger.setLevel(logging.INFO)
+ handler = logging.StreamHandler()
+ handler.setLevel(logging.INFO)
+ formatter = logging.Formatter(
+ '%(levelname)s [%(name)s:%(lineno)d]\n%(message)s\n')
+ handler.setFormatter(formatter)
+ logger.addHandler(handler)
+ return logger
+
+
+class DimensionlessCompartmentError(Exception):
+ """
+ Raise this error when an operation that is invalid for dimensionless
+ compartments is performed.
+ """
+ pass
+
+
+class DuplicateEquationsError(Exception):
+ """
+ Raise this error when a user tries to add the same equations twice.
+ """
+ pass
diff --git a/docs_sphinx/examples_to_rst.py b/docs_sphinx/examples_to_rst.py
new file mode 100644
index 0000000..1032195
--- /dev/null
+++ b/docs_sphinx/examples_to_rst.py
@@ -0,0 +1,107 @@
+from os import listdir, path
+
+import brian2 as b # needed for exec
+import matplotlib.pyplot as plt
+from brian2.units import * # needed for exec
+from scipy.optimize import curve_fit # needed for exec
+
+
+# Analysis code
+def func(t, a, tau):
+ """Exponential decay function"""
+ return a * b.exp(-t / tau)
+
+def get_tau(trace, t0):
+ dt = b.defaultclock.dt
+ Vmin = min(trace)
+ time_to_peak = list(trace).index(Vmin)
+
+ # Find voltage from current-start to min value
+ voltages = trace[int(t0/dt): time_to_peak] / mV
+
+ # Min-max normalize voltages
+ v_norm = (voltages - voltages.min()) / (voltages.max() - voltages.min())
+
+ # Fit exp decay function to normalized data
+ X = b.arange(0, len(v_norm)) * dt / ms
+ popt, _ = curve_fit(func, X, v_norm)
+
+ return popt, X, v_norm
+
+class Parser:
+ def __init__(self, file, docs_path):
+ self.file = file
+ self.lines = self.read_file()
+ self.info_lines = self.get_info_lines()
+ self.docs_path = docs_path
+ self.figs_path = path.join(docs_path, 'source/examples/_static')
+
+ def read_file(self):
+ with open(self.file, 'r') as f:
+ return f.read().splitlines()
+
+ def get_info_lines(self):
+ return [i for i, x in enumerate(self.lines) if x == '"""']
+
+ def run_code(self):
+ figname = self.filename.replace('.py', '.png')
+ fig_path = path.join(self.figs_path, figname)
+ exec(self.code.replace('show()', f'savefig("{fig_path}", dpi=300)'), locals())
+
+ def write_rst(self):
+ filename = path.join(self.docs_path, 'source', 'examples',
+ self.filename.replace('.py', '.rst'))
+ with open(filename, 'w') as f:
+ f.write(self.rst_file)
+
+ @property
+ def filename(self):
+ return path.basename(self.file)
+
+ @property
+ def title(self):
+ for index, value in enumerate(self.lines):
+ if value == 'Title':
+ return self.lines[index + 2]
+ @property
+ def description(self):
+ start = [i for i, x in enumerate(self.lines) if x == 'Description'][0]
+ end = self.info_lines[-1]
+ return '\n'.join(self.lines[start + 2:end])
+
+ @property
+ def code(self):
+ start = self.info_lines[-1] + 1
+ return '\n'.join(self.lines[start:])
+
+ @property
+ def rst_code(self):
+ directive = '.. code-block:: python'
+ indented_code = self.code.replace('\n', '\n ')
+ return '\n'.join([directive, indented_code])
+
+ @property
+ def rst_file(self):
+ image_name = path.join('_static', self.filename.replace('.py', '.png'))
+ image = (f'.. image:: {image_name}\n'
+ ' :align: center')
+ content = [f"{self.title}\n{'=' * len(self.title)}",
+ self.description,
+ self.rst_code, image]
+ return '\n\n\n'.join(content)
+
+
+if __name__ == '__main__':
+ # Get the path to the directory that is one level up
+ root = path.abspath(path.join(path.dirname(__file__), '..'))
+ docs = path.join(root, 'docs_sphinx')
+ examples = path.join(root, 'examples_new')
+ files = listdir(examples)
+
+ for file in files:
+ filename = path.join(examples, file)
+ example = Parser(filename, docs)
+ print(example.title)
+ example.run_code()
+ example.write_rst()
+ plt.close('all')
diff --git a/docs_sphinx/source/_static/dendrify_logo_dark.png b/docs_sphinx/source/_static/dendrify_logo_dark.png
new file mode 100644
index 0000000000000000000000000000000000000000..53678ea8dcd73de35418c75761da320a9c8e79e1
GIT binary patch
literal 123315
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