dendrotweaks 0.3.1__py3-none-any.whl

dendrotweaks/stimuli/populations.py

@@ -0,0 +1,265 @@
+from dendrotweaks.morphology.seg_trees import Segment
+from dendrotweaks.stimuli.synapses import Synapse
+
+from collections import defaultdict
+
+from typing import List
+import numpy as np
+
+KINETIC_PARAMS = {
+    'AMPA': {
+        'gmax': 0.001,
+        'tau_rise': 0.1,
+        'tau_decay': 2.5,
+        'e': 0
+    },
+    'NMDA': {
+        'gmax': 0.7 * 0.001,
+        'tau_rise': 2,
+        'tau_decay': 30,
+        'e': 0,
+        'gamma': 0.062,
+        'mu': 0.28,
+    },
+    'AMPA_NMDA': {
+        'gmax_AMPA': 0.001,
+        'gmax_NMDA': 0.7 * 0.001,
+        'tau_rise_AMPA': 0.1,
+        'tau_decay_AMPA': 2.5,
+        'tau_rise_NMDA': 2,
+        'tau_decay_NMDA': 30,
+        'e': 0,
+        'gamma': 0.062,
+        'mu': 0.28,
+    },
+    'GABAa': {
+        'gmax': 0.001,
+        'tau_rise': 0.1,
+        'tau_decay': 8,
+        'e': -70
+    }
+}
+
+class Population():
+    """
+    A population of "virtual" presynaptic neurons forming synapses on the
+    explicitely modelled postsynaptic neuron. 
+
+    The population is defined by the number of synapses N, the segments
+    on which the synapses are placed, and the type of synapse. All synapses
+    in the population share the same kinetic parameters. Global input parameters
+    such as rate, noise, etc. are shared by all synapses in the population, 
+    however, each synapse receives a unique input spike train.
+
+    Parameters
+    ----------
+    idx : str
+        The index of the population.
+    segments : List[Segment]
+        The segments on which the synapses are placed.
+    N : int
+        The number of synapses in the population.
+    syn_type : str
+        The type of synapse to create e.g. 'AMPA', 'NMDA', 'AMPA_NMDA', 'GABA'.
+
+    Attributes
+    ----------
+    idx : str
+        The index of the population.
+    segments : List[Segment]
+        The segments on which the synapses are placed.
+    N : int
+        The number of synapses in the population.
+    syn_type : str
+        The type of synapse to create e.g. 'AMPA', 'NMDA', 'AMPA_NMDA', 'GABA'.
+    synapses : dict
+        A dictionary of synapses in the population, where the key is the segment index.
+    input_params : dict
+        The input parameters of the synapses in the population.
+    kinetic_params : dict
+        The kinetic parameters of the synapses in the population.
+    """
+
+    def __init__(self, idx: str, segments: List[Segment], N: int, syn_type: str) -> None:
+
+        self.idx = idx
+        self.segments = segments
+        self.sections = list(set([seg._section for seg in segments]))
+        self._excluded_segments = [seg for sec in self.sections for seg in sec if seg not in segments]
+        self.syn_type = syn_type
+
+        self.N = N
+
+        self.synapses = {}
+
+        self.input_params = {
+            'rate': 1,
+            'noise': 0,
+            'start': 100,
+            'end': 200,
+            'weight': 1,
+            'delay': 0
+        }
+
+        self.kinetic_params = KINETIC_PARAMS[syn_type]
+
+    def __repr__(self):
+        return f"<Population({self.name}, N={self.N})>"
+    
+    @property
+    def name(self):
+        """A unique name for the population."""
+        return f"{self.syn_type}_{self.idx}"
+
+
+    @property
+    def spike_times(self):
+        """
+        Return the spike times of the synapses in the population.
+        """
+        spike_times = defaultdict(list)
+        for seg, syns in self.synapses.items():
+            for syn in syns:
+                spike_times[syn].extend(syn.spike_times)
+        return dict(spike_times)
+
+
+    def update_kinetic_params(self, **params):
+        """
+        Update the kinetic parameters of the synapses.
+
+        Parameters
+        ----------
+        **params : dict
+            The parameters to update self.kinetic_params.
+            Options are:
+            - gmax: the maximum conductance of the synapse
+            - tau_rise: the rise time of the synapse
+            - tau_decay: the decay time of the synapse
+            - e: the reversal potential of the synapse
+            - gamma: the voltage dependence of the magnesium block (NMDA only)
+            - mu: the sensitivity of the magnesium block to Mg2+ concentration (NMDA only)
+        """
+        self.kinetic_params.update(params)
+        for syns in self.synapses.values():
+            for syn in syns:
+                for key, value in params.items():
+                    if hasattr(syn._ref_syn, key):
+                        setattr(syn._ref_syn, key, value)
+
+    def update_input_params(self, **params):
+        """
+        Update the input parameters of the synapses.
+
+        Parameters
+        ----------
+        **params : dict
+            The parameters to update self.input_params.
+            Options are:
+            - rate: the rate of the input in Hz
+            - noise: the noise level of the input
+            - start: the start time of the input
+            - end: the end time of the input
+            - weight: the weight of the synapse
+            - delay: the delay of the synapse
+        """
+        self.input_params.update(params)
+        self.create_inputs()
+
+    # ALLOCATION METHODS
+
+    def _choose_synapse_locations(self):
+        
+        valid_locs = [(sec, x) for sec in self.sections 
+            for x in np.linspace(0, 1, 1001) 
+            if sec(x) not in self._excluded_segments]
+        
+        syn_locs = [valid_locs[np.random.choice(len(valid_locs))] for _ in range(self.N)]
+        
+        return syn_locs
+
+
+    def allocate_synapses(self, syn_locs=None):
+
+        if syn_locs is None:
+            syn_locs = self._choose_synapse_locations()
+        syn_type = self.syn_type
+        self.synapses = {(sec, x) : [] for sec, x in syn_locs}
+        for sec, x in syn_locs:
+            self.synapses[(sec, x)].append(Synapse(syn_type, sec, x))
+
+        self.update_kinetic_params(**self.kinetic_params)
+            
+
+
+    # CREATION METHODS
+
+    def create_inputs(self):
+        """
+        Create and reference the synapses in a simulator.
+        
+        This method should be called after the synapses have been allocated.
+        """
+        for syns in self.synapses.values():
+            for syn in syns:
+
+                syn.create_stim(
+                    rate=self.input_params['rate'],
+                    noise=self.input_params['noise'],
+                    duration=self.input_params['end'] - self.input_params['start'],
+                    delay=self.input_params['start']
+                )
+
+                syn.create_con(
+                    delay=self.input_params['delay'],
+                    weight=self.input_params['weight']
+                )
+
+
+    def to_dict(self):
+        """
+        Convert the population to a dictionary.
+        """
+        return {
+                'name': self.name,
+                'syn_type': self.syn_type,
+                'N': self.N,
+                'input_params': {**self.input_params},
+                'kinetic_params': {**self.kinetic_params},
+        }
+
+    @property
+    def flat_synapses(self):
+        """
+        Return a flat list of synapses.
+        """
+        return [syn for syns in self.synapses.values() for syn in syns]
+
+    def to_csv(self):
+        """
+        Prepare the data about the location of synapses for saving to a CSV file.
+        """
+        flat_synapses = self.flat_synapses
+        return {
+            'syn_type': [self.syn_type] * len(flat_synapses),
+            'name': [self.name] * len(flat_synapses),
+            'sec_idx': [syn.sec.idx for syn in flat_synapses],
+            'loc': [syn.loc for syn in flat_synapses],
+        }
+        
+
+    def clean(self):
+        """
+        Clear the synapses and connections from the simulator.
+
+        Removes all synapses, NetCon and NetStim objects.
+        """
+        for syns in self.synapses.values():
+            for syn in syns:
+                if syn._ref_stim:
+                    syn._clear_stim()
+                if syn._ref_con:
+                    syn._clear_con()
+        self.synapses.clear()
+
+    

