Skip to content

fw-classification

Introduction

fw-classification is a generalized file classifier for medical images. At its core, it's an engine that takes in a JSON document and applies a set of declarative rules to modify that JSON. This package enables automated organization and labeling of data within Flywheel based on configurable rules and profiles.

Key Features

  • Declarative Rules: Define classification rules using YAML profiles
  • Multiple File Types: Support for various medical imaging formats
  • Extensible Architecture: Easily add new classification rules and operators
  • Integration with Flywheel: Seamless integration with the Flywheel platform
  • Standalone Operation: Can be used both inside and outside of Flywheel

Motivation

Existing DICOM classification in Flywheel relies on using hard-coded rules and heuristics, principally using DICOM tags like SeriesDescription and ProtocolName to classify a DICOM. This has many drawbacks, including the difficulty to change classification rules.

This library provides a generalized declarative metadata modification system that can perform classification on multiple file types, both inside and outside of Flywheel.

Installation

fw-classification requires Python >= 3.8, and can be installed via pip:

1
pip install fw-classification

Or using poetry:

1
poetry add fw-classification

Optional Dependencies

There are several extras that can be optionally installed:

1
pip install "fw-classification[<extra>]"

Or with poetry:

1
poetry add -E <extra> fw-classification

Available extras:

  • all: Includes both of the following
  • fw: Includes fw-core-client for integration with Flywheel
  • geartk: Includes flywheel-gear-toolkit for updating metadata via gears

Basic Concepts

Profiles

A profile is a YAML file that defines how to classify files. It contains blocks of rules that match on certain criteria and perform various actions.

Blocks

Blocks are collections of rules that are applied to the input JSON. Each block has a name and contains one or more rules.

Rules

Rules define the conditions for matching and the actions to take when a match is found. They use logical operators to match specific keys in the input JSON.

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from fw_classification import Classifier
from fw_classification.profile import Profile

# Load a profile from a YAML file
profile = Profile.load("path/to/profile.yml")

# Create a classifier with the profile
classifier = Classifier(profile)

# Apply classification to a JSON document
input_json = {
    "SeriesDescription": "T1w_MPR",
    "ProtocolName": "Structural"
}

result = classifier.classify(input_json)
print(result)

Example Profile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
name: MRI Classification
version: 1.0.0
blocks:
  - name: T1w
    rules:
      - match:
          operator: contains
          key: SeriesDescription
          value: T1w
        action:
          operator: set
          key: classification.Intent
          value: Structural

  - name: fMRI
    rules:
      - match:
          operator: contains
          key: SeriesDescription
          value: fMRI
        action:
          operator: set
          key: classification.Intent
          value: Functional

Resources