# PySERA: Python-Based Standardized Extraction for Radiomics Analysis – Python Radiomics Script and Library
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://pypi.org/project/pysera/)
**PySERA** (Python-based Standardized Extraction for Radiomics Analysis) 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 and comprehensive logging capabilities. This is a development version and the final version (v1.1.0) will release by September 2025.
## 🔍 Table of Contents
- [🧩IBSI (Image Biomarker Standardisation Initiative) Standardization-1.0](#IBSI-Standardization)
- [🛠️Key Features](#key-features)
- [📥Installation](#installation)
- [🌐GitHub Installation](#github-installation)
- [💻Python Script - Command Line Interface (CLI)](#python-script---command-line-interface-cli)
- [📦Library Installation via pip](#library-installation-via-pip)
- [📚Library Usage](#library-usage)
- [📂Single File Processing](#single-file-processing)
- [🧠In-Memory Array Processing](#in-memory-array-processing)
- [⚡Parallel Batch Processing](#parallel-batch-processing)
- [🔧Advanced Configuration](#advanced-configuration)
- [📂Data Structure Requirements](#data-structure-requirements)
- [📋PySERA Parameters Reference](#pysera-parameters-reference)
- [📚API Reference](#api-reference)
- [📊Output Structure](#output-structure)
- [🔢Feature Extraction Modes](#feature-extraction-modes)
- [📁Supported File Formats](#supported-file-formats)
- [🎯Library Examples](#library-examples)
- [⚡Performance Tips](#performance-tips)
- [❓Troubleshooting](#troubleshooting)
- [🕒Version History](#Version-History)
- [📬Contact](#contact)
- [👥Authors](#authors)
- [🙏Acknowledgment](#acknowledgment)
- [📜License](#license)
## ✨IBSI Standardization
Both the script and library have been rigorously standardized based on **IBSI** (Image Biomarker Standardisation Initiative) Standardization 1.0.
See the detailed evaluation and test cases here: [IBSI_Evaluation Folder](https://github.com/MohammadRSalmanpour/PySERATest/tree/main/IBSI_Evaluation)
## 🛠️Key Features
PySERA provides a **single-function API** that handles all radiomics processing:
```python
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 Logging**: Excel export functionality for detailed analysis
- **Extensive Features**: 497 radiomics features with 12 extraction modes
- **Medical Image Optimized**: Designed for CT, MRI, PET, and other medical imaging
## 📥Installation
PySERA can be installed as a Python library for integration into your projects or as a standalone script for command-line usage. It supports Windows, macOS, and Linux. Below are the installation options.
### 🌐GitHub Installation
For users who want to develop with the source code or run PySERA as a standalone command-line tool (CLI) without installing it as a Python package, you can clone the repository from GitHub.
This gives you access to the standalone script radiomics_standalone.py and all example files. After installing the dependencies, you can run the script directly (see the [💻Python Script - Command Line Interface (CLI)](#python-script---command-line-interface-cli) section).
```bash
# Clone the repository
git clone https://github.com/MohammadRSalmanpour/PySERA.git
cd pysera
```
### macOS/Linux Installation
#### Quick Setup (Recommended):
```bash
# Quick setup (creates a virtual environment and installs everything)
./dev_setup.sh
```
#### Manual Setup:
```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .
```
### Windows Setup
#### Quick Setup (Recommended):
```bash
# Quick setup
./dev_setup.sh
```
#### Manual Setup
```bash
python3 -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
```
### 💻Python Script - Command Line Interface (CLI)
If you just want to run the CLI without installing the library into Python,the standalone script 'radiomics_standalone.py' provides a command-line interface for radiomics processing :
```bash
# Process single files
python radiomics_standalone.py \
--image_input image.nii.gz \
--mask_input mask.nii.gz \
--output ./results
# Batch processing (folders)
python radiomics_standalone.py \
--image_input ./images \
--mask_input ./masks \
--output ./results \
--num_workers 4
```
### 📦Library Installation via pip
Install the PySERA library directly from PyPI:
```bash
pip install pysera
```
## 📚Library Usage
Once installed, you can use PySERA directly in your Python code.
### 📂Single File Processing
```python
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
```python
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
```python
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
feats2out=5, # Extract all features + Moment
apply_preprocessing=True, # Apply ROI preprocessing
)
print(f"Processed {result['processed_files']} files")
print(f"Total processing time: {result['processing_time']:.2f} seconds")
```
## 🔧Advanced Configuration
```python
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="auto", # Use all available CPU cores
enable_parallelism=True, # Enable multiprocessing
# Image feature extraction settings
feats2out=2, # 1st+3D+2.5D features (default)
bin_size=25, # Texture analysis bin size
roi_num=10, # Number of ROIs to process
roi_selection_mode="per_Img", # ROI selection strategy
min_roi_volume=10, # Minimum ROI volume threshold
# Processing options
apply_preprocessing=True, # Apply ROI preprocessing
feature_value_mode="REAL_VALUE", # Fast computation
# Optional parameters (advanced, overrides defaults)
optional_params={
"radiomics_DataType": "CT",
"radiomics_DiscType": "FBN",
"radiomics_isScale": 1
},
# Logging options
report=True # Enable detailed logging
)
```
## 📂Data Structure Requirements
For batch processing or multi-DICOM inputs, the folder structure for images and masks must follow these rules:
- The **final folders** containing images and masks (e.g., ``images/`` and ``masks/``) must **not contain additional subfolders**. Only the image and mask files should be present in these folders.
- There must be **only one folder level** between the parent folder and the image/mask files (e.g., ``parent/images/image001.nii.gz`` or ``parent/masks/mask001.nii.gz``).
- **Warning**: Any additional internal subfolders within the final images or masks folders will cause PySERA to **malfunction** and fail to process the data correctly.
## Patient-Subfolder Organization (NIfTI/DICOM)
**Works with both:**
1. **DICOM Series** (multiple `.dcm` files per patient)
2. **NIfTI Files** (single `.nii.gz` per patient)
### 🏷️Example Structures
**Note:** PySERA supports all major formats, including DICOM, multi-slice DICOM, NIfTI, NRRD, RT Struct, and NumPy arrays.
#### 1️⃣**Flat NIfTI/NRRD Structure**
**✅Correct:**
parent/
├── images/ # All scan files directly here
│ ├── patient001.nii.gz
│ ├── patient002.nii.gz
│ └── patient003.nii.gz
└── masks/ # All mask files directly here
├── patient001.nii.gz
├── patient002.nii.gz
└── patient003.nii.gz
#### 2️⃣**Patient-Subfolder NIfTI Structure**
**✅Correct:**
parent/
├── CT_Images/ # Each patient has own folder
│ ├── patient_01/
│ │ └── scan.nii.gz # Single NIfTI file
│ └── patient_02/
│ └── scan.nii.gz
└── CT_Masks/ # Mirrored structure
├── patient_01/
│ └── segmentation.nii.gz
└── patient_02/
└── segmentation.nii.gz
**Notes:**
- PySERA automatically processes DICOM series organized in patient subfolders.
- **Patient subfolders are required** (one folder per patient).
- **All DICOM slices for one series must be in the same patient folder.**
- **Mask files must mirror the image folder structure.**
If there is a folder for `patient_01` under `CT_Images/`, there must be a corresponding `patient_01` folder under `CT_Masks/` containing the RTSTRUCT or mask.
### 3️⃣DICOM Series Structure
**✅Correct:**
parent/
├── CT_Images/ # --image-input
│ ├── patient_01/ # DICOM series folder
│ │ ├── slice1.dcm # Any number of slices
│ │ ├── slice2.dcm
│ │ └── slice3.dcm
│ └── patient_02/
│ ├── slice1.dcm
│ └── slice2.dcm
└── CT_Masks/ # --mask-input
├── patient_01/
│ └── mask.dcm
└── patient_02/
└── mask.dcm
**❌Incorrect Structure (Will Fail):**
parent/
├── images/
│ ├── subfolder1/
│ │ ├── patient001.nii.gz
│ └── subfolder2/
│ ├── patient002.nii.gz
└── masks/
├── subfolderA/
│ ├── patient001.nii.gz
└── patient002.nii.gz
### 📋PySERA Parameters Reference
| Parameter | Type | Default | Description |
|----------------------|------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **image_input** | str / .npy | Required | Path to the image file, directory, or NumPy file containing the image data. |
| **mask_input** | str / .npy | Required | Path to the mask file, directory, or NumPy file defining the regions of interest. |
| **output_path** | str | ./output_optimized | Directory where the processing results will be saved. |
| **num_workers** | str | auto | Number of CPU cores to use for processing. If auto, uses all available cores. |
| **feats2out** | int | 2 | Feature extraction mode (integer value from 1 to 12). |
| **apply_preprocessing** | bool | False | If True, applies preprocessing to the regions of interest (ROI).**Full preprocessing pipeline control:**<br>- When True:<br> • Applies intensity normalization (CT: [-1000,400] rescaling)<br> • Filters small ROIs (< min_roi_volume voxels)<br> • Optimizes mask connectivity<br> • Logs all preprocessing steps<br>- When False:<br> • Uses raw image/mask without modifications<br> |
| **enable_parallelism** | bool | True | If True, enables parallel processing for the analysis. |
| **min_roi_volume** | int | 10 | Minimum volume threshold for regions of interest (ROI). |
| **bin_size** | int | 25 | Bin size used for texture analysis. |
| **roi_selection_mode** | str | per_Img | **ROI selection strategy:**<br>- **"per_Img"** (default): Selects the top `roi_num` ROIs per image based on size, regardless of label category.<br> • Suitable for single or dominant lesions per scan.<br> • Preserves original spatial relationships.<br>- **"per_region"**: Selects up to `roi_num` ROIs separately for each label category, ensuring balanced representation across regions.<br> • Useful in multi-lesion, multi-label, or longitudinal studies.<br> • Requires consistent ROI labeling across datasets.<br> |
| **roi_num** | int | 10 | Number of ROIs to process. |
| **feature_value_mode** | str | REAL_VALUE | Strategy for handling NaN values. Options: "APPROXIMATE_VALUE" or "REAL_VALUE". **"APPROXIMATE_VALUE"**: Replaces NaN features with substitutes (e.g., very small constants like `1e-30` or synthetic masks) to maintain pipeline continuity.<br>- **"REAL_VALUE"** (default): Keeps NaN values whenever feature extraction fails (e.g., small ROI, numerical instability), preserving the raw outcome without substitution.<br> |
| **report** | bool | True | If True, enables comprehensive report of the processing steps. |
| **optional_params** | dict / JSON | See defaults | Advanced configuration parameters. See the table below for detailed descriptions. |
#### 🔧Advanced configuration parameters (optional_params)
| Parameter | Type | Default | Description |
|-----------------------------|--------|------------------------|-----------------------------------------------------------------------------|
| **TOOLTYPE** | str | "Handcrafted radiomic" | Tool classification. |
| **radiomics_DataType** | str | "OTHER" | Image modality type (CT / PET / MRI / OTHER). |
| **radiomics_DiscType** | str | "FBS" | Discretization type: either 'FBN' (fixed bin numbers) or 'FBS' (fixed bin size or fixed bin width). |
| **radiomics_isScale** | int | 0 | whether to do scaling. Has to be 1 to perform any resampling. If 0, always uses the original voxel dimension. |
| **radiomics_VoxInterp** | str | "Nearest" | Image resampling interpolation type ('nearest', 'linear', or 'cubic'). Note: 'cubic' yeilds inconsistensies with IBSI results. |
| **radiomics_ROIInterp** | str | "Nearest" | ROI resampling interpolation type ('nearest', 'linear', or 'cubic'), default: 'linear' |
| **radiomics_isotVoxSize** | int | 2 | New isotropic voxel size for resampling in 3D. This will be the new voxel size in X, Y and Z dimension. |
| **radiomics_isotVoxSize2D** | int | 2 | New voxel size for resampling slices in 2D. This maintains the Z dimension, and rescales both X and Y to this number. |
| **radiomics_isIsot2D** | int | 0 | (default 0) whether to resample image to isotropic 2D voxels (=1, i.e.keep the original slice thickness) or resample to isotropic 3D voxels (=0). (This is for 1st order features. Higher order 2D features are always calculated with original slice thickness). |
| **radiomics_isGLround** | int | 0 | whether to round voxel intensities to the nearest integer (usually =1 for CT images, =0 for PET and SPECT) |
| **radiomics_isReSegRng** | int | 0 | whether to perform range re-segmentation. The range is defined below in ReSegIntrvl. NOTE: Re-segmentation generally cannot be provided for arbitrary-unit modalities (MRI, SPECT) |
| **radiomics_isOutliers** | int | 0 | Outlier removal flag (1 = remove ±3σ intensities). |
| **radiomics_isQuntzStat** | int | 1 | (default 1) whether to use quantized image to calculate first order statistical features. If 0, no image resample/interp for calculating statistical features. (0 is preferrable for PET images) |
| **radiomics_ReSegIntrvl01** | int | -1000 | Range resegmentation interval. Intensity values outside this interval would be replaced by NaN. |
| **radiomics_ReSegIntrvl02** | int | 400 | Range resegmentation interval. Intensity values outside this interval would be replaced by NaN. Resegmentation upper bound (e.g., 400 for CT). |
| **radiomics_ROI_PV** | float | 0.5 | (default 0.5) ROI partial volume threshold. Used to threshold ROI after resampling: i.e. ROI(ROI<ROI_PV) = 0, ROI(ROI>ROI_PV) = 1. |
| **radiomics_qntz** | str | "Uniform" | An extra option for FBN Discretization Type: Either 'Uniform' quantization or 'Lloyd' for Max-Lloyd quantization. (defualt: Uniform) |
| **radiomics_IVH_Type** | int | 3 | Setting for Intensity Volume Histogram (IVH) Unit type={0: Definite(PET,CT), 1:Arbitrary(MRI,SPECT. This is FNB), 2: use 1000 bins, 3: use same discritization as histogram (for CT)} |
| **radiomics_IVH_DiscCont** | int | 1 | Disc/Cont = {0:Discrete(for CT), 1:Continuous(for CT,PET. This is FBS)} |
| **radiomics_IVH_binSize** | float | 2.0 | Bin size for Intensity Volumen Histogram in case choosing setting 1 for FNB, or setting 0 and either IVH_DiscCont options. |
| **radiomics_isROIsCombined**| int | 0 | Whether to combine ROIs for multiple tumors to one. |
## 📚API Reference
### `pysera.process_batch()`
The main and only function you need for radiomics processing.
## 📊Output Structure
The ``pysera.process_batch()`` function produces two types of output: a **Python dictionary** with processing results and an **Excel file** containing detailed analysis data. Ensure your data follows `Data Structure Requirements` to avoid errors affecting output.
**Python Dictionary Output**
The function returns a dictionary with the following keys:
```python
{
'success': bool, # True if processing completed
'output_path': str, # Path to results directory
'processed_files': int, # Number of files processed
'features_extracted': Dataframe, # extracted features
'processing_time': float, # Processing time in seconds
'logs': list, # Log messages (if logging enabled)
'error': str # Error message (if failed)
}
```
**Excel File Output**
**PySERA** generates an Excel file with three sheets:
📑1. **Radiomics Features**: Lists feature names (e.g., first-order, texture, shape) and their computed values for each processed image-mask pair.
⚙️2. **Selected Parameters**: Details the parameters used for the run (e.g., ``feats2out``, ``bin_size``, ``min_roi_volume``, ``roi_selection_mode``).
⚠️3. **Bugs, Warnings, and Errors**: Logs issues for each patient sample, including ROI labels, warnings (e.g., small ROI volume), and errors (e.g., “No matching mask found for patient001.nii.gz”).
## 🔢Feature Extraction Modes
| Mode | Feature Set | Approx. Features | Best Use Case | Performance Impact |
|------|-------------|------------------|---------------|--------------------|
| **1** | All IBSI-compliant features | 487 | Research studies requiring IBSI compliance | High computational load |
| **2** | 1st-order + 3D + 2.5D (default) | 215 | General purpose radiomics | Balanced performance |
| **3** | 1st-order + 2D + 2.5D | 351 | 2D slice analysis | Moderate |
| **4** | 1st-order + 3D + selected 2D + 2.5D | 351 | Comprehensive spatial analysis | High |
| **5** | All features + Moment invariants | 497 | Maximum feature extraction | Very high |
| **6** | 1st-order + 2D + 2.5D (alternative) | 351 | Secondary 2D analysis | Moderate |
| **7** | 1st-order + 2.5D only | 133 | Quick volumetric analysis | Fast |
| **8** | 1st-order statistics only | 79 | Rapid preliminary analysis | Very fast |
| **9** | 2D texture features only | 164 | Pure 2D texture studies | Moderate |
| **10** | 2.5D transitional features only | 54 | Volumetric transition analysis | Moderate |
| **11** | 3D texture features only | 82 | Pure volumetric analysis | High |
| **12** | Moment invariants only | 10 | Shape characterization | Fast |
**Selection Guidelines**:
- For **clinical workflows**: Modes 2 or 8 (balance of speed/features)
- For **research studies**: Modes 1 or 5 (maximum features)
- For **2D analysis**: Modes 3 or 9
- For **3D analysis**: Modes 11 or 4
- For **quick results**: Modes 7 or 8
## 📁Supported File Formats
### Image Files
- **NIfTI**: `.nii`, `.nii.gz`
- **DICOM**: `.dcm`, `.dicom`, directories with DICOM files
- **NRRD**: `.nrrd`, `.nhdr`
- **NumPy**: `.npy` arrays
- **Multi-DICOM**: Directory structure with patient subdirectories
- **RTSTRUCT**: DICOM-RT Structure Set files for contour-based images.
- **Other**: Any format readable by SimpleITK (e.g., CT, MRI, PET medical images).
### Mask Files
- Same formats as image files: NIfTI, DICOM, NRRD, NumPy, RTSTRUCT.
- **Type**: Binary or labeled segmentation masks.
- **Requirements**:
- Must have the **same dimensions and geometry** as the corresponding image.
- When loading folders containing images and masks, mask file names must **exactly match** the corresponding image file names.
## 🎯Library Examples
See the [`library_examples`](https://github.com/MohammadRSalmanpour/PySERATest/tree/main/library_examples) directory for comprehensive usage examples:
```bash
# Run library_examples
cd library_examples
python basic_usage.py
```
Example use cases:
- Basic single-file processing
- Batch processing with multiprocessing
- High-performance processing
- Custom parameter configuration
- Single-core processing
- Comprehensive analysis with full logging
## ⚡Performance Tips
1. **Use All Cores**: Set `num_workers=auto` to use all CPU cores
2. **Optimize ROI Volume**: Use `min_roi_volume` to filter small regions
3. **Choose Right Mode**: Use `feats2out=8` for speed, `feats2out=5` for comprehensive analysis
4. **Enable Preprocessing**: `apply_preprocessing=True` improves results
5. **Batch Processing**: Process multiple files in one call for efficiency
## ❓Troubleshooting
### Quick Guide
1. **Import Error**: `pip install -e .` in the project directory
2. **Missing Dependencies**: `pip install -r requirements-library.txt`
3. **File Not Found**: Check file paths and formats
4. **Memory Issues**: Reduce `num_workers` or increase `min_roi_volume`
### Get Help
- **Installation Issues**: See [INSTALL.md](INSTALL.md)
- **Examples**: Run `python examples/basic_usage.py`
## 🕒Version History
For detailed release notes, explanations of updates, and technical changes, please see the
👉 [Development Report](https://github.com/MohammadRSalmanpour/PySERATest/blob/main/development_report.md)
v1
├── v1.0
│ ├── v1.0.2 - 2025-08-20
│ │ - 🛠️change PySera name to pysera
│ │
│ ├── v1.0.1 - 2025-08-20
│ │ - 🐛fixing bug in numpy array file processing in in-memory mode
│ │
│ └── v1.0.0 - 2025-08-19
│ - 🛠️Structural modifications
│ - ⚡Improved image loader
│ - ✨Added two strategies for feature value mode (real vs. approximate)
│ - 🔢New parameter for number of ROIs to select
│ - ✨Synthetic generation for ROI lesions smaller than 10 voxels
│ - ✨New strategy for ROI selection (image-based vs. region-based)
│ - 💾Disk-based processing to prevent RAM overflow
│ - 🐛Fixed NaN value bug in some features
│ - ✨Added support for processing NumPy array files in addition to file paths
│ - ✅IBSI compliance validation
│ - 📊New output structure including parameter set, error log, and warning report
│ - 📦Updated package dependencies
v0
├── v0.0
│ └── v0.0.0 - 2025-08-13
│ - 🔧IBSI Standardization
│ - 🐛Some Bug fix
│
└── initial version - 2022-02-12
- 🎉Initial implementation
- 🛠️Core radiomics pipeline
- 📄Support for some types of files
## 📬Contact
SERA is available **free of charge**.
For access, questions, or feedback:
**Dr. Mohammad R. Salmanpour (Team Lead)**
📧[msalman@bccrc.ca](mailto:msalman@bccrc.ca) | [m.salmanpoor66@gmail.com](mailto:m.salmanpoor66@gmail.com), [m.salmanpour@ubc.ca](mailto:m.salmanpour@ubc.ca)
---
## 🛠️Maintenance
For technical support and maintenance inquiries, please contact:
**Dr. Mohammad R. Salmanpour (Team Lead)**
msalman@bccrc.ca – m.salmanpoor66@gmail.com – m.salmanpour@ubc.ca
**Amir Hossein Pouria**
amirporia99.1378@gmail.com
## 👥Authors
- **Dr. Mohammad R. Salmanpour (Team Lead, Fund Provider, Evaluator, Medical Imaging Expert, Backend Development, Code Refactoring, Debugging, Library Management, IBSI Standardization, and Activation of the PySERA Library, and GUI Development in 3D Slicer)** – [msalman@bccrc.ca](mailto:msalman@bccrc.ca), [m.salmanpoor66@gmail.com](mailto:m.salmanpoor66@gmail.com), [m.salmanpour@ubc.ca](mailto:m.salmanpour@ubc.ca)
- **Amir Hossein Pouria (Assistant Team Lead; Backend Development, Code Refactoring, Debugging, and Library Management)** – [amirporia99.1378@gmail.com](mailto:amirporia99.1378@gmail.com)
- **Sirwan Barichin (IBSI Standardization, Debugging, and Activation of the PySERA Library, and GUI Development in 3D Slicer)** – [sirwanbarichin@gmail.com](mailto:sirwanbarichin@gmail.com)
- **Yasaman Salehi (Backend Development, Code Refactoring, and Debugging)** – [y.salehi7698@gmail.com](mailto:y.salehi7698@gmail.com)
- **Sonya Falahati (Tesing and Data prepration)** – [falahati.sonya@gmail.com](mailto:falahati.sonya@gmail.com)
- **Dr. Mehrdad Oveisi (Evaluator, Software Engineer, and Advisor)** – [moveisi@cs.ubc.ca](mailto:moveisi@cs.ubc.ca)
- **Dr. Arman Rahmim (Fund Provider, Medical Imaging Expert, Evaluator, and Advisor)** – [arman.rahmim@ubc.ca](mailto:arman.rahmim@ubc.ca), [arahmim@bccrc.ca ](mailto:arahmim@bccrc.ca)
## 📚Citation
```bibtex
@software{pysera2025,
title={pysera: A Simple Python Library for Radiomics Feature Extraction},
author={pysera Team},
year={2025},
url={https://github.com/MohammadRSalmanpour/PySERA}
}
```
## 📜License
This open-source software is released under the **MIT License**, which grants permission to use, modify, and distribute it for any purpose, including research or commercial use, without requiring modified versions to be shared as open source. See the [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/MohammadRSalmanpour/PySERA/issues)
- **Documentation**: This README and the included guides
- **Examples**: See `examples/basic_usage.py`
## Acknowledgment
This study was supported by:
- [🔬 **Qu**antitative **R**adiomolecular **I**maging and **T**herapy (Qurit) Lab, University of British Columbia, Vancouver, BC, Canada](https://www.qurit.ca)
- [🏥 BC Cancer Research Institute, Department of Basic and Translational Research, Vancouver, BC, Canada](https://www.bccrc.ca/)
- [💻 **Vir**tual **Collaboration (VirCollab) Group, Vancouver, BC, Canada](https://www.vircollab.com)
- [🏭 **Tec**hnological **Vi**rtual **Co**llaboration **Corp**oration (TECVICO Corp.), Vancouver, BC, Canada](https://www.tecvico.com)
We gratefully acknowledge funding from the💰 Natural Sciences and Engineering Research Council of Canada (**NSERC**) Idea to Innovation [**I2I**] Grant **GR034192**.
---
*PySERA - Simple, powerful radiomics in one function call. 🚀*
Raw data
{
"_id": null,
"home_page": "https://github.com/MohammadRSalmanpour/PySERA",
"name": "pysera",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"Mohammad R. Salmanpour\" <M.salmanpoor66@gmail.com>, Amir Hossein Pouria <amirporia99.1378@gmail.com>",
"keywords": "medical-imaging, Standardized-Radiomics-Feature-Extraction, Quantitative-Analysis, IBSI-Standardization, healthcare",
"author": "Mohammad R. Salmanpour, Amir Hossein Pouria",
"author_email": "\"Mohammad R. Salmanpour\" <M.salmanpoor66@gmail.com>, Amir Hossein Pouria <amirporia99.1378@gmail.com>, Mehrdad Oveisi <moveisi@cs.ubc.ca>, Arman Rahmim <arman.rahmim@ubc.ca>",
"download_url": "https://files.pythonhosted.org/packages/26/38/222702b59e7ddf0b44c729533e0b7a17182af576e869591345a088e59bd6/pysera-1.0.2.tar.gz",
"platform": null,
"description": "# PySERA: Python-Based Standardized Extraction for Radiomics Analysis \u2013 Python Radiomics Script and Library\r\n\r\n[](https://www.python.org/downloads/)\r\n[](LICENSE)\r\n[](https://pypi.org/project/pysera/)\r\n\r\n**PySERA** (Python-based Standardized Extraction for Radiomics Analysis) 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 and comprehensive logging capabilities. This is a development version and the final version (v1.1.0) will release by September 2025. \r\n\r\n## \ud83d\udd0d Table of Contents\r\n- [\ud83e\udde9IBSI (Image Biomarker Standardisation Initiative) Standardization-1.0](#IBSI-Standardization)\r\n- [\ud83d\udee0\ufe0fKey Features](#key-features)\r\n- [\ud83d\udce5Installation](#installation)\r\n - [\ud83c\udf10GitHub Installation](#github-installation)\r\n - [\ud83d\udcbbPython Script - Command Line Interface (CLI)](#python-script---command-line-interface-cli)\r\n - [\ud83d\udce6Library Installation via pip](#library-installation-via-pip)\r\n- [\ud83d\udcdaLibrary Usage](#library-usage)\r\n - [\ud83d\udcc2Single File Processing](#single-file-processing)\r\n - [\ud83e\udde0In-Memory Array Processing](#in-memory-array-processing)\r\n - [\u26a1Parallel Batch Processing](#parallel-batch-processing)\r\n - [\ud83d\udd27Advanced Configuration](#advanced-configuration)\r\n- [\ud83d\udcc2Data Structure Requirements](#data-structure-requirements)\r\n- [\ud83d\udccbPySERA Parameters Reference](#pysera-parameters-reference)\r\n- [\ud83d\udcdaAPI Reference](#api-reference)\r\n- [\ud83d\udccaOutput Structure](#output-structure)\r\n- [\ud83d\udd22Feature Extraction Modes](#feature-extraction-modes)\r\n- [\ud83d\udcc1Supported File Formats](#supported-file-formats)\r\n- [\ud83c\udfafLibrary Examples](#library-examples)\r\n- [\u26a1Performance Tips](#performance-tips)\r\n- [\u2753Troubleshooting](#troubleshooting)\r\n- [\ud83d\udd52Version History](#Version-History)\r\n- [\ud83d\udcecContact](#contact)\r\n- [\ud83d\udc65Authors](#authors)\r\n- [\ud83d\ude4fAcknowledgment](#acknowledgment)\r\n- [\ud83d\udcdcLicense](#license)\r\n\r\n## \u2728IBSI Standardization\r\nBoth the script and library have been rigorously standardized based on **IBSI** (Image Biomarker Standardisation Initiative) Standardization 1.0.\r\nSee the detailed evaluation and test cases here: [IBSI_Evaluation Folder](https://github.com/MohammadRSalmanpour/PySERATest/tree/main/IBSI_Evaluation)\r\n\r\n## \ud83d\udee0\ufe0fKey Features\r\n\r\nPySERA provides a **single-function API** that handles all radiomics processing:\r\n\r\n```python\r\nimport pysera\r\n\r\nresult = pysera.process_batch(\r\n image_input=\"image.nii.gz\",\r\n mask_input=\"mask.nii.gz\",\r\n output_path=\"./results\"\r\n)\r\n```\r\n\r\nThat's it! \ud83c\udf89 All the complexity of multiprocessing, error & warning reports, file format handling, and feature extraction is handled automatically.\r\n\r\n- **Single Function API**: One function does everything - `pysera.process_batch()`\r\n- **Multi-format Support**: NIfTI, DICOM, NRRD, RTSTRUCT, NumPy arrays, and more\r\n- **Automatic Multiprocessing**: Built-in parallel processing for maximum performance\r\n- **Comprehensive Logging**: Excel export functionality for detailed analysis\r\n- **Extensive Features**: 497 radiomics features with 12 extraction modes\r\n- **Medical Image Optimized**: Designed for CT, MRI, PET, and other medical imaging\r\n\r\n## \ud83d\udce5Installation\r\n\r\nPySERA can be installed as a Python library for integration into your projects or as a standalone script for command-line usage. It supports Windows, macOS, and Linux. Below are the installation options.\r\n\r\n### \ud83c\udf10GitHub Installation \r\n\r\nFor users who want to develop with the source code or run PySERA as a standalone command-line tool (CLI) without installing it as a Python package, you can clone the repository from GitHub.\r\nThis gives you access to the standalone script radiomics_standalone.py and all example files. After installing the dependencies, you can run the script directly (see the [\ud83d\udcbbPython Script - Command Line Interface (CLI)](#python-script---command-line-interface-cli) section).\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/MohammadRSalmanpour/PySERA.git\r\ncd pysera\r\n```\r\n### macOS/Linux Installation\r\n#### Quick Setup (Recommended):\r\n\r\n```bash\r\n# Quick setup (creates a virtual environment and installs everything)\r\n./dev_setup.sh\r\n```\r\n#### Manual Setup:\r\n\r\n```bash\r\npython3 -m venv venv\r\nsource venv/bin/activate\r\npip install -e .\r\n\r\n```\r\n### Windows Setup\r\n#### Quick Setup (Recommended):\r\n\r\n```bash\r\n# Quick setup\r\n./dev_setup.sh\r\n```\r\n\r\n#### Manual Setup\r\n\r\n```bash\r\n\r\npython3 -m venv venv\r\n.\\venv\\Scripts\\activate\r\npip install -r requirements.txt\r\n\r\n```\r\n\r\n### \ud83d\udcbbPython Script - Command Line Interface (CLI)\r\n\r\nIf you just want to run the CLI without installing the library into Python,the standalone script 'radiomics_standalone.py' provides a command-line interface for radiomics processing :\r\n\r\n```bash\r\n# Process single files\r\npython radiomics_standalone.py \\\r\n --image_input image.nii.gz \\\r\n --mask_input mask.nii.gz \\\r\n --output ./results\r\n\r\n# Batch processing (folders)\r\npython radiomics_standalone.py \\\r\n --image_input ./images \\\r\n --mask_input ./masks \\\r\n --output ./results \\\r\n --num_workers 4\r\n```\r\n\r\n### \ud83d\udce6Library Installation via pip\r\n\r\nInstall the PySERA library directly from PyPI:\r\n\r\n```bash\r\npip install pysera\r\n```\r\n\r\n## \ud83d\udcdaLibrary Usage\r\n\r\nOnce installed, you can use PySERA directly in your Python code.\r\n\r\n### \ud83d\udcc2Single File Processing\r\n\r\n```python\r\nimport pysera\r\n\r\n# Process single image-mask pair\r\nresult = pysera.process_batch(\r\n image_input=\"scan.nii.gz\",\r\n mask_input=\"mask.nii.gz\",\r\n output_path=\"./results\"\r\n)\r\n\r\nprint(f\"Success: {result['success']}\")\r\nprint(f\"Features extracted: {result['features_extracted']}\")\r\nprint(f\"Processing time: {result['processing_time']:.2f} seconds\")\r\n```\r\n\r\n### \ud83e\udde0In-Memory Array Processing\r\n\r\n```python\r\nimport numpy as np\r\nimport nibabel as nib\r\nimport pysera\r\n\r\n# Load image and mask as NumPy arrays (for example, using nibabel)\r\nimage_array = nib.load(\"patient002_image.nii.gz\").get_fdata()\r\nmask_array = nib.load(\"patient002_mask.nii.gz\").get_fdata()\r\n\r\n# Process the image and mask directly from memory\r\nresult = pysera.process_batch(\r\n image_input=image_array,\r\n mask_input=mask_array,\r\n output_path=\"./results\"\r\n)\r\n\r\n# Display results\r\nprint(f\"Success: {result['success']}\")\r\nprint(f\"Features extracted: {result['features_extracted']}\")\r\nprint(f\"Processing time: {result['processing_time']:.2f} seconds\")\r\n```\r\n\r\n### \u26a1Parallel Batch Processing\r\n\r\n```python\r\nimport pysera\r\n\r\n# Process multiple files with 4 CPU cores\r\nresult = pysera.process_batch(\r\n image_input=\"./patient_scans\",\r\n mask_input=\"./patient_masks\", \r\n output_path=\"./results\",\r\n num_workers=\"4\", # Use 4 CPU cores\r\n feats2out=5, # Extract all features + Moment\r\n apply_preprocessing=True, # Apply ROI preprocessing\r\n)\r\n\r\nprint(f\"Processed {result['processed_files']} files\")\r\nprint(f\"Total processing time: {result['processing_time']:.2f} seconds\")\r\n```\r\n\r\n## \ud83d\udd27Advanced Configuration\r\n\r\n```python\r\nimport pysera\r\n\r\n# Comprehensive processing with custom parameters\r\nresult = pysera.process_batch(\r\n image_input=\"image.nii.gz\",\r\n mask_input=\"mask.nii.gz\",\r\n output_path=\"./results\",\r\n \r\n # Performance settings\r\n num_workers=\"auto\", # Use all available CPU cores\r\n enable_parallelism=True, # Enable multiprocessing\r\n \r\n # Image feature extraction settings\r\n feats2out=2, # 1st+3D+2.5D features (default)\r\n bin_size=25, # Texture analysis bin size\r\n roi_num=10, # Number of ROIs to process\r\n roi_selection_mode=\"per_Img\", # ROI selection strategy\r\n min_roi_volume=10, # Minimum ROI volume threshold\r\n \r\n # Processing options\r\n apply_preprocessing=True, # Apply ROI preprocessing\r\n feature_value_mode=\"REAL_VALUE\", # Fast computation\r\n\r\n # Optional parameters (advanced, overrides defaults)\r\n optional_params={\r\n \"radiomics_DataType\": \"CT\",\r\n \"radiomics_DiscType\": \"FBN\",\r\n \"radiomics_isScale\": 1\r\n },\r\n \r\n # Logging options\r\n report=True # Enable detailed logging\r\n)\r\n```\r\n\r\n\r\n## \ud83d\udcc2Data Structure Requirements\r\n\r\nFor batch processing or multi-DICOM inputs, the folder structure for images and masks must follow these rules:\r\n - The **final folders** containing images and masks (e.g., ``images/`` and ``masks/``) must **not contain additional subfolders**. Only the image and mask files should be present in these folders.\r\n - There must be **only one folder level** between the parent folder and the image/mask files (e.g., ``parent/images/image001.nii.gz`` or ``parent/masks/mask001.nii.gz``).\r\n - **Warning**: Any additional internal subfolders within the final images or masks folders will cause PySERA to **malfunction** and fail to process the data correctly.\r\n\r\n## Patient-Subfolder Organization (NIfTI/DICOM)\r\n\r\n**Works with both:**\r\n\r\n1. **DICOM Series** (multiple `.dcm` files per patient) \r\n2. **NIfTI Files** (single `.nii.gz` per patient)\r\n\r\n\r\n### \ud83c\udff7\ufe0fExample Structures\r\n\r\n**Note:** PySERA supports all major formats, including DICOM, multi-slice DICOM, NIfTI, NRRD, RT Struct, and NumPy arrays.\r\n\r\n#### 1\ufe0f\u20e3**Flat NIfTI/NRRD Structure** \r\n\r\n**\u2705Correct:**\r\n \r\n parent/\r\n \u251c\u2500\u2500 images/ # All scan files directly here\r\n \u2502 \u251c\u2500\u2500 patient001.nii.gz\r\n \u2502 \u251c\u2500\u2500 patient002.nii.gz\r\n \u2502 \u2514\u2500\u2500 patient003.nii.gz\r\n \u2514\u2500\u2500 masks/ # All mask files directly here\r\n \u251c\u2500\u2500 patient001.nii.gz\r\n \u251c\u2500\u2500 patient002.nii.gz\r\n \u2514\u2500\u2500 patient003.nii.gz\r\n\r\n#### 2\ufe0f\u20e3**Patient-Subfolder NIfTI Structure**\r\n\r\n**\u2705Correct:**\r\n\r\n parent/\r\n \u251c\u2500\u2500 CT_Images/ # Each patient has own folder\r\n \u2502 \u251c\u2500\u2500 patient_01/\r\n \u2502 \u2502 \u2514\u2500\u2500 scan.nii.gz # Single NIfTI file\r\n \u2502 \u2514\u2500\u2500 patient_02/\r\n \u2502 \u2514\u2500\u2500 scan.nii.gz\r\n \u2514\u2500\u2500 CT_Masks/ # Mirrored structure\r\n \u251c\u2500\u2500 patient_01/\r\n \u2502 \u2514\u2500\u2500 segmentation.nii.gz\r\n \u2514\u2500\u2500 patient_02/\r\n \u2514\u2500\u2500 segmentation.nii.gz\r\n \r\n**Notes:** \r\n\r\n- PySERA automatically processes DICOM series organized in patient subfolders. \r\n- **Patient subfolders are required** (one folder per patient). \r\n- **All DICOM slices for one series must be in the same patient folder.** \r\n- **Mask files must mirror the image folder structure.** \r\n If there is a folder for `patient_01` under `CT_Images/`, there must be a corresponding `patient_01` folder under `CT_Masks/` containing the RTSTRUCT or mask.\r\n \r\n \r\n### 3\ufe0f\u20e3DICOM Series Structure\r\n\r\n**\u2705Correct:**\r\n \r\n\r\n parent/\r\n \u251c\u2500\u2500 CT_Images/ # --image-input\r\n \u2502 \u251c\u2500\u2500 patient_01/ # DICOM series folder\r\n \u2502 \u2502 \u251c\u2500\u2500 slice1.dcm # Any number of slices\r\n \u2502 \u2502 \u251c\u2500\u2500 slice2.dcm\r\n \u2502 \u2502 \u2514\u2500\u2500 slice3.dcm\r\n \u2502 \u2514\u2500\u2500 patient_02/\r\n \u2502 \u251c\u2500\u2500 slice1.dcm\r\n \u2502 \u2514\u2500\u2500 slice2.dcm\r\n \u2514\u2500\u2500 CT_Masks/ # --mask-input\r\n \u251c\u2500\u2500 patient_01/\r\n \u2502 \u2514\u2500\u2500 mask.dcm \r\n \u2514\u2500\u2500 patient_02/\r\n \u2514\u2500\u2500 mask.dcm\r\n\r\n \r\n**\u274cIncorrect Structure (Will Fail):**\r\n\r\n parent/\r\n \u251c\u2500\u2500 images/\r\n \u2502 \u251c\u2500\u2500 subfolder1/\r\n \u2502 \u2502 \u251c\u2500\u2500 patient001.nii.gz\r\n \u2502 \u2514\u2500\u2500 subfolder2/\r\n \u2502 \u251c\u2500\u2500 patient002.nii.gz\r\n \u2514\u2500\u2500 masks/\r\n \u251c\u2500\u2500 subfolderA/\r\n \u2502 \u251c\u2500\u2500 patient001.nii.gz\r\n \u2514\u2500\u2500 patient002.nii.gz\r\n\r\n### \ud83d\udccbPySERA Parameters Reference\r\n\r\n\r\n| Parameter | Type | Default | Description |\r\n|----------------------|------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| **image_input** | str / .npy | Required | Path to the image file, directory, or NumPy file containing the image data. |\r\n| **mask_input** | str / .npy | Required | Path to the mask file, directory, or NumPy file defining the regions of interest. |\r\n| **output_path** | str | ./output_optimized | Directory where the processing results will be saved. |\r\n| **num_workers** | str | auto | Number of CPU cores to use for processing. If auto, uses all available cores. |\r\n| **feats2out** | int | 2 | Feature extraction mode (integer value from 1 to 12). | \r\n| **apply_preprocessing** | bool | False | If True, applies preprocessing to the regions of interest (ROI).**Full preprocessing pipeline control:**<br>- When True:<br> \u2022 Applies intensity normalization (CT: [-1000,400] rescaling)<br> \u2022 Filters small ROIs (< min_roi_volume voxels)<br> \u2022 Optimizes mask connectivity<br> \u2022 Logs all preprocessing steps<br>- When False:<br> \u2022 Uses raw image/mask without modifications<br> | \r\n| **enable_parallelism** | bool | True | If True, enables parallel processing for the analysis. |\r\n| **min_roi_volume** | int | 10 | Minimum volume threshold for regions of interest (ROI). |\r\n| **bin_size** | int | 25 | Bin size used for texture analysis. |\r\n| **roi_selection_mode** | str | per_Img | **ROI selection strategy:**<br>- **\"per_Img\"** (default): Selects the top `roi_num` ROIs per image based on size, regardless of label category.<br> \u2022 Suitable for single or dominant lesions per scan.<br> \u2022 Preserves original spatial relationships.<br>- **\"per_region\"**: Selects up to `roi_num` ROIs separately for each label category, ensuring balanced representation across regions.<br> \u2022 Useful in multi-lesion, multi-label, or longitudinal studies.<br> \u2022 Requires consistent ROI labeling across datasets.<br> |\r\n| **roi_num** | int | 10 | Number of ROIs to process. |\r\n| **feature_value_mode** | str | REAL_VALUE | Strategy for handling NaN values. Options: \"APPROXIMATE_VALUE\" or \"REAL_VALUE\". **\"APPROXIMATE_VALUE\"**: Replaces NaN features with substitutes (e.g., very small constants like `1e-30` or synthetic masks) to maintain pipeline continuity.<br>- **\"REAL_VALUE\"** (default): Keeps NaN values whenever feature extraction fails (e.g., small ROI, numerical instability), preserving the raw outcome without substitution.<br> |\r\n| **report** | bool | True | If True, enables comprehensive report of the processing steps. |\r\n| **optional_params** | dict / JSON | See defaults | Advanced configuration parameters. See the table below for detailed descriptions. |\r\n\r\n#### \ud83d\udd27Advanced configuration parameters (optional_params)\r\n\r\n\r\n| Parameter | Type | Default | Description |\r\n|-----------------------------|--------|------------------------|-----------------------------------------------------------------------------|\r\n| **TOOLTYPE** | str | \"Handcrafted radiomic\" | Tool classification. |\r\n| **radiomics_DataType** | str | \"OTHER\" | Image modality type (CT / PET / MRI / OTHER). |\r\n| **radiomics_DiscType** | str | \"FBS\" | Discretization type: either 'FBN' (fixed bin numbers) or 'FBS' (fixed bin size or fixed bin width). |\r\n| **radiomics_isScale** | int | 0 | whether to do scaling. Has to be 1 to perform any resampling. If 0, always uses the original voxel dimension. |\r\n| **radiomics_VoxInterp** | str | \"Nearest\" | Image resampling interpolation type ('nearest', 'linear', or 'cubic'). Note: 'cubic' yeilds inconsistensies with IBSI results. |\r\n| **radiomics_ROIInterp** | str | \"Nearest\" | ROI resampling interpolation type ('nearest', 'linear', or 'cubic'), default: 'linear' |\r\n| **radiomics_isotVoxSize** | int | 2 | New isotropic voxel size for resampling in 3D. This will be the new voxel size in X, Y and Z dimension. |\r\n| **radiomics_isotVoxSize2D** | int | 2 | New voxel size for resampling slices in 2D. This maintains the Z dimension, and rescales both X and Y to this number. |\r\n| **radiomics_isIsot2D** | int | 0 | (default 0) whether to resample image to isotropic 2D voxels (=1, i.e.keep the original slice thickness) or resample to isotropic 3D voxels (=0). (This is for 1st order features. Higher order 2D features are always calculated with original slice thickness). |\r\n| **radiomics_isGLround** | int | 0 | whether to round voxel intensities to the nearest integer (usually =1 for CT images, =0 for PET and SPECT) |\r\n| **radiomics_isReSegRng** | int | 0 | whether to perform range re-segmentation. The range is defined below in ReSegIntrvl. NOTE: Re-segmentation generally cannot be provided for arbitrary-unit modalities (MRI, SPECT) |\r\n| **radiomics_isOutliers** | int | 0 | Outlier removal flag (1 = remove \u00b13\u03c3 intensities). |\r\n| **radiomics_isQuntzStat** | int | 1 | (default 1) whether to use quantized image to calculate first order statistical features. If 0, no image resample/interp for calculating statistical features. (0 is preferrable for PET images) |\r\n| **radiomics_ReSegIntrvl01** | int | -1000 | Range resegmentation interval. Intensity values outside this interval would be replaced by NaN. |\r\n| **radiomics_ReSegIntrvl02** | int | 400 | Range resegmentation interval. Intensity values outside this interval would be replaced by NaN. Resegmentation upper bound (e.g., 400 for CT). |\r\n| **radiomics_ROI_PV** | float | 0.5 | (default 0.5) ROI partial volume threshold. Used to threshold ROI after resampling: i.e. ROI(ROI<ROI_PV) = 0, ROI(ROI>ROI_PV) = 1. |\r\n| **radiomics_qntz** | str | \"Uniform\" | An extra option for FBN Discretization Type: Either 'Uniform' quantization or 'Lloyd' for Max-Lloyd quantization. (defualt: Uniform) |\r\n| **radiomics_IVH_Type** | int | 3 | Setting for Intensity Volume Histogram (IVH) Unit type={0: Definite(PET,CT), 1:Arbitrary(MRI,SPECT. This is FNB), 2: use 1000 bins, 3: use same discritization as histogram (for CT)} |\r\n| **radiomics_IVH_DiscCont** | int | 1 | Disc/Cont = {0:Discrete(for CT), 1:Continuous(for CT,PET. This is FBS)} |\r\n| **radiomics_IVH_binSize** | float | 2.0 | Bin size for Intensity Volumen Histogram in case choosing setting 1 for FNB, or setting 0 and either IVH_DiscCont options. |\r\n| **radiomics_isROIsCombined**| int | 0 | Whether to combine ROIs for multiple tumors to one. |\r\n\r\n\r\n\r\n## \ud83d\udcdaAPI Reference\r\n\r\n### `pysera.process_batch()`\r\n\r\nThe main and only function you need for radiomics processing.\r\n\r\n\r\n## \ud83d\udccaOutput Structure\r\n\r\nThe ``pysera.process_batch()`` function produces two types of output: a **Python dictionary** with processing results and an **Excel file** containing detailed analysis data. Ensure your data follows `Data Structure Requirements` to avoid errors affecting output.\r\n\r\n**Python Dictionary Output**\r\n\r\nThe function returns a dictionary with the following keys:\r\n\r\n```python\r\n{\r\n 'success': bool, # True if processing completed\r\n 'output_path': str, # Path to results directory\r\n 'processed_files': int, # Number of files processed\r\n 'features_extracted': Dataframe, # extracted features\r\n 'processing_time': float, # Processing time in seconds\r\n 'logs': list, # Log messages (if logging enabled)\r\n 'error': str # Error message (if failed)\r\n}\r\n```\r\n**Excel File Output**\r\n\r\n**PySERA** generates an Excel file with three sheets:\r\n\r\n\ud83d\udcd11. **Radiomics Features**: Lists feature names (e.g., first-order, texture, shape) and their computed values for each processed image-mask pair.\r\n\r\n\u2699\ufe0f2. **Selected Parameters**: Details the parameters used for the run (e.g., ``feats2out``, ``bin_size``, ``min_roi_volume``, ``roi_selection_mode``).\r\n\r\n\u26a0\ufe0f3. **Bugs, Warnings, and Errors**: Logs issues for each patient sample, including ROI labels, warnings (e.g., small ROI volume), and errors (e.g., \u201cNo matching mask found for patient001.nii.gz\u201d).\r\n\r\n\r\n## \ud83d\udd22Feature Extraction Modes\r\n\r\n\r\n| Mode | Feature Set | Approx. Features | Best Use Case | Performance Impact |\r\n|------|-------------|------------------|---------------|--------------------|\r\n| **1** | All IBSI-compliant features | 487 | Research studies requiring IBSI compliance | High computational load |\r\n| **2** | 1st-order + 3D + 2.5D (default) | 215 | General purpose radiomics | Balanced performance |\r\n| **3** | 1st-order + 2D + 2.5D | 351 | 2D slice analysis | Moderate |\r\n| **4** | 1st-order + 3D + selected 2D + 2.5D | 351 | Comprehensive spatial analysis | High |\r\n| **5** | All features + Moment invariants | 497 | Maximum feature extraction | Very high |\r\n| **6** | 1st-order + 2D + 2.5D (alternative) | 351 | Secondary 2D analysis | Moderate |\r\n| **7** | 1st-order + 2.5D only | 133 | Quick volumetric analysis | Fast |\r\n| **8** | 1st-order statistics only | 79 | Rapid preliminary analysis | Very fast |\r\n| **9** | 2D texture features only | 164 | Pure 2D texture studies | Moderate |\r\n| **10** | 2.5D transitional features only | 54 | Volumetric transition analysis | Moderate |\r\n| **11** | 3D texture features only | 82 | Pure volumetric analysis | High |\r\n| **12** | Moment invariants only | 10 | Shape characterization | Fast |\r\n\r\n**Selection Guidelines**:\r\n- For **clinical workflows**: Modes 2 or 8 (balance of speed/features)\r\n- For **research studies**: Modes 1 or 5 (maximum features)\r\n- For **2D analysis**: Modes 3 or 9\r\n- For **3D analysis**: Modes 11 or 4\r\n- For **quick results**: Modes 7 or 8\r\n\r\n## \ud83d\udcc1Supported File Formats\r\n\r\n### Image Files\r\n- **NIfTI**: `.nii`, `.nii.gz`\r\n- **DICOM**: `.dcm`, `.dicom`, directories with DICOM files\r\n- **NRRD**: `.nrrd`, `.nhdr`\r\n- **NumPy**: `.npy` arrays\r\n- **Multi-DICOM**: Directory structure with patient subdirectories\r\n- **RTSTRUCT**: DICOM-RT Structure Set files for contour-based images.\r\n- **Other**: Any format readable by SimpleITK (e.g., CT, MRI, PET medical images).\r\n\r\n### Mask Files\r\n- Same formats as image files: NIfTI, DICOM, NRRD, NumPy, RTSTRUCT.\r\n - **Type**: Binary or labeled segmentation masks.\r\n\r\n - **Requirements**:\r\n - Must have the **same dimensions and geometry** as the corresponding image.\r\n - When loading folders containing images and masks, mask file names must **exactly match** the corresponding image file names.\r\n\r\n## \ud83c\udfafLibrary Examples\r\n\r\nSee the [`library_examples`](https://github.com/MohammadRSalmanpour/PySERATest/tree/main/library_examples) directory for comprehensive usage examples:\r\n\r\n```bash\r\n# Run library_examples\r\ncd library_examples\r\npython basic_usage.py\r\n```\r\n\r\nExample use cases:\r\n- Basic single-file processing\r\n- Batch processing with multiprocessing\r\n- High-performance processing\r\n- Custom parameter configuration\r\n- Single-core processing\r\n- Comprehensive analysis with full logging\r\n\r\n## \u26a1Performance Tips\r\n\r\n1. **Use All Cores**: Set `num_workers=auto` to use all CPU cores\r\n2. **Optimize ROI Volume**: Use `min_roi_volume` to filter small regions\r\n3. **Choose Right Mode**: Use `feats2out=8` for speed, `feats2out=5` for comprehensive analysis\r\n4. **Enable Preprocessing**: `apply_preprocessing=True` improves results\r\n5. **Batch Processing**: Process multiple files in one call for efficiency\r\n\r\n## \u2753Troubleshooting\r\n\r\n### Quick Guide\r\n\r\n1. **Import Error**: `pip install -e .` in the project directory\r\n2. **Missing Dependencies**: `pip install -r requirements-library.txt`\r\n3. **File Not Found**: Check file paths and formats\r\n4. **Memory Issues**: Reduce `num_workers` or increase `min_roi_volume`\r\n\r\n### Get Help\r\n\r\n- **Installation Issues**: See [INSTALL.md](INSTALL.md)\r\n- **Examples**: Run `python examples/basic_usage.py`\r\n\r\n## \ud83d\udd52Version History\r\n\r\nFor detailed release notes, explanations of updates, and technical changes, please see the \r\n\ud83d\udc49 [Development Report](https://github.com/MohammadRSalmanpour/PySERATest/blob/main/development_report.md)\r\n\r\n v1\r\n \u251c\u2500\u2500 v1.0\r\n \u2502 \u251c\u2500\u2500 v1.0.2 - 2025-08-20\r\n \u2502 \u2502 - \ud83d\udee0\ufe0fchange PySera name to pysera\r\n \u2502 \u2502\r\n \u2502 \u251c\u2500\u2500 v1.0.1 - 2025-08-20\r\n \u2502 \u2502 - \ud83d\udc1bfixing bug in numpy array file processing in in-memory mode\r\n \u2502 \u2502\r\n \u2502 \u2514\u2500\u2500 v1.0.0 - 2025-08-19\r\n \u2502 - \ud83d\udee0\ufe0fStructural modifications\r\n \u2502 - \u26a1Improved image loader \r\n \u2502 - \u2728Added two strategies for feature value mode (real vs. approximate)\r\n \u2502 - \ud83d\udd22New parameter for number of ROIs to select\r\n \u2502 - \u2728Synthetic generation for ROI lesions smaller than 10 voxels\r\n \u2502 - \u2728New strategy for ROI selection (image-based vs. region-based)\r\n \u2502 - \ud83d\udcbeDisk-based processing to prevent RAM overflow\r\n \u2502 - \ud83d\udc1bFixed NaN value bug in some features\r\n \u2502 - \u2728Added support for processing NumPy array files in addition to file paths\r\n \u2502 - \u2705IBSI compliance validation\r\n \u2502 - \ud83d\udccaNew output structure including parameter set, error log, and warning report\r\n \u2502 - \ud83d\udce6Updated package dependencies\r\n v0\r\n \u251c\u2500\u2500 v0.0\r\n \u2502 \u2514\u2500\u2500 v0.0.0 - 2025-08-13\r\n \u2502 - \ud83d\udd27IBSI Standardization \r\n \u2502 - \ud83d\udc1bSome Bug fix\r\n \u2502\r\n \u2514\u2500\u2500 initial version - 2022-02-12\r\n - \ud83c\udf89Initial implementation \r\n - \ud83d\udee0\ufe0fCore radiomics pipeline \r\n - \ud83d\udcc4Support for some types of files\r\n\r\n## \ud83d\udcecContact\r\nSERA is available **free of charge**.\r\nFor access, questions, or feedback:\r\n\r\n**Dr. Mohammad R. Salmanpour (Team Lead)** \r\n\ud83d\udce7[msalman@bccrc.ca](mailto:msalman@bccrc.ca) | [m.salmanpoor66@gmail.com](mailto:m.salmanpoor66@gmail.com), [m.salmanpour@ubc.ca](mailto:m.salmanpour@ubc.ca)\r\n\r\n---\r\n\r\n## \ud83d\udee0\ufe0fMaintenance\r\nFor technical support and maintenance inquiries, please contact:\r\n\r\n**Dr. Mohammad R. Salmanpour (Team Lead)** \r\n msalman@bccrc.ca \u2013 m.salmanpoor66@gmail.com \u2013 m.salmanpour@ubc.ca\r\n\r\n**Amir Hossein Pouria** \r\namirporia99.1378@gmail.com \r\n\r\n## \ud83d\udc65Authors\r\n- **Dr. Mohammad R. Salmanpour (Team Lead, Fund Provider, Evaluator, Medical Imaging Expert, Backend Development, Code Refactoring, Debugging, Library Management, IBSI Standardization, and Activation of the PySERA Library, and GUI Development in 3D Slicer)** \u2013 [msalman@bccrc.ca](mailto:msalman@bccrc.ca), [m.salmanpoor66@gmail.com](mailto:m.salmanpoor66@gmail.com), [m.salmanpour@ubc.ca](mailto:m.salmanpour@ubc.ca)\r\n- **Amir Hossein Pouria (Assistant Team Lead; Backend Development, Code Refactoring, Debugging, and Library Management)** \u2013 [amirporia99.1378@gmail.com](mailto:amirporia99.1378@gmail.com)\r\n- **Sirwan Barichin (IBSI Standardization, Debugging, and Activation of the PySERA Library, and GUI Development in 3D Slicer)** \u2013 [sirwanbarichin@gmail.com](mailto:sirwanbarichin@gmail.com)\r\n- **Yasaman Salehi (Backend Development, Code Refactoring, and Debugging)** \u2013 [y.salehi7698@gmail.com](mailto:y.salehi7698@gmail.com)\r\n- **Sonya Falahati (Tesing and Data prepration)** \u2013 [falahati.sonya@gmail.com](mailto:falahati.sonya@gmail.com)\r\n- **Dr. Mehrdad Oveisi (Evaluator, Software Engineer, and Advisor)** \u2013 [moveisi@cs.ubc.ca](mailto:moveisi@cs.ubc.ca)\r\n- **Dr. Arman Rahmim (Fund Provider, Medical Imaging Expert, Evaluator, and Advisor)** \u2013 [arman.rahmim@ubc.ca](mailto:arman.rahmim@ubc.ca), [arahmim@bccrc.ca ](mailto:arahmim@bccrc.ca)\r\n\r\n## \ud83d\udcdaCitation\r\n\r\n```bibtex\r\n@software{pysera2025,\r\n title={pysera: A Simple Python Library for Radiomics Feature Extraction},\r\n author={pysera Team},\r\n year={2025},\r\n url={https://github.com/MohammadRSalmanpour/PySERA}\r\n}\r\n```\r\n## \ud83d\udcdcLicense\r\n\r\nThis open-source software is released under the **MIT License**, which grants permission to use, modify, and distribute it for any purpose, including research or commercial use, without requiring modified versions to be shared as open source. See the [LICENSE](LICENSE) file for details.\r\n\r\n## Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/MohammadRSalmanpour/PySERA/issues)\r\n- **Documentation**: This README and the included guides\r\n- **Examples**: See `examples/basic_usage.py`\r\n\r\n## Acknowledgment\r\n\r\nThis study was supported by: \r\n\r\n- [\ud83d\udd2c **Qu**antitative **R**adiomolecular **I**maging and **T**herapy (Qurit) Lab, University of British Columbia, Vancouver, BC, Canada](https://www.qurit.ca) \r\n- [\ud83c\udfe5 BC Cancer Research Institute, Department of Basic and Translational Research, Vancouver, BC, Canada](https://www.bccrc.ca/) \r\n- [\ud83d\udcbb **Vir**tual **Collaboration (VirCollab) Group, Vancouver, BC, Canada](https://www.vircollab.com) \r\n- [\ud83c\udfed **Tec**hnological **Vi**rtual **Co**llaboration **Corp**oration (TECVICO Corp.), Vancouver, BC, Canada](https://www.tecvico.com) \r\nWe gratefully acknowledge funding from the\ud83d\udcb0 Natural Sciences and Engineering Research Council of Canada (**NSERC**) Idea to Innovation [**I2I**] Grant **GR034192**.\r\n---\r\n\r\n*PySERA - Simple, powerful radiomics in one function call. \ud83d\ude80*\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for radiomics feature extraction with multiprocessing support",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/MohammadRSalmanpour/PySERA/issues",
"Documentation": "https://pysera.readthedocs.io/",
"Homepage": "https://github.com/MohammadRSalmanpour/PySERA",
"Repository": "https://github.com/MohammadRSalmanpour/PySERA.git"
},
"split_keywords": [
"medical-imaging",
" standardized-radiomics-feature-extraction",
" quantitative-analysis",
" ibsi-standardization",
" healthcare"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9d7ba361defaff3cdffdd23f687d2b5690a5c027c8cb346c596b0db83527885a",
"md5": "dd6f7c70687f8ba65bd4589f543d0379",
"sha256": "7c626156935dbd1035f6f7729894af8b3cf52e735c82848a284ddf3fea23fee9"
},
"downloads": -1,
"filename": "pysera-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd6f7c70687f8ba65bd4589f543d0379",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 189830,
"upload_time": "2025-08-20T07:13:38",
"upload_time_iso_8601": "2025-08-20T07:13:38.443993Z",
"url": "https://files.pythonhosted.org/packages/9d/7b/a361defaff3cdffdd23f687d2b5690a5c027c8cb346c596b0db83527885a/pysera-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2638222702b59e7ddf0b44c729533e0b7a17182af576e869591345a088e59bd6",
"md5": "3c0d8e6f0032308b3318d1a724513462",
"sha256": "a2f0675b6c92ee5e798390290db4b68598660703437e43820dfcc6e943a449f7"
},
"downloads": -1,
"filename": "pysera-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "3c0d8e6f0032308b3318d1a724513462",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 191104,
"upload_time": "2025-08-20T07:13:52",
"upload_time_iso_8601": "2025-08-20T07:13:52.436786Z",
"url": "https://files.pythonhosted.org/packages/26/38/222702b59e7ddf0b44c729533e0b7a17182af576e869591345a088e59bd6/pysera-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 07:13:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MohammadRSalmanpour",
"github_project": "PySERA",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pysera"
}
JSON
