Tools¶

DTI_QA¶

This interface assists in executing Bennett Landman’s DTI_QA toolkit.

TBD: More documentation here.

Because DTI_QA is built upon matlab, the generated commands are m-code.

Functions¶

seam.dti_qa.dtiqa_mcode(images, basedir, dtiqa_path, n_b0=1)¶

Returns m-code that can be executed in matlab to run DTI_QA

Parameters:	images (str,list) – path to single raw DTI image or list of multiple basedir (str) – base directory to write results dtiqa_path (str) – path to DTI_QA installation n_b0 (int) – # of b0 averages (default is 1)

Usage:

>>> from seam.dti_qa.v1 import dtiqa_mcode
>>> images = ['/path/to/first.nii', '/path/to/second.nii']
>>> basedir, n_b0, dtiqa_path = '/path/to/output', 6, '/path/to/dtiqa'
>>> f = open('dti_qa.m', 'w')
>>> f.write(dtiqa_mcode(images, basedir, dtiqa_path, n_b0))
>>> f.close()

Versioning:

V1 defines the following:
- seam.dti_qa.v1.dtiqa_mcode() that generates m-code to run DTI_QA.

Freesurfer¶

Freesurfer is a set of software tools for the study of cortical and subcortical anatomy. In the cortical surface stream, the tools construct models of the boundary between white matter and cortical gray matter as well as the pial surface. Once these surfaces are known, an array of anatomical measures becomes possible, including: cortical thickness, surface area, curvature, and surface normal at each point on the cortex. The surfaces can be inflated and/or flattened for improved visualization. The surfaces can also be used to constrain the solutions to inverse optical, EEG and MEG problems. In addition, a cortical surface-based atlas has been defined based on average folding patterns mapped to a sphere. Surfaces from individuals can be aligned with this atlas with a high-dimensional nonlinear registration algorithm. The registration is based on aligning the cortical folding patterns and so directly aligns the anatomy instead of image intensities. The spherical atlas naturally forms a coordinate system in which point-to-point correspondence between subjects can be achieved. This coordinate system can then be used to create group maps (similar to how Talairach space is used for volumetric measurements).

Most of the FreeSurfer pipeline is automated, which makes it ideal for use on large data sets.

Recipes¶

seam.freesurfer.v1.recipe.build_recipe(subject_id, input_data, script_dir, use_xvfb=False, recon_flags=None)[source]¶

This function builds a complete pipeline around Freesufer.

It does the following:

Imports data using recon-all -i
Runs the main recon-all command with the following flags:
- -qcache
- -measure thickness
- -measure curv
- -measure sulc
- -measure area
- -measure jacobian_white
Takes volumetric snapshots using tkmedit
Per hemisphere:
- Converts the aparc.a2009s.annot file to labels in the subject’s label directory
- Takes screenshots of the inflated surface with and without the advanced labels.

Parameters:	subject_id (str) – subject identifier input_data (str,list) – list of paths or string to subject’s T1 images script_dir (str) – directory to write scripts & screenshots use_xvfb (boolean) – Wrap `tksurfer` & `tkmedit` commands in xvfb-run, useful if running in a non-graphical (ie cluster) environment. recon_flags (list) – other flags to pass to `recon-all`
Return type:	tuple
Returns:	paths to recon script, tkmedit script and lh & rh tksurfer scripts
Note:	the main script is set as executable
Note:	This function is exposed on the command line through `build-recon-v1`

Functions¶

These are lower-level functions to be used when more customization is needed than provided by the above recipes.

seam.freesurfer.v1.core.recon_input(subject_id, data)[source]¶

