BIRN Header

Software at CIS : lddmm-volume : Namespace

about | tutorial | user validation | remote validation | manual | namespace | faq | credits | changelog | feedback

Content

Overview

Integration of LDDMM into the Biomedical Informatics Research Network (BIRN) has assisted in evolving LDDMM from a command line application to a web portal application making use of globus. This evolution has been gradual. In the development of the LDDMM BIRN portal, it became evident that a consistent namespace for data access and file organization is needed.

LDDMM takes as input two analyze images in 2d or 3d and compares them. The resultant output is timestep velocity vector data describing the change in shape of the objects. There is a voluminous amount of resultant data from the comparison of the two images. Due to this large volume, a consistent file structure is needed for storing the data. In typical research studies, there is an atlas which is compared to many target images. In this case, LDDMM would input be an Atlas image and a directory which contains a collection of target images to compare. In order, to streamline the lddmm processing, the images may be local or in SRB.

We will not look at the LDDMM parameters for processing but will focus on providing a simple consistent way of addressing input and output for the LDDMM processing. Input/Output to LDDMM may be a directory or a file, it may be local or within SRB. In order to allow a flexible way of describing input/ouput locations of data for LDDMM, we decided to user the Uniform Resource Locator (URL) style of format to address our data location.

A url_io module is used in the LDDMM script to acquire or upload the data. url_io will parse the URL formatted input and output statments.

Assumptions

The LDDMM script will use an url_io parsing script to manipulate the URL formated data. The url_io script will have a 'url_input' and a 'url_output' command. The 'url_input' will return the local location of data or will create a local temporary copy of the data from a remote location. The 'url_output' will put data to the provided location. If the output is to a remote location, it will do the necessary upload process. If group permissions are defined in the upload process, it is assumed all upload data will have the same group permissions.

URL format

/tmp/mydata/ default local directory
/tmp/mydata/my.img local file
file:/tmp/mydata/my.img local file
dir:/tmp/mydata/ local directory
srbfile:/tmp/mydata/my.img SRB access to image
srbdir:/tmp/mydir/ SRB access to dir
srbdir://jhu-cis.groups.a,birn.groups.r/tmp/mydir/ SRB access to dir with group permission settings.
srbdir://@uiowa-gpop.nbirn.net/tmp/mydir/ SRB access to data at uiowa-gpop.nbirn.net

URL_IO Script

The url_io module is used to parse the URL formatted input and output statements. Example use: 
#!/bin/bash
# Include URL I/O
#
# URL_TEMP=/tmp/url_io.$$	# default temp is the process ID under tmp.
# KEEP_TEMP=no			# automatically removes temp data.
#
. ./url_io
# Then something like this would map the birn_url to a
# local location for processing.
url_input($3, tmp_local_location)
url_output(tmp_local_location, $4)

LDDMM Example

SRB_HOME=/home/BIRN/Human/Dev/jhu-cis/lddmm/analysis/hippocampus/mgh.20030505/results/020109_vc8289_left_hippo/

lddmm  -A srbdir:${SRB_HOME}/020109_vc8289_left_hippo/ \
      -S srbdir:${SRB_HOME} -o srbdir:/home/akolasny.jhu-cis/results/

BIRN Portal Example

JHU_GPOP: jhu-cis-gpop.nbirn.net

/opt/birn/lddmm/bin/lddmm --help

USAGE (1): lddmm [-d dimension] [OUTPUT OPTIONS] -A atlas_path -T single_target_path [PARAMETERS]
Maps from atlas to target

USAGE (2): lddmm [-d dimension] [OUTPUT OPTIONS] [-A atlas_path] -S target_series_path [PARAMETERS]
Performs a mapping from atlas to every directory in the target path
If the Atlas is not specified, the program assumes the target folder is the
name of the atlas (i.e., a directory structure of the form .../ATLAS/TARGET{1..n}
where ATLAS is also one of the TARGETs

OUTPUT OPTIONS:
[-o OUTPUT_DIR] Places results for each target in OUTPUT_DIR/TARGET.  If unspecified,
output is written to TARGET directory
[-t] for each TARGET, creates OUTPUT_DIR/TARGET.tar.gz if -o is specified,
TARGET/TARGET.tar.gz otherwise
[-m] creates TARGET/vtk/movies/preview.mpg showing atlas deformation along with
corresponding velocity vector fields

[-v, --all-info] print version information
[-h, --help] print this message

Dimension can be 2 or 3 (default)

Paths can be specified in BIRN URL_IO format, and can be relative or absolute.  Example:
   /tmp/mydata/                 local directory (default)
   /tmp/mydata/my.img           local file
   dir:/tmp/mydata/             local directory
   file:/tmp/mydata/my.img      local file
   srbdir:/tmp/mydir/           SRB access to dir
   srbfile:/tmp/mydata/my.img   SRB access to image
See http://www.cis.jhu.edu/software/lddmm/namespace.html for more information
SRB functionality not enabled through BIRN Portal

PARAMETERS - All or none must be specified; Defaults in parentheses
 1.Total Simulations (1000)                    2.Timesteps (10)
 3.Delta (0.1)                                 4.EpsilonEnergy (0.0000000001)
 5.ProcsZ (1)                                  6.ProcsY (1)
 7.ProcsX (1)                                  8.Gamma (0.01)
 9.Operator L (1)                             10.PadI (20)
11.PadH (5)                                   12.NormGradientToStopSimulation (1000)
13.Restart (0)                                14.NoiseStandardDeviation (1)
15.FractionOriginalImageErrorToReach (0.02)   16.StepsAfterWhichChangeImgMatchEpsilon (25)
Currently, only serial processing is supported (Procs{X,Y,Z} = 1).
See http://www.cis.jhu.edu/software/lddmm/manual.html for more information on parameters

Example with parameters:
lddmm -A my.img -T your.img 1000 10 0.1 0.0000000001 1 1 1 0.01 1 20 5 1000 0 1 0.02 25

Last Modified: Thursday, 30th May, 2013 @ 09:26am

NIHNCRRDHHSTeraGrid