# Synaptipy User Guide

This guide provides detailed instructions for installing, configuring, and using Synaptipy for electrophysiology data visualization and analysis.

## Table of Contents

- [Installation](#installation)
 - [Requirements](#requirements)
 - [Standard Installation](#standard-installation)
 - [Developer Installation](#developer-installation)
- [Getting Started](#getting-started)
 - [Running the Application](#running-the-application)
 - [User Interface Overview](#user-interface-overview)
 - [Quick Start with Demo Data](#quick-start-with-demo-data)
- [Loading Data](#loading-data)
 - [Supported File Formats](#supported-file-formats)
 - [Opening Files](#opening-files)
- [Using the Explorer Tab](#using-the-explorer-tab)
 - [Navigation Controls](#navigation-controls)
 - [Plot Options](#plot-options)
- [Using the Analyser Tab](#using-the-analyser-tab)
 - [Input Resistance/Conductance Analysis](#input-resistanceconductance-analysis)
 - [Baseline/RMP Analysis](#baselinermp-analysis)
 - [Evoked Responses](#evoked-responses)
 - [Sag Ratio (Ih) Analysis](#sag-ratio-ih-analysis)
- [Using the Exporter Tab](#using-the-exporter-tab)
 - [Exporting to NWB](#exporting-to-nwb)
 - [Exporting Analysis Results](#exporting-analysis-results)
- [Advanced Options](#advanced-options)
 - [Command Line Arguments](#command-line-arguments)
 - [Logging and Debugging](#logging-and-debugging)
- [Licensing](#licensing)
- [Troubleshooting](#troubleshooting)

## Installation

### Requirements

- Python 3.11 (recommended); Python 3.10 and 3.12 are also supported
- Dependencies are automatically installed during package installation:
 - [PySide6](https://doc.qt.io/qtforpython-6/) - Qt6 bindings for Python (GUI framework)
 - [PyQtGraph](https://www.pyqtgraph.org) - OpenGL-accelerated plotting library
 - [Neo](https://neo.readthedocs.io/en/latest/) - electrophysiology file I/O (Garcia et al., 2014, *Front. Neuroinformatics* [doi:10.3389/fninf.2014.00010](https://doi.org/10.3389/fninf.2014.00010))
 - [NumPy](https://numpy.org) / [SciPy](https://scipy.org) - numerical computation and signal processing
 - [PyNWB](https://pynwb.readthedocs.io/en/stable/) - NWB data export (Rubel et al., 2022, *eLife* [doi:10.7554/eLife.78362](https://doi.org/10.7554/eLife.78362))

### Standard Installation

Synaptipy is available both as a standalone application and as a Python package.

#### Standalone Application (Recommended)
You can download pre-built installers for macOS (`.dmg`), Windows (`.exe`), and Linux (`.AppImage`) directly from the [GitHub Releases page](https://github.com/anzalks/synaptipy/releases).
- **macOS**: Download the `.dmg`, open it, and drag Synaptipy to your Applications folder.
- **Windows**: Download and run the `_Setup.exe` installer.
- **Linux**: Download the `.AppImage` file, make it executable (`chmod +x Synaptipy-*.AppImage`), and run it directly.

#### Python Package Installation

Install from source using the conda environment:

```bash
git clone https://github.com/anzalks/synaptipy.git
cd synaptipy
conda env create -f environment.yml
conda activate synaptipy
pip install .
```

### Developer Installation

For contributing to Synaptipy, install in editable mode with development dependencies:

```bash
git clone https://github.com/anzalks/synaptipy.git
cd synaptipy
conda env create -f environment.yml
conda activate synaptipy
pip install -e ".[dev]"
```

## Getting Started

### Running the Application

After installation, run the application using one of these methods:

1. **Using the installed entry point:**
 ```bash
 synaptipy
 ```

2. **Using the Python module:**
 ```bash
 python -m Synaptipy
 ```

### User Interface Overview

The Synaptipy interface consists of three main tabs:

1. **Explorer Tab**: View and navigate through data files, with interactive plotting
2. **Analyser Tab**: Perform various analyses on the loaded data
3. **Exporter Tab**: Export data and results to different formats

### Quick Start with Demo Data

If you have no recordings to hand, Synaptipy can download a set of curated
example files automatically.

1. Open **Help > Download Demo Data...**  A banner appears below the menu bar.
2. Click **Download Demo Data**.  Synaptipy downloads five example recordings
   from the public repository to `~/Documents/SynaptiPy_Demo/`:

   | File | Format | Description |
   |------|--------|-------------|
   | `2023_04_11_0018.abf` | ABF v2 | Whole-cell current-clamp, step protocol |
   | `2023_04_11_0019.abf` | ABF v2 | Whole-cell current-clamp, ramp protocol |
   | `2023_04_11_0021.abf` | ABF v2 | Voltage-clamp, IV curve |
   | `2023_04_11_0022.abf` | ABF v2 | Optogenetic stimulation protocol |
   | `240326_003.wcp` | WinWCP | WinWCP current-clamp recording |

3. Once all files are downloaded the banner closes automatically and the
   first ABF file opens in the **Explorer Tab**.
4. The **Help > Download Demo Data...** menu item is disabled for the rest of
   the session (and on future launches if the files are already present).

:::{note}
The download requires an internet connection.  Files already present on disk
are never re-downloaded.  If a download is interrupted, partially written
files are cleaned up so the next attempt starts fresh.
:::

## Loading Data

### Supported File Formats

File I/O is handled through the [Neo](https://neo.readthedocs.io/en/latest/) library
(Garcia et al., 2014, *Front. Neuroinformatics*, [doi:10.3389/fninf.2014.00010](https://doi.org/10.3389/fninf.2014.00010)).
Synaptipy can load any recording format for which Neo provides a reader - this includes
whole-cell patch-clamp and intracellular recordings as well as extracellular, sharp-electrode,
and multi-channel data, provided the file format is supported. Confirmed formats include:

| Format | Extension(s) | Acquisition System |
|---|---|---|
| Axon Binary Format | `.abf` | Axon / Molecular Devices |
| WinWCP | `.wcp` | Strathclyde Electrophysiology Software |
| CED / Spike2 | `.smr`, `.smrx` | Cambridge Electronic Design |
| Igor Pro | `.ibw`, `.pxp` | WaveMetrics |
| Intan | `.rhd`, `.rhs` | Intan Technologies |
| Neurodata Without Borders | `.nwb` | NWB standard |
| BrainVision | `.vhdr` | Brain Products |
| European Data Format | `.edf` | EDF/EDF+ |
| Plexon | `.plx`, `.pl2` | Plexon |
| Open Ephys | `.continuous`, `.oebin` | Open Ephys |
| Tucker Davis Technologies | `.tev`, `.tbk` | TDT |
| Neuralynx | `.ncs`, `.nse`, `.nev` | Neuralynx |
| NeuroExplorer | `.nex` | NeuroExplorer |
| MATLAB | `.mat` | - |
| ASCII / CSV | `.txt`, `.csv`, `.tsv` | - |

For the full list of Neo-supported formats, see the
[Neo I/O documentation](https://neo.readthedocs.io/en/latest/iolist.html).

### Opening Files

1. Click "Open File..." in the menu or use the shortcut (Ctrl+O or Cmd+O)
2. Navigate to your data file and select it
3. The file will open in the Explorer tab
4. If other files with the same extension exist in the folder, they will be available
   for navigation with **Prev / Next File** - this applies whether you opened one
   file or many, and whether you used the menu, drag-and-drop, or
   **Help > Download Demo Data**

## Using the Explorer Tab

### Navigation Controls

- **Zoom**: Use the mouse wheel, or zoom buttons
- **Pan**: Click and drag in the plot area
- **Reset View**: Click the "Reset View" button to return to the initial view
- **Navigate Between Files**:
 - Use the "Previous File" and "Next File" buttons (if multiple files were found)
 - The current file index is shown between the navigation buttons

### Plot Options

- **Plot Mode**:
  - "Overlay All + Avg": Shows all trials with the average highlighted
  - "Cycle Single Trial": Shows one trial at a time with navigation controls
- **Cross-File Trial Averaging**:
  While in "Cycle Single Trial" mode, you can manually build a grand average
  from any combination of files and trials across the entire session:
  1. Use the **"Add Current Trial to Avg Set"** button to add the currently
     displayed trial - including any active preprocessing transforms - to the
     global selection set.
  2. Navigate freely between files (even files of different durations or
     sampling protocols) and continue adding trials. The selection accumulates
     persistently until cleared.
  3. Enable **"Plot Selected Avg"** to overlay the grand average on the current
     recording view.

  **Shape-mismatch handling:** Because recordings from different files may have
  different durations, the accumulator uses
  `sum[:min_len] += trial[:min_len]` where
  `min_len = min(len(accumulator), len(trial))`. This silently truncates every
  trial to the shortest array in the selection before summing, so recordings
  with different lengths never cause a NumPy broadcast error. The resulting
  average is plotted against the time vector of the first trial added to the
  set.
- **Channel Selection**: Choose which channel to view from the dropdown
- **Channel Visibility**: Use the per-channel show/hide checkboxes to hide channels
  you are not interested in. When a channel is hidden its plot row collapses
  entirely - no blank white space remains in the canvas. Re-checking the box
  restores the row immediately.
- **Downsampling**: Enable/disable automatic downsampling for large datasets

## Using the Analyser Tab

The Analyser tab provides 17 built-in analysis routines organised into five
module tabs. Each sub-tab is auto-generated from registry metadata and provides
parameter widgets, an interactive plot, a results table, and plot overlays.

The five Analyser pillars are:

| Pillar | Registry name | What it covers |
|---|---|---|
| **Intrinsic Properties** | `passive_properties` | RMP, Rin, Tau, Sag Ratio, I-V Curve, Capacitance |
| **Spike Analysis** | `single_spike` | Spike detection, Phase-plane analysis |
| **Excitability** | `firing_dynamics` | F-I curve, Burst analysis, Spike Train Dynamics |
| **Synaptic Events** | `synaptic_events` | Event detection (threshold, template match, baseline-to-peak) |
| **Evoked Responses** | `evoked_responses` | Evoked Sync, Paired-Pulse Ratio, Stimulus Train (STP) |

All analysis sub-tabs share the following interface behaviours:

- **Free-form numeric input** - Number fields accept freely typed values;
 intermediate states (empty field, a lone minus sign, etc.) are tolerated while
 typing. Stepping uses adaptive decimal increments.
- **Interactive vs Manual mode** - Sub-tabs that have draggable plot regions
 (e.g. Rin, Tau, Capacitance) expose a mode selector. In **Interactive** mode
 the time-window spinboxes are read-only and driven by the plot regions.
 Switching to **Manual** mode unlocks all spinboxes for direct entry.
- **Conditional parameter visibility** - Parameters irrelevant to the current
 clamp mode or analysis type are hidden automatically.

### Input Resistance/Conductance Analysis

1. Select data for analysis from the Explorer tab
2. Switch to the Analyser tab and select the *Input Resistance* sub-tab
3. Choose analysis mode:
 - **Interactive Mode**: Drag the blue (baseline) and red (response) regions
 on the plot - the time-window spinboxes update in real time and become
 read-only
 - **Manual Mode**: Unlock the spinboxes and type time windows directly
4. Enable **Auto Detect Pulse** to let the analysis locate step edges
 automatically from the stimulus derivative. If auto-detection produces
 invalid windows (e.g. due to action potentials in the trace), the analysis
 falls back to the current spinbox values and updates the spinboxes
 to reflect the windows actually used
5. Results will be displayed showing:
 - Input resistance in MΩ
 - Conductance in μS
 - Voltage and current changes
6. Click "Save Result" to store the analysis for later export

### Baseline/RMP Analysis

1. Select a channel for analysis
2. Specify the time window for baseline calculation
3. Choose analysis method:
 - **Mean**: Calculates the average over the specified window
 - **Median**: Uses the median (more robust to outliers)
4. Results will display the baseline value and variability metrics
5. Save results as needed

### Evoked Responses

The **Evoked Responses** tab contains three analysis sub-tabs for stimulus-evoked
measurements.

#### Evoked Sync

1. Load a recording that contains a TTL/digital stimulus channel alongside the
 signal channel
2. Switch to the *Evoked Sync* sub-tab in the Analyser
3. Select the TTL channel from the channel selector and set the **TTL Threshold**
 voltage used to binarise the stimulus signal
4. Choose the **Event Detection Type**:
 - **Spikes** - threshold-crossing AP detection; set the **Spike Threshold** (mV)
 - **Events (Threshold)** - prominence-based threshold event detection; set
 **Event Threshold**, **Event Direction**, and **Refractory Period**
 - **Events (Template)** - matched-filter cross-correlation using a bi-exponential kernel; set
 **Rise Tau**, **Decay Tau**, **Template Threshold** (SD), and
 **Template Direction**.
 A bank of three kernels scaled at 1x, 2x, and 3x the user-specified decay
 constant is applied automatically to tolerate dendritic filtering; events
 are detected on the pointwise maximum of the three z-scored filtered traces.
 Only the parameters relevant to the selected detection mode are shown.
5. Set the **Response Window** (ms) to define how far after each TTL onset
 to search for an event
6. Results include optical latency, response probability, jitter, stimulus
 count, and event count
7. Click "Save Result" to store for later export

#### Paired-Pulse Ratio

1. Load a two-pulse paired-stimulus recording
2. Switch to the *Paired-Pulse Ratio* sub-tab
3. Configure the two stimulus times (**Pulse 1 Time**, **Pulse 2 Time**, in seconds)
4. Set the **Amplitude Measurement Window (ms)** used to measure R1 and R2
5. Enable **Subtract R1 Tail** to fit a mono- or bi-exponential decay to the
 R1 tail and subtract the residual baseline at the time of the second stimulus;
 this prevents contamination of R2 by the decaying R1 current
6. Results include R1 amplitude, R2 amplitude, PPR (R2/R1), and, when tail
 subtraction is enabled, the corrected R2 and corrected PPR
7. Click "Save Result" to store for later export

#### Stimulus Train (STP)

1. Load a multi-pulse train recording
2. Switch to the *Stimulus Train (STP)* sub-tab
3. Set **Number of Pulses** and the inter-stimulus interval (**ISI (ms)**)
4. Set the **First Pulse Time (s)** and the **Amplitude Window (ms)**
 used to measure each response amplitude
5. Results include per-pulse amplitudes, amplitudes normalised to R1, and an
 STP classification (facilitation or depression) based on whether the mean
 normalised amplitude over pulses 2-N is above or below 1.0
6. Click "Save Result" to store for later export

### Sag Ratio (Ih) Analysis

1. Load a recording containing a hyperpolarising current-step protocol
2. Switch to the *Sag Ratio (Ih)* sub-tab in the Analyser
3. Configure the measurement windows:
 - **Baseline Start / End** - resting membrane potential window (before the step)
 - **Peak Window Start / End** - early part of the step where the sag minimum occurs
 - **Steady-State Start / End** - late part of the step where voltage has plateaued
4. Adjust **Peak Smoothing (ms)** to control Savitzky-Golay smoothing of the
 peak detection (default 5 ms). Increase for noisy traces
5. Set **Rebound Window (ms)** to control how far after stimulus offset the
 rebound depolarisation is measured (default 100 ms)
6. Results include:
 - **sag_ratio** - ratio form (>1 indicates I_h sag, 1 = no sag)
 - **sag_percentage** - percentage of sag deflection
 - **v_peak**, **v_ss**, **v_baseline** - the three voltage levels
 - **rebound_depolarization** - post-stimulus rebound amplitude
7. The plot shows horizontal lines at V_baseline (blue), V_peak (magenta),
 and V_ss (red)

### Additional Analysis Modules

The following analysis modules are also available in the Analyser tab.
All parameters are auto-generated from registry metadata and include tooltips,
valid ranges, and conditional visibility based on clamp mode.

**Intrinsic Properties tab:**
- **Tau (Time Constant)** - Single or bi-exponential fit to the voltage decay
  after a current step. Returns tau in ms with an overlay of the fitted curve.
  A **cyan trace overlay** automatically highlights the 5 ms baseline window
  immediately before the step onset for at-a-glance verification.
- **I-V Curve** - Current-voltage relationship across multi-trial step protocols.
  Fits aggregate Rin from the slope and opens a popup I-V scatter plot.
- **Capacitance** - Membrane capacitance from Tau/Rin (current-clamp) or
  capacitive-transient integration (voltage-clamp).  In current-clamp mode the
  series resistance ($R_s$) is automatically estimated from the fast voltage
  artifact at step onset (0.1 ms window) and used in the corrected formula
  $C_m = \tau / (R_{\text{in}} - R_s)$.

**Spike Analysis tab:**
- **Phase Plane** - dV/dt vs. voltage trajectory for AP initiation dynamics.
  Detects threshold via kink-slope criterion; reports mean threshold voltage
  and maximum dV/dt. Opens a popup phase-plane plot.

**Excitability tab:**
- **Excitability (F-I Curve)** - Multi-trial rheobase, F-I slope, maximum
  firing frequency, and spike-frequency adaptation ratio. Opens a popup
  F-I scatter plot. Requires multi-trial recordings.
- **Burst Analysis** - Max-ISI burst detection; reports burst count, mean
  spikes per burst, mean burst duration, and intra-burst frequency.
- **Spike Train Dynamics** - ISI statistics: mean ISI, coefficient of variation
  (CV), local variation (LV), and CV2. Opens a popup ISI plot.

**Synaptic Events tab:**
- **Event Detection (Template Match)** - Matched-filter cross-correlation using a
  bi-exponential kernel for miniature event detection. A fixed bank of three
  kernels at 1x, 2x, and 3x the user-specified decay constant is convolved with
  the trace; events are detected on the pointwise maximum of the three z-scored
  outputs, providing automatic tolerance for dendritic cable filtering.
  Configurable parameters: rise tau, decay tau, threshold in SD, and direction.
- **Event Detection (Baseline Peak)** - Direct baseline-to-peak amplitude
  detection with kinetics estimation for evoked or spontaneous events.

### Visual Validation Overlays

Several analysis sub-tabs draw semi-transparent overlays directly on top of the
raw trace to assist with visual validation of the analysis windows and fitted
curves. These overlays are rendered entirely in pyqtgraph and do not affect the
underlying data.

| Overlay type | Where it appears | Default colour |
|---|---|---|
| **Trace overlay** (cyan) | Baseline region highlighted before the stimulus | Cyan (#00cfff) |
| **Event fit overlay** (amber) | Bi-exponential or mono-exponential decay fits on the P1 tail in PPR | Amber (#ff9900) |

**Customising overlay appearance:**

1. Open **Edit > Plot Preferences** (or the settings toolbar button).
2. Switch to the **Trace Overlay** tab to adjust the highlight colour, line
   width, and opacity with a slider.
3. Switch to the **Event Fit Overlay** tab to adjust the fitted-curve colour,
   width, and opacity.

All overlay settings are persisted via QSettings and restored across sessions.

## Using the Exporter Tab

### Exporting to NWB

1. Load a recording in the Explorer tab
2. Navigate to the Exporter tab and select the "NWB Export" sub-tab
3. Specify the output file location
4. Fill in required metadata:
 - Session description
 - Experimenter information
 - Lab/institution details
5. Click "Export to NWB" and wait for the export to complete

:::{note}
The NWB exporter writes:

- Voltage/current traces as `CurrentClampSeries` / `VoltageClampSeries` with SI
  unit conversion
- Electrode metadata and session information
- **Stimulus waveforms** via a 3-step fallback: (1) raw digitized command
  waveform from the acquisition file; (2) synthetic step waveform reconstructed
  from ABF epoch metadata (description notes "Synthetic stimulus array
  reconstructed from protocol metadata."); (3) `stimulus=None` with a warning
  appended to the response trace description when no waveform is available
- **IntracellularRecordingsTable** linking each response to its electrode and
  stimulus series
- **SimultaneousRecordingsTable** and **SequentialRecordingsTable** for NWB 2.x
  icephys sweep grouping
- **ProcessingModule** containing discrete event arrays (spike times, synaptic
  event times) produced by the batch engine, stored as HDMF `DynamicTable`
  objects

See [NWB Export Mapping](nwb_mapping.md) for full container mapping details.
:::

### Exporting Analysis Results

1. Navigate to the "Analysis Results" sub-tab in the Exporter tab
2. Click "Refresh Results" to see all saved analysis results
3. Select which results to export
4. Specify the CSV output file location.
5. Click "Export Selected" to create the output.
 - **Note**: If your exported results contain *multiple different types of analysis* (e.g. some RMP results and some Spike Detection results), Synaptipy will automatically generate a **ZIP Archive** containing separate, perfectly cleanly formatted CSV files for each unique analysis type, fully supporting custom plugin columns!

## Advanced Options

### Reproducibility: How GUI Adjustments Serialize to the Batch Engine

A key design goal of Synaptipy is that any parameter tweak made interactively
in the GUI produces an identical result when replayed by the headless
`BatchAnalysisEngine`.  This section explains the serialization pathway.

#### Parameter capture

Every widget in an analysis tab (spin-boxes, check-boxes, combo-boxes,
draggable region handles) corresponds to one entry in the tab's
`ui_params` list, which is declared alongside the
`@AnalysisRegistry.register(...)` decorator for that analysis function.  The
parameter name, type, and current value are stored together.

When the user clicks **Run Analysis**, the tab calls
`_gather_analysis_parameters()`, which iterates over every `ui_params` entry
and reads the current widget value.  The result is a plain Python dictionary:

```python
# Example parameter dict for the Tau analysis tab
params = {
    "stim_start_time": 0.200,   # s  (from a QDoubleSpinBox)
    "fit_duration":    0.300,   # s
    "model":           "mono",  # (from a QComboBox)
    "artifact_blanking_ms": 0.5,
}
```

#### Interactive region handles

Draggable baseline or fit windows rendered as `pyqtgraph.LinearRegionItem`
objects are two-way linked to the corresponding spin-box pair via Qt signals.
Dragging the region emits `sigRegionChangeFinished`, which updates the
spin-box values.  Conversely, typing in a spin-box moves the region.
At the moment of analysis, the spin-box values - not the graphical object
positions - are read into the parameter dictionary.  The graphical object is
therefore only a visual convenience; the canonical parameter value is always
the spin-box number.

#### SessionManager serialization

`SessionManager` (a singleton) stores:

```python
# Simplified SessionManager state
{
    "active_analysis": "tau_analysis",
    "preprocessing_settings": { "lowpass_hz": 2000 },
    "analysis_params": {
        "tau_analysis": {
            "stim_start_time": 0.200,
            "fit_duration":    0.300,
            "model":           "mono",
        },
        ...
    }
}
```

These dictionaries are serialized to JSON when the user saves a session file
(**File - Save Session**).  Loading a session file restores them, so every
tab shows the same parameter values as when the session was saved.

#### Batch engine replay

The `BatchAnalysisEngine` accepts a list of file paths plus a parameter
dictionary in exactly the same format produced by `_gather_analysis_parameters()`:

```python
from Synaptipy.core.analysis.batch_engine import BatchAnalysisEngine
import Synaptipy.core.analysis  # populates the registry

engine = BatchAnalysisEngine()

pipeline = [
    {
        "analysis": "tau_analysis",
        "scope": "all_trials",
        "params": {
            "stim_start_time": 0.200,
            "fit_duration":    0.300,
            "model":           "mono",
            "artifact_blanking_ms": 0.5,
        },
    }
]

results = engine.run_batch(
    files=["cell_01.abf", "cell_02.abf"],
    pipeline_config=pipeline,
)
```

Because both paths invoke the same registered wrapper function with the same
parameter dictionary, the batch result is mathematically identical to the
GUI result - provided the same preprocessing pipeline is applied.

#### Preprocessing pipeline

Preprocessing settings (filters, baseline subtraction) are stored in
`SessionManager().preprocessing_settings` as a nested dictionary and can be
passed to the engine via the `preprocessing_settings` argument of
`BatchAnalysisEngine.run()`.  The engine applies the identical
`ProcessingPipeline` that the GUI uses, ensuring the batch trace matches the
trace the user visually validated.

### Preferences

Open **Edit > Preferences** (or **Synaptipy > Preferences** on macOS) to access the application settings:

| Setting | Description |
|---------|-------------|
| **Scroll Behavior** | Choose Natural, Inverted, or System scroll direction for plots. |
| **Appearance** | Switch between Light, Dark, or System color theme. |
| **Enable Custom Plugins** | When checked, Synaptipy loads Python plugins from `~/.synaptipy/plugins/` and `examples/plugins/`. See below for the hot-reload mechanism. |

### Checking for Updates

Synaptipy performs a silent version check in the background each time it
starts.  If a newer release is found on
[GitHub Releases](https://github.com/anzalks/synaptipy/releases) a
non-intrusive yellow banner appears below the menu bar showing the new version
number and a link to the release notes.  The banner can be dismissed with the
**Dismiss** button.

You can also trigger a manual check at any time via **Help > Check for
Updates...**.  The status bar reports the outcome:

- *"Checking for updates..."* - check in progress.
- *"You are on the latest version."* - no newer release found.
- Yellow banner - a newer version is available (click the link to open the
  release page in your browser).

The check is a single lightweight request to the GitHub Releases API
(`api.github.com`).  If your machine is offline or behind a firewall the
check fails silently - no error message is shown and no data is sent.

#### Enable Custom Plugins - Hot-Reload Mechanism

Toggling "Enable Custom Plugins" does **not** require an application restart.
When the checkbox state changes and the dialog is accepted, Synaptipy:

1. Calls `PluginManager.reload_plugins()`, which first calls
   `AnalysisRegistry.unregister_plugins()` to purge every plugin-sourced
   entry (those flagged `source="plugin"`) from the registry while leaving
   all built-in analyses intact.
2. If the setting is now **enabled**, re-executes every `.py` file discovered
   in `examples/plugins/` (bundled examples) then `~/.synaptipy/plugins/`
   (user additions). Each file's `@AnalysisRegistry.register(...)` decorator
   re-runs and re-populates the registry.
3. Calls `AnalyserTab.rebuild_analysis_tabs()` to destroy the existing
   sub-tab widgets and regenerate them from the updated registry - all within
   the running process.

The net effect is that plugin tabs appear or disappear immediately without
reloading the application. A syntax error or import failure in a single plugin
is caught and logged; remaining plugins still load normally.

> **Tip:** If you install a new plugin file while Synaptipy is running, open
> Preferences and toggle "Enable Custom Plugins" off then on to force an
> immediate reload of all plugins from disk.

#### Included Example Plugins

Synaptipy ships three ready-to-run example plugins in `examples/plugins/`.
With **Enable Custom Plugins** active they load automatically:

| Plugin file | Analyser tab label | What it measures |
|-------------|--------------------|------------------|
| `synaptic_charge.py` | Synaptic Charge (AUC) | Area under a postsynaptic current trace (total charge in pC); shaded fill + peak star overlay |
| `opto_jitter.py` | Opto Latency Jitter | Trial-to-trial variability in spike latency after an optogenetic TTL pulse |
| `ap_repolarization.py` | AP Repolarization Rate | Maximum rate of membrane-potential decline (dV/dt minimum) during an action potential |

Copy any of these files to `~/.synaptipy/plugins/` and edit your copy to create
a personalised variant without modifying the Synaptipy installation.

### Command Line Arguments

Synaptipy supports several command-line arguments:

```bash
synaptipy --help # Show help
synaptipy --dev # Run in development mode with detailed logging
synaptipy --log-dir /path/to/logs # Specify custom log directory
synaptipy --verbose # Enable verbose output
synaptipy --file /path/to/data.abf # Open a file directly on launch
```

### Logging and Debugging

Logs are stored in `~/.synaptipy/logs/` by default. In development mode, logs include detailed information for debugging.

To activate development mode:

```bash
# Using command line flag
synaptipy --dev

# Using environment variable
SYNAPTIPY_DEV_MODE=1 synaptipy
```

## Licensing

Synaptipy is released under the GNU Affero General Public License Version 3 (AGPL-3.0). This license ensures that the software remains free and open source, even when used as a service over a network.

Key aspects of the AGPL-3.0 license:

- You are free to use, modify, and distribute the software
- If you modify the software, you must release the modified source code
- If you use the software to provide a service over a network, you must make the complete source code available to users of that service
- Any derivative works must also be licensed under AGPL-3.0

For the full license text, see the LICENSE file in the root of the Synaptipy repository.

## Troubleshooting

### Common Issues

1. **File Format Not Recognized**:
 - Ensure the file is one of the supported formats
 - Check if you have the necessary dependencies for that format
 - Some formats require additional libraries not included by default

2. **GUI Display Issues**:
 - Ensure PySide6 is properly installed
 - Try updating your graphics drivers
 - If running remotely, ensure X forwarding is enabled

3. **Performance Problems with Large Files**:
 - Enable downsampling for visualization
 - Increase system RAM if possible
 - Consider splitting very large recordings into smaller files

4. **Export Failures**:
 - Check available disk space
 - Ensure write permissions for the target directory
 - For NWB exports, verify all required metadata is provided

### Biological Troubleshooting

These scenarios describe what analysis outputs mean in terms of patch-clamp
physiology, not just software errors.

**"Tau returns NaN after a current step"**

A failed exponential fit almost always means one of:
1. The patch is leaky - the cell membrane has not sealed properly (seal
   resistance below ~1 GOhm), so the voltage decays non-exponentially.
2. The cell has not fully charged - the current step is too short for the
   membrane RC to reach steady-state. Increase the step duration (>5 x tau,
   typically 200-500 ms for neurons).
3. The fit window includes the stimulus artifact - check that
   **Baseline End** is placed after the artifact but before the voltage
   plateau, and that **Fit Start** skips the initial capacitive transient.
4. Access resistance is too high (>30 MOhm for whole-cell) - the series
   resistance is limiting current delivery, making the apparent decay
   multi-exponential. Compensate or replace the pipette.

**"Input resistance (Rin) is abnormally low (< 50 MOhm for a cortical neuron)"**

- The holding current is wrong: the cell may be partially clamped at an
  unphysiological potential. Check your resting Vm before stepping.
- Shunt conductance: an imperfect seal or damaged membrane adds parallel
  conductance that reduces apparent Rin. Check seal resistance.
- The step amplitude is too large - nonlinear I-V conductances (Ih, inward
  rectifier K+) are activated. Use small hyperpolarising steps (5-20 pA).

**"Spike threshold is reported as NaN"**

The d2V/dt2 AP onset detector returns NaN when:
- The dV/dt at the detected threshold point is outside the biological range
  (> 300 V/s indicates a digital artifact; < 2 V/s indicates a noise
  crossing rather than a true AP upstroke).
- The rising phase of the AP is shorter than 0.2 ms (photo-electric artifact
  or electrical transient picked up from the stimulator).
- Increase filtering (Savitzky-Golay smoothing) or reduce the onset lookback
  window if thresholds are unreliable on noisy recordings.

**"Synaptic charge (AUC) is negative or much larger than expected"**

- Check that the baseline method is set to **Pre-Window (Local 10 ms)**.
  A global baseline corrupts the measurement when holding current drifts
  during long recording epochs.
- Verify the search window does not include the stimulus artifact. Set
  **Search Window Start** at least 2 ms after the stimulus.
- If the cell is in voltage-clamp, check the polarity: PSCs are downward
  (negative) in the standard convention. Use **Detection Method: Negative Peak**
  for IPSCs or **Absolute Peak** when sign is uncertain.

**"Opto-jitter is impossibly short (< 1 ms)"**

This almost always means the photo-electric artifact from the LED or laser
shutter is being detected as a spike. Set the **Artifact Blanking Window**
to at least 1-2 ms. Genuine monosynaptic latencies are 2-5 ms for direct
ChR2-expressing targets; disynaptic latencies are 8-15 ms.

**"Rs QC warning in batch output: Series resistance destabilized"**

The Rs warning appears when the series resistance increased by more than
20% (default) compared to the first sweep. This typically means:
- The pipette tip clogged partially during the recording.
- The gigaohm seal broke down gradually.
Sweeps flagged with `rs_qc_warning` should be excluded from analysis. The
default threshold (20%) can be adjusted via the `rs_tolerance` parameter
in `BatchAnalysisEngine.run_batch()`.

---

## Analysis Parameter Reference

The table below explains every common parameter in biological terms so you
can choose values that match your experimental design.

| Parameter | Unit | Biological meaning | Typical range |
|---|---|---|---|
| `prominence` | mV or pA | Minimum height of an event above the local baseline. Prevents noise peaks from being counted as real spikes or synaptic events. | 5-30 mV (spikes); 5-50 pA (PSCs) |
| `width` | ms | Minimum duration of an event at half-maximum. Excludes electrical transients that are far narrower than real APs (0.5-2 ms) or PSCs (2-20 ms). | 0.3-1.0 ms (spikes); 2-10 ms (PSCs) |
| `threshold` | mV or pA | Voltage (or current) level a trace must cross to be counted as an event. Set just above the noise floor. | -20 mV (spikes); 3 x noise RMS (PSCs) |
| `refractory_period` | ms | Minimum inter-event interval. Prevents double-counting the same AP or the same PSC. Should be slightly shorter than the fastest real inter-event interval in your data. | 2-5 ms (spikes); 5-20 ms (PSCs) |
| `baseline_window` | ms or s | Duration of the pre-event window used to measure the resting level. Shorter windows (10 ms) track slow holding-current drift more accurately than long windows. | 5-20 ms |
| `onset_lookback` | ms | How far before each spike peak to search for the AP onset (threshold crossing). Should span the full AP upstroke plus noise margin. | 2-5 ms |
| `smoothing` | ms | Width of the Savitzky-Golay smoothing kernel applied to the trace before differentiation (dV/dt). Increase for noisy recordings; decrease to preserve fast upstroke kinetics. | 0.1-0.5 ms |
| `step_onset_time` | s | Time of the voltage or current step command. Auto-detected from the stimulus derivative; override if auto-detection fails. | Protocol-dependent |
| `voltage_step_mv` | mV | Amplitude of the VC command step. Required for Rs and Cm calculation. Use the actual command amplitude, not the measured response. | -10 to -5 mV (typical access resistance protocol) |
| `blanking_window` | ms | Duration after a TTL stimulus to ignore. Prevents the photo-electric artifact from the LED from being misclassified as a spike. | 1-2 ms |
| `rs_tolerance` | fraction | Maximum fractional increase in series resistance before a sweep is flagged as unstable. 0.20 = flag sweeps where Rs has increased by >20% compared to Sweep 1. | 0.10-0.30 |

### Getting Help

If you encounter issues not covered here:

1. Check the [GitHub Issues](https://github.com/anzalks/synaptipy/issues) for known problems
2. Create a new issue with details about your problem
3. Include the log files and error messages in your report
