theatRICS

theatRICS is a Python GUI application for quantitative fluorescence microscopy analysis, integrating multiple workflows into a single interface:

• RICS — Raster Image Correlation Spectroscopy
• SFCS / pSFCS — scanning / perpendicular scanning FCS
• FCS curve fitting
• FRAP analysis
• ICS — temporal Image Correlation Spectroscopy
• Vesicle / GUV detection and membrane analysis
• AFM profile analysis
• Synthetic image simulation

Highlights

• Unified GUI for multiple fluctuation-analysis and microscopy workflows
• Interactive plotting with embedded Matplotlib canvases
• Support for single-file and batch processing
• Background worker processes for all heavy computations keeping the GUI responsive
• Export of numerical outputs and publication-quality SVG figures
• Model-based fitting for correlation curves and recovery experiments
• 20+ FCS models including MEMFCS with Shannon and Shannon-Jaynes entropy
• Spatially resolved diffusion maps from sliding-window RICS fitting
• GUV detection with multiple methods including the improved and modified version of Kohyama et al. 2022 weighted peripheral intensity method
• Membrane straightening and intensity heatmaps for GUV time series
• AFM wetting angle and height measurement with real-time slider feedback
• Bleach correction for SFCS data
• Session saving/loading and central logging inside the GUI
• Dark mode toggle

Main capabilities

RICS

• export correlation maps from image stacks
• compute uncertainty maps
• optional drift correction
• fit diffusion models
• generate diffusion maps

SFCS

• correlate line-scan data
• optional bleach correction
• inspect intensity traces and autocorrelation curves

FCS fitting

• fit exported correlation curves from CSV files
• support for diffusion, blinking, offset, two-component, and calibration models
• recursive batch fitting across subfolders
• model-dependent initial parameter editor

FRAP

• analyze FRAP experiments from CZI files with circular ROI annotations
• automatic bleach-frame and control-ROI detection
• optional imaging bleach correction
• export raw data and summary spreadsheets

ICS

• perform temporal Image Correlation Spectroscopy on TIFF image stacks
• block-wise normalised correlation computation at user-defined temporal lag
• intensity thresholding and pixel masking per block
• per-block diagnostic image export
• normalised correlation traces over time
• batch aggregation across sample subfolders with combined CSV and plot export

AFM

• load JPK QI atomic force microscopy height images
• interactive line-profile drawing by clicking two points on the image
• automatic linear baseline correction from user-clicked membrane heights
• Savitzky-Golay smoothing and contact-point detection
• wetting angle measurement at left and right contact points
• peak height and FWHM measurement
• real-time wetting angle update using the fit-points slider
• export of per-profile arrays, summary CSV, and SVG figure

Vesicle Finder

• detect GUVs in CZI fluorescence or transmitted-light images
• five detection methods:
  • Hough circle transform (fluorescence membrane images)
  • Hough transmitted light (transmitted-light images with gradient preprocessing)
  • Weighted peripheral intensity (Kohyama et al. 2022, works for both image types)
  • Cellpose with shape filtering and circle fitting
  • Otsu threshold fallback
• all spatial parameters in µm with automatic pixel size reading from CZI metadata
• interactive vesicle selection by clicking on the image or listbox
• export square crop time series per vesicle
• membrane straightening: unroll the annular membrane region into a flat strip
• intensity heatmaps (intensity vs angle vs time) for membrane dynamics analysis
• total membrane intensity time traces
• debug image saving for parameter optimization

Image simulation

• simulate isotropic and anisotropic diffusion image stacks
• inspect outputs directly in the GUI
• useful for benchmarking and validation

Getting started in 2 minutes

1. Install

Clone the repository and install in your Python environment:

git clone https://github.com/yusuf-qutbuddin/theatRICS.git
cd theatRICS
pip install -e .

or simply using pip on a virtual environment with Python >=3.10

pip install theatrics

2. Run

Start the GUI with:

theatrics

3. Try a workflow

RICS analysis:

• open RICS Export, load a CZI or TIFF stack, export correlation map
• open RICS Fitting, fit a diffusion model

GUV membrane analysis:

• open Vesicle Finder, select a CZI file
• choose weighted_intensity or hough method
• click Detect Vesicles
• select vesicles by clicking on them
• click Straighten Selected to unroll and analyze the membrane

Installation

Requirements