dendrotweaks/stimuli/synapses.py

@@ -0,0 +1,203 @@
+from typing import List
+from neuron import h
+import numpy as np
+from dendrotweaks.morphology.seg_trees import Segment
+
+class Synapse():
+    """
+    A synapse object that can be placed on a section of a neuron.
+
+    Contains references to the NEURON synapse object, the stimulus object (NetStim),
+    and the connection object (NetCon).
+
+    Parameters
+    ----------
+    syn_type : str
+        The type of synapse to create e.g. 'AMPA', 'NMDA', 'AMPA_NMDA', 'GABA'.
+    sec : Section
+        The section on which the synapse is placed.
+    loc : float
+        The location on the section where the synapse is placed, between 0 and 1.
+
+    Attributes
+    ----------
+    sec : Section
+        The section on which the synapse is placed.
+    loc : float
+        The location on the section where the synapse is placed, between 0 and 1.
+    """
+
+    def __init__(self, syn_type: str, sec, loc=0.5) -> None:
+        """
+        Creates a new synapse object.
+        """
+        self._Model = getattr(h, syn_type)
+        self.sec = sec
+        self.loc = loc
+
+        self._ref_syn = self._Model(self.seg._ref)
+        self._ref_stim = None
+        self._ref_con = None
+
+    @property
+    def seg(self):
+        """
+        The segment on which the synapse is placed.
+        """
+        return self.sec(self.loc)
+
+    def __repr__(self):
+        return f"<Synapse({self.sec}({self.loc:.3f}))>"
+
+    @property
+    def spike_times(self):
+        """
+        The spike times of the stimulus from the NetStim object.
+        """
+        if self._ref_stim is not None:
+            return self._ref_stim[1].to_python()
+        return []
+
+    def _clear_stim(self):
+        """
+        Clears the stimulus (NetStim) object.
+        """
+        self._ref_stim[0] = None
+        self._ref_stim[1] = None
+        self._ref_stim.pop(0)
+        self._ref_stim.pop(0)
+        self._ref_stim = None
+
+    def create_stim(self, **kwargs):
+        """
+        Creates a stimulus (NetStim) for the synapse.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for the create_spike_times function.
+        """
+
+        if self._ref_stim is not None:
+            self._clear_stim()
+
+        spike_times = create_spike_times(**kwargs)
+        spike_vec = h.Vector(spike_times)
+        stim = h.VecStim()
+        stim.play(spike_vec)
+
+        self._ref_stim = [stim, spike_vec]
+
+    def _clear_con(self):
+        """
+        Clears the connection (NetCon) object.
+        """
+        self._ref_con = None
+
+    def create_con(self, delay, weight):
+        """
+        Create a connection (NetCon) between the stimulus and the synapse.
+
+        Parameters
+        ----------
+        delay : int
+            The delay of the connection, in ms.
+        weight : float
+            The weight of the connection.
+        """
+        if self._ref_con is not None:
+            self._clear_con()
+        self._ref_con = h.NetCon(self._ref_stim[0],
+                                 self._ref_syn,
+                                 0,
+                                 delay,
+                                 weight)
+
+
+def create_spike_times(rate=1, noise=1, duration=300, delay=0):
+    """
+    Create a spike train with a given regularity.
+
+    Parameters
+    ----------
+    rate : float
+        The rate of the spike train, in Hz.
+    noise : float
+        A parameter between 0 and 1 that controls the regularity of the spike train. 
+        0 corresponds to a regular spike train. 1 corresponds to a Poisson process.
+    duration : int
+        The total time to run the simulation for, in ms.
+    delay : int
+        The delay of the spike train, in ms.
+
+    Returns
+    -------
+    np.array
+        The spike times as a vector, in ms.
+    """
+
+    if noise == 1:
+        return delay + generate_poisson_process(rate, duration)
+    else:
+        return delay + generate_jittered_spikes(rate, duration, noise)
+
+
+def generate_poisson_process(lam, dur):
+    """
+    Generate a Poisson process.
+
+    Parameters
+    ----------
+    lam : float
+        The rate parameter (lambda) of the Poisson process, in Hz.
+    dur : int
+        The total time to run the simulation for, in ms.
+
+    Returns
+    -------
+    np.array
+        The spike times as a vector, in ms.    
+    """
+    dur_s = dur / 1000
+    intervals = np.random.exponential(1/lam, int(lam*dur_s))
+    spike_times = np.cumsum(intervals)
+    spike_times = spike_times[spike_times <= dur_s]
+    spike_times_ms = spike_times * 1000
+
+    return spike_times_ms
+
+
+def generate_jittered_spikes(rate, dur, noise):
+    """
+    Generate a jittered spike train.
+
+    Parameters
+    ----------
+    rate : float
+        The rate of the spike train, in Hz.
+    dur : int
+        The total time to run the simulation for, in ms.
+    noise : float
+        A parameter between 0 and 1 that controls the regularity of the spike train. 
+        0 corresponds to a regular spike train. 1 corresponds to a Poisson process.
+
+
+    Returns
+    -------
+    np.array
+        The spike times as a vector, in ms.
+    """
+    dur_s = dur / 1000
+    spike_times = np.arange(0, dur_s, 1/rate)
+
+    # Add noise
+    noise_values = np.random.normal(0, noise/rate, len(spike_times))
+    spike_times += noise_values
+
+    # Ensure spike times are within the duration and sort them
+    spike_times = spike_times[(spike_times >= 0) & (spike_times <= dur_s)]
+    spike_times.sort()
+
+    spike_times_ms = spike_times * 1000
+
+    return spike_times_ms

