feature: refactor the tme_analysis folder and prototype the core functions

The tme_analysis module provides comprehensive analysis of tumor microenvironment (TME) interactions, with a primary focus on Tumor-Associated Collagen Signatures (TACS) classification for cancer prognosis.

Module purpose: Analyze spatial interactions between cells, collagen fibers, and tumor boundaries to:
Classify TACS-1/2/3 patterns (primary use case)
Compute prognostic scores for clinical outcomes
Quantify cell-fiber interactions
Measure TME spatial organization

Design Principles:
Modular: Each component has clear responsibilities
Extensible: Easy to add new detection methods
Reusable: Integrates with existing cell/fiber modules
Separation of Concerns: Detection → Measurement → Analysis

Main module structure/functions:
tme_analysis/
├── config/
│   └── analysis_params.py          # Configuration & data models
├── core/
│   ├── interaction_detector.py     # 6 interaction detection methods
│   ├── region_manager.py           # Tumor detection & ROI management
│   ├── measurement_engine.py       # Feature computation
│   └── tme_analyzer.py             # Main coordinator
├── measurements/
│   ├── tacs_features.py            # TACS-specific features
│   └── spatial_features.py         # Spatial relationships
├── io/
│   └── exporters.py                # CSV, Excel, JSON export
└── utils/
    └── distance_utils.py           # Spatial utilities

Author: yuminguw

src/tme_quant/src/examples/Cell_based_fiber_interaction_analysis.py

@@ -0,0 +1,54 @@
+"""
+Example 1: Cell-based fiber interaction analysis
+"""
+
+from tme_quant.tme_analysis import TMEAnalyzer
+from tme_quant.tme_analysis.config import (
+    TMEAnalysisParams,
+    AnalysisMode,
+    InteractionStrategy
+)
+from tme_quant.cell_analysis import CellAnalyzer
+from tme_quant.fiber_analysis import FiberAnalyzer
+
+# Segment cells
+cell_analyzer = CellAnalyzer()
+cell_result = cell_analyzer.segment_cells_2d(cell_image, cell_seg_params)
+cells = [
+    create_cell_object_from_segmentation(c, parent_id="region_1")
+    for c in cell_result.cells
+]
+
+# Extract fibers
+fiber_analyzer = FiberAnalyzer()
+fiber_result = fiber_analyzer.extract_fibers_2d(fiber_image, fiber_extract_params)
+fibers = [
+    create_fiber_object_from_extraction(f, parent_id="region_1")
+    for f in fiber_result.fibers
+]
+
+# Configure cell-based analysis
+params = TMEAnalysisParams(
+    mode=AnalysisMode.CELL_BASED,
+    interaction_strategy=InteractionStrategy.RADIUS,
+    cell_fiber_distance=50.0,  # 50 micron radius around each cell
+    compute_morphology=True,
+    compute_spatial=True,
+    compute_orientation=True
+)
+
+# Run analysis
+tme_analyzer = TMEAnalyzer(verbose=True)
+result = tme_analyzer.analyze(
+    cells=cells,
+    fibers=fibers,
+    params=params,
+    analysis_id="cell_based_001"
+)
+
+# Access results
+print(f"Found {len(result.interaction_pairs)} cell-fiber interactions")
+print(f"Mean distance: {result.spatial_features['mean_interaction_distance']:.2f} µm")
+
+# Export
+tme_analyzer.export_results("output/cell_based/", formats=["csv", "json"])

src/tme_quant/src/examples/fiber_based_cell_guidance_analysis.py

@@ -0,0 +1,26 @@
+"""
+Example 3: Fiber-based cell guidance analysis
+"""
+
+params = TMEAnalysisParams(
+    mode=AnalysisMode.FIBER_BASED,
+    interaction_strategy=InteractionStrategy.NEAREST,  # Find nearest cell
+    cell_fiber_distance=50.0,
+    compute_orientation=True,
+    compute_spatial=True
+)
+
+result = tme_analyzer.analyze(
+    cells=cells,
+    fibers=fibers,
+    params=params,
+    analysis_id="fiber_guidance_001"
+)
+
+# Analyze fiber alignment
+orientation = result.orientation_features
+
+print(f"Fiber-cell alignment:")
+print(f"  Parallel: {orientation['parallel_ratio']:.1%}")
+print(f"  Perpendicular: {orientation['perpendicular_ratio']:.1%}")
+print(f"  Coherence: {orientation['orientation_coherence']:.3f}")

src/tme_quant/src/examples/integration_of_tmeq_modules.py

@@ -0,0 +1,32 @@
+"""
+Example 4: Analysis within custom user-defined ROIs
+"""
+
+from shapely.geometry import box
+
+# Define custom ROI (e.g., manually annotated region)
+custom_roi = box(100, 100, 500, 500)  # Bounding box
+
+custom_rois = [
+    ROI.from_shapely(custom_roi, roi_id="invasive_front")
+]
+
+params = TMEAnalysisParams(
+    mode=AnalysisMode.ROI_BASED,
+    interaction_distance=50.0,
+    compute_tacs=False,  # Not tumor-based
+    compute_morphology=True,
+    compute_density=True
+)
+
+result = tme_analyzer.analyze(
+    cells=cells,
+    fibers=fibers,
+    custom_rois=custom_rois,
+    params=params,
+    analysis_id="roi_custom_001"
+)
+
+print(f"ROI Analysis:")
+print(f"  Cell density: {result.density_features['cell_density']:.2f} cells/mm²")
+print(f"  Fiber density: {result.density_features['fiber_density']:.2f} fibers/mm²")