• Python >= 3.10
• Tkinter-enabled Python installation
• scientific Python stack

Main Python dependencies

• numpy
• scipy
• matplotlib
• pandas
• tifffile
• scikit-image
• lmfit
• multipletau
• statsmodels
• openpyxl
• sv-ttk
• pylibCZIrw

Optional dependencies

Install optional vesicle dependencies:

pip install opencv-python cellpose 

Recommended: install in a virtual environment

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -U pip
pip install -e .

Or with conda:

conda create -n theatrics python=3.11
conda activate theatrics
pip install -e .

GUI overview

The main interface is organized into tabs.

Typical workflows

RICS from microscopy stacks

1. RICS Export → compute correlation map
2. RICS Fitting → fit diffusion model

SFCS correlation

1. SFCS → correlate line-scan data
2. FCS Fitting (optional) → fit exported curves

FRAP

1. FRAP → analyze recovery from annotated CZI files

ICS (temporal correlation)

1. ICS → load TIFF stack, set block length and frame lag
2. Inspect normalised G vs time trace
3. (Batch) process sample subfolders and export combined plot

AFM condensate/particle analysis

1. AFM → load JPK QI image
2. Click two points on the membrane (one on each side of the object)
3. Inspect height profile, wetting angles, and FWHM
4. Adjust fit-points slider to optimise angle calculation
5. Draw additional profiles, then click Save results

GUV membrane analysis

1. Vesicle Finder → detect GUVs
2. Select vesicles interactively
3. Crop → export time series
4. Straighten → unroll membrane and analyze intensity heatmaps

Simulation and validation

1. Image Simulation → generate synthetic stacks
2. RICS Export + RICS Fitting → validate pipeline

Supported FCS fitting models

2D / SFCS-style models

g2diff, g2diffSFCS, g2diffOffset, g2diffBlink, g2diffTwoComponents

3D / extended models

g3diff, g3diffOffset, g3diffBlink, g3diffBlinkOffset, g3diffDoubleBlink, g3diffTwoComponents, g3diffTwoComponentsBlink, g3diffLargeParticles, g3anomalousDiff, g3anomalousDiffBlink, g3lorentzianZ

Calibration models

g3diffCal, g3diffBlinkCal, g3lorentzianZCal

Other models

siFCS, siFCSTwoComponents, g3diffMEMFCS

Vesicle detection methods

Output files

Common output types

• TIFF — correlation maps and image stacks
• CSV — fit summaries and intensity profiles
• NPZ — stored fit arrays
• SVG — publication-quality figures
• XLSX — FRAP spreadsheets
• JSON — saved GUI sessions

Examples

FCS fitting

• Results/<file>_<model>.svg
• Results/<file>_<model>.csv
• Results/<file>_<model>_iMSD.csv
• Results/<model>_fit_summary.csv (batch)

FRAP

• *_FRAP_raw_data.xlsx
• *_FRAP_summary.xlsx
• *_FRAP_overview.svg

ICS

• <stem>_threshold<value>_corr.csv (per-file block statistics)
• <stem>_ICS_overview.svg (per-file overview figure)
• <stem>_b<n>_MIP.tiff, *_mean.tiff, *_mask.tiff, *_corr.tiff (optional block diagnostic images)
• <timestamp>_allSamples_ICS.csv (batch combined CSV)
• <timestamp>_allSamples_ICS.svg (batch combined plot)

AFM

• <stem>_profile<n>.csv (full profile arrays per profile)
• <stem>_AFM_summary.csv (scalar measurements for all profiles)
• <stem>_AFM_overview.svg (combined figure export)

Vesicle Finder (crops)

• <stem>_vesicle_crops/vesicle_1.tif

Vesicle Finder (straightening)

• <stem>_straightened/vesicle_1_straightened.tif
• <stem>_straightened/vesicle_1_intensity_profile.csv
• <stem>_straightened/vesicle_1_total_intensity.csv
• <stem>_straightened/straighten_overview.svg

Vesicle Finder (debug)

• <stem>_debug/01_raw_normalized.tif
• <stem>_debug/04_binary_after_threshold.tif
• <stem>_debug/05_binary_dilated.tif
• <stem>_debug/06_interior.tif
• <stem>_debug/07_distance_interior.tif
• <stem>_debug/08_distance_smooth.tif

Repository structure

