pyneurorg 0.1.58

Python Brain Organoid Simulator

PYNEURORG

Python Brain Organoid Simulator

pyneurorg is a Python module designed for simulating brain organoids, leveraging the power and flexibility of the Brian2 spiking neural network simulator. It provides a structured framework to model neurons and synapses within organoids, simulate their development and activity, and interact with them using simulated Microelectrode Arrays (MEAs) and calcium imaging techniques.

Objective

The primary goal of pyneurorg is to provide researchers with an accessible, modular, and extensible in-silico platform to:

• Model the formation and maturation of neural networks in brain organoids.
• Simulate electrophysiological experiments, including MEA-based stimulation and recording.
• Simulate calcium imaging experiments to observe network activity with high spatial resolution.
• Investigate the effects of various stimuli, genetic modifications, or disease states on organoid network dynamics.
• Facilitate the exploration of structural and synaptic plasticity mechanisms.

Key Features

• Brian2-Powered Core: Utilizes Brian2 for efficient and accurate simulation of spiking neuron and synapse models.
• Organoid Construction: Flexible tools to create 3D organoid structures with defined neuronal populations and spatial arrangements.
• MEA Integration:
  • Model MEA geometries.
  • Simulate targeted electrical stimulation of organoids via MEA electrodes.
  • Record spike activity and Local Field Potential (LFP) proxies from MEA electrodes.
