theatrics 1.7.2

GUI for RICS, SFCS, FCS Fitting, FRAP, and vesicle analysis

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
• Vesicle / GUV detection and membrane 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
• Export of numerical outputs and publication-quality SVG figures
• Model-based fitting for correlation curves and recovery experiments
• 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
• Session saving/loading and central logging inside the GUI

---

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

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

Package	Purpose
opencv-python	Faster Hough circle detection in Vesicle Finder
cellpose	Deep learning vesicle segmentation

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.

Tab	Purpose
Image Simulation	Generate synthetic image stacks
RICS Export	Compute RICS correlation maps from image stacks
RICS Fitting	Fit diffusion models to RICS maps
SFCS	Compute scanning FCS autocorrelation curves
FCS Fitting	Fit precomputed FCS correlation CSVs
FRAP	Analyze FRAP recovery from CZI files
Vesicle Finder	Detect GUVs, export crops, straighten membranes
Results & Logs	Log output, session management

---

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

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

Method	Image type	Speed	Notes
hough	Fluorescence membrane	Fast (OpenCV)	Best for bright ring, dark interior
hough_transmitted	Transmitted light	Fast	Gradient preprocessing
weighted_intensity	Both	Medium	Most robust, improved and modified from Kohyama et al. 2022
cellpose	Fluorescence	Slow (CPU) / Fast (GPU)	Deep learning, requires installation
otsu	High contrast	Very fast	Simple fallback

---

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

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

src/
  theatrics/
    main.py
    gui_app.py
    workers/
      vesicle_worker.py
      frap_worker.py
      fcsfit_worker.py
      ...
    vesicle/
      __init__.py
      detection.py
    fcsfit/
      __init__.py
      calculations.py
      models_and_fit.py
      batch.py
    frap/
      __init__.py
      analysis.py
docs/
pyproject.toml
.readthedocs.yaml

---

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

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 ([e-mail]) 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. Perplexity.ai and ChatGPT 5.2 has been used for debugging, annotation and file parsing algorithms and for searching and implementing tkinter.

---

License

See the LICENSE file in this repository.