docs/folder-context.md

🧬 Contexto de la Competencia: Biohub - Cell Tracking During Development

Documento de Contexto Maestro (folder-context.md)
Diseñado para que cualquier agente o modelo de Inteligencia Artificial entienda de inmediato el problema biológico, la estructura de datos, las métricas de evaluación, el ecosistema de código, los modelos campeones y las reglas operativas del proyecto.

---

📌 1. Resumen Ejecutivo y Objetivo Biológico

• Nombre de la Competencia: Biohub - Cell Tracking During Development (Kaggle Code Competition).
• Organizador: Chan Zuckerberg Biohub San Francisco.
• Problema Científico: Reconstruir el linaje celular completo en 3D+Tiempo (árboles genealógicos y grafos acíclicos dirigidos - DAGs) a partir de grabaciones de microscopía de fluorescencia 4D durante el desarrollo embrionario del pez cebra (Danio rerio).
• Objetivo del Algoritmo:
  1. Detección Espacial (Nodos): Predecir las coordenadas 3D $(t, z, y, x)$ de cada centroide celular activo en cada fotograma temporal.
  2. Asociación Temporal (Enlaces / Edges): Conectar los centroides entre fotogramas consecutivos $(t \to t+1)$ o con salto de fotograma (gap closing, $t \to t+2$).
  3. Divisiones Celulares (Mitosis): Identificar cuándo una célula madre da origen a dos células hijas ($1 \to 2$).

---

📦 2. Estructura y Física de los Datos

A. Anisotropía Espacial (CRÍTICO)

Los vóxeles de microscopía no son cúbicos; el eje axial ($Z$) tiene 4 veces menor resolución que los ejes laterales ($Y, X$): $$\text{SCALE}=[1.625,0.40625,0.40625]\mu \text{m/v}\acute{\text{o}}\text{xel}\backslash text\{SCALE\}\; =\; [1.625,\backslash ,\; 0.40625,\backslash ,\; 0.40625]\backslash ,\backslash mu\backslash text\{m/vóxel\}$$

Toda distancia euclidiana o cálculo de costo de emparejamiento temporal DEBE multiplicar las coordenadas por este vector de escala física antes de calcular distancias.

B. Formato de Archivos

• Imágenes 4D (.zarr): Volúmenes $(T, Z, Y, X)$ en formato Zarr v3 con compresión Blosc, típicamente de forma $(100, 64, 256, 256)$ en uint16.
• Etiquetas de Entrenamiento (.geff): Grafos biológicos (Graph Exchange Format) con propiedades de nodos $(t, z, y, x)$ y enlaces de linaje.
• Directorio en Kaggle:

  biohub-cell-tracking-during-development/
  ├── train/                  # 199 videos (Imágenes + Etiquetas .geff) -> SOLO PARA ENTRENAR
  ├── test/                   # Videos de Test (4 en modo edición / ~199 privados en Submit)
  └── sample_submission.csv   # Formato requerido (Solo contiene IDs de test/)
  

---

📐 3. Métrica Oficial y Reglas de Evaluación

• Métrica: Promedio ponderado de Edge Jaccard (asociaciones temporales correctas con penalización por densidad) y Division Jaccard (detección exacta de mitosis).
• Restricciones de Kaggle:
  • Competencia de código pura (Code Competition).
  • Sin acceso a internet durante la inferencia.
  • Límite estricto de tiempo: 9 a 12 horas máximo.
  • Hardware permitido: GPU Tesla T4 (Dual T4 x2) o CPU (4 vCPUs). Las GPUs P100 (sm_60) están prohibidas por reglas y generan error de CUDA.

---

🏆 4. Modelos Campeones y Hallazgos Consolidados

Experimento	Arquitectura	Esquema	Score CV	Hallazgo Principal
EXP-017	3D Wide Anisotropic U-Net (64ch)	90/10	0.9010 🏆	Grand Champion: Cuadruplicar canales a 64 y entrenar en 179 volúmenes rompió la barrera de 0.90.
EXP-019	3D Wide ResUNet (64ch)	90/10	0.8867	Bloques residuales ResBlock3D con menor pérdida de entrenamiento histórica (0.000343).
EXP-022	StarDist 3D Polyhedra (32 Rayos)	90/10	0.8601	Récord Histórico de Recall (99.23%): Despega cúmulos densos sin mapas gaussianos continuos.
EXP-028	3D Wide Attention U-Net (64ch)	90/10	En Progreso	Spatial Attention Gates 3D para filtrar el 98% de líquido de fondo.
EXP-029	3D Full-Volume GroupNorm U-Net	90/10	En Progreso	GroupNorm3d (8 grupos) para estabilidad numérica total con batch size 1 en volúmenes completos.

---

🚀 5. Protocolo Estricto de Despliegue en Kaggle (Kaggle Submissions)

Cualquier cuaderno generado para Kaggle DEBE seguir estas 5 reglas obligatorias:

