pictologics 0.4.1

IBSI-compliant radiomic feature extraction package

Pictologics

Pictologics is a high-performance, IBSI-compliant Python library for radiomic feature extraction from medical images (NIfTI, DICOM).

Documentation (User Guide, API, Benchmarks): https://martonkolossvary.github.io/pictologics/

Why Pictologics?

• 🚀 High Performance: Uses numba for Just In Time (JIT) compilation, achieving significant speedups over other libraries (speedups between 15-300x compared to pyradiomics, see Benchmarks page for details).
• ✅ IBSI Compliant: Implements standard algorithms verified against the IBSI digital and CT phantoms, and clinical datasets:
  • IBSI 1: Feature extraction (compliance report)
  • IBSI 2: Image filters (Phase 1), filtered features (Phase 2), reproducibility (Phase 3)
• 🔧 Versatile: Provides utilities for DICOM parsing and common scientific image processing tasks. Natively supports common image formats (NIfTI, DICOM, DICOM-SEG, DICOM-SR).
• ✨ User-Friendly: Pure Python implementation with a simple installation process and user-friendly pipeline module supporting easy feature extraction and analysis, ensuring a smooth experience from setup to analysis.
• 🛡️ Predictable Results: Every pipeline run returns a complete, fixed set of feature columns — even when individual features or entire configurations fail (values are NaN). Batch processing never produces missing columns or ragged rows.
• 🛠️ Actively Maintained: Continuously maintained and developed with the intention to provide robust latent radiomic features that can reliably describe morphological characteristics of diseases on radiological images.

Installation

Pictologics requires Python 3.12+.

pip install pictologics

Or install from source:

git clone https://github.com/martonkolossvary/pictologics.git
cd pictologics
pip install .

Quick Start

from pictologics import RadiomicsPipeline, format_results, save_results

# 1. Initialize the pipeline
pipeline = RadiomicsPipeline()

# 2. Run the "all_standard" configurations
results = pipeline.run(
    image="path/to/image.nii.gz",
    mask="path/to/mask.nii.gz",
    subject_id="Subject_001",
    config_names=["all_standard"]
)

# 3. Inject subject ID or other metadata directly into the row
row = format_results(
    results, 
    fmt="wide", 
    meta={"subject_id": "Subject_001", "group": "control"}
)

# 4. Save to CSV
save_results([row], "results.csv")

Performance Benchmarks

Benchmark Configuration

Comparisons between Pictologics and PyRadiomics (single-thread parity).

[!TIP] Detailed performance tables and extra feature (IVH, local intensity, GLDZM, etc.) measurements available in the Benchmarks Documentation.

Test Data Generation:

• Texture: 3D correlated noise generated using Gaussian smoothing.
• Mask: Blob-like structures generated via thresholded smooth noise with random holes.
• Voxel Distribution: Mean=486.04, Std=90.24, Min=0.00, Max=1000.00.

HARDWARE USED FOR CALCULATIONS

• Hardware: Apple M4 Pro, 14 cores, 48 GB
• OS: macOS 26.4.1 (arm64)
• Python: 3.12.10
• Core deps: pictologics 0.4.1, numpy 2.2.6, scipy 1.17.0, numba 0.62.1, pandas 2.3.3, matplotlib 3.10.7
• BLAS/LAPACK: Apple Accelerate (from numpy.show_config())

Note: the benchmark script explicitly calls warmup_jit() before timing to avoid including Numba compilation overhead in the measured runtimes. Timing and memory measurement are separated — tracemalloc is NOT active during timing to avoid biasing the comparison (its per-allocation hooks penalise pure-Python code more than JIT/C code). All calculations are repeated 5 times and the mean runtime is reported; peak memory is measured once separately.

Intensity

Execution Time (Log-Log)	Speedup

Morphology

Execution Time (Log-Log)	Speedup

Texture

Execution Time (Log-Log)	Speedup

Filters

Execution Time (Log-Log)	Speedup

Quality & Compliance

IBSI Compliance: IBSI 1 Features | IBSI 2 Phase 1 Filters | Phase 2 Features | Phase 3 Reproducibility

Code Health

• Test Coverage: 100.00%
• Mypy Errors: 0
• Ruff Issues: 0

See Quality Report for full details.

Citation

Citation information will be added/updated.

License

Apache-2.0