GRAY LEVEL AFFINITY METRICS - GLAM RADIOMICS

This project introduces and implements a novel class of quantitative imaging features, termed Gray Level Affinity Metrics (GLAM), derived from the foundational principles of statistical mechanics. By treating image voxels as interacting particles within a multi-component system, the GLAM framework provides a set of physically interpretable metrics that characterize the spatial organization and texture of 3D medical images.

The GLAM framework is written in Python and leverages high-performance libraries for medical image analysis. It operates as a fully standalone extraction engine, meaning it does not require external radiomics packages to compute conventional texture matrices.

Citation

If you use the GLAM framework in your research, please cite our paper:

Physics-Informed Multiscale Decoding of Tissue Microstructure: The Gray Level Affinity Metrics (GLAM) Framework > Accepted for publication in the Journal of Imaging Informatics in Medicine (2026).

Installing from GitHub

You can install GLAM-radiomics using the following command:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ glam-radiomics

or

pip install glam-radiomics

Note: This release (v1.5.2) was successfully built and tested using Python 3.12.10 and NumPy 2.3.2.

GPU Acceleration (Optional but Recommended): > GLAM features automatic GPU-accelerated matrix batching for massive speed improvements. To enable this, you must install CuPy. It is highly recommended to install the pre-compiled binary wheel that matches your system's NVIDIA CUDA version (e.g., pip install cupy-cuda12x) rather than running pip install cupy, which requires a complex C++ build environment and can cause installation failures.

Key Dependencies

When you install GLAM, the following core libraries are automatically integrated:

• NumPy & SciPy: Provide the computational backbone for RDF calculations, spatial KD-trees, and Statistical Mechanics descriptors.
• SimpleITK: Handles the loading and normalization of 3D medical imaging formats like NIfTI (.nii.gz).
• Pandas: Manages the structured output of multiscale Radial Distribution Functions and feature aggregation.
• Scikit-image & Scikit-learn: Powers the morphological marching cubes (surface area), K-Means clustering, and advanced geometric descriptors.
• tqdm: Used to display progress bars during long-running feature extraction operations.

Usage Guide

Configuration (config.ini)

GLAM uses a .ini file to standardize extraction parameters across different datasets. This ensures reproducibility, which is critical for multi-center studies.

A typical configuration file is structured as follows:

# Note: configparser keys are case-insensitive, but values preserve case.

[System]
# Number of parallel patient folders to process simultaneously.
# CRITICAL: If using GPU Acceleration (CuPy), this dictates how many 
# matrices are loaded into VRAM. 
# For NumWorkers = 1, the system requires a 4–6 core CPU and a 4 GB GPU
NumWorkers = 1

[GLAM_Settings]
MaxRdfRadius = 100
AnisotropyCutoffRadius = 5
MaxLocalShellRadius = 30
NumRandomisations = 4
RdfSamplePoints = 1000

# QuantizationMethod can be "FixedCount" (for MRI) or "FixedWidth" (for CT)
QuantizationMethod = FixedCount

# --- FixedCount Parameters ---
NumGrayLevels = 24

# --- FixedWidth Parameters ---
BinWidth = 25
QuantizationMin = -1000
QuantizationMax = 1000

[File_Naming]
# Segmentation file identifiers.
MaskIdentifiers = ["_seg.nii.gz", "-seg.nii.gz", "_mask.nii.gz", "-mask.nii.gz"]

SequenceIdentifiers = {
    "FLAIR": ["_flair", "-flair"],
    "T2": ["_t2", "-t2"],
    "T1": ["_t1", "-t1"],
    "T1c": ["_t1ce", "-t1ce", "_t1gd", "-t1gd", "_t1c", "-t1c"]
    }

[Label_Mapping]
# JSON keys need to be strings ("1", "99").
LabelMapping = {
    "1": "Enhancing_Tumor",
    "2": "Non_Enhancing_Tumor_Core",
    "4": "Peritumoral_Edema",
    "99": "Whole_Tumor"
    }

# Available habitats you can swap in:
# "1": "Enhancing_Tumor"
# "1+2": "Tumor_Core",
# "1+4": "Enhancing_and_Edema"
# "99": "Whole_Tumor"

LabelsForAnalysis = {
    "1": "Enhancing_Tumor"
    "1+2": "Tumor_Core",
    "1+4": "Enhancing_and_Edema"
    "99": "Whole_Tumor"
    }

[Algorithm_Parameters]
SavgolWindow = 7
SavgolPoly = 3
PeakProminence = 4

Basic Extraction Script

The following script demonstrates how to initialize the global configuration and process a cohort of scans.

import os
from glam_radiomics.config import load_config
from glam_radiomics.run import process_scans

# 1. Define your project paths
CONFIG_PATH = "path_to/config.ini"
INPUT_DIR = "path_to/mri_scans"
OUTPUT_DIR = "path_to/results"
PROJECT_NAME = "My_GLAM_Project"

def main():
    # 2. Load the configuration globally
    load_config(CONFIG_PATH)

    # 3. Ensure the output directory exists
    if not os.path.exists(OUTPUT_DIR):
        os.makedirs(OUTPUT_DIR)

    # 4. Execute the analysis
    process_scans(
        INPUT_DIR,
        OUTPUT_DIR,
        project_name=PROJECT_NAME,
        config_path=CONFIG_PATH
    )

if __name__ == '__main__':
    main()

Batch Processing Multiple Scans

For multi-center studies or large cohorts, you can configure a script to loop through multiple project directories. This approach utilizes parallel processing defined by NumWorkers in your config.ini.

import os
from glam_radiomics.config import load_config
from glam_radiomics.run import process_scans

CONFIG_PATH = "path/to/config.ini"

# Define project batches (Project Name, Input, Output)
projects_to_run = [
    ("Cohort_A", "C:/data/cohort_a_scans", "C:/results/cohort_a"),
    ("Cohort_B", "C:/data/cohort_b_scans", "C:/results/cohort_b")
]

def main():
    load_config(CONFIG_PATH)

    for proj_name, input_path, output_path in projects_to_run:
        if not os.path.exists(output_path):
            os.makedirs(output_path)

        process_scans(input_path, output_path,
                      project_name=proj_name,
                      config_path=CONFIG_PATH)

if __name__ == '__main__':
    main()

File and Folder Organization

To ensure the pipeline pairs the correct masks with the correct sequences, structure your input directory as follows:

C:\...\Research\GLAM\scans\   <-- Your 'INPUT_DIR'
├── PT011901\
│   ├── PT011901_t1.nii.gz
│   ├── PT011901_t2.nii.gz
│   └── PT011901_mask.nii.gz
├── PT011902\
│   ├── PT011902_t1.nii.gz
│   ├── PT011902_flair.nii.gz
│   └── PT011902_seg.nii.gz
└── ...