Ca²⁺ Signature Analyzer

A Python toolkit for analyzing plant calcium signaling dynamics using information theory and biophysical modeling.

Features

Signature Database Management: Store, load, and analyze Ca²⁺ signatures
Biophysical Modeling: ODE-based simulation of Ca²⁺ dynamics with multiple stimuli
Decoder Analysis: Model CDPK and other Ca²⁺ decoder responses
Information Theory: Calculate mutual information, channel capacity, and discriminability
Comprehensive Visualization: UMAP projections, heatmaps, signature comparisons
Dual Interface: Both GUI and command-line scripts available

Installation

Requirements

Python 3.7 or higher
pip package manager

Setup

Clone or download this repository
Navigate to the project directory:

cd ca_signature_analyzer

Install dependencies:

pip install -r requirements.txt

Dependencies

numpy >= 1.20.0
scipy >= 1.7.0
pandas >= 1.3.0
matplotlib >= 3.4.0
seaborn >= 0.11.0
scikit-learn >= 0.24.0
umap-learn >= 0.5.0

Usage

GUI Application

Launch the graphical interface:

python src/gui_app.py

The GUI provides five main tabs:

Database: Load, view, and manage signature databases
Simulate Signatures: Run biophysical model simulations
Decoder Analysis: Analyze CDPK responses to signatures
Information Theory: Calculate MI and classification accuracy
Visualizations: Generate UMAP, heatmaps, and reports

Command-Line Scripts

Run a Simulation

python run_simulation.py --stimulus ABA --duration 600 --output outputs/simulation.csv

Options:

--stimulus: Stimulus type (ABA, NaCl, mechanical_touch, flg22, cold_shock, H2O2, glutamate)
--duration: Simulation duration in seconds (default: 600)
--intensity: Stimulus intensity (default: 1.0)
--output: Output CSV file path
--plot: Output plot file path

Analyze a Database

python analyze_database.py --input data/signatures.csv --output outputs/analysis

Options:

--input: Input CSV file (if not provided, uses example database)
--output: Output directory for results

This performs:

Database statistics
Signature simulation
Decoder analysis
Information theory calculations
UMAP projection
Classification testing
Information flow analysis

Python API

You can also use the modules directly in Python:

from src.signature_database import SignatureDatabase, create_example_database
from src.biophysical_model import CalciumDynamicsModel
from src.decoder_model import DecoderPanel
from src.information_theory import InformationAnalyzer

# Load example database
db = create_example_database()
print(f"Loaded {len(db)} signatures")

# Run simulation
model = CalciumDynamicsModel()
t, sol = model.simulate('ABA', duration=600)
ca_cyt = sol[:, 0]

# Analyze with decoders
panel = DecoderPanel()
responses = panel.analyze_signature(t, ca_cyt)

# Calculate mutual information
features = db.get_feature_matrix()
labels = [sig.stimulus for sig in db.signatures]
# ... continue analysis

Project Structure

ca_signature_analyzer/
├── src/                          # Source code modules
│   ├── __init__.py
│   ├── signature_database.py    # Signature data management
│   ├── biophysical_model.py     # ODE-based Ca²⁺ dynamics
│   ├── decoder_model.py         # CDPK decoder models
│   ├── information_theory.py    # MI and information metrics
│   ├── visualization.py         # Plotting functions
│   ├── utils.py                 # Helper utilities
│   └── gui_app.py              # Main GUI application
├── data/                        # Data directory
│   └── example_signatures.csv   # Example database
├── outputs/                     # Output directory
├── examples/                    # Example scripts
├── docs/                        # Documentation
├── tests/                       # Unit tests
├── run_simulation.py           # Standalone simulation script
├── analyze_database.py         # Standalone analysis script
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Core Modules

signature_database.py

Manages Ca²⁺ signature data:

CalciumSignature: Data class for individual signatures
SignatureDatabase: Database management
create_example_database(): Generate example data

biophysical_model.py

ODE-based Ca²⁺ dynamics simulation:

CalciumDynamicsModel: Main simulation class
ModelParameters: Model parameters
Supports 7 stimulus types with distinct signatures

decoder_model.py

CDPK decoder activation models:

CDPKDecoder: Single decoder model
DecoderPanel: Panel of 10 CDPKs with different affinities
PhosphorylationTarget: Target protein phosphorylation

information_theory.py

Information-theoretic analyses:

InformationAnalyzer: MI and entropy calculations
PathwayInformationFlow: Multi-stage information flow
SignatureDiscriminability: Classification and discrimination

visualization.py

Plotting and visualization:

SignaturePlotter: Signature plots, heatmaps, UMAP
IntegratedReport: HTML report generation

Example Workflows

Workflow 1: Basic Simulation and Analysis

from src.biophysical_model import CalciumDynamicsModel
from src.decoder_model import DecoderPanel
import matplotlib.pyplot as plt

