PULSE

A Fiji/ImageJ plugin for automated circadian rhythm analysis from longitudinal time-lapse recordings of SCN organotypic slices.

Features

• Two pipeline modes: Guided (single interactive session) or Advanced (module-by-module)
• 7-module pipeline: Pre-processing, ROI Definition, Signal Extraction, Rhythm Analysis, Visualization, Export, Cell Tracking
• Incucyte import: Auto-detects Incucyte image sequences (VID_Well_Field_DDdHHhMMm.tif), groups by series, assembles into stacks, and incrementally appends new frames
• Automatic drift analysis: Fast 4x-downsampled phase correlation scan (~2s) classifies drift pattern and recommends registration method
• 9 registration methods: Automatic, Phase Correlation, Phase Correlation + Epoch Detection, Anchor-Patch Tracking, Cross-Correlation, SIFT, Descriptor-Based, Correct 3D Drift, Correct 3D Drift (Manual Landmarks)
• Two-stage crop: Broad crop before registration (loose, speeds up processing) + tight crop after registration (precise, on stabilized image)
• Interactive registration approval: View each registered stack, accept/retry/restart, apply same transforms or method to remaining
• Pre-processing: Alignment rotation, frame binning, background subtraction, bleach/decay correction, spatial and temporal filtering, pre-ROI filter presets, LUT application
• ROI tools: Grid-based ROI generation, dorsal/ventral splitting, automatic boundary detection, individual cells, custom regions
• Rhythm analysis: FFT, autocorrelation, Lomb-Scargle, cosinor fitting (standard/damped), wavelet CWT, JTK_CYCLE, CircaCompare, Rayleigh test
• Detrending: Linear/quadratic/cubic polynomial, Sinc filter (FFT bandpass), EMD, LOESS
• Pre-ROI filter presets: Dropdown with bundled filter macros (e.g., "Extract Green (Incucyte GFP)" — HSB saturation + double paraboloid + median)
• Output LUT: Apply a lookup table (Green, Fire, Cyan Hot, etc.) to corrected stacks before saving (automatically skipped for RGB images)
• Registration checks: Plugin-dependent registration methods (SIFT, Correct 3D Drift, Descriptor-Based) are checked at runtime — unavailable methods show a clear warning
• Consolidated traces: Per-series combined CSVs with all trace types (Raw, dF/F, Isolated, Z-score) side by side
• ROI overlay: Sanity check PNG showing color-coded ROI outlines on mean projection
• Signal isolation: Apply custom ImageJ macro (e.g., HSB channel split) for secondary signal extraction, with optional interactive signal threshold (preview per image, apply uniformly)
• Cell tracking: TrackMate + StarDist AI detection with per-object-per-frame CSV (TrackID, centroid, mean/total intensity, area, perimeter)
• Visualization: Time-series plots, kymographs, spatial maps (phase/period/amplitude), polar plots, scalograms, drift trace plots, summary dashboard
• Export: Excel workbook with all results, consolidated CSVs

Pipeline Modes

Guided Pipeline

Walks through the entire workflow in one session:

1. Settings (reporter type, frame interval, preprocessing params)
2. Image discovery (scan corrected/assembled/raw, show status)
3. Assembly (Incucyte frame assembly with incremental append)
4. Registration (drift analysis → method recommendation → interactive approval)
5. ROI definition (interactive drawing on projections)
6. Signal extraction (per-ROI traces + optional whole-image trace)
7. Signal isolation (optional user macro for secondary extraction + signal threshold)
8. Trace consolidation (combined per-series CSVs)
9. Cell tracking (optional TrackMate + StarDist)

Advanced (Module-by-Module)

Select individual modules to run independently — useful for re-running specific analysis steps.

Supported Reporter Types

Reporter	Example	Bleach Correction
Bioluminescence	PER2::LUC	Sliding percentile
Fluorescent	CRY1-GFP, HIBA1-GFP, TMEM-EFYP	Bi-exponential
Calcium	jRCaMP, GCaMP	Bi-exponential

Installation

1. Build: bash mvnw clean package -Denforcer.skip=true
2. Copy target/PULSE-0.5.0.jar to your Fiji plugins/ folder
3. Restart Fiji
4. Run: Plugins > PULSE > PULSE

Optional: Cell Tracking

For cell tracking support, enable these Fiji update sites:

• TrackMate
• StarDist
• CSBDeep

Usage

1. Select the experiment folder containing TIF stacks (or Incucyte individual frames)
2. Choose Guided Pipeline or Advanced (Module-by-Module)
3. Configure parameters and follow interactive prompts
4. Results are saved to .circadian/ within the experiment folder

Session Directory Structure

experiment_folder/
  *.tif                              (input stacks)
  .circadian/
    config.txt                       (persisted parameters)
    alignment_angles.txt             (per-file rotation angles)
    crop_regions.txt                 (per-file broad crop rectangles)
    tight_crop_regions.txt           (per-file tight crop rectangles)
    frame_intervals.txt              (per-file frame intervals)
    assembled/                       (Incucyte assembled stacks)
    corrected/                       (pre-processed stacks)
      registration_transforms_*.csv  (cached registration shifts)
      drift_analysis_*.csv           (drift pattern classification)
      drift_trace_*.csv              (per-frame shift trace)
    projections/                     (mean/max projections + ROI overlay PNGs)
    ROIs/                            (ROI ZIP files)
    traces/                          (consolidated + individual trace CSVs)
    rhythm/                          (FFT, autocorrelation, cosinor, wavelet results)
    visualizations/                  (plots, maps, drift traces, dashboard)
    exports/                         (Excel workbook, consolidated CSVs)
    tracking/                        (per-object-per-frame tracking CSVs)

Requirements

• Fiji (ImageJ distribution) with bundled plugins
• Java 8+
• Dependencies (provided by Fiji): ImageJ 1.x, Commons Math 3, Apache POI
• Optional: TrackMate 7.14.0 + StarDist 1.2.1 (for cell tracking)

Citing PULSE

If you use PULSE in published work, please cite it. Citation metadata is in CITATION.cff (use GitHub's "Cite this repository" button). A Zenodo DOI will be added here once the first tagged release is archived.

When you use specific features through PULSE, please also cite the underlying methods:

• TrackMate (Tinevez et al., Methods, 2017, doi:10.1016/j.ymeth.2016.09.016) for cell tracking
• StarDist (Schmidt et al., MICCAI 2018; Weigert et al., WACV 2020) for star-convex segmentation
• The specific rhythm-analysis methods used (cosinor, Lomb-Scargle, JTK_CYCLE, CircaCompare etc.) per the original references

License

BSD 3-Clause License. See LICENSE for the full text.

Acknowledgements

Developed by Jamie Malcolm in the Brancaccio Lab at the UK Dementia Research Institute, Imperial College London.

This work was supported by the UK Dementia Research Institute, which receives its core funding from the UK Medical Research Council, the Alzheimer's Society, and Alzheimer's Research UK.

Built on the Fiji / ImageJ ecosystem; we thank the SciJava community for the platform.