Usage Guide

This guide demonstrates how to perform a multi-parametric radiomic analysis using the GLAM library. The framework relies on a centralized configuration file to manage the complex physics and radiomics parameters.

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 processes to run.
# Use 1 for no parallelism. Use 4, 8, etc. based on your CPU.
# Recomendation: NumWorkers ~ 2 * Number of CPU Cores.
NumWorkers = 8

[GLAM_Settings]
MaxRdfRadius = 100
AnisotropyCutoffRadius = 5
NumRandomisations = 4
RdfSamplePoints = 100

# 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"
    }

LabelsForAnalysis = {
    "99": "Whole_Tumor"
    }

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

Key settings include:

GLAM_Settings: Defines the discretization and the maximum radius for the Radial Distribution Function (RDF) calculation.
Radiomics_Settings: Ensures parity with conventional libraries by setting matching bin counts.
File_Naming: Uses identifiers to automatically pair MRI sequences (T1, T1c, T2, FLAIR) with their corresponding tumor masks.
Label_Mapping: Maps voxel values to biological compartments, such as the Whole Tumor or Enhancing Tumor.

Image Quantization Methods

To calculate texture and GLAM matrices, continuous image intensities must first be discretized into discrete bins (gray levels). GLAM supports two primary quantization methods depending on your imaging modality.

1. Fixed Bin Count (MRI) Recommended for MRI, where intensity values are relative and lack an absolute physical meaning. This method rescales the Region of Interest (ROI) intensities directly into a fixed number of bins, \(N_g\) (NumGrayLevels).

\[X_{d} = \left\lfloor \frac{I - I_{min}}{I_{max} - I_{min}} \times N_g \right\rfloor\]

Where \(I_{min}\) and \(I_{max}\) are the minimum and maximum intensities within the ROI. To ensure the absolute maximum intensity (\(I = I_{max}\)) does not fall out of bounds, the final discrete value \(X_d\) is capped at \(N_g - 1\). This produces a 0-indexed range from \(0\) to \(N_g - 1\).

2. Fixed Bin Width (CT) Recommended for CT scans, where Hounsfield Units (HU) represent absolute physical densities (e.g., water = 0 HU, bone = ~1000 HU). Using a fixed bin count on CTs would destroy this absolute density mapping. Instead, this method clips the image to a defined range \([Q_{min}, Q_{max}]\) and divides the intensities into bins of a fixed physical width, \(W\) (BinWidth).

\[I_{clipped} = \max(Q_{min}, \min(I, Q_{max}))\]

\[X_{d} = \left\lfloor \frac{I_{clipped} - Q_{min}}{W} \right\rfloor\]

In this mode, GLAM dynamically calculates the total number of gray levels needed to cover the range: \(N_g = \lceil (Q_{max} - Q_{min}) / W \rceil\). This ensures the meaning of “Gray Level 5” is identical across every patient in your dataset.

Basic Extraction Script

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

Note

If you are running on a multi-core system, you can increase the NumWorkers in your config file to enable parallel processing.

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()

Output Files

After execution, the output directory will contain:

GLAM Matrices: CSV files containing the \(N \times N\) interaction data (e.g., PressureVirial_Symlog.csv).
Feature CSVs: Consolidated tables of physics descriptors (3d_glam_primary_features.csv) and topological metrics (3d_glam_meta_and_radiomic_features.csv).
Log Files: Details on the extraction process and data harmonization.