Bits & Flames
bitsandflames/fyron

Datasets

fyron.datasets prepares practical dataset folders for clinical imaging AI workflows. It includes tiny synthetic demo data helpers and first-class preparation helpers for nnU-Net v2 segmentation, YOLO classification, and YOLO object detection.

Use this module when your cohort table already identifies local image files, masks, classes, boxes, and train/validation/test splits, and you need a reproducible folder structure with a manifest.

Install

Dataset preparation uses Fyron's base imaging stack:

bash
uv add fyron

For a full local research environment:

bash
uv add "fyron[all]"

Core Concepts

ConceptMeaning
manifestDataFrame, CSV, or JSON table describing image paths, labels, classes, boxes, and splits.
splittrain, val, or test; validation rows follow the target framework's expected folder layout.
copy modecopy, symlink, or explicit move; default is copy.
conversionNIfTI and DICOM can be converted into the target folder shape when needed.
output manifestDataFrame recording source paths, written paths, split, status, and errors.

API Contract

TopicContract
Input shapeDataFrame, CSV, or JSON manifest describing images, labels, classes, boxes, case IDs, and splits.
Required columns/filesnnU-Net needs case/image/split and train/val labels; YOLO classification needs image/class/split; YOLO detection needs image/split/class/bounding-box columns.
Return shapeOutput manifest DataFrame with source paths, written paths, split, status, and errors.
Saved artifactsnnU-Net folders and dataset.json; YOLO image/label folders and data.yaml; dataset manifests.
Failure modesMissing columns/files, invalid splits, unsupported image formats, malformed boxes, shape mismatches, overwrite conflicts, or conversion failures.

nnU-Net v2 Preparation

Use prepare_nnunetv2_dataset when you have 3D images and segmentation masks that should be trained with nnU-Net v2.

Fyron creates:

text
Dataset501_LungTumor/
  imagesTr/
    case_0001_0000.nii.gz
  labelsTr/
    case_0001.nii.gz
  imagesTs/
    case_0002_0000.nii.gz
  dataset.json

The image suffix _0000 is the nnU-Net channel suffix for channel 0. Label files do not include the channel suffix.

python
import pandas as pd
from fyron.datasets import prepare_nnunetv2_dataset

manifest = pd.DataFrame(
    {
        "case_id": ["case_0001", "case_0002"],
        "split": ["train", "test"],
        "image_path": ["images/case_0001_ct.nii.gz", "images/case_0002_ct.nii.gz"],
        "label_path": ["masks/case_0001_mask.nii.gz", ""],
    }
)

written = prepare_nnunetv2_dataset(
    manifest,
    output_dir="datasets/nnunet",
    dataset_id=501,
    dataset_name="LungTumor",
)

Parameters

ParameterMeaning
dataset_idNumeric nnU-Net dataset ID; written as DatasetXXX_Name.
dataset_nameDataset name sanitized into the output folder.
image_colManifest column with NIfTI file paths or DICOM series folders.
label_colManifest column with segmentation masks; required for train and val.
case_id_colStable case identifier used in output filenames.
channel_namesOptional channel mapping for dataset.json, default {0: "CT"}.
labelsOptional label mapping for dataset.json, default background/foreground.

Research Decisions

  • Fyron does not resample images or masks for nnU-Net. Align them before calling the preparation helper.
  • DICOM input is converted to NIfTI with SimpleITK using the first discovered series.
  • train and val rows both go into nnU-Net's training folders. Keep your split table as the source of truth for cross-validation.
  • Official format reference: nnU-Net documentation.

YOLO Classification Preparation

Use prepare_yolo_classification_dataset when each image or slice has one class label.

Fyron creates:

text
yolo_cls/
  train/
    benign/
      case_001.png
    malignant/
      case_002.png
  val/
    benign/
      case_003.png
python
from fyron.datasets import prepare_yolo_classification_dataset

written = prepare_yolo_classification_dataset(
    "cohort.csv",
    output_dir="datasets/yolo_cls",
    image_col="image_path",
    class_col="class",
    split_col="split",
    sample_id_col="patient_id",
)

Image Inputs

InputBehavior
.png, .jpg, .jpegcopied into split/class/.
DICOM file or DICOM series folderconverted to axial PNG slice(s).
NIfTI volumeconverted to axial PNG slice(s).

For 3D input, nifti_slice="middle" writes one representative axial slice. Use nifti_slice="all" only when every slice should become a training image.

Official format reference: Ultralytics YOLO classification datasets.

YOLO Object Detection Preparation

Use prepare_yolo_detection_dataset when each image can have zero or more bounding boxes.

Fyron creates:

text
yolo_det/
  images/train/
    case_001.png
  labels/train/
    case_001.txt
  data.yaml

YOLO label rows use normalized xywh:

text
class_id x_center y_center width height
python
from fyron.datasets import prepare_yolo_detection_dataset

written = prepare_yolo_detection_dataset(
    "boxes.csv",
    output_dir="datasets/yolo_det",
    image_col="image_path",
    class_col="class",
    bbox_cols=("x_min", "y_min", "x_max", "y_max"),
    split_col="split",
    sample_id_col="image_id",
)

Box Rules

  • Input boxes are pixel xyxy by default: x_min, y_min, x_max, y_max.
  • Fyron converts boxes to normalized YOLO xywh.
  • Multiple rows for the same image become multiple lines in the same label file.
  • If a row has an image but empty box values, Fyron writes an empty label file for a negative image.
  • Class IDs are zero-indexed and written to data.yaml.

Official format reference: Ultralytics YOLO detection datasets.

CLI

bash
fyron dataset-nnunetv2 \
  --manifest cohort.csv \
  --output-dir datasets/nnunet \
  --dataset-id 501 \
  --dataset-name LungTumor \
  --image-col image_path \
  --label-col label_path \
  --case-id-col case_id \
  --split-col split
bash
fyron dataset-yolo-classify \
  --manifest cohort.csv \
  --output-dir datasets/yolo_cls \
  --image-col image_path \
  --class-col label \
  --split-col split
bash
fyron dataset-yolo-detect \
  --manifest boxes.csv \
  --output-dir datasets/yolo_det \
  --image-col image_path \
  --class-col class \
  --bbox-cols x_min,y_min,x_max,y_max \
  --split-col split

Validation

python
from fyron.datasets import validate_nnunetv2_dataset, validate_yolo_dataset

nnunet_qc = validate_nnunetv2_dataset("datasets/nnunet/Dataset501_LungTumor")
yolo_qc = validate_yolo_dataset("datasets/yolo_det", task="detect")

Validation returns a DataFrame with path, check, status, and message.