dendrotweaks/utils.py

@@ -0,0 +1,239 @@
+"""
+Utility functions for dendrotweaks package.
+"""
+
+import time
+import numpy as np
+import os
+import zipfile
+import urllib.request
+import matplotlib.pyplot as plt
+
+SWC_ID_TO_DOMAIN = {
+    0: 'undefined',
+    1: 'soma',
+    11: 'perisomatic',
+    2: 'axon',
+    3: 'dend',
+    31: 'basal',
+    4: 'apic',
+    41: 'trunk',
+    42: 'tuft',
+    43: 'oblique',
+    5: 'custom',
+    6: 'neurite',
+    7: 'glia',
+    8: 'reduced',
+}
+
+DOMAIN_TO_SWC_ID = {
+    v: k for k, v in SWC_ID_TO_DOMAIN.items()
+}
+
+def get_swc_idx(domain_name):
+    base_domain, _, idx = domain_name.partition('_')
+    if base_domain == 'reduced':
+        return int(f'8{idx}')
+    elif base_domain == 'custom':
+        return int(f'5{idx}')
+    return DOMAIN_TO_SWC_ID.get(base_domain, 0)
+
+def get_domain_name(swc_idx):
+    if str(swc_idx).startswith('8'):
+        return 'reduced_' + str(swc_idx)[1:]
+    elif str(swc_idx).startswith('5'):
+        return 'custom_' + str(swc_idx)[1:]
+    return SWC_ID_TO_DOMAIN.get(swc_idx, 'undefined')
+
+DOMAINS_TO_COLORS = {
+    'soma': '#E69F00',
+    'apic': '#0072B2',
+    'dend': '#019E73',
+    'basal': '#31A354',
+    'axon': '#F0E442',
+    'trunk': '#56B4E9',
+    'tuft': '#A55194',
+    'oblique': '#8C564B',
+    'perisomatic': '#D55E00',
+    'custom': '#D62728',
+    'reduced': '#E377C2',
+    'undefined': '#7F7F7F',
+}
+
+def get_domain_color(domain_name):
+    base_domain, _, idx = domain_name.partition('_')
+    return DOMAINS_TO_COLORS.get(base_domain, '#7F7F7F')
+
+
+
+def timeit(func):
+    def wrapper(*args, **kwargs):
+        start = time.time()
+        result = func(*args, **kwargs)
+        end = time.time()
+        print(f"  Elapsed time: {round(end-start, 3)} seconds")
+        return result
+    return wrapper
+
+
+def calculate_lambda_f(distances, diameters, Ra=35.4, Cm=1, frequency=100):
+    """
+    Calculate the frequency-dependent length constant (lambda_f) according to NEURON's implementation,
+    using 3D point data for accurate representation of varying diameter frusta.
+    
+    Args:
+        distances (list/array): Cumulative euclidean distances between 3D points along the section from 0 to section length
+        diameters (list/array): Corresponding diameters at each position in micrometers
+        Ra (float): Axial resistance in ohm*cm
+        Cm (float): Specific membrane capacitance in µF/cm²
+        frequency (float): Frequency in Hz
+    
+    Returns:
+        float: Lambda_f in micrometers
+    """
+    if len(distances) < 2 or len(diameters) < 2:
+        raise ValueError("At least 2 points are required for 3D calculation")
+    
+    if len(distances) != len(diameters):
+        raise ValueError("distances and diameters must have the same length")
+    
+    # Initialize variables
+    lam = 0
+    section_L = distances[-1]
+    
+    # Calculate the contribution of each frustum
+    for i in range(1, len(distances)):
+        # Frustum length
+        frustum_length = distances[i] - distances[i-1]
+        # Average of diameters at endpoints
+        d1 = diameters[i-1]
+        d2 = diameters[i]
+        
+        # Add frustum contribution to lambda calculation
+        lam += frustum_length / np.sqrt(d1 + d2)
+    
+    # Apply the frequency-dependent factor
+    lam *= np.sqrt(2) * 1e-5 * np.sqrt(4 * np.pi * frequency * Ra * Cm)
+    
+    # Return section_L/lam (electrotonic length of the section)
+    return section_L / lam
+
+if (__name__ == '__main__'):
+    print('Executing as standalone script')
+
+
+def dynamic_import(module_name, class_name):
+    """
+    Dynamically import a class from a module.
+
+    Parameters
+    ----------
+    module_name : str
+        Name of the module to import.
+    class_name : str
+        Name of the class to import.
+    """
+
+    from importlib import import_module
+
+    import sys
+    sys.path.append('app/src')
+    print(f"Importing class {class_name} from module {module_name}.py")
+    module = import_module(module_name)
+    return getattr(module, class_name)
+
+
+def list_folders(path_to_folder):
+    folders = [f for f in os.listdir(path_to_folder)
+            if os.path.isdir(os.path.join(path_to_folder, f))]
+    sorted_folders = sorted(folders, key=lambda x: x.lower())
+    return sorted_folders
+
+    
+def list_files(path_to_folder, extension):
+    files = [f for f in os.listdir(path_to_folder)
+            if f.endswith(extension)]
+    return files
+
+
+def write_file(content: str, path_to_file: str, verbose: bool = True) -> None:
+    """
+    Write content to a file.
+
+    Parameters
+    ----------
+    content : str
+        The content to write to the file.
+    path_to_file : str
+        The path to the file.
+    verbose : bool, optional
+        Whether to print a message after writing the file. The default is True.
+    """
+    if not os.path.exists(os.path.dirname(path_to_file)):
+        os.makedirs(os.path.dirname(path_to_file))
+    with open(path_to_file, 'w') as f:
+        f.write(content)
+    print(f"Saved content to {path_to_file}")
+
+
+def read_file(path_to_file):
+    with open(path_to_file, 'r') as f:
+        content = f.read()
+    return content
+
+
+def download_example_data(path_to_destination):
+    """
+    Download the examples subfolder from the DendroTweaks GitHub repository.
+
+    Parameters
+    ----------
+    path_to_destination : str
+        The path to the destination folder where the examples will be downloaded.
+    """
+    if not os.path.exists(path_to_destination):
+        os.makedirs(path_to_destination)
+
+    repo_url = "https://github.com/Poirazi-Lab/DendroTweaks/archive/refs/heads/main.zip"
+    zip_path = os.path.join(path_to_destination, "examples.zip")
+
+    print(f"Downloading examples from {repo_url}...")
+    urllib.request.urlretrieve(repo_url, zip_path)
+
+    print(f"Extracting examples to {path_to_destination}")
+    with zipfile.ZipFile(zip_path, 'r') as zip_ref:
+        for member in zip_ref.namelist():
+            if member.startswith("DendroTweaks-main/examples/"):
+                # Extract the file with the correct path
+                member_path = os.path.relpath(member, "DendroTweaks-main/examples")
+                target_path = os.path.join(path_to_destination, member_path)
+                if member.endswith('/'):
+                    os.makedirs(target_path, exist_ok=True)
+                else:
+                    os.makedirs(os.path.dirname(target_path), exist_ok=True)
+                    with zip_ref.open(member) as source, open(target_path, 'wb') as target:
+                        target.write(source.read())
+
+    os.remove(zip_path)  # Clean up the zip file
+    print(f"Examples downloaded successfully to {path_to_destination}/.")
+
+
+
+def apply_dark_theme():
+    """
+    Apply a dark theme to matplotlib plots.
+    """
+    # dark theme
+    plt.style.use('dark_background')
+
+    # customize the style
+    plt.rcParams.update({
+        'figure.facecolor': '#131416',
+        'axes.facecolor': '#131416',
+        'axes.edgecolor': 'white',
+        'axes.labelcolor': 'white',
+        'xtick.color': 'white',
+        'ytick.color': 'white',
+        'text.color': 'white',
+        'axes.prop_cycle': plt.cycler(color=plt.cm.tab10.colors),  # use standard matplotlib colors
+    })