Interactive and batch fiber-photometry analysis, from raw acquisition to reviewable results.
Inspect every processing decision in the desktop app, or run the same pipeline reproducibly from the CLI.
Download the Windows GUI (exe) | Download the Windows CLI | Read the full guide
pyBer combines a visual workflow with a deterministic processing backend. The GUI is designed for inspection and parameter discovery. The CLI is designed for unattended cohorts and reproducibility. Both use the same loaders, recommendations, signal processing, metadata schema, and exports.
Numeric settings in both panels accept direct keyboard entry: select the value, type, and press Enter or Tab to apply. Selected threshold, smoothing and timing fields also have sliders alongside the exact value. Broad time/frequency ranges use logarithmic sliders for finer adjustment near small values. Alt-drag adjusts any numeric field; ordinary dragging selects text. Disabled fields become editable when their associated method is enabled; use Adjust from auto to edit an automatic peak-prominence estimate.
Drop files or folders onto the preprocessing file list or Open/Add Folder buttons. In postprocessing, drop onto the Preprocessed Files or Behaviors list, or its load button, to choose the appropriate loader for CSV files. Drops also work in detached drawers and import files without moving the originals.
On Windows, launch pyBer without Run as administrator. An administrator
VS Code session also starts Python elevated, so Windows blocks incoming drops
from ordinary File Explorer before they reach pyBer. Save your session and
reopen VS Code normally, or launch the executable directly from Explorer.
The status bar and drop-target tooltips explain this when elevation is detected;
the load buttons still work. Source users can run
python scripts/create_windows_shortcut.py in the pyBer environment, then
double-click Launch pyBer.lnk from Explorer. This leaves existing sessions
open and does not change system permissions.
| Stage | Capabilities |
|---|---|
| Ingest | Current and legacy Doric HDF5 layouts, generic .h5 / .hdf5, RWD fluorescence CSV exports, multiple channels, DIO/AOUT triggers, and recursive folder discovery. |
| Recommendations | Recording-aware settings from sampling rate, duration, artifact load, signal shape, 405/465 coupling, and the selected sensor's kinetics. Each recommendation explains what to use and why. |
| Preprocessing | Time windows and sections, resampling, low-pass filtering, Savitzky-Golay or moving-window smoothing, asls / arpls / airpls baselines, fitted-reference motion correction, and multiple dF/F and z-score outputs. |
| Artifact review | Smart multi-evidence detection, adaptive or global MAD modes, manual regions, interpolation, cutting, strong local low-pass repair, or annotation without modification. |
| Quality control | Strict PASS / WARN / FAIL checks for artifact burden, motion bleed, fitted-reference signal retention, corrected-output SNR, reference noise, coverage, signal noise, coupling stability, output shape, and photobleaching. Includes report images and batch flagging. |
| Event alignment | DIO onset or offset, behavior onset or offset, state transitions, continuous variables, individual recordings, and grouped animals. |
| PSTH and behavior | Trial heatmaps, mean with SEM, eight behavior measures with medians and adjustable bins, and seven selectable PSTH metrics, each in its own panel. |
| Baseline suggestions (source) | Automatic pre-event choices below the baseline fields, ranked by suitability with one-click Apply. The score describes signal and event coverage, not statistical confidence. Method and limitations. |
| Spatial analysis | Occupancy-normalized activity maps, trajectories, and velocity-aware views when tracking coordinates are available. |
| Signal events | SciPy peak detection, manual or MAD-noise thresholds, minimum height/prominence/distance, smoothing, baseline-prominence normalization, AUC, amplitude, inter-peak interval, and rate-over-time summaries. |
| Synchronization | Align photometry to an external signal or video ROI, detect shared TTL/barcode edges, estimate lag and drift, review matching quality, batch apply, and export time_aligned. |
| Temporal models | Continuous GLM with FIR, raised-cosine, or B-spline bases and ridge/lasso/OLS fits; trial-level FLMM through fastFMM; block cross-validation, diagnostics, kernels, prediction, residuals, importance, and group summaries. |
| Projects and export | Save/load postprocessing projects, autosave recovery, recent files, processed CSV and HDF5, metadata sidecars, tables, plots, model reports, and publication figures. |
These captures were generated by pyBer itself from trial_0010.doric and its binary behavior table trial_0010_with_time.csv. The script in scripts/generate_readme_screenshots.py makes the demo reproducible. No traces, metrics, or model results were mocked.
The three synchronized plots show the raw signal and reference, filtered traces and baselines, and the selected output. The open drawer states the output formula, fit method, recommended values, and the evidence behind them.
The smart detector requires multiple forms of evidence before flagging a sample. Detected regions retain their evidence, core interval, padded repair interval, and enabled state. Manual regions can be added directly from the plot.
QC does not hide weak checks inside a weighted average. Critical and advisory checks are graded separately, the worst critical result controls the overall tier, and the recommendation card explains whether to keep, review, repair, or reject the recording.
The supplied behavior file produces 33 social-contact onset trials. pyBer displays the full recording, event-aligned heatmap, average with SEM, event-duration distribution, and pre/post summaries together.
 |
 |
