spikertools 0.1.0__tar.gz

spikertools-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: spikertools
+Version: 0.1.0
+Summary: A Python library for neuroscience data analysis of Backyard Brains SpikeRecorder files - forked from Backyard Brains github
+Home-page: https://github.com/LeonardoFerrisi/SpikerTools
+Author: Greg Gage
+Author-email: gagegreg@backyardbrains.com
+Maintainer: Leonardo Ferrisi
+Maintainer-email: Leonardo.Ferrisi@utah.edu
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# SpikerTools
+
+**SpikerTools** is a Python library designed to help students analyze SpikeRecorder files from SpikerBoxes. It provides easy-to-use functions for loading, processing, and visualizing neural and EEG data, enabling students to explore neuroscience concepts through hands-on data analysis.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Usage Examples](#usage-examples)
+  - [Loading Data](#loading-data)
+  - [Plotting Session Overview](#plotting-session-overview)
+  - [Event-Related Potential (ERP)](#event-related-potential-erp)
+  - [Peri-Event Time Histogram (PETH)](#peri-event-time-histogram-peth)
+  - [Spectrogram Analysis](#spectrogram-analysis)
+  - [Average Power Spectrum](#average-power-spectrum)
+- [For Teachers](#for-teachers)
+  - [Sample Lesson Plan](#sample-lesson-plan)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- Load neural and EEG data from WAV files.
+- Handle events and neuronal spikes with timestamped annotations.
+- Filter and normalize signal data.
+- Compute statistical measures like inter-spike intervals and firing rates.
+- Visualize data with various plots:
+  - Session overview with event markers.
+  - Event-Related Potentials (ERPs).
+  - Peri-Event Time Histograms (PETH) with raster plots.
+  - Spectrograms with event overlays.
+  - Average power spectra for frequency analysis.
+  - Histograms of inter-event and inter-spike intervals.
+
+## Installation
+
+You can install SpikerTools using pip:
+
+```bash
+pip install spikertools
+```
+
+Note: If SpikerTools is not yet available on PyPI, you can install it directly from the source code:
+
+```bash
+git clone https://github.com/BackyardBrains/SpikerTools.git
+pip install -e ./SpikerTools
+```
+### If you are in a jupyter notebook
+```bash
+!pip install ./Spikertools
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.6 or higher
+- Required Python packages:
+  - numpy
+  - scipy
+  - matplotlib
+  - seaborn
+
+Install the required packages using:
+
+```bash
+pip install numpy scipy matplotlib seaborn
+```
+
+## Usage Examples
+
+### Loading Data
+
+```python
+from spikertools import Session
+
+# Load your data file (WAV file and corresponding events file)
+wav_file_path = 'data/neurons/rate_coding/BYB_Recording_2022-01-13_13.18.29.wav'
+
+# Initialize the Session
+session = Session(wav_file_path)
+```
+
+### Plotting Channels from Session
+
+```python
+# Plot the session overview with event markers
+session.plots.plot_channels()
+```
+
+### Event-Related Potential (ERP)
+
+```python
+
+p300_wav_file = 'data/eeg/p300/BYB_Recording_2019-06-11_13.23.58.wav'
+s = Session(p300_wav_file)
+
+# Define events for P300 (default is '1' and '2') and add colors
+s.events[0].name = 'standard'
+s.events[0].color = 'blue'
+
+s.events[1].name = 'oddball'
+s.events[1].color = 'red'
+
+# Assign location as name to the P300 channel (Optional)
+s.channels[0].name = 'P4'
+
+# Optional: Filter the P300 channel to reduce high frequency noise
+s.channels[0].filter(ftype='lp', cutoff=10, order=3)
+```
+
+### Peri-Event Time Histogram (PETH)
+
+```python
+# Plot PETH with raster for a neuron aligned to an event
+session.plots.plot_peth(
+    neuron=s.neurons[0],     # Neuron to plot (defaults to first)
+    events=s.events,        # List of Event objects (defaults to all)
+    epoch_window=(-0.5, 1.0),      # 500ms before to 1000ms after event
+    bin_size=0.04,           # 40ms bins
+    title="Peri-Event Time Histogram (PETH) with Raster Plots for Touch Pressure Events", # Add a custom title
+    save_path=None, # Save the plot to a file
+    show=True
+)
+```
+
+### Spectrogram Analysis
+
+```python
+# Plot spectrogram of the EEG data with event markers
+session.plots.plot_spectrogram(
+    channel=session.channels[0],
+    freq_range=(0, 50),
+    events=session.events
+)
+```
+
+### Average Power Spectrum
+
+```python
+# Plot average power spectra during 'Open' and 'Close' events
+session.plots.plot_average_power(
+    events=session.events,
+    freq_range=(0, 30),
+    epoch_window=(0, 5),
+    channel=session.channels[0]
+)
+```
+
+## For Teachers
+
+SpikerTools is designed to be an educational tool that integrates seamlessly into classroom activities. Here's how you can incorporate it into your teaching:
+
+- **Hands-On Data Analysis**: Provide students with real neural or EEG data recordings and guide them through loading and analyzing the data using SpikerTools.
+- **Visualization of Neural Activity**: Use the plotting functions to help students visualize neural spikes, event-related potentials, and frequency content of EEG signals.
+- **Concept Reinforcement**: Reinforce concepts like neuronal firing rates, inter-spike intervals, and the effects of stimuli on neural activity.
+- **Customizable Plots**: Encourage students to explore different parameters and customize plots to deepen their understanding.
+- **Interdisciplinary Learning**: Integrate programming skills with neuroscience, promoting interdisciplinary education.
+
+### Sample Lesson Plan
+
+1. **Introduction to Neural Signals:**
+   - Discuss the basics of neural spikes and EEG signals.
+   - Explain the significance of events and stimuli in neural recordings.
+   
+2. **Data Loading and Preprocessing:**
+   - Show students how to load data into SpikerTools.
+   - Demonstrate filtering and normalization techniques.
+
+3. **Data Visualization:**
+   - Guide students through plotting session overviews and ERPs.
+   - Analyze spectrograms to understand frequency components.
+
+4. **Data Analysis:**
+   - Calculate firing rates and inter-spike intervals.
+   - Compare neural responses to different stimuli.
+
+5. **Discussion and Interpretation:**
+   - Interpret the results and discuss their implications.
+   - Encourage students to ask questions and explore further.
+
+## Contributing
+
+We welcome contributions to enhance SpikerTools. If you have ideas for new features, improvements, or bug fixes, please:
+
+1. Fork the repository.
+2. Create a new branch for your feature or fix.
+3. Commit your changes with clear messages.
+4. Submit a pull request describing your changes.
+
+Please ensure that your code follows best practices and includes appropriate tests.
+
+## License
+
+SpikerTools is released under the **MIT License**.

spikertools-0.1.0/README.md

@@ -0,0 +1,197 @@
+# SpikerTools
+
+**SpikerTools** is a Python library designed to help students analyze SpikeRecorder files from SpikerBoxes. It provides easy-to-use functions for loading, processing, and visualizing neural and EEG data, enabling students to explore neuroscience concepts through hands-on data analysis.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Usage Examples](#usage-examples)
+  - [Loading Data](#loading-data)
+  - [Plotting Session Overview](#plotting-session-overview)
+  - [Event-Related Potential (ERP)](#event-related-potential-erp)
+  - [Peri-Event Time Histogram (PETH)](#peri-event-time-histogram-peth)
+  - [Spectrogram Analysis](#spectrogram-analysis)
+  - [Average Power Spectrum](#average-power-spectrum)
+- [For Teachers](#for-teachers)
+  - [Sample Lesson Plan](#sample-lesson-plan)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- Load neural and EEG data from WAV files.
+- Handle events and neuronal spikes with timestamped annotations.
+- Filter and normalize signal data.
+- Compute statistical measures like inter-spike intervals and firing rates.
+- Visualize data with various plots:
+  - Session overview with event markers.
+  - Event-Related Potentials (ERPs).
+  - Peri-Event Time Histograms (PETH) with raster plots.
+  - Spectrograms with event overlays.
+  - Average power spectra for frequency analysis.
+  - Histograms of inter-event and inter-spike intervals.
+
+## Installation
+
+You can install SpikerTools using pip:
+
+```bash
+pip install spikertools
+```
+
+Note: If SpikerTools is not yet available on PyPI, you can install it directly from the source code:
+
+```bash
+git clone https://github.com/BackyardBrains/SpikerTools.git
+pip install -e ./SpikerTools
+```
+### If you are in a jupyter notebook
+```bash
+!pip install ./Spikertools
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.6 or higher
+- Required Python packages:
+  - numpy
+  - scipy
+  - matplotlib
+  - seaborn
+
+Install the required packages using:
+
+```bash
+pip install numpy scipy matplotlib seaborn
+```
+
+## Usage Examples
+
+### Loading Data
+
+```python
+from spikertools import Session
+
+# Load your data file (WAV file and corresponding events file)
+wav_file_path = 'data/neurons/rate_coding/BYB_Recording_2022-01-13_13.18.29.wav'
+
+# Initialize the Session
+session = Session(wav_file_path)
+```
+
+### Plotting Channels from Session
+
+```python
+# Plot the session overview with event markers
+session.plots.plot_channels()
+```
+
+### Event-Related Potential (ERP)
+
+```python
+
+p300_wav_file = 'data/eeg/p300/BYB_Recording_2019-06-11_13.23.58.wav'
+s = Session(p300_wav_file)
+
+# Define events for P300 (default is '1' and '2') and add colors
+s.events[0].name = 'standard'
+s.events[0].color = 'blue'
+
+s.events[1].name = 'oddball'
+s.events[1].color = 'red'
+
+# Assign location as name to the P300 channel (Optional)
+s.channels[0].name = 'P4'
+
+# Optional: Filter the P300 channel to reduce high frequency noise
+s.channels[0].filter(ftype='lp', cutoff=10, order=3)
+```
+
+### Peri-Event Time Histogram (PETH)
+
+```python
+# Plot PETH with raster for a neuron aligned to an event
+session.plots.plot_peth(
+    neuron=s.neurons[0],     # Neuron to plot (defaults to first)
+    events=s.events,        # List of Event objects (defaults to all)
+    epoch_window=(-0.5, 1.0),      # 500ms before to 1000ms after event
+    bin_size=0.04,           # 40ms bins
+    title="Peri-Event Time Histogram (PETH) with Raster Plots for Touch Pressure Events", # Add a custom title
+    save_path=None, # Save the plot to a file
+    show=True
+)
+```
+
+### Spectrogram Analysis
+
+```python
+# Plot spectrogram of the EEG data with event markers
+session.plots.plot_spectrogram(
+    channel=session.channels[0],
+    freq_range=(0, 50),
+    events=session.events
+)
+```
+
+### Average Power Spectrum
+
+```python
+# Plot average power spectra during 'Open' and 'Close' events
+session.plots.plot_average_power(
+    events=session.events,
+    freq_range=(0, 30),
+    epoch_window=(0, 5),
+    channel=session.channels[0]
+)
+```
+
+## For Teachers
+
+SpikerTools is designed to be an educational tool that integrates seamlessly into classroom activities. Here's how you can incorporate it into your teaching:
+
+- **Hands-On Data Analysis**: Provide students with real neural or EEG data recordings and guide them through loading and analyzing the data using SpikerTools.
+- **Visualization of Neural Activity**: Use the plotting functions to help students visualize neural spikes, event-related potentials, and frequency content of EEG signals.
+- **Concept Reinforcement**: Reinforce concepts like neuronal firing rates, inter-spike intervals, and the effects of stimuli on neural activity.
+- **Customizable Plots**: Encourage students to explore different parameters and customize plots to deepen their understanding.
+- **Interdisciplinary Learning**: Integrate programming skills with neuroscience, promoting interdisciplinary education.
+
+### Sample Lesson Plan
+
+1. **Introduction to Neural Signals:**
+   - Discuss the basics of neural spikes and EEG signals.
+   - Explain the significance of events and stimuli in neural recordings.
+   
+2. **Data Loading and Preprocessing:**
+   - Show students how to load data into SpikerTools.
+   - Demonstrate filtering and normalization techniques.
+
+3. **Data Visualization:**
+   - Guide students through plotting session overviews and ERPs.
+   - Analyze spectrograms to understand frequency components.
+
+4. **Data Analysis:**
+   - Calculate firing rates and inter-spike intervals.
+   - Compare neural responses to different stimuli.
+
+5. **Discussion and Interpretation:**
+   - Interpret the results and discuss their implications.
+   - Encourage students to ask questions and explore further.
+
+## Contributing
+
+We welcome contributions to enhance SpikerTools. If you have ideas for new features, improvements, or bug fixes, please:
+
+1. Fork the repository.
+2. Create a new branch for your feature or fix.
+3. Commit your changes with clear messages.
+4. Submit a pull request describing your changes.
+
+Please ensure that your code follows best practices and includes appropriate tests.
+
+## License
+
+SpikerTools is released under the **MIT License**.

spikertools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spikertools-0.1.0/setup.py

@@ -0,0 +1,39 @@
+# setup.py
+
+from pathlib import Path
+
+from setuptools import setup, find_packages
+
+long_description = Path(__file__).parent.joinpath("README.md").read_text(encoding="utf-8")
+
+setup(
+    name='spikertools',
+    version='0.1.0',
+    packages=find_packages(),
+    install_requires=[
+        'numpy',
+        'scipy',
+        'matplotlib',
+        'seaborn',
+    ],
+    python_requires='>=3.9',
+    include_package_data=True,
+    description='A Python library for neuroscience data analysis of Backyard Brains SpikeRecorder files - forked from Backyard Brains github',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    author='Greg Gage',
+    author_email='gagegreg@backyardbrains.com',
+    maintainer='Leonardo Ferrisi',
+    maintainer_email='Leonardo.Ferrisi@utah.edu',
+    url='https://github.com/LeonardoFerrisi/SpikerTools',
+    classifiers=[
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+        'Operating System :: OS Independent',
+        'Intended Audience :: Science/Research',
+        'Topic :: Scientific/Engineering',
+    ],
+)

spikertools-0.1.0/spikertools/__init__.py

@@ -0,0 +1,7 @@
+# spikertools/__init__.py
+
+from .models import Event
+from .core import Session, Channel, Neuron, Events
+from .plots import Plots
+
+__all__ = ['Session', 'Channel', 'Event', 'Neuron', 'Events', 'Plots']

spikertools-0.1.0/spikertools/core.py

@@ -0,0 +1,149 @@
+# spikertools/core.py
+
+from spikertools.models import Event, Neuron, Channel, Session, Events, Channels
+from spikertools.plots import Plots
+import numpy as np
+from scipy.io import wavfile
+import os
+import re
+from datetime import datetime
+
+class Session:
+    def __init__(self, wav_file_path, events_file_path=None):
+        self.wav_file = wav_file_path
+        self.sample_rate, self.data = wavfile.read(wav_file_path)
+        print(f"Loaded WAV file: {wav_file_path}")
+        print(f"Sample rate: {self.sample_rate} Hz")
+        print(f"Data length: {len(self.data)} samples")
+
+        if events_file_path is None:
+            # Infer events file path
+            events_file = wav_file_path.replace('.wav', '-events.txt')
+        else:
+            events_file = events_file_path
+
+        print(f"Looking for events file: {events_file}")
+
+        # Initialize events and neurons before loading
+        self.events = Events([])  # Changed from list to Events
+        self.neurons = []
+
+        # Initialize the Plots class
+        self.plots = Plots(self)
+        
+        if os.path.exists(events_file):
+            self._load_events(events_file)
+            print(f"Loaded {len(self.events)} events and {len(self.neurons)} neurons.")
+        else:
+            print("No events file found.")
+
+        # Initialize other attributes
+        self.channels = self._initialize_channels()
+        self.datetime = self._extract_datetime()
+
+    def _load_events(self, events_file):
+        with open(events_file, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith('#'):
+                    continue
+                parts = line.split(',')
+                if len(parts) != 2:
+                    continue
+                name, timestamp = parts
+                name = name.strip()
+                try:
+                    timestamp = float(timestamp.strip())
+                except ValueError:
+                    print(f"Invalid timestamp: {timestamp} in line: {line}")
+                    continue
+                self._add_event(name, timestamp)
+
+    def _add_event(self, name, timestamp):
+        # Normalize the event name by stripping leading/trailing spaces
+        name = name.strip()
+        
+        # Assign colors to events and neurons
+        color = 'k'  # Default color is black
+        color_map = {
+            '1': 'r', '2': 'g', '3': 'b', '4': 'c', '5': 'm',
+            'Open': 'orange', 'Close': 'purple',
+        }
+        if name in color_map:
+            color = color_map[name]
+
+        # Check if event already exists
+        if self.events.has_event(name):
+            self.events[name].timestamps.append(timestamp)
+            return
+        
+        # Handle threshold events for neurons
+        if 'thresh' in name.lower():
+            # Use regex to parse threshold events
+            match = re.match(r'_(neuron\d+)thresh(\w+)-(\d+)', name, re.IGNORECASE)
+            if match:
+                neuron_id, thresh_type_partial, thresh_value_str = match.groups()
+                thresh_value = -int(thresh_value_str)  # Assuming thresholds are negative
+
+                # Find the neuron that corresponds to this threshold
+                target_neuron = None
+                for neuron in self.neurons:
+                    if neuron_id in neuron.name:
+                        target_neuron = neuron
+                        break
+                
+                if target_neuron:
+                    if 'hig' in thresh_type_partial.lower():
+                        target_neuron.thresh_high = thresh_value
+                        #print(f"Set high threshold for {target_neuron.name} to {thresh_value}")
+                    elif 'low' in thresh_type_partial.lower():
+                        target_neuron.thresh_low = thresh_value
+                        #print(f"Set low threshold for {target_neuron.name} to {thresh_value}")
+                    else:
+                        print(f"Unknown threshold type in event name: {name}")
+                else:
+                    print(f"Neuron '{neuron_id}' not found for threshold event: {name}")
+                return  # Threshold event processed; exit the method
+        
+        # Check if neuron already exists for spike events
+        if name.startswith('_'):
+            for neuron in self.neurons:
+                if neuron.name == name:
+                    neuron.timestamps.append(timestamp)
+                    return
+            
+            # If not, create a new neuron
+            neuron = Neuron(name, timestamps=[timestamp], color=color)
+            self.neurons.append(neuron)
+            #print(f"Added neuron: '{name}' with initial spike at timestamp: {timestamp}")
+        else:
+            # If not a neuron, treat as a regular event
+            event = Event(name, timestamps=[timestamp], color=color)
+            self.events.append(event)
+            #print(f"Added event: '{name}' at timestamp: {timestamp}")
+
+    def _initialize_channels(self):
+        # Initialize channels based on the data
+        channels = Channels([])  # Initialize empty Channels container (this uses models.Channels)
+        if self.data.ndim == 1:
+            channel = Channel(self.data, sample_rate=self.sample_rate, number=0) # This will now use models.Channel
+            channels.append(channel)
+        else:
+            for i in range(self.data.shape[1]):
+                channel_data = self.data[:, i]
+                channel = Channel(channel_data, sample_rate=self.sample_rate, number=i) # This will now use models.Channel
+                channels.append(channel)
+        return channels
+
+    def _extract_datetime(self):
+        # Extract datetime from the filename
+        basename = os.path.basename(self.wav_file)
+        match = re.search(r'(\d{4}-\d{2}-\d{2})_(\d{2}\.\d{2}\.\d{2})', basename)
+        if match:
+            date_str, time_str = match.groups()
+            date_parts = [int(part) for part in date_str.split('-')]
+            time_parts = [int(part) for part in time_str.split('.')]
+            return datetime(*date_parts, *time_parts)
+        return None
+
+