Metadata-Version: 2.4
Name: theatrics
Version: 1.6.1
Summary: GUI for RICS, SFCS, FCS Fitting, FRAP, and vesicle analysis
Author-email: Yusuf Qutbuddin <yusuf.qutbuddin@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Yusuf Qutbuddin
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: tifffile
Requires-Dist: tqdm
Requires-Dist: multipletau
Requires-Dist: sv-ttk
Requires-Dist: pylibCZIrw
Requires-Dist: scikit-image
Requires-Dist: lmfit
Requires-Dist: statsmodels
Requires-Dist: openpyxl
Requires-Dist: path
Provides-Extra: opencv
Requires-Dist: opencv-python; extra == "opencv"
Provides-Extra: cellpose
Requires-Dist: cellpose; extra == "cellpose"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Dynamic: license-file

# theatRICS

[![Documentation Status](https://readthedocs.org/projects/theatrics/badge/?version=latest)](https://theatrics.readthedocs.io/en/latest/?badge=latest)

**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 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:

```bash
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

```bash
pip install theatrics
```

### 2. Run
Start the GUI with:

```bash
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:

```bash
pip install opencv-python cellpose 
```

### Recommended: install in a virtual environment

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

Or with conda:

```bash
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

```text
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 (yusufqq@biochem.mpg.de) and the code and the method is inspired and follows similar algorithms as the [PAM](https://gitlab.com/PAM-PIE/PAM.git) 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.