| Transient detection MAD-noise threshold, detected peaks, amplitudes, intervals, and rate. |
Behavior analysis Per-file event count, time, duration, rate, raster, and distributions. |
Select a video ROI or load an external reference signal, extract the shared pulse train, review edge matching and drift, then apply the alignment to the photometry timebase.
The modeling workbench consumes the current processed recordings, behavior variables, DIO channels, and PSTH events. This demo fits a ridge-regularized continuous GLM to the supplied social-contact onset and state predictors. The screenshot reports the real cross-validated fit, including an instability warning, rather than presenting an idealized result.
- Add a recording or a folder. Folder import searches through nested folders.
- Select the photometry channel, optional DIO/AOUT trigger, time window, and sensor.
- Review the recommendation cards. Apply all recommendations or accept them one section at a time.
- Inspect artifacts, filtering, baseline, motion correction, and the final output on the linked plots.
- Run strict QC. Repair or exclude flagged intervals before exporting.
- Send processed recordings to Postprocessing.
- Load behavior, timestamps, tracking, video, or an external sync signal as needed.
- Compute individual or group PSTHs, spatial maps, behavior metrics, signal events, synchronization, or temporal models.
- Save the project and export the exact tables, HDF5 bundles, reports, and figures needed downstream.
In Events, choose Selected file or All files. Automatic detection estimates MAD noise after removing slow baseline drift, using the chosen quiet time window, behavior exclusions, or whole recording. The MAD multiplier controls automatic prominence and the optional Noise height gate above the local baseline. Adjust from auto copies a fresh estimate for the selected recording into Min prominence, switches to manual prominence, and keeps the optional height gate available. Opening Events or changing detection settings automatically refreshes the peaks, thresholds, and charts after a 300 ms pause. Refresh now remains available for an immediate rerun. Manual zoom is retained during these updates. In manual mode, the absolute prominence applies to all files in a batch.
The preview shows translucent noise bands at one and two estimated standard deviations, a dashed prominence guide, and a solid height threshold when enabled. Noise shading is an empirical scale, not a confidence interval. Prominence is measured from each peak's contour, so its baseline guide is not an absolute height cutoff. Filtering, peak widths, and shaded bands stop at missing intervals. AUC is unavailable when the full requested window crosses a cut or recording edge.
Batch detection estimates noise independently per recording, reports zero-peak and failed files, and supports cancellation between files. Rates use observed recording duration; inter-peak intervals never join different files or cross cuts. The export includes peak rows, a per-file summary CSV, and the exact detection settings JSON. Projects preserve the results and threshold overlays. Duplicate filenames receive distinct channel/occurrence labels in the signal file selector and batch report. Automatic refresh follows the selected scope without a modal dialog, yields between recordings, and replaces results only when the entire run is complete. New edits discard unfinished work and restart with the latest settings.
The reproducible synthetic benchmark in scripts/benchmark_signal_events.py
compares the earlier method with residual-noise detection and the height gate.
Synthetic results are not biological validation: a single per-file noise estimate
can still produce false positives when noise changes sharply within a recording.
Version 0.45 adds pyber-cli for one file, many files, or an entire directory tree. Recursive discovery is on by default.
pyBer-cli-windows.exe "D:\photometry\cohort_1" `
--sensor gcamp6f `
--channel AIN01 `
--trigger DIO02 `
--output-dir "D:\photometry\cohort_1_processed"From a source checkout, use the same interface through Python:
conda activate pyBer
python .\pyBer\cli.py recording.doric `
--sensor dlight12 `
--format both `
--set target_fs_hz=50 `
--set lowpass_hz=10 `
--set artifact_handling=Interpolate `
--set baseline_lambda=1e9 `
--set output_mode="dFF (motion corrected with fitted ref)"Recommendations are computed first. A JSON parameter file is applied next, then repeatable --set NAME=VALUE arguments take final precedence.
| CLI option | Purpose |
|---|---|
inputs |
One or more files or folders. |
-o, --output-dir |
Destination. Defaults to pyber_processed. |
--sensor |
Sensor ID or exact sensor name. Use unspecified for generic assumptions. |
--channel |
Select one or more channels. Repeat or comma-separate the option. |
--trigger |
Include a DIO/AOUT trigger channel. |
--params-file |
JSON object containing ProcessingParams overrides. |
--set NAME=VALUE |
Override any processing field after recommendations. Repeatable. |
| `--format both | csv |
--no-recursive |
Restrict folder inputs to their top level. |
--verbose |
Include tracebacks for failed recordings. |
Each recording-channel pair can produce:
pyber_processed/
recording__AIN01.csv
recording__AIN01.h5
recording__AIN01.pyber.json
recording__AIN01_preprocessing_report.png
recording__AIN01_preprocessing_report.json
batch_summary.csv
batch_summary.json
flagged_recordings.csv
The flagged table collects processing failures, excessive artifact load, poor finite coverage, flat traces, low corrected SNR, recordings whose apparent activity disappears during reference fitting, high motion coupling, low-confidence recommendations, and sensor/trace warnings. It is a review queue, not a substitute for inspecting the report image.
| Kind | Native support |
|---|---|
| Raw photometry | Doric .doric, including current LockInAOUT02/AIN01 and legacy AIN01xAOUT02-LockIn/Values layouts; compatible .h5 / .hdf5; RWD fluorescence .csv. |
| Behavior | Binary state tables and timestamp/event tables from .csv, .tsv, .xlsx, and .xls, including onsets, offsets, transitions, and continuous variables. |
| Synchronization | Embedded DIO/AOUT, external timestamped signals, and video ROI intensity or barcode pulse trains. |
| Processed data | Self-describing CSV with .pyber.json sidecar and HDF5 with embedded metadata. |
| Reports | Preprocessing PNG, strict QC report images, batch summaries, flagged-recording tables, analysis CSVs, model tables, and publication figure exports. |
Brutally honest limitation: pyBer does not currently read TDT .tev or Neurophotometrics .sev files natively. The previous README claimed it did. Convert those acquisitions to a supported CSV or HDF5 layout first. The packaged v0.56 builds target Windows; source execution on other platforms is not part of the tested release path.
- Combine two or more behaviors/zones into one named OR event using Combine… in PSTH or the Behavior comparison controls.
- Overlapping and touching bouts merge without double counting; original labels, timestamps and missing observations are preserved.
- Combined labels work in Individual and Group analyses, project saves and exports; definitions are recorded for reproducibility.
- Combinations are computed separately per recording. Sources missing a selected component are excluded and reported.
- See release notes and the combined-label guide.
- Multi-animal frame tables ask which animal/arena ID to use before reading the timeline. Two, four, or more IDs are supported.
- Explicit fiber pairing prevents a selected animal from being silently reused for other Group recordings.
- Original times, row order, behavior values and missing observations are preserved; source files are never rewritten.
- Saved projects retain the selected identity. Invalid older embedded timelines produce a clear re-import message instead of an unexpected-error dialog in the comparison panel.
- Existing workbook arena selection, PSTH calculations and heatmap color controls remain available.
- See release notes and the multi-animal import guide.
- Visible heatmap color controls for Zone/Behavior and Individual/Group views: draggable limits, exact minimum/maximum values, palettes and Auto reset.
- Blue–white–red palette for signed signals; full-range, robust and symmetric automatic contrast remain available.
- Saved projects and publication figures retain the selected palette and limits; plot exports omit the interactive color editor.
- PSTH limits no longer carry over to spatial maps. Opening the color editor preserves plot space.
- Display-only adjustments: baseline normalization, event filtering, signal values and statistics are unchanged.
- See release notes and the heatmap color guide.
- Choose Zone or Behavior in the existing postprocessing workspace; Zone retains its original pre/post analysis.
- Automatically detect MAMIR behavior/zone exports and EthoVision arena sheets, with explicit animal-to-fiber pairing.
- Click behaviors to compare before/during/after signal, using individual recordings or equally weighted recording means in Group view.
- Resizable behavior controls, clearer PSTH/heatmap timing, and plot labels kept clear of data.
- Existing generic imports, saved projects, PSTH filtering and baseline normalization remain available. Baselines are not automatically behavior-free.
- Fixed frame-column mapping in the development MAMIR importer and View-menu submenu lifetime on affected Qt versions.
- See release notes and the behavior/zone guide.
- Compact toolbars and resizable shared heatmap/PSTH and behavior panels.
- Automatic whole-second baseline suggestions, selectable behavior and PSTH summaries, and ten global metrics.
- Saved view preferences and embedded behavior restoration; readable wrapped output titles.
- Windows remains a single executable. See the release notes.
-
Windows GUI ships as a single executable. Download and run
pyBer-windows.exe. -
Fixed the Qt rendering error in image/PDF exports and corrected PDF plot sizing.
-
Pykaboo metadata imports automatically detect behavior states, software/camera clocks and trajectory coordinates without renaming columns.
-
Select the behavior clock, retain it in saved projects, and automatically match
_metadata.csvfiles to recordings in batches. -
Spatial maps select paired coordinates and exclude missing detections; generic CSV and Ethovision inputs remain supported.
-
See the release notes and behavior import guide.
- Automatic signal-event previews, adjustable automatic thresholds, shaded noise bands, and improved per-file batch summaries.
- Corrected initial trace fitting and cut-gap display, plus heatmap autoscaling when PSTH normalization changes.
- Direct keyboard value editing and synchronized sliders, with a more compact postprocessing workspace.
- Windows file/folder drops work in detached panels; the original SVG logo has a frameless taskbar variant and explicit Windows shell branding.
- See the full release notes for numerical compatibility and installation details.
- Clean empty workspaces reveal traces and results only when data is available, with consistent vector tool icons and quieter panel headings.
- Redesigned postprocessing plots offer Midnight, Paper, and Sand themes, flexible layouts, and adjustable heatmap contrast.
- Corrected onset/offset export naming, selected-recording exports, repeated-bundle preservation, and CSV/HDF5 coverage.
- Improved event alignment, missing-data handling, normalization, SEM, AUC, and statistical summaries. These corrections can change older results near gaps and boundaries.
- Windows taskbar branding now handles early startup, detached windows, and high-DPI icon sizes more consistently.
- See the full release notes for download instructions and analysis compatibility notes.
- Smart artifact detection now recognizes repeated downward events shared by the 465 and 405 channels. Repeated bilateral dips corroborate one another without globally lowering the threshold, while isolated moderate dips and independent heavy-tailed noise remain suppressed.
- Auto-detected artifact IDs are stable across enable and disable operations. Disabling artifact 45 removes only overlay 45, artifact 46 remains 46, and re-enabling 45 restores its original label and interval.
- Manual artifact overlays use
M1,M2, and subsequent IDs so they cannot collide with automatic artifact numbers. - Artifact checkbox updates preserve the exact preview zoom and time position across the raw, filtered, and output plots.
- Long processing summaries no longer inflate the output plot geometry or destabilize linked x-axis navigation. The complete summary remains available from the plot-title tooltip.
- Added recording-grounded and GUI regression coverage for repeated downward artifacts, stable overlay identity, and linked-range preservation.
- This older release shipped the Windows GUI as a zip archive of a one-folder build (v0.51 restores a single executable): extract it anywhere and run
pyBer\pyBer.exe. The previous single-file executable unpacked its entire runtime on every launch; warm start-to-window time dropped from roughly 36 s to 16 s on the reference machine. - Plot rendering was reworked for speed and quality together: interactive pan/zoom on a 10-minute 120 Hz recording went from about 1-6 frames per second to 18-27, and traces are antialiased instead of pixelated. All long traces draw with thin crisp pens; the decorative glow strokes introduced in v0.46 were removed because they forced Qt's slowest rendering path.
- Smart artifact detection gained a session-corroboration gate: borderline threshold crossings are flagged only when the recording also contains at least one unambiguous strong artifact. Clean recordings with heavy-tailed channel noise no longer accumulate false positive regions, while artifact-laden sessions detect exactly as before.
- Regenerated the documentation screenshots from the current application and extended the artifact regression suite with corroboration-gate coverage.
- Fixed compiled loading paths for supported Doric, CSV, and processed HDF5 inputs.
- Recalibrated QC around the fitted-reference corrected output, including corrected SNR and signal-retention checks that reject shared 405/465 contamination.
- Improved artifact repair with robust median anchors, short-gap merging, and higher-fidelity resampling across repaired spans.
- Fixed the Cut-mode plotting crash triggered by large artifact sets whose label windows contain only NaN samples.
- Refined artifact selection, linked plot navigation, and manual-region history behavior.
- Added a branded startup splash and refreshed the application theme, controls, recommendation cards, plots, and modeling workspace.
- Regenerated the documentation screenshots from the current application and expanded regression coverage for loading, QC, artifact repair, and overlays.
Install Miniforge or Anaconda, then run:
git clone https://github.com/BelloneLab/pyBer.git
cd pyBer
powershell -ExecutionPolicy Bypass -File .\scripts\create_pyber_env.ps1
conda activate pyBer
python .\pyBer\main.pyThe helper creates or updates the pyBer environment, installs R, and installs the CRAN fastFMM package used by trial-level FLMM analysis. To repair only that R dependency:
conda activate pyBer
Rscript .\scripts\install_fastfmm.RIf VS Code selects the wrong Python, run Python: Select Interpreter and choose the environment created from environment.yml.
- GUI and CLI call the same processing implementation in
analysis_core.py. - Exports record the pyBer version, source file, channel, sensor, acquisition metadata, effective parameters, output definition, artifact regions, and QC decision.
- CSV columns use stable names such as
time,time_aligned,raw_465,raw_405,baseline_465,baseline_405, and the selected processed output. - HDF5 files embed the same metadata used by the CSV sidecar.
- Postprocessing projects can be saved as HDF5 and recovered through autosave.
- The exact README demo can be regenerated with:
conda activate pyBer
python .\scripts\generate_readme_screenshots.py `
--doric "C:\path\to\trial_0010.doric" `
--behavior "C:\path\to\trial_0010_with_time.csv"The full user guide covers installation, first launch, preprocessing, sensor selection, artifacts, QC, postprocessing, synchronization, transient detection, temporal modeling, group workflows, exports, and troubleshooting.
Run the test suite from the pinned environment:
conda activate pyBer
python -m unittest discover -s tests -vBuild both Windows executables:
conda activate pyBer
python -m PyInstaller --noconfirm --clean pyBer.spec
python -m PyInstaller --noconfirm --clean pyBer-cli.spec| Path | Responsibility |
|---|---|
pyBer/main.py |
Application entry point, preprocessing shell, and strict QC. |
pyBer/analysis_core.py |
Loaders, recommendations, preprocessing, and export schema. |
pyBer/gui_preprocessing.py |
Interactive preprocessing panels and linked plots. |
pyBer/gui_postprocessing.py |
PSTH, behavior, spatial, event, sync, project, and export workflows. |
pyBer/temporal_modeling.py |
Continuous GLM and trial-level FLMM workbench. |
pyBer/led_extract.py |
Video ROI and barcode signal extraction. |
pyBer/time_sync.py |
Edge detection, pairing, lag, and drift estimation. |
pyBer/cli.py |
Recursive batch preprocessing CLI. |
tests/ |
Unit, integration, GUI, legacy-format, CLI, and export regression tests. |
pyBer sets PYTHONNOUSERSITE=1 so stale packages from the user Python directory cannot shadow the conda environment. This prevents common Windows conflicts between Qt, pyqtgraph, NumPy, and rpy2.
Developed for transparent fiber-photometry analysis at the Bellone Lab.