trace-selector

Trace Selector

Table of Contents

• Overview
• Installation
• Adapt the Settings
  • General
  • Detection
  • Threshold Settings
  • Stimulation
• Usage
  • Shortcuts and brief overview
  • Detailed Explanation
• Train a custom Model

Overview

A small GUI programm to ease the post-selection of average traces of functional recordings. The user can edit automatically detected response events (thresholding, ML-detecition, or both). Trace Selector will automatically compute various commonly used metrics (e.g. failure rate, paired-pulse ratio)

Installation

You will need Anaconda to be installed. If Anaconda is installed, open the "Anaconda Prompt" (Windows) or a terminal (Linux + Mac).

• Create a conda enviorment:

     conda create -n trace_selector python=3.10 pip
     conda activate trace_selector
  

• Install trace selector:

     pip install trace_selector
  

Build from source

Alternatively, you can also clone this repository and install it from there

   git clone https://github.com/s-weissbach/trace_selector.git
   cd trace_selector
   pip install -e .

Getting Started

The mean traces should be stored in a .csv or an excel file .xls, .xlsx. Ensure that the mean traces are organized with one trace per column. You can have columns with meta information (e.g. Time) that will be carried over to the output files.

Example input file

Time (ms)	Trace 1	Trace 2	(...)
0	23.5	18.7	(...)
1	25.1	20.3	(...)
2	22.8	17.6	(...)
3	21.4	19.2	(...)
4	(...)	(...)	(...)

[!Tip] Meta columns won't be included for analysis, but will be carried over to the output files.

Run Trace Selector

To run Trace Selector, follow these steps:

• conda activate trace_selector
  

• Launch the Trace Selector using the following command:

  python -m trace_selector
  

Adapt the Settings

To access the settings, press the settings symbol in the top icon bar. The settings are organized in the Tabs General, Detection, Local Maximum Detection Settings, and Stimulation.

General

In the general settings section, you can configure the following options:

• Set Output Path: Specify the directory where you want the output files to be saved.
• Export as XLSX: Choose whether to export the results in XLSX format, otherwise .csv files will be created.
• Add/Remove Meta Columns: Customize the meta columns based on your requirements.

Detection

[!NOTE] Rolling window z-normalization will be applied for detection.

Configure the detection settings according to your analysis preferences:

• Selection Methods: Choose between ML-based and Local maxima detection.
• Deep Learning Model: If ML-based selection is chosen, specify the deep learning model specific for the sensor you used.
• Time Window for Tau Computation: Set the time window for tau computation, which determines the decay estimate.
• Show Normalized Trace (Toggle): Toggle this option to display z-normalized traces in the output.
• Compute PPR (Toggle): If stimulation was used, enable this option to compute the paired pulse ratio (PPR).

Threshold Settings

• Prominence: Simply speeking, the prominence is the difference between a summit and a valley. In case of detection it allows to find peaks based on their neighbourhood and acts as a kind of local threshold.
• Noise multiplier: Each peak must exceed the treshold defined as mean+std*noise_multiplier
• Minimum peak distance: The minimum distance between peaks (in general not needed with a proper prominence value)

[!NOTE] Threshold is calculated witht the formula: $$\text{threshold} = (\text{multiplier} * std_{baseline}) + mean_{baseline}$$

Stimulation

• Enable Stimulation (Toggle): Toggle this option when you used stimulation in this recording.
• Start Frame for Stimulation: Specify the starting frame for stimulation. Stimulation frames will be infered automatically.
• Step Size for Stimulation: Set the step size for stimulation. Stimulation frames will be infered automatically.
• Patience: Define the duration for which a response should be counted as a valid response to the stimulation.
• Use Manual Stimulation Frames: Input stimulation frames manually

[!IMPORTANT] When entering stimulation frames manually, separate the frames by commas without spaces.

Usage

Shortcuts and brief overview

Command	Button	Shortcut	Description
Open File		Ctrl + O	Open a file
Save File		Ctrl + S	Save all traces up to this point and discard the rest
Settings		S	Open the settings
Back		B	Go one trace back
Discard		Q	Discard trace from analysis
Accept		E	Accept trace and keep for analysis
Modify Responses		W	Add or remove responses

Detailed explanation

• Open a File pressing the open button in the top bar.

  • Trace Selector will visualize the first column of the file that is not a meta column.
  • All detected responses will be annotated.
  • If specified in the settings, a horizontal, red dashed line will be shown

• Modify responses pressing the modify response button in the top bar

  • A window with all detected responses will be opened
  • Deselect false-positive responses
  • Add false-negative responses

• Accept or Discard a trace

  • To accept a trace and subsequently include it in the analysis:
  • To discard a trace from analysis:

• Change certantiy threshold (only when using ML-based detection):

  • Use the slider at the bottom to adjust the certantiy threshold used in the model. A lower threshold will lead to more detections, possibly, to more false-positives.

• Save and skip rest: press the save button in the top bar. All remaining traces of the file will be discarded.

Train a custom Model

See the Synapse Selector Detect for detailed tutorial on how to train a custom model.

[!Tip] You can share your model with the community - submit it to Trace Selector Modelzoo.GitHub - s-weissbach/synapse_selector_modelzoo.

How to Cite

If you use this software, please cite it as below:

Weißbach, S. and Milkovits, J. (2024) „s-weissbach/trace_selector: Trace Selector 0.2.13“. Zenodo. doi: 10.5281/zenodo.11949063.