# Create model
model = CalciumDynamicsModel()

# Simulate ABA response
t, sol = model.simulate('ABA', duration=600, intensity=1.0)
ca_cyt = sol[:, 0]

# Extract features
features = model.extract_signature_features(t, ca_cyt)
print("Signature features:", features)

# Analyze with decoders
panel = DecoderPanel()
responses = panel.analyze_signature(t, ca_cyt)

# Plot
plt.plot(t, ca_cyt / 1000)  # Convert to μM
plt.xlabel('Time (s)')
plt.ylabel('[Ca²⁺] (μM)')
plt.title('ABA-induced Ca²⁺ Signature')
plt.show()

Workflow 2: Database Analysis

from src.signature_database import create_example_database
from src.information_theory import SignatureDiscriminability
import numpy as np

# Load database
db = create_example_database()

# Get features
features = db.get_feature_matrix()
labels = np.array([sig.stimulus for sig in db.signatures])

# Test classification
results = SignatureDiscriminability.classification_accuracy(
    features, labels, classifier='random_forest'
)

print(f"Classification accuracy: {results['accuracy_mean']:.3f}")
print(f"Information transmitted: {results['information_bits']:.3f} bits")

Workflow 3: Custom Signature Addition

from src.signature_database import SignatureDatabase, CalciumSignature

# Create database
db = SignatureDatabase()

# Add custom signature
custom_sig = CalciumSignature(
    signature_id="CUSTOM_001",
    species="Arabidopsis thaliana",
    cell_type="mesophyll",
    stimulus="my_stimulus",
    baseline_ca=100,
    peak_amplitude=1200,
    rise_time=10,
    decay_tau=50,
    duration=200,
    oscillatory=False
)

db.add_signature(custom_sig)

# Save to file
db.save_to_csv("my_signatures.csv")

Output Files

The analyzer generates various output files in the outputs/ directory:

CSV files: Simulation time series data
PNG files: Plots and visualizations
- signature_comparison.png: Multi-signature overlay
- decoder_heatmap.png: CDPK response heatmap
- umap_projection.png: Feature space visualization
- confusion_matrix.png: Classification results
- information_flow.png: Information flow diagram
JSON files: Analysis results and statistics
HTML files: Comprehensive reports

Testing

Run unit tests (when available):

python -m pytest tests/

Run module self-tests:

python src/signature_database.py
python src/biophysical_model.py
python src/decoder_model.py
python src/information_theory.py
python src/visualization.py
python src/utils.py

Advanced Configuration

Custom Model Parameters

Modify biophysical model parameters:

from src.biophysical_model import CalciumDynamicsModel, ModelParameters

# Create custom parameters
params = ModelParameters(
    V_PM_GLR=100.0,  # Increase channel activity
    K_pump=150.0,    # Change pump affinity
    # ... other parameters
)

# Use custom model
model = CalciumDynamicsModel(params)
t, sol = model.simulate('ABA', duration=600)

Custom CDPK Parameters

Add custom CDPK decoders:

from src.decoder_model import CDPKParameters, DecoderPanel, CDPKDecoder

# Define custom CDPK
custom_cdpk = CDPKParameters(
    name="CUSTOM_CPK",
    K_d=500.0,      # 500 nM affinity
    n_Hill=3.0,     # Cooperativity
    k_on=1e8,
    k_off=50.0,
    k_cat=12.0
)

# Create decoder
decoder = CDPKDecoder(custom_cdpk)

# Or add to panel
panel = DecoderPanel([custom_cdpk])

Troubleshooting

Common Issues

Import errors: Ensure all dependencies are installed

pip install -r requirements.txt

GUI doesn't launch: Check that tkinter is installed (usually comes with Python)

python -m tkinter  # Should open a test window

UMAP errors: Install umap-learn

pip install umap-learn

Plotting errors: Ensure matplotlib backend is properly configured

import matplotlib
matplotlib.use('TkAgg')  # Or 'Qt5Agg'

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Contact

For questions, issues, or suggestions, please open an issue on GitHub.

Acknowledgments

This project was developed as part of research on plant calcium signaling and information theory analysis.

Version History

v1.0.0 (2025): Initial release
- Core modules implemented
- GUI application
- Standalone scripts
- Example database
- Comprehensive documentation

Built with AI assistance from Claude (Anthropic).

Name		Name	Last commit message	Last commit date
data		data
docs		docs
outputs		outputs
src		src
tests		tests
.DS_Store		.DS_Store
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
INTERFACE.md		INTERFACE.md
README.md		README.md
ROADMAP.md		ROADMAP.md
analyze_database.py		analyze_database.py
launch_gui.py		launch_gui.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run_simulation.py		run_simulation.py

Latest commit

History

Folders and files

Repository files navigation