SlicerPySERA — PySERA Radiomics Extension for 3D Slicer

SlicerPySERA integrates the PySERA radiomics engine into 3D Slicer as an interactive extension. It provides a practical, UI-driven workflow for reproducible radiomics extraction inside Slicer, supporting both:

• Handcrafted radiomics (IBSI-aligned feature families when configured in PySERA)
• Deep feature extraction (CNN-based embeddings through PySERA’s deep pipeline)

This repository is designed to support research-grade feature extraction workflows in Slicer while keeping the user experience simple enough for everyday use.

---

Table of Contents

1. What This Extension Is (and Isn’t)
2. Overview
3. Key Features
4. Feature Families and Dimensions
5. Screenshots
6. Installation
   • Option 1 — Install via the Extension Manager
   • Option 2 — Install from Source (Developer Mode)
   • Offline / Restricted Network Environments
7. Quick Start
8. Inputs and Supported Data
9. Batch Processing
   • Folder Mirroring Rules
   • Recommended Naming Conventions
10. Configuration and Parameters
    • Where Parameters Live
    • Common Parameters
    • Handcrafted Mode Parameters
    • Deep Feature Mode Parameters
    • Logging and Reproducibility Metadata
11. Outputs
12. Reproducibility Checklist
13. Performance Notes
14. Troubleshooting and FAQ
15. Data Privacy and Security Notes
16. Citation
17. License
18. Support and Contact
19. Acknowledgments
20. For Developers
    • Repository Structure
    • Build & Packaging Notes (CMake / CI)
    • Development Install (Local Testing)
    • Registering the Extension for Slicer 5.10+
    • Contributing
    • Versioning and Release Notes

---

What This Extension Is (and Isn’t)

SlicerPySERA is a Slicer-facing UI and workflow layer around the PySERA computation engine. The extension’s job is to:

• Collect inputs (image + mask / segmentation)
• Collect configuration options (UI + parameter files)
• Run PySERA reliably (single-case or batch)
• Save outputs to disk and display them in Slicer tables

It is not intended to replace the PySERA Python library for scripting-heavy or HPC pipelines.
If you already run PySERA in a Python environment (e.g., notebooks, Snakemake, SLURM), that is still the best route for large-scale experiments. This extension is for situations where you want a transparent, interactive, Slicer-native workflow.

---

Overview

SlicerPySERA provides a graphical user interface (GUI) for configuring and running radiomics pipelines on medical images and segmentations (masks) within 3D Slicer.

It leverages the PySERA library to compute standardized radiomics outputs and aims to make feature extraction:

• Easier to run (no scripting required for typical use)
• Easier to reproduce (parameters are visible and saved)
• Consistent across datasets and users (a single pipeline definition)

Typical use cases include:

• Feature extraction from ROIs for radiomics modeling
• Dataset-wide batch extraction for research workflows
• Comparing handcrafted radiomics vs deep features for downstream tasks

---

Key Features

User-facing workflow

• Integrated into 3D Slicer: use the module like any other Slicer tool.
• Two input workflows:
  • Single case: one image + one mask
  • Batch: two folders (images + masks) with mirrored structure
• Two extraction modes:
  • Handcrafted radiomics (IBSI-aligned feature families when enabled in PySERA)
  • Deep features (CNN-based representation)
• Clear results display:
  • “Summary” panel for run information and paths
  • “Extracted Features” table with exactly two columns: Feature | Value
• Disk outputs:
  • Timestamped CSV files
  • Consistent naming conventions for batch runs
• Parameter-driven:
  • Defaults and UI hints come from bundled configuration files

Engineering choices that matter for Slicer extensions

• Packaging-safe scripting:
  • Avoid importing pip-installed packages at module import time.
  • Install/import runtime dependencies in the module logic only.
• Extension indexing compatibility:
  • Uses standard CMake patterns and avoids absolute resource paths (important for CI packaging).

---

Feature Families and Dimensions

SlicerPySERA exposes feature families (“categories”) and dimensionality modes (“dimensions”) using a clear UI selection model.

Categories (feature families)

The selection panel supports the following families:

• DIAG, MORPH, IP, STAT, IH, IVH,
• GLCM, GLRLM, GLSZM, GLDZM, NGTDM, NGLDM,
• MI

In the UI you can either select a subset or simply keep all enabled.

Dimensions

The dimension panel supports:

• 1st, 2D, 2_5D, 3D

A convenience behavior is implemented: changing the selected dimensions can automatically constrain the compatible category families.

Note: the exact feature definitions and what is computed for a given mode ultimately depends on PySERA and your configuration.

---

Screenshots

All screenshots are stored in Resources/Screenshots/.

GitHub renders these using repository-relative paths.
If images do not render, verify the filenames and paths match the repository exactly (case-sensitive on Linux).

Module Overview

Input / Output Tab

Handcrafted Radiomics Mode

Deep Feature Mode

Advanced Settings

Feature Subset Selection

Run & Results

---

Installation

Option 1 — Install via the Extension Manager (recommended)

1. Open 3D Slicer
2. Go to Extensions Manager
3. Search for PySERA / SlicerPySERA (name depends on the extension catalog entry)
4. Install and restart Slicer

After installation, the module should appear under:

Modules → Analysis → PySERA
(category may vary depending on the extension catalog entry)

If the extension is not available in your Slicer build yet, see Registering the Extension for Slicer 5.10+.

---

Option 2 — Install from Source (Developer Mode)

This option is recommended for:

• local development
• testing changes before submitting a PR
• running the latest main branch version

A quick approach is to add the module path in Slicer:

1. Open 3D Slicer

2. Go to Edit → Application Settings → Modules

3. Under Additional module paths, add the path to the module directory:

   • .../SlicerPySERA/

4. Restart Slicer

See Development Install (Local Testing) for more details and tips.

---

Offline / Restricted Network Environments

SlicerPySERA can auto-install Python dependencies using slicer.util.pip_install() at runtime.

If you are behind a proxy, on a restricted network, or offline:

• You may need to preinstall Python packages into Slicer’s Python environment.
• This is most relevant for:
  • pysera (required)
  • PyYAML (optional but recommended; see parameter file notes below)
  • deep learning dependencies used by PySERA (if you enable deep features)

A practical workflow is:

1. Download wheels (.whl) for required packages on a machine with internet
2. Transfer them to the offline machine
3. Install them from the Slicer Python console using slicer.util.pip_install(<path_to_wheel>)

---

Quick Start

1. Open 3D Slicer
2. Load:
   • an image (e.g., NIfTI/NRRD/DICOM series)
   • a segmentation / mask (ROI)
3. Open the module:
   • Modules → Analysis → PySERA
4. Go to Input/Output
   • Choose Single Case or Batch (Folders)
   • Set an Output Folder (must be writable)
5. Choose Extraction Mode
   • Handcrafted Radiomics or Deep Features
6. (Optional) adjust Advanced Settings and Feature Selection
7. Click Run in Run and Results