PySERA: Python-Based Standardized Extraction for Radiomics Analysis – Python Radiomics Script and Library

PySERA (Python-based Standardized Extraction for Radiomics Analysis), published in "PySERA" is a comprehensive Python library for radiomics feature extraction from medical imaging data. It provides a simple, single-function API with built-in multiprocessing support, comprehensive report capabilities, and optimized performance through OOP architecture, RAM optimization, and CPU-efficient parallel processing. PySERA supports both traditional handcrafted radiomics (557 features including 487 IBSI-compliant, 60 diagnostic, and 10 moment-invariant features) and deep learning-based feature extraction using pre-trained models like ResNet50, VGG16, and DenseNet121.

🔍 Table of Contents

• 🧩IBSI (Image Biomarker Standardisation Initiative) Standardization-1.0

• ✨Key Features

• 🤖Deep Learning Feature Extraction

• 📚Library Usage

  • 📂Single File Processing
  • 🧠In-Memory Array Processing
  • ⚡Parallel Batch Processing
  • 🤖Deep Features Extraction
  • 🔧Advanced Configuration

• 📥Installation

  • 🌐GitHub Installation
  • 🖥️Python Script - Command Line Interface (CLI)
  • 📦Library Installation via pip

• 📂Data Structure Requirements

• 📋PySERA Parameters Reference

• 📊Parameter Compatibility

• 📚API Reference

• 📊Output Structure

• 🔢Feature Extraction Modes

• 📁Supported File Formats

• 🎯Library Examples

• ⚡Performance Tips

• 💻Integration of PySERA to GUI

• ❓Troubleshooting

• 🕒Version History

• 📬Contact

• 👥Authors

• 📚Citation

• 🙏Acknowledgment

• 📜License

🧩IBSI Standardization

Both the script and library have been rigorously standardized based on IBSI (Image Biomarker Standardisation Initiative) Standardization 1.0. PySERA returns IBSI-compliant feature values that match the reference standard, ensuring reproducibility and comparability across studies. See the detailed evaluation and test cases here: IBSI_Evaluation Folder

✨Key Features

PySERA provides a single-function API that handles all radiomics processing:

import pysera

result = pysera.process_batch(
    image_input="image.nii.gz",
    mask_input="mask.nii.gz",
    output_path="./results"
)

That's it! 🎉 All the complexity of multiprocessing, error & warning reports, file format handling, and feature extraction is handled automatically.

• Single Function API: One function does everything - pysera.process_batch()
• Multi-format Support: NIfTI, DICOM, NRRD, RTSTRUCT, NumPy arrays, and more
• Automatic Multiprocessing: Built-in parallel processing for maximum performance
• Comprehensive Report: Excel export functionality for detailed analysis
• Extensive Features: 557 total radiomics features across multiple categories (morphological, statistical, texture, etc.) and dimensions (1st, 2D, 2.5D, 3D) including:
  • 487 IBSI-compliant features (standardized radiomics)
  • 60 diagnostic features (image quality and metadata)
  • 10 moment-invariant features (shape descriptors)
• Medical Image Optimized: Designed for CT, MRI, PET, SPECT, X-Ray, Ultrasound, and other medical imaging modalities.
• Dual Extraction Modes: Both traditional IBSI-compliant radiomics (557 features) and deep learning features (ResNet50, VGG16, DenseNet121)

🤖Deep Learning Feature Extraction

PySERA supports advanced deep learning-based feature extraction alongside traditional radiomics, providing multiple pre-trained models for comprehensive feature representation. When using extraction_mode="deep_feature", the categories parameter is automatically handled by the deep learning model. Deep features are extracted in 3D dimension by default for comprehensive volumetric analysis. All deep learning features are extracted specifically from the ROI regions defined by the mask and model outputs provide complementary feature representations to traditional radiomics.

Available Deep Learning Models:

• resnet50 - 2048 features: Residual Network with 50 layers, balanced performance and accuracy
• vgg16 - 512 features: Visual Geometry Group with 16 layers, strong hierarchical feature representation
• densenet121 - 1024 features: Dense Convolutional Network with 121 layers, efficient feature reuse

