# Technical Documentation & Experimental Rationale

This document provides a detailed technical overview of the computational choices, hyperparameter tuning, and validation strategies implemented in the hybrid Julia-Python MSI workflow.

## Docker Maintenance & Disk Space
If you encounter disk space issues due to failed builds or unused images, use these commands:

- **Safe Clean (Dangling layers only):** `docker image prune`
- **Deep Clean (Everything unused):** `docker system prune -a --volumes`
- **Clear Build Cache:** `docker builder prune`

## 1. Hyperparameter Tuning Rationale (SimCLR)

The training configuration in `scripts_python/CNN_proof_1.py` follows the standard SimCLR framework (Chen et al., 2020) while being optimized for the morphological characteristics of Mass Spectrometry Imaging (MSI) data.

| Hyperparameter | Value | Rationale |
| :--- | :--- | :--- |
| **Temperature ($\tau$)** | 0.5 | **Selected via grid search.** We tested $\tau \in \{0.1, 0.5, 1.0\}$. A value of 0.1 led to unstable gradients and collapsed representations, while 1.0 was too permissive. $\tau=0.5$ provided the most stable convergence and distinct cluster boundaries. |
| **Projection Dim** | 128 | Standard for SimCLR. Reducing to 64 lost anatomical detail; increasing to 256 did not improve Silhouette scores but increased computational overhead. |
| **Training Epochs** | 50 | Observed convergence of NT-Xent loss between epochs 40-50. Further training (tested up to 200 epochs) led to minor overfitting to instrumental artifacts. |
| **Batch Size** | 32 | Optimized for the i5 CPU environment to balance memory usage and gradient stability. |

## 2. Advanced Validation Strategies

To satisfy rigorous peer review, we implemented three quantitative validation layers in `scripts_python/quantitative_validation.py`:

### 2.1 Baseline Comparison (PCA vs. SimCLR)
*   **Method:** We compared our self-supervised approach against a traditional baseline where PCA is applied directly to raw pixel vectors (flattened ion images).
*   **Result:** SimCLR consistently yields higher Silhouette scores and lower Davies-Bouldin indices. This proves that the neural network's non-linear feature extraction captures anatomical "shapes" better than linear variance-based methods.

### 2.2 Stability & Reproducibility Analysis
*   **Metric:** Adjusted Rand Index (ARI).
*   **Method:** We ran the clustering pipeline across 10 different random seeds. By computing the ARI between all pairs of runs, we demonstrate that the metabolic domains identified (Clusters 0-9) are stable and not artifacts of k-means initialization.

### 2.3 Isotope Co-localization (Natural Ground Truth)
*   **Scientific Anchor:** Isotopes ($[M+H]^+$ and $[M+H+1]^+$) must co-localize perfectly in tissue.
*   **Validation:** We measure the Euclidean distance of isotopic pairs in the latent manifold. A t-test confirms that these distances are significantly smaller than those of random ion pairs, providing objective evidence that the model has learned chemical-biological reality.

## 3. Biological & Mathematical Rationale for $k=10$

While mathematical metrics (Elbow method, Silhouette) often suggest $k=2$ or $k=3$ (tissue vs. background), we selected **$k=10$** based on:
1.  **Anatomical Fidelity:** This threshold is required to resolve the hierarchy between the primary midrib, secondary veins, and apical accumulation zones.
2.  **Stability:** Metric stabilization was observed in the $k=8$ to $k=12$ range.
3.  **Metabolic Heatmaps:** Average ion intensities per cluster for scopolamine ($m/z$ 304.1) and atropine ($m/z$ 290.1) show clear sequestration in Clusters 9 (Vascular) and 7 (Apical), validating the biological relevance of the segmentation.

## 4. Technical Specifications & Citations

### 4.1 Data Augmentations
We implemented **Additive Gaussian Noise ($\sigma=0.01$)**. This is critical for MSI to simulate detector background noise.
*   *Citation:* DeepION (2024) and Hu et al. (2022, Table S1).

### 4.2 Model Backbone
**EfficientNet-B0** with ImageNet weights was used for transfer learning. The MBConv blocks are highly efficient for CPU-based inference.
*   *Citation:* Tan & Le (2019).

### 4.3 Preprocessing (JuliaMSI)
*   **Spectral Averaging:** Done via `MSI_src.get_average_spectrum`.
*   **Tolerance:** $\pm 0.05$ Da window for mass slices. This is standard for low-resolution Ion Trap instruments (LCQ Fleet) to ensure all isotopic signal is captured.
*   *Citation:* Sierra-Álvarez et al. (2025).

### 4.4 Dimensionality Reduction
PCA was used to reduce the 1280-dim (EfficientNet) or 128-dim (Projector) features to **50 components** before k-means. This heuristic stabilizes clustering by removing noise and redundant dimensions.
*   *Citation:* Jolliffe (2002).


## Benchmarking & Hardware Realism
The pipeline is optimized for efficiency on consumer-grade hardware. 
- **Julia Stage**: Uses `BenchmarkTools.jl` to profile binary parsing.
- **Python Stage**: Uses `psutil` and `CUDA` monitoring to track hardware overhead.
- **Determinism**: All stochastic steps are locked with `seed=42`.

## Julia-Python Bridge Details
The "two-language problem" is solved by an intermediate file-system bridge. Julia performs binary MSI parsing and **Threshold Intensity Quantization (TrIQ)**. The resulting data is saved as high-contrast 224x224 grayscale PNG images, allowing the Python PyTorch pipeline to consume it efficiently.