User's Manual
MICFlow v0.3.0 Usuer's Manual
This is still under construction. More will be added later. You are welcome to submit your example workflows.
What is MICFlow
Medical Image Computing Workflow (MICFlow) is a simple, lightweight but flexible, extensible and powerful computing workflow system aiming to automate large quantity and/or time-consuming medical image computing tasks such as segmentation, registration and analysis. The system consists of three components: workflow engine, definition files, and workflow script language, all of which are written in Python. Naturally Python is the basis of the workflow script language. This makes any script and definition file in the workflow system possess the same power and extensibility as a standalone python program. Workflow being directly debuggable is the big feature of MICFlow. It is also easy and flexible: you can just use any Python debug tool and IDE, such as Wing IDE, IDLE, DrPython, BOA Constructor, or Python's pdb module to debug a workflow. I use Wing IDE with which debugging is like a breeze in a manor similar to MATLAB IDE.
Installation
MICFlow is cross-platform. It is pure Python and command-line only. You need Python 2.2 or above installed. Theoretically MICFlow runs under any platform supported by Python, but I only tested it on Windows and Linux. Please see Python documents. There is no special requirement for installation. Simply put all MICFlow files in one directory, normally called 'micflow', then change to the directory.
MICFlow components
MICFlow system incldue three parts: the workflow engine, the workflow definition and configuration files, and the script language, The distinct feature of MICFlow is that the three parts are actually closely integrated to form a complete application to carry out workflow tasks in a simple strcture and easy way while being very flexible and powerful, and highly extensible.
The workflow engine is 'micflow.py'.
There are four types of workflow definition and configuration files: Process Configuration File (.pcf), Input Definition File (.idf), Output Definition File (.odf), and Workflow Definition File (.wdf). However, only the Process Configuration File is essential. The other definition files are optional and are beneficial for designing complex workflows. Using all the four definition and configuration files for a simple workflow is also good but sometimes may be troublesome if you simply want a quick solution.
As the names suggest, the Process Configuration File defines the parameters and settings of the workflow process; the Input Definition File and Output Definition File define the input and output files and relevant settings, respectively; the Workflow Definition File defines the workflow process itself. However, the above differentiation is not strict. Complying with the Python spirit, the use of these files and their differentiation are recommended conventions but not compulsory standards.
The contents of hese files are written in the workflow script language. Executable statements are allowed. Actually each definition and configuration file is treated as a standard Python snippet embeded in the workflow, so you can use the full power of a Python program and all the environment of the workflow.
The workflow script language of MICFlow is, of course, Python, but enhanced with a set of high level classes dealing specifically with medical image computing workflows.
Writing a workflow is rather straightforward if you are familiar with Python - exactly the same as writing any Python programs.
How to use
First you have to write the workflow definition and configuration files using the workflow script language (see Class Reference). Then change into the MICFlow directory, normally 'micflow'. If you have only the Process Configuration File, then run
python micflow.py -c myworkflow.pcf
If you have more definition and configuration files, the full format is:
python micflow.py -c path/to/workflow.pcf -i path/to/workflow.idf -o path/to/workflow.odf -w path/to/workflow.wdf
Simple Examples
Here is a simple example of the workflow. Suppose we want to extract brain images from 100 MRI head images using the FSL's tool BET. All images are in Analyze 7.5 format. Creat a file named example1.pcf under the MICFlow directory, and type in the following:
#Set some parameters:
MFOptions['ComputingMode'] = 'Local'
HomePath = '/images/'
#Define input images:
SrcImages1 = Images()
SrcImages1['FilePath'] = HomePath
SrcImages1['FileFormat'] = 'ANALYZE' #Set current file format
SrcImages1['FileNames'] = '&AllFilesInCurrentPath;' #Add files under current path with current file format
#Define output images:
SrcImages1.AddDerived('Brain')
SrcImages1.Derived['Brain']['FilePath'] = 'brain1'
SrcImages1.Derived['Brain']['FileNameSuffix'] = '-b'
BettedImages1 = SrcImages1.Derived['Brain'] #Just a shortcut
#Define the workflow process:
Bet = Command()
Bet.AddCommand(Name='Local', FullFileName='bet')
Bet.Commands['Local']['CommandLines'] = '${Self} ${InputImage} ${OutputImage} -v'
Bet.Variables['InputImage'] = SrcImages1
Bet.Variables['OutputImage'] = BettedImages1
#Run the workflow:
Bet.Execute(Name=MFOptions['ComputingMode'])
Run this example like this:
python micflow.py -c example1.pcf
This will BET all images of Analyze format in "/images/" directory, and write the output brain images to the "/images/brain1" directory. Each brain image file name has a suffix of '-b'. For example, an image named "/images/abc.hdr" will have a corresponding BETted image named "/images/brain1/abc-b.hdr".
Complex examples
MICFlow can be used to handle rather complex workflows. (more to come...).