The function supplies the recon-all -i command. This command initializes the Freesurfer directory for a subject and converts the raw data into an internal format for use by the rest of the recon-all pipeline.`

Parameters:	subject_id (str) – Subject identifier data (str,list) – path(s) to input data
Returns:	command that will execute `recon-all -i` command
Return type:	str

Usage:

>>> from seam.freesurfer import recon_input
>>> recon_input('sub0001', '/full/path/to/data.nii')
'recon-all -s sub0001 -i /full/path/to/data.nii'
>>> # or with multiple inputs...
>>> recon_input('sub0001', ['/path/first.nii', '/path/second.nii'])
'recon-all -s sub0001 -i /path/first.nii -i /path/second.nii'

seam.freesurfer.v1.core.recon_all(subject_id, flags=None)[source]¶

This function supplies the recon-all -all command. This command will run the entire anatomical analysis suite of Freesurfer.

Note:	Use `seam.freesurfer.recon_input()` to setup this subject
Parameters:	subject_id (str) – Subject identifier on which to run `recon-all` flags (list) – command-line flags to pass to `recon-all`
Returns:	command that will execute `recon-all -all`
Return type:	str

Usage:

>>> from seam.freesurfer import recon_all
>>> recon_all('sub0001', flags=['-use-gpu'])
'recon-all -s sub0001 -all -qcache -measure thickness -measure curv -measure sulc -measure area -measure jacobian_white -use-gpu'

seam.freesurfer.v1.core.tkmedit_screenshot_tcl(basepath, beg=5, end=256, step=10)[source]¶

Supplies a tcl string that can be used to take screenshots of a volume using tkmedit

Images are written to *basepath*/tkmedit-$i.tiff where beg <= i <= end in increments of step

Parameters:	basepath – base directory to write images in beg (int) – Beginning slice where screenshots begin end (int) – End slice where screenshots end step (int) – Value to increment successive screenshots

Usage:

>>> from seam.freesurfer import tkmedit_screenshot_tcl
>>> f = open('tmedit_screenshots.tcl', 'w')
>>> f.write(tkmedit_screenshot_tcl('/path/to/image_dir'))
>>> f.close()
$ tkmedit sub0001 brain.finalsurfs.mgz -aseg -surfs -tcl tkmedit_screenshots.tcl

seam.freesurfer.v1.core.tkmedit_screenshot_cmd(subject_id, volume, tcl_path, flags=None)[source]¶

Supplies a command to execute a tcl script in tkmedit for subject_id‘s volume

Parameters:	subject_id (str) – subject identifier volume (str) – Volume for tkmedit to load tcl_path (str) – Path to tcl script flags (list) – Flags to pass to `tkmedit`

Usage:

>>> from seam.freesurfer import tkmedit_screenshot_cmd
>>> tkmedit_screenshot_cmd('sub0001', 'brain.finalsurfs.mgz', '/path/tkmedit.tcl', ['-aseg', '-surfs'])
'tkmedit sub0001 brain.finalsurfs.mgz -aseg -surfs -tcl /path/tkmedit.tcl'

seam.freesurfer.v1.core.tksurfer_screenshot_tcl(basepath, annot='aparc.a2009s.annot')[source]¶

Supplies a tcl command to take screenshots of a surface using tksurfer

Four screenshots are taken:

lateral view (default view when tksurfer opens) saved to basepath-lateral.tiff
medial view saved to basepath-medial.tiff
Lateral view with an annotation loaded (given by annot) saved to basepath-annot-lateral.tiff
Medial view with an annotation loaded (given by annot) saved to basepath-annot-medial.tiff

Parameters:	basepath (str) – prefix for images to be saved annot (str) – annotation file to load for overlay on the surface

Usage:

>>> from seam.freesurfer import tksurfer_screenshot_tcl
>>> f = open('tksurfer.lh.tcl', 'w')
>>> f.write(tksurfer_screenshot_tcl('/path/to/screenshots/lh'))
>>> f.close()

seam.freesurfer.v1.core.tksurfer_screenshot_cmd(subject_id, hemi, surface, tcl_path, flags=None)[source]¶

Supply a command that will run tksurfer using the surface from subject_id‘s hemi hemisphere and execute a tcl script.

Parameters:	subject_id (str) – subject identifier hemi (str) – ‘lh’ or ‘rh’, hemisphere to open in tksurfer surface (str) – surface to view tcl_path (str) – path to tcl script to execute flags (list) – flags to pass into `tksurfer`

Usage:

>>> from seam.freesurfer import tksurfer_screenshot_cmd
>>> tksurfer_screenshot_cmd('sub0001', 'lh', 'inflated', '/path/tksurfer.lh.tcl', ['-gray'])
'tksurfer sub0001 lh inflated -gray -tcl /path/tksurfer.lh.tcl'

seam.freesurfer.v1.core.annot2label_cmd(subject_id, hemi, annot_path, outdir, surface='white')[source]¶

Build the mri_annotation2label commandline string.

Parameters:	subject_id (str) – subject identifier hemi (str) – ‘lh’ or ‘rh’, hemisphere to use annot_path (str) – path to annotation file outdir (str) – output directory to place labels surface (str) – surface to use when generating coords in labels

Versions:

V1 defines the following recipes:

seam.freesurfer.v1.build_recipe() for building a complete script for executing the recon-all pipeline.

V1 defines the following functions:

recon-all -all exposed through seam.freesurfer.v1.recon_all()
recon-all -i exposed through seam.freesurfer.v1.recon_input()
seam.freesurfer.v1.tkmedit_screenshot_tcl() for generating tcl to take screenshots of a volume loaded in tkmedit.
seam.freesurfer.v1.tkmedit_screenshot_cmd() for supplying a command to execute tkmedit with a tcl script.
seam.freesurfer.v1.tksurfer_screenshot_tcl() for generating a tcl script to take screenshots of a hemisphere using tksurfer
seam.freesurfer.v1.tksurfer_screenshot_cmd() for supplying a command to run tksurfer and generate screenshots.
seam.freesufer.v1.annot2label_cmd() for building a mri_annotation2label command.