1. Búsqueda Exclusiva en test/:
   Nunca incluir train/ en la búsqueda de inferencia; de lo contrario, Kaggle procesará 203 videos en lugar de 4 durante el Save Version y tardará 8 horas en lugar de 2 minutos.
2. Cargador Universal Zarr (zarr.open):
   Cargar usando zarr.open(path)["0"][t] con fallback Blosc2, evitando nombres fijos como {t}.0.0.0 para prevenir imágenes vacías de ceros (0 nodes, 0 edges).
3. Metadatos kernelspec en el .ipynb:
   Incluir "kernelspec": {"name": "python3", "display_name": "Python 3"} para evitar errores de Papermill.
4. Validación Previa de state_dict:
   Probar localmente model.load_state_dict(...) antes de subir para evitar desajustes de capas.
5. Configuración de Acelerador:
   • GPU: "enable_gpu": "true", "machine_shape": "NvidiaTeslaT4".
   • CPU: "enable_gpu": "false", con torch.set_num_threads(4) para inferencia rápida AVX-512.

---

🖥️ 6. Infraestructura de Hardware y Reglas Operativas

1. Máquina Local del Usuario (Mac):
   CERO cómputo pesado. Solo se utiliza para edición de código, control de versiones y sincronización SSH/Kaggle CLI.
2. Cluster Físico Remoto (4x Servidores con GPU NVIDIA RTX 4090 24GB):
   • A1557-UBU (100.87.128.33:2222)
   • A1556-UBU (100.107.113.22:2222)
   • A1560-UBU (100.84.253.117:2222)
   • A1552-UBU (100.112.138.117:2222)
3. Bóveda de Conocimiento Obsidian:
   Ubicada en Librería-Registros/. Todo nuevo experimento o hallazgo se documenta automáticamente en 01_Registro_Experimentos.md.

---

🗂️ 7. Mapa de Directorios del Repositorio

/Users/matias/Proyects/Biohub/
├── folder-context.md               # Este archivo (Contexto maestro para IAs)
├── src/                            # Código fuente modular
│   ├── dataset.py                  # Dataset por parches 3D con augmentations
│   ├── dataset_full_volume.py      # Dataset de volumen completo (64x256x256)
│   ├── models/
│   │   ├── unet3d_anisotropic.py   # AnisotropicUNet3D (EXP-017 Champion)
│   │   ├── resnet_unet3d.py        # ResUNet3D (EXP-019)
│   │   ├── stardist3d.py           # StarDist3D Polyhedra (EXP-022)
│   │   ├── attention_unet3d.py     # AttentionUNet3D (EXP-028)
│   │   └── unet3d_groupnorm.py     # GroupNormUNet3D (EXP-029)
│   └── tracking/
│       └── gap_closing_tracker.py  # Algoritmo de tracking LAP + Gap Closing
├── champion_weights/               # Pesos .pt de los modelos campeones
├── kaggle_submission_exp017/       # Paquete de envío Kaggle EXP-017 (Wide UNet T4)
├── kaggle_submission_exp019/       # Paquete de envío Kaggle EXP-019 (ResUNet T4)
├── kaggle_submission_exp022/       # Paquete de envío Kaggle EXP-022 (StarDist CPU)
└── Librería-Registros/             # Bóveda Obsidian de Bitácoras y Experimentos

---

🧪 8. Ramas experimentales independientes preparadas

Además de la familia de detectores 3D por heatmaps, existen dos estrategias experimentales y una nueva variante full-fit:

• EXP-030: versión original con dos seeds de TemporalUNet3D + Node Transformer, TTA de ocho vistas, fusión calibrada, retention guard e ILP. Conservar su historial y checkpoints.
• EXP-030B: nueva versión de EXP-030; entrena ambos seeds con 100 % de los datos, sin validación, durante 55 × 750 por seed.
• EXP-031: revisión detector-first full-fit con hard-negative mining, 100 % train / 0 % validación, 65 × 850, ILP preservado y motion/divisiones sólo sobre nodos no asociados.

EXP-030B y la revisión de EXP-031 deben entrenarse únicamente en una GPU remota. Su estado no debe cambiarse a “En progreso” hasta observar el sentinel RUNNING.json correspondiente. Como no tienen holdout, su CV debe registrarse como N/A — full-fit sin validación, nunca como la loss de train.

---

🚦 9. Experiment Promotion Board

El evaluador y selector reusable están concentrados en test-exp-local/: inferencia real, validación, agregación, CLI, protocolo congelado y tests. Sólo acepta artefactos con conteos oficiales por dataset, mismo protocol_id y exactamente las mismas muestras. Ordena por el límite inferior bootstrap 95% del score oficial y usa integridad, cobertura y runtime como gates.

El piloto remoto EXP-017 vs EXP-019 está en experiments/Promotion_Board_EXP017_EXP019_Pilot/: EXP-017 0.8098, EXP-019 0.7783, delta pareado +0.0315 con IC 95% [+0.0046, +0.0592]. El framework queda adoptado; el protocolo legacy de 12 muestras sigue siendo piloto y no una métrica global definitiva.