Examples

Code snippets showing how to use Radiomics.jl in different scenarios.

Function Signature

The complete signature of the main function with all available parameters:

extract_radiomic_features(img_input, mask_input, voxel_spacing_input;
                          features=Symbol[],
                          labels=nothing,
                          n_bins=nothing,
                          bin_width=nothing,
                          weighting_norm=nothing,
                          force_2d::Bool=false,
                          force_2d_dimension::Int=1,
                          keep_largest_only::Bool=true,
                          get_raw_matrices::Bool=false,
                          sample_rate=0.03,
                          verbose::Bool=false)

# Parameters:
#  img_input           – Input image (Array).
#  mask_input          – Mask defining the region of interest (Array).
#  voxel_spacing_input – Voxel spacing in mm, e.g. [1.0, 1.0, 2.5] (Array).
#  features            – Symbols selecting which groups to compute.
#                        Options: :first_order, :glcm, :shape2d, :shape3d,
#                                 :glszm, :ngtdm, :glrlm, :gldm.
#                        Default Symbol[] computes all groups.
#  labels              – Int, Vector{Int}, or nothing (defaults to label 1).
#  n_bins              – Number of histogram bins for discretisation.
#  bin_width           – Fixed bin width for discretisation (alternative to n_bins).
#  weighting_norm      – Norm used for GLCM distance weighting.
#  force_2d            – If true, features are computed slice-by-slice.
#  force_2d_dimension  – Axis along which 2-D slicing is performed (default: 1).
#  keep_largest_only   – If true, only the largest connected component is used.
#  get_raw_matrices    – If true, returns the raw matrices for texture features.
#  sample_rate         – Fraction of voxel pairs sampled for GLCM (0–1).
#  verbose             – Print progress information during extraction.

# Returns:
# Single label or nothing: Dict{String,Any} with feature names as keys
# Multiple labels: Dict{Int,Dict{String,Any}} where outer keys are label values

Features Extraction

Basic Usage

Load a NIfTI image and mask, then extract all radiomic features with default settings:

using NIfTI
using Radiomics

# Load image and mask
ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")

# Extract voxel spacing from header (x, y, z in mm)
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing)

Select Specific Feature Groups

To compute only a subset of features, specify the desired ones using the features flags:

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; features=[:first_order, :glcm]);

Select Specific label

To extract features from a specific label (default is 1), execute:

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; labels=1);

Select list of labels

To extract features from a list of labels, execute:

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; labels=[1,2]);

Please note that, in this case, the function returns a dictionary with integer keys (e.g., 3, 5, and 11).

Extraction with a specific bin_width

To compute more features with a specific bin_width (by default it is 25.0):

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; features=[:first_order, :glcm], bin_width=35);

Extraction with a specific n_bins

To compute with a specific number of bins:

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; features=[:first_order, :glcm], n_bins=16);

Extraction all islands

To compute features from the entire mask regardless of fragmentation, set keep_largest_only to false; set it to true to isolate and analyze only the largest connected component:

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; sample_rate = 1.0, verbose = true, keep_largest_only=false)

Extraction with a specific weighting_norm

To compute with a specific weighting_norm

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; sample_rate = 1.0, verbose = true, keep_largest_only=false, weighting_norm="euclidean");

Extraction raw matrices from Texture Features

Basic Usage

To compute the raw matrices from the texture features, set get_raw_matrices. This option returns a dictionary containing the raw matrix for each direction. When enabled, the output will include all the extracted features as well as the raw texture matrices. Please note that activating this option can significantly increase memory usage.

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; verbose = true, get_raw_matrices=true);

Get raw matrices from specific features

To compute the raw matrices from the texture features, set features param.

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; verbose = true, get_raw_matrices=true, features=[:glrlm, :glcm]);

Get raw matrices from labels

To compute the raw matrices from the texture features, set labels param.

using NIfTI
using Radiomics

ct   = niread("sample_data/CTChest.nii.gz")
mask = niread("sample_data/Lungs.nii.gz")
spacing = [ct.header.pixdim[2], ct.header.pixdim[3], ct.header.pixdim[4]]

features = Radiomics.extract_radiomic_features(ct.raw, mask.raw, spacing; verbose = true, get_raw_matrices=true, labels=[1,2]);

Accessing matrix data

To access the raw matrices from the texture features, use the following code:

mat = features["raw_glcm_matrices"]