📦Library Installation via pip

Install the PySERA library directly from PyPI:

pip install pysera

📚Library Usage

Once installed, you can use PySERA directly in your Python code.

📂Single File Processing

import pysera

# Process single image-mask pair
result = pysera.process_batch(
    image_input="scan.nii.gz",
    mask_input="mask.nii.gz",
    output_path="./results"
)

print(f"Success: {result['success']}")
print(f"Features extracted: {result['features_extracted']}")
print(f"Processing time: {result['processing_time']:.2f} seconds")

🧠In-Memory Array Processing

import numpy as np
import nibabel as nib
import pysera

# Load image and mask as NumPy arrays (for example, using nibabel)
image_array = nib.load("patient002_image.nii.gz").get_fdata()
mask_array = nib.load("patient002_mask.nii.gz").get_fdata()

# Process the image and mask directly from memory
result = pysera.process_batch(
    image_input=image_array,
    mask_input=mask_array,
    output_path="./results"
)

# Display results
print(f"Success: {result['success']}")
print(f"Features extracted: {result['features_extracted']}")
print(f"Processing time: {result['processing_time']:.2f} seconds")

⚡Parallel Batch Processing

import pysera

# Process multiple files with 4 CPU cores
result = pysera.process_batch(
    image_input="./patient_scans",
    mask_input="./patient_masks", 
    output_path="./results",
    num_workers="4",              # Use 4 CPU cores
    categories="glcm, glrlm",     # Extract specific feature categories
    dimensions="1st, 2_5d, 3d",   # Extract features in specified dimensions
    apply_preprocessing=True,   # Apply ROI preprocessing
)

print(f"Processed {result['processed_files']} files")
print(f"Total processing time: {result['processing_time']:.2f} seconds")

🤖Deep Features Extraction

import pysera

# Process multiple files with 4 CPU cores
result = pysera.process_batch(
    image_input="./patient_scans",
    mask_input="./patient_masks", 
    output_path="./results",

    # Deep learning configuration
    extraction_mode="deep_feature",      # Enable deep learning features
    deep_learning_model="resnet50",      # Use ResNet50 model (2047 features)

    roi_num=5,                           # Number of ROIs to process
    roi_selection_mode="per_img",        # ROI selection strategy


    # Logging options
    report="warning"            # Report detail level: "all" (full processing details), 
                              # "info" (essential information), "warning" (warnings only), 
                              # "error" (errors only), "none" (no reporting). Default: "all"

)

print(f"Processed {result['processed_files']} files")
print(f"Total processing time: {result['processing_time']:.2f} seconds")

🔧Advanced Configuration

import pysera

# Comprehensive processing with custom parameters
result = pysera.process_batch(
    image_input="image.nii.gz",
    mask_input="mask.nii.gz",
    output_path="./results",
    
    # Performance settings
    num_workers="2",           # Use 2 CPU cores
    enable_parallelism=False ,     # Disable multiprocessing
    
    # Image feature extraction settings
    categories="glcm, glrlm, glszm",  # Extract specific texture feature categories
    dimensions="1st, 2_5d, 3d",       # Extract features in 1st order, 2.5D and 3D dimensions
    # Alternative examples for categories and dimensions:
    # categories="all",                 # Extract all 557 features
    # categories="stat, morph, glcm",   # Statistical, morphological and GLCM features
    # dimensions="2D",                  # Extract only 2D features
    # dimensions="all",                 # Extract features in all dimensions
    
    bin_size=25,               # Texture analysis bin size
    roi_num=2,                # Number of ROIs to process
    roi_selection_mode="per_region",  # ROI selection strategy
    min_roi_volume=5,          # Minimum ROI volume threshold
    
    # Processing options
    apply_preprocessing=True,   # Apply ROI preprocessing
    feature_value_mode="APPROXIMATE_VALUE",  #	Strategy for handling NaN values.

    # IBSI parameters (advanced, overrides defaults)
    IBSI_based_parameters={
        "radiomics_DataType": "CT",
        "radiomics_DiscType": "FBN",
        "radiomics_isScale": 1
    },
    
    # Logging options
    report="info"             # Report detail level: "all" (full processing details),