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:

Anatomical Fidelity: This threshold is required to resolve the hierarchy between the primary midrib, secondary veins, and apical accumulation zones.
Stability: Metric stabilization was observed in the k=8 to k=12 range.
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.

5.3 KiB Raw Blame History