• Calcium Imaging Simulation:
  • Neuron models incorporating intracellular calcium dynamics.
  • Simulation of fluorescent calcium indicator signals (e.g., GCaMP's ΔF/F).
• Network Plasticity: (Module named plasticity)
  • Implement common synaptic plasticity rules (e.g., STDP).
  • Simulate structural plasticity for activity-dependent network formation and pruning.
• Electrophysiology Suite:
  • Generate complex stimulus patterns.
  • Comprehensive data recording capabilities.
  • Persistent data storage using SQLite for simulation results.
• Analysis & Visualization:
  • Tools for spike train analysis (firing rates, synchrony, bursting).
  • Calcium trace analysis (ΔF/F, event detection).
  • Functional network inference from spike or calcium activity.
  • Plotting utilities for raster plots, LFP, calcium traces, and connectivity graphs.
• Modularity and Extensibility: Designed to easily add new neuron models, synapse types, plasticity rules, or analysis techniques.
• Jupyter Notebook Examples: A comprehensive suite of examples from basic setup to advanced simulations.

Installation

There are two primary ways to install pyneurorg:

Option 1: Install from PyPI (Recommended for users)

If pyneurorg is published on the Python Package Index (PyPI), you can install it directly using pip. This is the simplest method for end-users.

pip install pyneurorg

(Note: This requires the package to be uploaded to PyPI by the developers.)

Option 2: Install from a local directory (For developers or from source)

If you have cloned the pyneurorg repository or have the source code:

1. Navigate to the top-level pyneurorg project directory in your terminal (this is the directory that contains the setup.py file and the src/ folder).

   cd path/to/your/pyneurorg_project_root
   

2. (Recommended) Create and activate a virtual environment:

   python -m venv venv_pyneurorg
   source venv_pyneurorg/bin/activate  # On macOS/Linux
   # .\venv_pyneurorg\Scripts\activate  # On Windows
   

3. Install pyneurorg in editable mode and its dependencies: The -e flag installs the package in "editable" mode. The . tells pip to look for setup.py in the current directory.

   pip install -e .
   

   This command reads setup.py (which should be configured for the src/ layout) and installs dependencies listed in setup.py (which ideally reads them from requirements.txt).

   For a full development setup, including tools for testing, linting, and documentation:

   pip install -r requirements-dev.txt
   

   Or, if you have defined extras in your setup.py (e.g., dev, docs, test):

   pip install -e .[dev,docs,test]
   

Project Directory Structure

The pyneurorg project is organized with a clear separation between the installable package code, documentation, examples, and tests. The main package code resides within the src/ directory.

pyneurorg/
├── docs/
├── examples/
│   ├── 00_Installation_and_Setup.ipynb
│   ├── 01_Creating_Your_First_Organoid.ipynb
│   ├── 02_Running_a_Simple_Simulation_and_Recording_Spikes.ipynb
│   ├── 03_Exploring_Neuron_and_Synapse_Models.ipynb
│   ├── 04_Spatial_Arrangement_and_Connectivity_Rules.ipynb
│   ├── 05_MEA_Stimulation_and_Basic_Recording.ipynb
│   ├── 06_Simulating_Spontaneous_Activity_and_LFP_Proxy.ipynb
│   ├── 07_Patterned_Stimulation_and_Response_Analysis.ipynb
│   ├── 08_Implementing_Synaptic_Plasticity_STDP.ipynb
│   ├── 09_Simulating_Structural_Plasticity_Network_Formation.ipynb
│   ├── 10_Modeling_Calcium_Dynamics_and_Fluorescence_Imaging.ipynb
│   ├── 11_Data_Persistence_Saving_and_Loading_with_SQLite.ipynb
│   ├── 12_Inferring_Functional_Networks_from_Spike_Data.ipynb
│   ├── 13_Inferring_Functional_Networks_from_Calcium_Data.ipynb
│   ├── 14_Advanced_Analysis_Bursting_and_Synchrony.ipynb
│   └── 15_Example_Modeling_a_Simplified_Disease_Phenotype.ipynb
├── src/
│   └── pyneurorg/
│       ├── analysis/
│       ├── core/
│       ├── electrophysiology/
│       ├── mea/
│       ├── organoid/
│       ├── plasticity/
│       ├── simulation/
│       ├── utils/
│       └── visualization/
└── tests/

Description of Top-Level Directories

• docs/: Contains files for generating the project's official documentation (e.g., using Sphinx).
• examples/: A collection of Jupyter Notebooks providing practical tutorials and demonstrating pyneurorg usage.
• src/: Houses the source code of the pyneurorg Python package. Inside src/, the pyneurorg/ subdirectory is the main package.
• tests/: Contains automated tests (unit, integration) for the pyneurorg codebase.

Usage

Refer to the Quick Start Examples or to the Jupyter Notebooks in the examples/ directory for detailed usage instructions. Start with 00_Installation_and_Setup.ipynb.

Quick Start Examples

The following examples demonstrate basic functionalities of pyneurorg. Ensure pyneurorg is installed before running them.

Stimulating the Organoid with an MEA

This snippet shows how to set up a simple organoid, an MEA, and stimulate a specific region.

import brian2 as b2
import matplotlib.pyplot as plt
import numpy as np # Often needed with Brian2

# Assuming pyneurorg modules are importable
from pyneurorg.organoid.organoid import Organoid
from pyneurorg.organoid import spatial
from pyneurorg.core import neuron_models
from pyneurorg.mea.mea import MEA
from pyneurorg.simulation.simulator import Simulator
from pyneurorg.electrophysiology import stimulus_generator
from pyneurorg.visualization import spike_plotter

# Ensure reproducible results
b2.seed(423)
b2.prefs.codegen.target = 'numpy'

# 1. Create an Organoid
lif_model_definition = neuron_models.LIFNeuron(
    tau_m=20*b2.ms, v_rest=-65*b2.mV, v_reset=-65*b2.mV,
    v_thresh=-50*b2.mV, R_m=100*b2.Mohm, I_tonic=0.0*b2.nA,
    refractory_period=2*b2.ms
)
my_organoid_stim = Organoid(name="StimulationOrganoid")
neuron_positions_stim = spatial.random_positions_in_sphere(N=100, radius=150*b2.um)
my_organoid_stim.add_neurons(
    name="target_neurons", num_neurons=100, model_name="LIFNeuron",
    model_params={
        'tau_m': 20*b2.ms, 'v_rest': -65*b2.mV, 'v_reset': -65*b2.mV,
        'v_thresh': -50*b2.mV, 'R_m': 100*b2.Mohm, 'I_tonic': 0.0*b2.nA,
        'refractory_period': 2*b2.ms
    },
    positions=neuron_positions_stim, initial_values={'v': -65*b2.mV}
)

# 2. Create an MEA
electrode_coords = [(i*40*b2.um, j*40*b2.um, 0*b2.um) for i in range(4) for j in range(4)]
my_mea_stim = MEA(electrode_positions=electrode_coords)

# 3. Setup the Simulator
sim_stim = Simulator(organoid=my_organoid_stim, mea=my_mea_stim, brian2_dt=0.1*b2.ms)

# 4. Define a stimulus
stimulation_duration = 150*b2.ms
stimulus_waveform = stimulus_generator.create_pulse_train(
    amplitude=0.9*b2.nA, frequency=8*b2.Hz,
    pulse_width=2.5*b2.ms, duration=stimulation_duration,
    dt=sim_stim.brian_dt
)

# 5. Add stimulus to an MEA electrode
sim_stim.add_stimulus(
    electrode_id=0, stimulus_waveform=stimulus_waveform,
    target_group_name="target_neurons", influence_radius=50*b2.um
)

# 6. Add a spike monitor
sim_stim.add_recording(
    monitor_name="stimulation_spikes", monitor_type="spike",
    target_group_name="target_neurons", record=True
)

# 7. Run simulation
print("Running MEA stimulation example...")
sim_stim.run(stimulation_duration, report='text', report_period=50*b2.ms)
print("Stimulation simulation finished.")

# 8. Retrieve and plot data
spike_data = sim_stim.get_data("stimulation_spikes")
print(f"Recorded {len(spike_data.i)} spikes during stimulation.")
if len(spike_data.i) > 0:
    fig, ax = plt.subplots(figsize=(10,5))
    spike_plotter.plot_raster(
        spike_indices=spike_data.i, spike_times=spike_data.t,
        duration=stimulation_duration, ax=ax,
        title="Spikes from MEA Stimulation", marker_size=3
    )
    plt.tight_layout()
    plt.show()
else:
    print("No spikes recorded. Try increasing stimulus amplitude or influence_radius.")

Reading Activity: Spikes and Calcium Imaging (Full Example)

This snippet demonstrates recording spikes and simulated calcium fluorescence from active neurons.

import brian2 as b2
import numpy as np
import matplotlib.pyplot as plt

# Assuming pyneurorg modules are importable
from pyneurorg.organoid.organoid import Organoid
from pyneurorg.organoid import spatial
from pyneurorg.core import neuron_models
from pyneurorg.simulation.simulator import Simulator
from pyneurorg.visualization import spike_plotter, calcium_plotter
from pyneurorg.analysis import calcium_analysis

# Ensure reproducible results
b2.seed(12346) # Different seed
np.random.seed(12346)
b2.prefs.codegen.target = 'numpy'

# 1. Define parameters and get the calcium-enabled neuron model definition
# These parameters should match what your LIFCalciumFluorNeuron function expects
calcium_model_function_params = {
    'tau_m': 15*b2.ms, 'v_rest': -65*b2.mV, 'v_reset': -65*b2.mV, 'v_thresh': -50*b2.mV,
    'R_m': 120*b2.Mohm, 'refractory_period': 3*b2.ms,
    'tau_ca': 80*b2.ms,          # Example calcium decay time constant
    'ca_spike_increment': 0.25, # Example arbitrary unit increment of Ca per spike (unitless or specific based on model)
    'tau_f': 120*b2.ms,          # Example fluorescence decay (related to indicator off-rate)
    'k_f': 0.6,                  # Example scaling factor for fluorescence from Ca (unitless or specific)
    'I_tonic': 0.21*b2.nA        # Tonic current to induce spontaneous spiking
}
try:
    # Fetch the model definition dictionary
    calcium_model_def = neuron_models.LIFCalciumFluorNeuron(**calcium_model_function_params)
    model_name_for_organoid = "LIFCalciumFluorNeuron" # Use the function name string for Organoid
except AttributeError:
    print("CRITICAL ERROR: 'LIFCalciumFluorNeuron' model function not found in pyneurorg.core.neuron_models.")
    print("This example cannot proceed without it for calcium imaging simulation.")
    # To prevent error in a batch run of README, could raise SystemExit or use a fallback
    # For now, let's assume it exists for a "real" example.
    raise SystemExit("LIFCalciumFluorNeuron model is required for this example.")


# 2. Create an Organoid
calcium_activity_organoid = Organoid(name="CalciumActivityOrganoid")
num_activity_neurons = 20 # Smaller number for clearer Vm/Ca plots
activity_positions = spatial.random_positions_in_cube(N=num_activity_neurons, side_length=80*b2.um)

# Initial membrane potentials varied to desynchronize initial firing
initial_v_activity = np.random.uniform(-65, -55, num_activity_neurons) * b2.mV
# Initial calcium and fluorescence (assuming they start at baseline, e.g., 0)
initial_ca = calcium_model_def['namespace'].get('Ca_default_init', 0.0)
initial_f = calcium_model_def['namespace'].get('F_default_init', 0.0)

active_neurons_group = calcium_activity_organoid.add_neurons(
    name="active_ca_neurons",
    num_neurons=num_activity_neurons,
    model_name=model_name_for_organoid, # Pass the string name
    model_params=calcium_model_function_params, # Pass the parameters for the model function
    positions=activity_positions,
    initial_values={
        'v': initial_v_activity,
        'Ca': initial_ca, # Assuming 'Ca' is a state variable in the model
        'F': initial_f    # Assuming 'F' is a state variable in the model
    }
)

# 3. Setup the Simulator
sim_activity = Simulator(organoid=calcium_activity_organoid, brian2_dt=0.1*b2.ms)
# sim_activity.setup_simulation_entry(...) # For SQLite logging

# 4. Add SpikeMonitor for all neurons in the group
sim_activity.add_recording(
    monitor_name="activity_spikes",
    monitor_type="spike",
    target_group_name="active_ca_neurons",
    record=True
)

# 5. Add StateMonitor for Vm, Ca, and F for a subset of neurons
# Record from first few neurons, or all if num_activity_neurons is small
indices_to_record_state = list(range(min(3, num_activity_neurons)))
if indices_to_record_state: # Only add if there are neurons to record
    sim_activity.add_recording(
        monitor_name="activity_states",
        monitor_type="state",
        target_group_name="active_ca_neurons",
        variables_to_record=['v', 'Ca', 'F'], # Must match variables in neuron model
        record_indices=indices_to_record_state,
        dt=0.2*b2.ms # Record states at a slightly lower frequency than simulation dt
    )
else:
    print("No neurons selected for state recording.")


# 6. Run simulation
activity_simulation_duration = 600*b2.ms
print(f"\nRunning activity and calcium imaging example for {activity_simulation_duration}...")
sim_activity.run(activity_simulation_duration, report='text', report_period=100*b2.ms)
print("Activity and calcium simulation finished.")

# 7. Retrieve and Plot Spike Data
spike_data_activity = sim_activity.get_data("activity_spikes")
print(f"Activity example recorded {len(spike_data_activity.i)} spikes.")

if len(spike_data_activity.i) > 0:
    fig_spikes_act, ax_spikes_act = plt.subplots(figsize=(10,4))
    spike_plotter.plot_raster(
        spike_indices=spike_data_activity.i,
        spike_times=spike_data_activity.t,
        duration=activity_simulation_duration,
        ax=ax_spikes_act,
        title="Spikes from Active Calcium-Model Neurons"
    )
    plt.tight_layout()
    plt.show()

# 8. Retrieve, Process, and Plot Vm, Calcium, and Fluorescence Data
if "activity_states" in sim_activity.monitors:
    state_data_activity = sim_activity.get_data("activity_states")
    time_pts_ms = state_data_activity.t / b2.ms

    # Plot Vm
    fig_vm, ax_vm = plt.subplots(figsize=(12,4))
    if hasattr(state_data_activity, 'v'):
        for i in range(state_data_activity.v.shape[0]):
            original_idx = indices_to_record_state[i]
            ax_vm.plot(time_pts_ms, state_data_activity.v[i,:] / b2.mV, label=f"Neuron {original_idx}")
        ax_vm.set_xlabel("Time (ms)"); ax_vm.set_ylabel("Vm (mV)")
        ax_vm.set_title("Membrane Potential (Vm) Traces"); ax_vm.legend(fontsize='small')
        plt.tight_layout(); plt.show()

    # Plot raw Ca and F traces
    if hasattr(state_data_activity, 'Ca') and hasattr(state_data_activity, 'F'):
        fig_ca_f, axes_ca_f = plt.subplots(2, 1, sharex=True, figsize=(12, 6))
        for i in range(state_data_activity.F.shape[0]): # Assuming F and Ca have same shape[0]
            original_idx = indices_to_record_state[i]
            axes_ca_f[0].plot(time_pts_ms, state_data_activity.F[i,:], label=f"Neuron {original_idx}")
            axes_ca_f[1].plot(time_pts_ms, state_data_activity.Ca[i,:], label=f"Neuron {original_idx}")
        axes_ca_f[0].set_ylabel("Fluorescence (F arbitrary units)")
        axes_ca_f[0].set_title("Raw Fluorescence Traces")
        axes_ca_f[0].legend(fontsize='small')
        axes_ca_f[1].set_ylabel("Calcium (Ca arbitrary units)")
        axes_ca_f[1].set_xlabel("Time (ms)")
        axes_ca_f[1].set_title("Raw Intracellular Calcium Traces")
        axes_ca_f[1].legend(fontsize='small')
        plt.tight_layout(); plt.show()

        # Calculate and plot ΔF/F
        try:
            # Using the placeholder ΔF/F calculation from previous response
            F_traces_np = np.array(state_data_activity.F)
            delta_F_F_traces_list = []
            for i_trace in range(F_traces_np.shape[0]):
                f_single_trace = F_traces_np[i_trace,:]
                baseline_end_idx = max(1, int(0.1 * len(f_single_trace))) # Use first 10% as baseline F0
                f0 = np.mean(f_single_trace[:baseline_end_idx])
                if abs(f0) < 1e-9: f0 = 1e-9 # Avoid division by zero or very small F0
                delta_F_F_traces_list.append((f_single_trace - f0) / f0)
            delta_F_F_traces_np = np.array(delta_F_F_traces_list)

            if delta_F_F_traces_np.size > 0:
                fig_dff, ax_dff = plt.subplots(figsize=(12,4))
                traces_dict_for_plotter = {
                    indices_to_record_state[i]: delta_F_F_traces_np[i,:] for i in range(delta_F_F_traces_np.shape[0])
                }
                # Assuming calcium_plotter.plot_calcium_traces can take a dict of traces
                # If not, plot directly:
                for i_plot in range(delta_F_F_traces_np.shape[0]):
                    ax_dff.plot(time_pts_ms, delta_F_F_traces_np[i_plot,:], label=f"Neuron {indices_to_record_state[i_plot]}")
                
                ax_dff.set_xlabel("Time (ms)"); ax_dff.set_ylabel("ΔF/F")
                ax_dff.set_title("Simulated ΔF/F Traces"); ax_dff.legend(fontsize='small')
                plt.tight_layout(); plt.show()

        except AttributeError as e_dff_attr:
            print(f"Note: Could not plot ΔF/F. A required analysis function might be missing: {e_dff_attr}")
        except Exception as e_dff:
            print(f"An error occurred during ΔF/F processing or plotting: {e_dff}")
    else:
        print("Fluorescence (F) or Calcium (Ca) variables not found in recorded states.")
else:
    print("State monitor 'activity_states' not found or no data to plot.")

# if hasattr(sim_activity, 'close'): sim_activity.close()

Overview of Example Notebooks (examples/)

The examples/ directory provides a guided tour through pyneurorg's features:

• 00_Installation_and_Setup.ipynb: Guides users through the installation process of pyneurorg and its dependencies, and includes a basic test to confirm a working setup.
• 01_Creating_Your_First_Organoid.ipynb: Introduces the Organoid class, demonstrating how to define neuronal populations, assign spatial positions, and conceptually add synapses.
• 02_Running_a_Simple_Simulation_and_Recording_Spikes.ipynb: Shows how to use the Simulator class to run a basic simulation of a created organoid and record neuronal spikes and membrane potentials.
• 03_Exploring_Neuron_and_Synapse_Models.ipynb: Details the various predefined neuron and synapse models available in pyneurorg.core and how to customize their parameters.
• 04_Spatial_Arrangement_and_Connectivity_Rules.ipynb: Focuses on creating 3D spatial layouts for neurons and defining rules for establishing synaptic connections between them (e.g., based on distance or probability).
• 05_MEA_Stimulation_and_Basic_Recording.ipynb: Demonstrates how to model a Microelectrode Array (MEA), simulate electrical stimulation of the organoid via MEA electrodes, and record activity.
• 06_Simulating_Spontaneous_Activity_and_LFP_Proxy.ipynb: Illustrates setting up a more complex network (e.g., with excitatory/inhibitory balance) to generate spontaneous activity and compute a proxy for Local Field Potentials (LFP).
• 07_Patterned_Stimulation_and_Response_Analysis.ipynb: Shows how to use the stimulus_generator to create complex temporal patterns of stimulation and analyze the network's response (e.g., PSTH).
• 08_Implementing_Synaptic_Plasticity_STDP.ipynb: Explains how to incorporate Spike-Timing-Dependent Plasticity (STDP) rules to modify synaptic strengths based on activity.
• 09_Simulating_Structural_Plasticity_Network_Formation.ipynb: Covers the simulation of structural changes in the network, such as the activity-dependent formation and pruning of synapses.
• 10_Modeling_Calcium_Dynamics_and_Fluorescence_Imaging.ipynb: Details how to use neuron models that include intracellular calcium dynamics and simulate the corresponding fluorescence signals from indicators like GCaMP.
• 11_Data_Persistence_Saving_and_Loading_with_SQLite.ipynb: Demonstrates how to save simulation results (metadata, spikes, state variables) to an SQLite database and load them back for later analysis.
• 12_Inferring_Functional_Networks_from_Spike_Data.ipynb: Shows how to use analysis tools to infer functional connectivity maps from recorded spike train data (e.g., using STTC or cross-correlation).
• 13_Inferring_Functional_Networks_from_Calcium_Data.ipynb: Similar to the above, but demonstrates inferring functional networks from simulated calcium imaging data.
• 14_Advanced_Analysis_Bursting_and_Synchrony.ipynb: Covers more advanced analysis techniques, such as detecting bursting patterns in neuronal activity and quantifying network synchrony.
• 15_Example_Modeling_a_Simplified_Disease_Phenotype.ipynb: Provides an example of how pyneurorg can be used to model and investigate network alterations associated with a simplified disease phenotype.

License

This project is licensed under the MIT License.