v0.1.0

🚀 v0.1.0 - Initial Release of tissue_simulator

We're thrilled to announce the inaugural release of tissue_simulator, a comprehensive Python package designed to generate simulated/synthetic tissue sections. This tool is specifically crafted for testing computational algorithms, especially for initializing spatially-aware simulation methods, ensuring robust research studies are not under-powered.

---

✨ Key Features & Highlights of v0.1.0

This initial release establishes the core functionalities of the tissue_simulator package, enabling robust simulation and analysis of tissue structures:

• 3D Tissue Generation: Create realistic 3D biological tissue sections populated with cells using efficient random sphere packing algorithms, complete with collision detection.
• Flexible Cell Configuration: Define single or multiple cell types with customizable size ranges, allowing for the simulation of diverse and biologically plausible tissue compositions.
• 2D Slicing & Analysis: Extract planar sections from the generated 3D tissue at any arbitrary angle, enabling detailed 2D analysis for histological comparisons or algorithm testing.
• Interactive GUI: A user-friendly PyQt5 interface for real-time 3D visualization, intuitive parameter control, and quick experimentation.
• Statistical Analysis & Data Export: Automatically calculate critical metrics like packing fractions and cell distributions, and export comprehensive cell data to CSV for further analysis and integration with other tools.
• LLM Integration (MCP Ready): The API is designed to be accessible via the Model Context Protocol (MCP), facilitating seamless integration with agentic AI workflows and large language models for powerful, natural language-driven simulations.

📦 Installation

Get started quickly with tissue_simulator:

Quick Install

cd tissue_simulator
pip install -e .

Manual Installation

# Install dependencies
pip install -r requirements.txt

# Install package
pip install -e .

Verify Installation

python verify_installation.py

🚀 Quick Start & Usage

Explore the capabilities of tissue_simulator through its interactive GUI or Python API.

Using the GUI

Launch the interactive interface:

python -m tissue_simulator.gui

Or, if installed as an executable:

tissue-simulator

Python API - Basic Tissue Generation

from tissue_simulator import TissueSection

# Create tissue with uniform cell sizes
tissue = TissueSection(
    height=500,      # μm (Y-axis)
    width=500,       # μm (X-axis)
    thickness=100,   # μm (Z-axis)
    cell_radii=(5, 15)  # min and max radius in μm
)

# Generate cells
num_cells = tissue.generate_cells(max_attempts=1000)
print(f"Generated {num_cells} cells")

# Visualize in 3D
tissue.visualize()

# Export data
tissue.export_to_csv('tissue_data.csv')

Python API - Multiple Cell Types & Slicing

from tissue_simulator import TissueSection, TissueSlicer

tissue = TissueSection(
    height=500,
    width=500,
    thickness=100,
    cell_radii={
        'epithelial': (6, 10),   # Epithelial cells
        'stromal': (8, 15),      # Stromal cells
        'immune': (3, 6),        # Immune cells
        'endothelial': (5, 8)    # Endothelial cells
    }
)

tissue.generate_cells(max_attempts=2000)
tissue.visualize()

# Extract a 2D slice
slicer = TissueSlicer(tissue)
slicer.slice_plane(z_position=50)  # Horizontal slice at z=50
slicer.visualize_slice_2d()        # View 2D cross-section
slicer.export_slice_csv('slice_data.csv')  # Export slice data

For more examples and detailed usage scenarios, please refer to the examples/ directory in the repository and the Comprehensive Guide.

⚠️ Known Issues & Limitations

The current implementation uses stochastic cell type assignment, which may limit precise, deterministic control over the exact spatial distribution of specific cell types in certain scenarios.

🔮 Future Plans

We're continuously working to enhance tissue_simulator and expand its capabilities. Upcoming developments include:

• Further refining the API's integration with Model Context Protocol (MCP) servers to fully leverage agentic AI workflows and advanced LLM-driven simulations.
• Support for non-spherical cell shapes (e.g., ellipsoids, cylinders).
• Implementation of tissue layering with distinct cell compositions.
• Integration of physical force models for more dynamic cell interactions.
• Development of time-dependent growth and simulation dynamics.

📚 Documentation & Support

• Quick Start Guide: Get up and running in minutes.
• Comprehensive Guide: Detailed documentation with examples.
• API Reference: Complete function and class documentation.
• MCP Quick Start: Get started with LLM integration.
  For issues, questions, or contributions, please visit the project repository and file an issue.

---

Made with ❤️ for the computational biology community