theatrics 1.3.4

GUI for RICS, SFCS, FCS Fitting, FRAP 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
• synthetic image simulation

It is designed for practical microscopy data analysis with embedded plotting, batch processing, exportable figures, and structured numerical outputs.

---

Highlights

• Unified GUI for multiple fluctuation-analysis 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
• 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

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 (preferably in a virtual environment with Python>=3.10)

pip install theatrics 

2. Run

Start the GUI with:

theatrics

3. Try a workflow

A simple first test:

• open Image Simulation
• generate a short synthetic image stack
• open RICS Export
• export a correlation map
• open RICS Fitting
• fit the diffusion model

---

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

Recommended: install in a virtual environment

Using venv

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

On Windows:

python -m venv .venv
.venv\Scripts\activate
pip install -U pip
pip install -e .

Using conda

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

or after cloning

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

---

GUI overview

The main interface is organized into tabs.

Image Simulation

Generate synthetic image stacks with user-defined diffusion and imaging parameters.

RICS Export

Compute correlation maps and uncertainty maps from TIFF or CZI image stacks.

RICS Fitting

Fit RICS maps using diffusion models and inspect residuals and diffusion-map outputs.

SFCS

Perform scanning FCS correlation analysis on suitable line-scan data.

FCS Fitting

Fit precomputed correlation curves from CSV files using a range of diffusion and blinking models.

FRAP

Analyze photobleaching recovery data from annotated CZI files.

Results & Logs

Inspect task progress, warnings, saved outputs, and session information.

---

Typical workflows

Workflow 1 — RICS from microscopy stacks

1. Open RICS Export
2. Load a TIFF or CZI stack
3. Export the correlation map
4. Open RICS Fitting
5. Fit the selected diffusion model

Workflow 2 — SFCS correlation

1. Open SFCS
2. Load a scanning dataset
3. Run correlation
4. Inspect the autocorrelation curve

Workflow 3 — FCS curve fitting

1. Open FCS Fitting
2. Select a single CSV or batch folder
3. Choose a model
4. Adjust model-dependent initial parameters
5. Run the fit

Workflow 4 — FRAP

1. Open FRAP
2. Load a single CZI file or batch folder
3. Run analysis
4. Inspect mobile fraction, diffusion, and half-time outputs

Workflow 5 — Simulation for validation

1. Open Image Simulation
2. Define image and particle parameters
3. Run and inspect the synthetic output

---

Supported FCS fitting model families

The exact set of models available in the GUI may include:

2D / SFCS-style models

• g2diff: 2D diffusion single component
• g2diffSFCS: 2D diffusion single component in XZ
• g2diffOffset: 2D diffusion single component with an offset
• g2diffBlink: 2D diffusion single component with blinking
• g2diffTwoComponents: 2D diffusion two components

3D / extended models

• g3diff: 3D diffusion single component
• g3diffOffset: 3D diffusion single component with an offset
• g3diffBlink: 3D diffusion single component with blinking
• g3diffBlinkOffset: 3D diffusion single component with blinking and an offset
• g3diffDoubleBlink: 3D diffusion single components with double blinking
• g3diffTwoComponents: 3D diffusion two components
• g3diffTwoComponentsBlink: 3D diffusion two components with blinking
• g3lorentzianZ: 3D diffusion single component with gaussian-lorentzian PSF
• g3anomalousDiff: 3D anomalous diffusion single component
• g3anomalousDiffBlink: 3D anomalous diffusion single component with blinking
• g3diffLargeParticles: 3D diffusion single component of large particles with a known size

Calibration models

• g3diffCal: 3D diffusion single component calibration
• g3diffBlinkCal: 3D diffusion single component calibration with blinking
• g3lorentzianZCal: 3D diffusion single component calibration for gaussian-lorentzian PSF

Other models

• siFCS: siFCS model for single component diffusion
• siFCSTwoComponents: siFCS model for two component diffusion
• g3diffMEMFCS: 3D diffusion model with Maximum Entropy Method

---

Output files

theatRICS writes both numerical and figure outputs.

Common output types

• TIFF — correlation maps
• CSV — summaries and fitted curves
• NPZ — stored fit arrays
• SVG — publication-quality figures
• XLSX — FRAP spreadsheets
• JSON — saved GUI sessions
• TXT — exported logs

Examples

FCS fitting

Per file:

• Results/<file>_<model>.svg
• Results/<file>_<model>.csv
• Results/<file>_<model>_iMSD.csv

Batch mode:

• Results/<model>_fit_summary.csv

FRAP

Per file:

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

RICS

Typical outputs:

• *_RICScorr.tif
• *_RICSunc.tif

---

Screenshots

RICS Export Tab

RICS Fitting Tab

---

Project structure

A typical layout is:

src/
  theatrics/
    main.py
    gui_app.py
    workers/
    fcsfit/
    frap/
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

This keeps computational workflows separated from the GUI while still allowing interactive progress monitoring.

---

Troubleshooting

GUI does not start

Check:

• Tkinter is installed
• the correct Python environment is active
• all required packages are installed

CZI workflows fail

Make sure:

• pylibCZIrw is installed and importable
• the CZI file contains valid metadata

FCS batch mode finds no files

Check the file pattern, for example:

*_xy_intensity_trace_correlation.csv

FRAP fails because of missing ROIs

The FRAP workflow requires circular ROI annotations in the CZI metadata.

Batch processing feels slow or unresponsive

Large batches can reduce GUI responsiveness if figures are redrawn too often. A common strategy is to update progress continuously and update the full display only for the latest or final file.

---

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.