src/tme_quant/src/examples/roi_based_tme_analysis.py

@@ -0,0 +1,156 @@
+"""
+Example 2: Tumor-based TACS analysis - Complete workflow
+"""
+
+from tme_quant.core.project import TMEProject
+from tme_quant.tme_analysis import TMEAnalyzer
+from tme_quant.tme_analysis.config import (
+    TMEAnalysisParams,
+    TumorDetectionParams,
+    AnalysisMode,
+    TumorDetectionMethod
+)
+
+# Create project
+project = TMEProject(name="TACS_Study")
+
+# Add image
+project.add_image(
+    image_id="patient_001",
+    image_path="data/patient_001.tif",
+    channels={'nuclei': 0, 'collagen': 1},
+    pixel_size=(0.5, 0.5)
+)
+
+# Segment cells (using project integration)
+from tme_quant.cell_analysis import CellAnalyzer
+cell_analyzer = CellAnalyzer()
+cell_result = cell_analyzer.segment_cells_2d(
+    cell_image, seg_params, image_id="patient_001"
+)
+
+# Add cells to project
+for cell_props in cell_result.cells:
+    cell_obj = create_cell_object_from_segmentation(
+        cell_props, parent_id="patient_001"
+    )
+    project.add_object(cell_obj)
+
+# Get cells from project
+cells = project.get_objects_by_type("cell")
+
+# Detect tumor regions automatically
+tme_analyzer = TMEAnalyzer(verbose=True)
+
+tumor_params = TumorDetectionParams(
+    method=TumorDetectionMethod.CLUSTERING,
+    dbscan_eps=100.0,
+    dbscan_min_samples=10,
+    min_tumor_area=1000.0,
+    smooth_boundary=True
+)
+
+tumor_regions = tme_analyzer.detect_tumor_regions(cells, tumor_params)
+
+print(f"Detected {len(tumor_regions)} tumor regions")
+
+# Add tumor regions to project
+for tumor in tumor_regions:
+    project.add_object(tumor)
+
+# Extract fibers
+fiber_result = project.extract_region_fibers(
+    image_id="patient_001",
+    region_id=tumor_regions[0].object_id,
+    params=fiber_extract_params
+)
+
+fibers = project.get_fibers_in_region(tumor_regions[0].object_id)
+
+# Configure TACS analysis
+tacs_params = TMEAnalysisParams(
+    mode=AnalysisMode.TUMOR_BASED,
+    tumor_boundary_distance=100.0,  # 100 µm boundary zone
+    compute_tacs=True,
+    compute_morphology=True,
+    compute_spatial=True,
+    compute_prognostic=True,
+    generate_zones=True,
+    invasive_margin_width=50.0,
+    stroma_width=200.0
+)
+
+# Run TACS analysis
+tacs_result = tme_analyzer.analyze(
+    cells=cells,
+    fibers=fibers,
+    tumor_regions=tumor_regions,
+    params=tacs_params,
+    analysis_id="tacs_patient_001"
+)
+
+# Access TACS features
+tacs = tacs_result.tacs_features
+
+print("\n=== TACS Analysis Results ===")
+print(f"Total boundary fibers: {tacs['total_boundary_fibers']}")
+print(f"TACS-1 (Random): {tacs['tacs1_ratio']:.1%} ({tacs['tacs1_count']})")
+print(f"TACS-2 (Parallel): {tacs['tacs2_ratio']:.1%} ({tacs['tacs2_count']})")
+print(f"TACS-3 (Perpendicular): {tacs['tacs3_ratio']:.1%} ({tacs['tacs3_count']})")
+print(f"Dominant TACS: {tacs['dominant_tacs_type']}")
+
+# Access prognostic scores
+prog = tacs_result.prognostic_scores
+
+print("\n=== Prognostic Scores ===")
+print(f"Collagen Prognostic Score: {prog['collagen_prognostic_score']:.3f}")
+print(f"TACS-3 Prognostic: {prog['tacs3_prognostic']:.3f}")
+print(f"TME Interaction Score: {prog['tme_interaction_score']:.3f}")
+print(f"Invasive Potential: {prog['invasive_potential_score']:.3f}")
+print(f"Overall TME Risk: {prog['overall_tme_risk_score']:.3f}")
+
+# Export results
+tme_analyzer.export_results(
+    output_dir="output/tacs_analysis/",
+    formats=["csv", "excel", "json"]
+)
+
+# Visualize in Napari
+import napari
+
+viewer = napari.Viewer()
+
+# Add collagen image
+viewer.add_image(collagen_image, name='Collagen', colormap='gray')
+
+# Add tumor boundary
+tumor_mask = tumor_regions[0].roi.get_mask(collagen_image.shape)
+viewer.add_labels(tumor_mask, name='Tumor Boundary')
+
+# Add TACS-classified fibers
+tacs_colors = {
+    'TACS-1': 'blue',
+    'TACS-2': 'green',
+    'TACS-3': 'red',
+}
+
+fiber_shapes = []
+fiber_colors = []
+
+for pair in tacs_result.interaction_pairs:
+    if pair.target_type == "tumor_boundary":
+        # Get fiber
+        fiber = next(f for f in fibers if f.object_id == pair.source_id)
+        
+        fiber_shapes.append(fiber.centerline)
+        fiber_colors.append(tacs_colors.get(pair.interaction_type, 'gray'))
+
+viewer.add_shapes(
+    fiber_shapes,
+    shape_type='path',
+    edge_color=fiber_colors,
+    edge_width=2,
+    name='TACS Fibers'
+)
+
+napari.run()