74 lines
5.3 KiB
Markdown
74 lines
5.3 KiB
Markdown
# 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.
|