theatRICS/
├── src/
│   └── theatrics/
│       ├── __init__.py
│       ├── main.py
│       ├── gui_app.py
│       │
│       ├── workers/
│       │   ├── afm_worker.py
│       │   ├── diffmap_worker.py
│       │   ├── export_worker.py
│       │   ├── fcsfit_worker.py
│       │   ├── fit_worker.py
│       │   ├── frap_worker.py
│       │   ├── ics_worker.py
│       │   ├── sfcs_worker.py
│       │   ├── sim_worker.py
│       │   └── vesicle_worker.py
│       │
│       ├── afm/
│       │   └── analysis.py
│       │
│       ├── fcsfit/
│       │   ├── batch.py
│       │   ├── calculations.py
│       │   ├── memfcs.py
│       │   └── models_and_fit.py
│       │
│       ├── frap/
│       │   └── analysis.py
│       │
│       ├── ics/
│       │   └── analysis.py
│       │
│       ├── modules/
│       │   ├── export_rics.py
│       │   ├── inspect_metadata.py
│       │   ├── rics_fit.py
│       │   ├── simRICS.py
│       │   └── SFCS_module.py
│       │
│       ├── utils/
│       │   ├── bleach_correction.py
│       │   ├── file_utils.py
│       │   └── mp_utils.py
│       │
│       └── vesicle/
│           └── detection.py
│

Development notes

theatRICS uses:

• Tkinter for the GUI
• Matplotlib for embedded plotting
• multiprocessing for long-running tasks
• worker queues for progress reporting and cancellation

The vesicle detection pipeline uses:

• scikit-image for thresholding, morphology, and Hough transforms
• OpenCV (optional) for faster Hough circle detection
• scipy for distance transforms and bilinear interpolation
• Cellpose (optional) for deep learning segmentation
• NumPy vectorization for fast peripheral intensity scoring

Troubleshooting

GUI does not start

• Check Tkinter is installed
• Ensure the correct Python environment is active

ICS produces all NaN G values

• reduce the Threshold multiplier
• check that the TIFF contains temporal intensity variation

ICS batch finds no files

• check the File pattern matches your file extension (.tif vs .tiff)
• ensure sample subfolders exist inside the selected parent folder

AFM file will not load

• install AFMReader: pip install AFMReader
• check the selected channel exists in the file

AFM contact points are placed incorrectly

• adjust the Threshold fraction in the profile parameters
• ensure both click points are on the flat membrane surface, not on the object itself

Vesicle detection finds wrong circles

• Enable Save debug images and inspect the intermediate outputs
• Check 08_distance_smooth.tif to verify one peak per GUV is visible
• Try different threshold methods (mean or triangle recommended)

Only one vesicle detected

• GUV peaks may be merging — check the distance smooth image
• Reduce the search range or adjust the min distance

CZI workflows fail

• Check that pylibCZIrw is installed and importable

Cellpose finds arc instead of full circle

• Enable Fit circles to detected masks

Citation / scientific context

theatRICS integrates several published methods:

• RICS: Raster Image Correlation Spectroscopy for diffusion measurement in cells
• SFCS/pSFCS: Scanning FCS for membrane diffusion
• FRAP: Fluorescence Recovery After Photobleaching (Soumpasis 1983 model)
• Weighted peripheral intensity GUV detection: Kohyama et al., Nature Communications 2022

If you use the software in scientific work, please document:

• software version
• analysis method and model
• microscope parameters
• fitting bounds and initial values

Contributing

Contributions, bug reports, and suggestions are welcome.

When reporting issues, please include:

• operating system
• Python version
• theatRICS version
• traceback or error message
• a description of the input file type
• whether the issue occurs in single-file or batch mode

Author

Yusuf Qutbuddin

Contributors

The majority of the code and functionality is developed by Yusuf Qutbuddin (yusufqq@biochem.mpg.de) and the code and the method is inspired and follows similar algorithms as the PAM software. Some functionalities have been derived from an earlier script by Jan-Hagen Krohn and the FRAP analysis has been contributed by Marco Halbeisen. The export of point FCS curves uses tttrlib and uses some algorithms from FCSFixer. Perplexity.ai, ChatGPT 5.2, and Claude Sonnet 4.6 have been used for debugging, annotation and file parsing algorithms and for searching and implementing tkinter, and for writing documentation and comments in the scripts.

License

See the LICENSE file in this repository.