viswanath-lab/RadQy

RadQy

RadQy is a quality assurance and evaluation platform for MRI and CT imaging datasets. It extracts metadata, computes image quality metrics, generates scan thumbnails, supports foreground/background mask generation, and provides an interactive front-end interface for visual quality review, cohort exploration, and LLM-assisted reporting and dataset interpretation.

RadQy Demo

Full demo video: https://youtu.be/pzJUZovFlT0?si=PcMnU4Dhdkh_qTX8

Front-end View

Backend View

Key Features

• MRI and CT quality assessment
• DICOM metadata/tag extraction
• Image quality metric computation
• Thumbnail generation for participant-level review
• Optional foreground/background mask export
• Interactive front-end visualization
• Parallel coordinate plots for quality metric exploration
• Subject/table filtering and cohort review
• Support for multiple segmentation options including otsuhull, adaptiveborder, and unet
• Supports DICOM and NIfTI('.nii' and '.nii.gz') inputs
• Supports scalar 2D and 3D NIfTI images, with optional JSON sidecars for additional metadata; 4D NIfTI images are not currently supported

Repository Structure

RadQy/
├── backend/          # Processing, IQM, segmentation, and CLI logic
├── frontend/         # Web-based RadQy interface
├── docs/             # Documentation and figures
├── tests/            # Test files
├── tools/            # Utility scripts
├── README.md
├── requirements.txt
└── pyproject.toml

Installation

Clone the repository:

git clone https://github.com/viswanath-lab/RadQy.git
cd RadQy

Create an environment:

conda create -n radqy python=3.10
conda activate radqy

Install requirements:

pip install -r requirements.txt

Running RadQy

Basic command:

python backend/radqy.py --inputdir "PATH_TO_DICOM_DATASET" --scantype mri

For CT data:

python backend/radqy.py --inputdir "PATH_TO_DICOM_DATASET" --scantype ct

Example with options:

python backend/radqy.py ^
  --inputdir "E:\Data\Rectal\input_data_folder" ^
  --scantype mri ^
  --middle-percent 50 ^
  --num-samples 2 ^
  --save-fgbg ^
  --segmenter otsuhull

Main Options

--inputdir          Root folder containing DICOM and NIfTI (`.nii` and `.nii.gz`) inputs
--scantype          Scan type: mri or ct
--middle-percent    Percent of middle slices to process
--num-samples       Slice sampling stride
--save-fgbg         Save foreground/background masks
--segmenter         Segmentation method: otsuhull (default), adaptiveborder, unet
--verbose           Print detailed per-file processing progress

Slice Selection and Mask Export

By default, RadQy processes all slices (--middle-percent 100 --num-samples 1).

• --middle-percent retains the specified percentage of central slices within each participant group. For example, --middle-percent 50 retains the middle half.
• --num-samples sets the sampling stride after middle-slice selection. A value of 1 processes every retained slice; 2 processes every other retained slice.
• --save-fgbg saves foreground and background masks as PNG files. Masks are computed for quality assessment even when this option is omitted.

Participant groups are defined by the top-level folder, immediate parent folder, and patient ID. Keep different scan series in separate folders to prevent them from being combined into one group.

Output

RadQy creates an output folder under:

frontend/Data/<dataset_name>/

The main output file is:

results.tsv

The output includes:

• participant-level metadata
• number of slices
• extracted DICOM tags
• image quality metrics
• thumbnail image filenames
• optional foreground/background mask outputs

Front-End Interface

Open frontend/index.html in your browser. Click View Results and select the results.tsv file generated by RadQy.

Keep the dataset output folder and its associated thumbnail and mask folders together under frontend/Data/<dataset_name>/. Loading results.tsv reads the results table; the image folders must remain accessible for thumbnails and masks to display.

The interface supports:

• Interactive review: Explore quality metrics through sortable tables, parallel coordinate plots, bar charts, and browser-based UMAP visualizations. Selections are linked across views.
• Image and mask viewing: Inspect participant thumbnails and, when generated with --save-fgbg, foreground and background masks.
• Annotations and filtering: Add editable annotation columns, select participants using custom conditions, hide metrics, and remove selected rows from the current review.
• External metadata: Import additional columns from CSV, TSV, TXT, or Excel files. Imported rows align by row position, not patient ID, so ensure their order matches the RadQy table.
• Export: Copy table data or save selected participants—or all participants when none are selected—and visible columns to Excel.
• Cohort Finder: Group participants using k-means clustering of the current UMAP coordinates and optionally assign train/test labels within each cluster.
• AI-assisted reporting: Generate a quality assessment report and ask questions about the loaded dataset. This optional feature requires an OpenAI API key and internet access. Table-derived dataset summaries and selected values are sent to OpenAI; scan images are not sent by this reporting workflow.

Export your table to retain annotations and review changes.

Feedback and usage

Please report issues, bugs, and enhancement requests through the Issues tab.

Detailed usage instructions and an example of using RadQy to analyze TCIA datasets are available in the Wiki.

You can cite this in any associated publication as:
Sadri, AR, Janowczyk, A, Zou, R, Verma, R, Beig, N, Antunes, J, Madabhushi, A, Tiwari, P, Viswanath, SE, "Technical Note: MRQy — An open-source tool for quality control of MR imaging data", Med. Phys., 2020, 47: 6029-6038. https://doi.org/10.1002/mp.14593

ArXiv: https://arxiv.org/abs/2004.04871

If you do use the tool in your own work, please drop us a line to let us know.