Installing and Running McStrip
mcstrip_consensusmask.pro mcstrip_tuner.pro reorient_vol.pro
Installing McStrip
Not much to it, really. Just unpack the tarfile or copy the contents of the CD to your system.
IDL savesets are supposed to be platform-independent. See the next section on Testing for
how to launch the program.
Notes:
1. Every attempt has been made to make McStrip backward-compatible to IDL version 5.5a. We are unable to test any lower versions.
2. McStrip and its component routines save images so an operator can make a quick inspection of intermediate results. PNG format is the default, as it is more compact that TIF. However, IDL verison 5.5a and RedHat8 used together are known to WEDGE or to cause a SEGMENTATION FAULT when a call is made to "write_png". (The error message, if you get one, is not helpful!) IDL 5.6 is fine. Both versions work properly with RedHat7. If you encounter this problem, the fix is to set the enviromental variable "USE_PNG" to "NO" in order to get tif files instead.
3. BSE3.0 is distrbuted as part of BRAINSUITE. McStrip will attempt to run an executable directly, but will also attempt to use the "wine" windows emulator if the program was compiled for another architecture. See http://www.winehq.com if you need wine for your system.
4. McStrip reads and writes some generic names for temporary files, (e.g. "AIR_svol.img", "BSEraw.img") so you will get into trouble if you attempt to run two instances in the same working directory! Volume-specific working files have a "McWorking" prefix. A Journal file is also saved for McStrip_INC, and individual logfiles are written for each MR volume you process.
5. If you are using the IDL6.0 Virtual Machine you will have to rename the McStrip_INC_V60.sav to McStrip_INC.sav. The virtual machine expects the program name to be the same as the save set name.
6. If you are using a runtime or development license, you are free to call components of McStrip directly without going through the GUI. See the documentation for the top-level routines below.
TopTesting McStrip
To test your installation of McStrip you can change to the example directory and do the following:
1. Edit McStrip_example.params to reflect the correct path name for the template volumes. I provided an example file for both linux and windows; also see the sample parameter file below.
2. Edit McStrip.environ to reflect the correct pathnames. I provided an example file for both linux and windows; also see the sample environment file below.
3. Launch IDL
IDL> restore
McStrip_INC_V??.sav ; ?? matches the version of
IDL
IDL> mcstrip_inc
; runs the GUI wrapper around McStrip_AN.pro
(Or, Launch the IDL virtual machine and specify
McStrip_INC.sav (see note 5 above), which will start the program for
you.)
This is the what the McStrip_INC GUI looks like:
4. Using the GUI:
Load the parameter file McStrip_example.params
Load the environment file McStrip.environ
Choose to "Run" or "Tune" McStrip, and use
subject_X.img as the mriname.
The left submenu becomes active when you select "Run McStrip on one or
more volumes". As you add mrivolumes by browsing or typing, they
appear at the top of the list in the scrollable window. Your
alternative to "Compute everything" is to "Reuse existing coarsemask".
The right submenu becomes active if you select "Tune McStrip on one
volume...". When you are tuning, you can never skip ahead, that
is, stuff from Stage 1 has to exist before you can tune Stage 2.
After you click on "Submit" in either case the submenus will be hidden,
and the cursor should change to a stopwatch.
At this point you can keep an eye on the standard output window (Linux)
to see what is happening, or ask to "View Journal".
(If I did it all correctly, you should get a little popup window that
tells you if a stage completed nicely or had an error.)
5. Exit IDL and compare your results to those in the subdirectory "expected_results".
6. Read the logfile and the McStrip_INC.journal file for help if McStrip does not complete properly.
7. If you can not get things working by fixing things in the
parameter and environment files, I will try to help you.
Please send me the following files:
McStrip.environ
McStrip_example.params
McStrip_INC.journal
subject_X.mcstrip_log
and a note about your
platform (OS and whether you are running IDL as a real license or as a
Virtual Machine)
8. If it does work properly, I'd like to know that too!
Kelly Rehm, Ph.D.
Assistant Professor, Department of Radiology, University of Minnesota.
earth-mail: International Neuroimaging Consortium
VA Medical Center (11P)
One Veteran's Drive
Minneapolis, MN 55417
phone: (612) 467-5532 fax: (612)
725-2068
e-mail: kelly@neurovia.umn.edu
Sample environment file (linux)
# McStrip expects the following environmental variables to be set, but they only affect entries in the logfile.
# HOSTNAME=myhost
# USER=me
# PWD=/home/mycomputer/me/mcstrip_bundle/example
#
# Here you can set the user, working directory, and executable paths. for example:
#
# -- If USE_PNG is present and set to NO, then you will get .tiff instead of .png files.
# -- BSE_BINARY should have the complete name of an executable version of
# bse version 2 or 3 if it is not in your search path
# -- AIR_PATH should be the directory in which AIR5 executables reside if they are not in your search path
#
USE_PNG=YES
BSE_BINARY= /usr/local/common/bin/bse
AIR_PATH=/usr/local/hbplib/bin/i86_linux-rh7/
Top
SAMPLE Parameter file (linux)
# McStrip parameters
# These are parameters that work well on the example subject
# Uses ";" to separate field and value. # denotes a comment.
# (NOTE: do not use TABs or quotes in this file)
#
# The storage format parameters are optional, but you may need to specify the orientation so the
# subject and template brains face the same direction. See the documentation for Reorient_vol.pro below
# for an explanation of the 6-character orientation string.
storage_format.name; ANALYZE
storage_format.orient; lrpais
#
# (See the documentation for mcstrip_coarsemask.pro for what these parameters mean.)
# also please read the README file included with in the refvol directory.
coarse_params.workdir; ./
coarse_params.skinfrac; 0.50
coarse_params.template_mriname; ../refvol/template_mri.img
coarse_params.template_skinmaskname; ../refvol/template_skinmask.img
coarse_params.template_brainmaskname; ../refvol/template_brainmask.img
coarse_params.model_number; 3
coarse_params.discord_cutoff; 15.0
coarse_params.dil_kern; 7 7 7
coarse_params.cleanup; 0
#
# (See the documentation for mcstrip_threshmask.pro for what the parameters mean.)
thresh_params.workdir; ./
thresh_params.greythr_frac; 0.15
thresh_params.auto_adj_frac; 0.35
#
#(See the documentation for mcstrip_bsemask.pro for what the parameters mean.)
bse_params.workdir; ./
bse_params.akerns; 10.0 5.0 15.0
bse_params.aiters; 3
bse_params.gkerns; .70 .64 .60 .80 .90
bse_params.matchval; 1.0
#
#(See the documentation for mcstrip_consensusmask.pro for what the parameters mean.)
consensus_params.workdir; ./
consensus_params.mask1_vote; 1
consensus_params.mask2_vote; 1
consensus_params.mask3_vote; 1
consensus_params.votes_to_pass; 2
consensus_params.smooth_fwhm; 0.3
consensus_params.keep_thr; 0.90
consensus_params.fill_voids; 1
#
Top
mcstrip_inc.pro
;
; NAME
; mcstrip_inc - provides a splash screen and prompts for all the
; files necessary to run McStrip.pro in a runtime
; environment. Verifies that mrifiles are in a supported format.
; SYNOPSIS
; mcstrip_inc
;
;
Top
mcstrip.pro
;
; NAME
; mcstrip - T1 consensus stripping - ANALYZE and VAPET formats. Routine that manages 4 "mcstrip_" modules.
;
; SYNOPSIS
; mcstrip, SUBJECT_MRINAME=subject_mriname,PARAMFILE=paramfile, $
; COMPLETE=complete, /RECYCLE_COARSE,/VERBOSE, /DEBUG
;
; PARAMETERS
; subject_mriname - T1 volume in VAPET or ANALYZE storage format with full pathname
; paramfile - can read this file for the module-specifc parameters,
; or the modules will prompt for what they need. An example file
; is included below.
; complete - returns a 1 if all modules appear to have run properly
; /RECYCLE_COARSE - when tuning for a new volume set, allows reuse of existing
; coarsemask (saving time)
; /VERBOSE - if set, you will get a lot of printout and pictures,
; though the program will still run automatically
; /DEBUG - optional flag for debug output
;
; DESCRIPTION
; T1 consensus stripping. Manages 4 modules:
; mcstrip_coarsemask.pro - a "Level 1" algorithm
; mcstrip_threshmask.pro - a "Level 2" algorithm, influenced by level 1
; mcstrip_bsemask.pro - a "Level 3" algorithm, influenced by levels 1&2
; mcstrip_consensus.pro - combines level 1,2,3 masks into one, then tidies
; up the result.
; mcstrip_get_thresh.pro is a routine used in the coarsemask and threshmask modules
; The individual routines have detailed descriptions of what
; they do.
;
; NOTE: This program accepts VAPET or ANALYZE format in any orientation, but makes
; "McWorking_*.img" versions in the working directory in ANALYZE format with orientation 'lrapis'.
; Masks that are generated are converted to the orientation and storage
; format of the original mrifile at completion.
;
Top
mcstrip_coarsemask.pro
;
; NAME_coarsemask - MODULE of McStrip that creates a coarse strip mask for a T1 MRI
;
; SYNOPSIS
; mcstrip_coarsemask, SUBJECT_MRINAME = subject_mriname, PARAMS=params, $
; BASENAME = basename, COMPLETE=complete,LOGFILE=logfile, $
; JUST_SKIN=just_skin,VERBOSE=verbose,DEBUG=debug
;
PARAMETERS
; subject_mriname - with full path (REQUIRED)
; params - structure variable containing the necessary operating
; parameters for this module (probably extracted from a
; general paramfile by McStrip). If not supplied, the operator
; will be prompted for each parameter.
; e.g.
; params = { workdir: './', $
; skinfrac: .50 , $ ; range between [0, 1.0] for [loose, tight]
; template_mriname: './template_mri.img' , $
; template_skinmaskname: './template_skinmask.img', $
; template_brainmaskname: './template_brainmask.img', $
; model_number: 3 , $ ; order of polynomial warp to be computed
; discord_cutoff: 25.0, $ ; if xformed mri disagrees with subject skinmask
; ; by > cutoff, treate eroded subject skinmask as coarse
; dil_kern: [9,9,9], $ ; warpmask dilation kernel (or skinmask erosion kernel when warp fails!)
; cleanup: 0} ; if set, only the coarsefile and the logfile will be kept
; basename - used to build output filenames; defaults to mriname with directory & suffix removed
; logfile - if it exists, output from this stage will be appended. Otherwise it will be created.
; Name defaults to 'basename.coarse_striplog'
; complete - will be set to 1 if the program finishes normally
; /RECYCLE_WARP - set if you are in tuning mode and want to save a little time. If your machine is fast, don't bother.
; /JUST_SKIN - set if you are in tuning mode and want to examine the mask before proceeding
; /VERBOSE - set if you want a lot of printout to your screen and some
; windows to pop up. If debug is set, this will be set too.
; /DEBUG - optional flag for debug output
;
; DESCRIPTION
; Fully automated creation of a coarse mask for a T1-weighted MRI, operating from parameters.
; A logfile documents the process.
;
; FILES GENERATED
; 'basename_skin_automask'
; 'basename.template_to_subject.warp' OR 'basename.template_to_subject.AIR'
; 'basename_warp_mask' (no matter what level of model it was)
; 'basename_coarse_mask'
; Plus quite a few 'McWorking_basename...' files that may be in a different orientation than the original volume.
; They will be removed if the cleanup flag is set.
;
; AIR5 programs required are:
; {crop, reslice, reslice_warp, alignlinear, align_warp, invert_air, combine_warp, determinant_mask, binarymask}
;
Top
mcstrip_threshmask.pro
;
; NAME
; mcstrip_threshmask - MODULE of McStrip that creates a thresh strip mask for an MRI.
;
; SYNOPSIS
; mcstrip_threshmask, SUBJECT_MRINAME = subject_mriname, PARAMS=params, $
; COARSEMASKNAME=coarsemaskname, GUIDE_THRESH=guide_thresh, $
; BASENAME = basename, LOGFILE=logfile, VERBOSE=verbose, $
; COMPLETE=complete, DEBUG=debug
;
; PARAMETERS
; subject_mriname - with full path ANALYZE format (REQUIRED)
; params - structure variable containing the necessary operating
; parameters for this module (probably extracted from a
; general paramfile by McStrip). If not supplied, the operator
; will be prompted for each parameter. These params are not very subject-dependent;
; thresh_guide and voxel_target (see below) are variable.
; e.g.
; params = { workdir: './', $
; greythr_frac: 0.15, ; use this fraction in setting csf/grey matter threshold
; auto_adj_frac: 0.35 } ; automatic threshold adjustment allowed up to this fraction
;
; coarsemaskname - Influence: Apply to raw mri before thresholding
; guide_thresh - grey-level intensity threshold of mri data - returned for use in guiding Level 3 algorithm
; basename - used to build output filenames; defaults to mriname
; with directory & suffix removed
; logfile - if it exists, output from this stage will be appended. Otherwise it will be created
; Name defaults to 'basename.thresh_striplog'
; complete - will be set to 1 if the program finishes normally
; /VERBOSE - set if you want a lot of printout to your screen and some
; windows to pop up. If debug is set, this will be set too.
; /DEBUG - optional flag for debug output. If set to 99, the operator will be
; prompted for override values of the grey, white and fat thresholds
;
; DESCRIPTION
; Fully automated creation of a thresh mask for a T1-weighted MRI, operating from parameters.
; A logfile documents the process.
;
; Naming convention = 'basename_thresh_mask.img'
;
Top
mcstrip_bsemask.pro
;
; NAME
; mcstrip_bsemask - MODULE of McStrip that creates a bse strip mask for an MRI.
;
; SYNOPSIS
; mcstrip_bsemask, SUBJECT_MRINAME = subject_mriname, PARAMS=params, $
; COARSEMASKNAME=coarsemaskname, $
; GUIDE_THRESH=guide_thresh, GUIDEMASKNAME=guidemaskname, $
; BASENAME = basename, LOGFILE=logfile, VERBOSE=verbose, $
; COMPLETE=complete, FINAL_VARS=final_vars, DEBUG=debug
;
; PARAMETERS
; subject_mriname - with full path, ANALYZE format (REQUIRED)
; params - structure variable containing the necessary operating
; parameters for this module (probably extracted from a
; general paramfile by McStrip). If not supplied, the operator
; will be prompted for each parameter. These params are NOT subject-dependent;
; thresh_guide and voxel_target (see below) are variable.
; e.g.
; params = { workdir: './', $
; akerns: [0.0,5.0,10.0,15.], $ ;-- anisotropic smoothing kernels to investigate
; aiters: [3], $ ;-- iterations of anisotropic smoothing to investigate
; gkerns: [.50,.55,.60,.65,.70,.75,.80,.85,.90,.95], $ ;-- Edge detector kernels to investigate
; matchval: 1.0 ] ;-- percentage deviation from desired volume that allows early exit
; coarsemaskname - Influence: provides a bounding cube for calculating the BSE masks.
; guide_thresh - intensity threshold of mri data - used in conjunction with voxel_target
; guidemaskname - The quantity of suprathreshold voxels in a BSE-generated mask against the suprathreshold voxels in
; the guidemask (e.g. a BSE mask is "good" if it captures nearly all of the high-voxels in a threshold mask)
; basename - used to build output filenames; defaults to mriname
; with directory & suffix removed
; logfile - if it exists, output from this stage will be appended. Otherwise it will be created
; Name defaults to 'basename.bse_striplog'
; complete - will be set to 1 if the program finishes normally
; final_vars - returned [akern,aiters,gkern]
; /VERBOSE - set if you want a lot of printout to your screen and some
; windows to pop up. If debug is set, this will be set too.
; /DEBUG - optional flag for debug output
;
; DESCRIPTION
; Fully automated creation of a bse mask for a T1-weighted MRI, operating from a parameter set.
; Parameter space is investigated in this order: for a given smoothing kernel, test iterations. Within that iteration,
; test edge detector kernels. Program will terminate early, if matching criterion is met.
; A logfile documents the process.
;
; Naming convention = 'basename_bse_mask'
Top
mcstrip_consensusmask.pro
;
; NAME
; mcstrip_consensusmask - uses 3 masks to create a consensus, fills voids and smooths
;
; SYNOPSIS
; mcstrip_consensusmask, SUBJECT_MRINAME=subject_mriname, PARAMS=params, $
; MASK1=coarsemaskname, MASK2=threshmaskname, MASK3=bsemaskname, $
; BASENAME = basename, LOGFILE=logfile, COMPLETE=complete, $
; VERBOSE=verbose,DEBUG=debug
;
; PARAMETERS
; subject_mriname - with full path, ANALYZE format (REQUIRED)
; params - structure variable containing the necessary operating
; parameters for this module (probably extracted from a
; general paramfile by McStrip). If not supplied, the operator
; will be prompted for each parameter.
; e.g, params ={ workdir: 'consensusmask', $
; mask1_vote: 1L, $ ; used to build a consensus
; mask2_vote: 1L, $ ; used to build a consensus
; mask3_vote: 1L, $ ; used to build a consensus
; votes_to_pass: 3L, $ ; votes to pass
; (above were for making the candidates, below is to clean them up into a nice mask)
; smooth_fwhm: 0.3, $ ; 3D Gaussian smooth of binary mask using this FWHM (cm)
; keep_thr: 0.90, $ ; after smoothing, keep voxels ge this (controls expansion)
; fill_voids: 1L } ; if set (RECOMMENDED) detects enclosed voids and fills them
; coarsemaskname - necessary if mask1_vote ne 0
; threshmaskname - necessary if mask2_vote ne 0
; bsemaskname - necessary if mask3_vote ne 0
; basename - used to build output filenames; defaults to mriname
; with directory & suffix removed
; logfile - if it exists, output from this stage will be appended. Otherwise it will be created
; Name defaults to 'basename.consensusmask_striplog'
; complete - will be set to 1 if the program finishes normally
; /VERBOSE - set if you want a lot of printout to your screen and some
; windows to pop up. If debug is set, this will be set too.
; /DEBUG - optional flag for debug output
;
; DESCRIPTION
; uses 3 masks to create a consensus, then fills voids and smooths just a little bit
;
; Naming convention: 'basename_mcstrip_mask.img'
;
Top
mcstrip_tuner.pro
;
; NAME
; mcstrip_tuner - helps select operating parameters for the components of mcstrip
;
; SYNOPSIS
; mcstrip_tuner, SUBJECT_MRINAME=subject_mriname,TARGETMASK=targetmaskname, WHAT=what, $
; PARAMFILE=paramfile, PROMPT=prompt, COMPLETE=complete,VERBOSE=verbose, DEBUG=debug
;
; PARAMETERS
; SUBJECT_MRINAME - raw file to use for tuning. Accepts VAPET or ANALYZE input.
; Expects volume indices to be as follows: x=sagittal, y=coronal,z=axial
; TARGETMASK - (optional) A good mask for this subject (e.g. a manual mask). Comparing the
; result mask at each stage of tuning against this allows the program to suggest
; appropriate adjustment of parameters. If not supplied, the user must heed
; instructions and carefully examine each mask when it is displayed.
; WHAT - the stage you want to tune. For complete tuning, go in this order:
; {CHECK_ORIENTATION,SKIN_MASK, WARP_MASK, COARSE_MASK, THRESH_MASK, BSE_MASK, CONSENSUS_MASK, CLEANUP}
; "CLEANUP" will remove duplicate entries from PARAMFILE.
;
; PARAMFILE - If not supplied, defaults to "McStrip_tuner.params". If supplied, the program will
; read the file for operating parameters. After each tuning stage, the program
; will append the relevant parameters to this file (in the case of duplicated entries
; the last instance will be used). The user may edit this text file.
; /PROMPT - if set, the user will be prompted for the necessary parameters for the stage
; (overriding entries in the paramfile)
; COMPLETE - pass this flag back to a calling program to indicate clean completion of specified task
; /VERBOSE - if set, will get lots of printout and popup graphic windows.
; /DEBUG - optional flag for debug output
;
; DESCRIPTION
; Helps select operating parameters for the components of mcstrip, using a target mask if available.
; Activity will be appended to "McStrip_tuner.log"
;
; PLEASE SEE THE HTML DOCUMENTATION "SETTING PARAMETERS IN MCSTRIP" FOR PICTORIAL
; EXAMPLES ALONG WITH DISCUSSION.
;
; NOTE: This program accepts VAPET or ANALYZE format in any orientation, but makes
; "McWorking_*.img" versions in the working directory in ANALYZE format with orientation 'lrapis'.
; Masks that are generated are converted to the orientation and storage
; format of the original mrifile at completion.
Top
reorient_vol.pro
;
; NAME
; reorient_vol - reorients 3D volume array based on orientation string
;
; DESCRIPTION
; Reorients 3D volume array based on orientation string.
; Orientation strings are 6-characters long and consist of three
; 2-character tuples, which specify the physical interpretation
; attached to the byte ordering of the volume. Each tuple may
; take one of two possible values, and one tuple from each of
; the three tuple pairs must be present. The following lists
; the tuple pairs and their meanings:
;
; lr rl -- left-to-right and right-to-left
; ap pa -- anterior-to-posterior and posterior-to-anterior
; is si -- inferior-to-superior and superior-to-inferior
;
; Therefore, the "standard" orientation string of "lrapis" has
; the meaning of: the voxel ordering in the volume is left-to-right,
; followed by anterior-to-posterior, followed by inferior-to-superior.
; (Note that this is a left-handed coordinate system.)
;
;
Top
Documentation last updated October 14, 2004. K. Rehm