Skip to content

Flywheel Gear Toolkit (fw-gear)

Introduction

fw-gear is a Python package designed to simplify the development of Flywheel gears. It provides a set of modules that make gear creation more efficient and streamlined. The package is maintained by Flywheel and requires Python 3.8 or higher.

This documentation provides an overview of the fw-gear library and points to the official documentation for detailed information.

Key Features

  • Simplified Gear Development: Provides a standardized framework for creating Flywheel gears
  • Context Management: Easily access and manage gear inputs, outputs, and configuration
  • Specification Handling: Tools for working with gear specifications and manifests
  • Utility Functions: Common operations for file handling, logging, and more
  • SDK Integration: Optional integration with the Flywheel SDK

Installation

The package can be installed using pip or poetry:

1
2
pip install fw-gear  # or
poetry add fw-gear

Optional Dependencies

The fw-gear library supports several optional dependencies that provide additional functionality:

  • all: Installs all optional dependencies
  • dicom: Provides the fw-file and nibabel packages
  • fw-file: Adds support for interacting with various file types and their metadata
  • nipype: Includes the nipype and nibabel packages
  • numpy: Adds support for numpy arrays in JSON operations
  • sdk: Provides the flywheel-sdk and flywheel-bids packages

Install optional dependencies using:

1
2
pip install "fw-gear[<extra>]"  # or
poetry add fw-gear -E <extra>

Core Modules

Context

The Context module provides access to the gear's runtime environment, including:

  • Input files and their metadata
  • Configuration options
  • Output directory
  • Logging facilities

Specs

The Specs module helps with handling gear specifications and manifests, including:

  • Parsing and validating manifest files
  • Working with input and configuration specifications
  • Managing gear metadata

Utils

The Utils module offers various utility functions for common gear operations:

  • File handling and manipulation
  • Logging and error reporting
  • Data conversion and formatting

Basic Usage Example

Here's a simple example of using fw-gear in a gear script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import logging
from pathlib import Path
from fw_gear.context import GearContext

# Initialize the gear toolkit context
with GearContext() as context:
    # Setup basic logging
    context.init_logging()
    log = logging.getLogger(__name__)

    # Get config settings
    config = context.config

    # Get input files
    input_file = context.get_input_path('input_file')

    # Process the file
    output_file = Path(context.output_dir) / 'output.txt'

    # Log the result
    log.info(f'Processing complete. Output saved to {output_file}')

API Reference

For detailed API documentation, please refer to the official fw-gear documentation.

Migration from gear-toolkit

If you're migrating from the older gear-toolkit package, please refer to the Migration Guide for detailed instructions on updating your code.

Additional Resources