CAWorks-template estimation

From CVRG Wiki

Jump to: navigation, search

Contents

User Guide to Cardiac Template Estimation, with examples

Overview

The template-estimation remote processing pipeline provides volume-based creation of a single template from a population of cardiac images.

PDF Documentation for the caworks template-estimation functionality is in: Lddmm-cardiac.pdf

Using CAWorks for Volume Template Estimation

CAWorks is the preferred means for invoking the template-estimation remote processing. It performs many of the tasks of creating a remote processing data file with md5 sum, and sending it to the proper ftp site. It is also possible from caworks to generate the landmarks that are necessary for the vte process.

The Remote Template Estimation Panel in CAWorks generates a template estimate from a population including a hypertemplate heart and multiple targets. The processing pipeline requires left ventricle segmentation masks and landmark files for each of the hypertemplate and target images. The mask files must be in Analyze (*.img, *.hdr) format. landmark files will be generated using CAWorks' Landmark filter (landmark files use the *.lmk file type). For instructions on using the Landmark filter, see below. The hypertemplate and target mask images and landmark files should all be placed in the same population directory and the filename for each image should match its corresponding landmark file name (e.g. patient1.img, patient1.hdr, patient1.lmk; patient2.img, patient2.hdr, patient2.lmk; etc.). The remote template estimation pipeline resamples each target to the hypertemplate resolution, performs rigid matching of the targets to the hypertemplate with global scaling, then performs LDDMM across the population to estimate a template for the dataset. It it assumed that the hypertemplate has no odd-valued dimensions, as LDDMM will not run properly if any of the image dimensions are not divisible by 2.

Using the Remote Template Estimation Panel

  1. To use the CAWorks Remote Template Estimation Panel, you must first register an email address at the MRI Studio website. Updates on the status of the remote process will be sent to this email address.
  2. Under the Remote Template Estimation tab in the CAWorks Panel, enter the email address and designate the locations of the work directory and desired result directory, as well as the directory containing the population data.
  3. In the Remote Template Estimation menu, indicate the hypertemplate by highlighting the filename of the hypertemplate image file.
  4. Press the “Send Remote Processing Job” button in the Remote Template Estimation tab to send the job for remote processing. You will receive emails when processing begins on this job and when it completes.
  5. When processing is complete, copy the MD5 Sum from the notification email into the space next to “Sent MD5 Sum” in the Remote Template Estimation tab, make sure the designated result directory is correct, and press the “Receive Remote Processing Job”. The results of the cardiac remote processing can now be accessed in the result directory. The output files should include the new template image as well as the rigid-transformed target images.

Cardiac Volume Template Estimation using ftp with examples

Template-estimation can be invoked via ftp. The input file you transfer to the incoming ftp address will be routed to the icm cluster and processed.

For this example, the user will create a new template from a population of cardiac images and their corresponding landmarks.

The population data files must reside in the same data directory (in this example, caleed "data"). The base file names for the images and the landmarks of each subject must be the same, with the following convention for the file extension:

Data File Extension Example
Analyze Image Data .img ES_JHU_Template.img
Analyze Image Header .hdr ES_JHU_Template.hdr
Landmark Data .lmk ES_JHU_Template.lmk

The user selects a "hypertemplate" from among the population (in this case, the subject ES_JHU_Template), which is essentially the starting point for calculating a new template from all the data. Example Input Data can be found here: VTEInputPopulation.zip

  1. Create these files, with example contents as follows...
    1. identity.txt - your mristudio registered e-mail
      youremail@yourdomain.com
    2. config.txt - configuration file.
      verbose=false
      hypertemplate=ES_JHU_Template
      template_data_directory=data
      • verbose - return intermediate processing outputs created by the auto-segmentation process
      • hypertemplate - specifies the base file name of the subject in the population to use as the hypertemplate
      • template_data_directory - directory containing the population data
    3. local_address.txt - contains the local name of the target.img and target.hdr files
      template_data_directory data
  2. Compress the following files into tmp.zip...
    1. identity.txt
    2. config.txt
    3. local_address.txt
    4. data
      $ zip tmp.zip config.txt identity.txt local_address.txt data # linux zip command
  3. Calculate the md5 hash of tmp.zip. You have changed the identity.txt to contain your e-mail address, so your md5 sum will be DIFFERENT than the one below...
    $ md5sum tmp.zip
    58ab0a3576e86818f81b361b32d7597e  tmp.zip
  4. Rename tmp.zip to its md5 hash. This is your file for upload. Here is an example: 58ab0a3576e86818f81b361b32d7597e.zip
    $ mv tmp.zip 58ab0a3576e86818f81b361b32d7597e.zip
  5. Login to the mristudio ftp server using your registered email for the password.
    $ ftp ftp.mristudio.org
    Connected to ftp.mristudio.org.
    220 Welcome to MRI STudio FTP service. -- Turn off Passive Mode.
    Name (ftp.mristudio.org:xxxxxxxx):  anonymous
    331 Please specify the password.
    Password:
    230 Login successful.
    Remote system type is UNIX.
    Using binary mode to transfer files.
  6. Put your compressed folder on the queue
    ftp>  cd /pub/INCOMING/template-estimation/process-queue
    250 Directory successfully changed.
    ftp> put
    58ab0a3576e86818f81b361b32d7597e.zip
    local: 58ab0a3576e86818f81b361b32d7597e.zip remote: 58ab0a3576e86818f81b361b32d7597e.zip
    200 PORT command successful. Consider using PASV.
    150 Ok to send data.
    226 File receive OK.
    615240 bytes sent in 0.02 secs (37418.0 kB/s)
  7. You should receive an email with the subject "ICM vte Processing: 58ab0a3576e86818f81b361b32d7597e" informing you that your segmentation is being processed.
  8. You should receive an email with the subject "vte Process Complete: 58ab0a3576e86818f81b361b32d7597e" informing you that your segmentation is complete.
  9. Get your results from the mristudio ftp server.
    $ ftp ftp.mristudio.org
    Connected to ftp.mristudio.org.
    220 Welcome to MRI STudio FTP service. -- Turn off Passive Mode.
    Name (ftp.mristudio.org:xxxxxxxx): anonymous
    331 Please specify the password.
    Password:
    230 Login successful.
    Remote system type is UNIX.
    Using binary mode to transfer files.
    ftp> bin
    200 Switching to Binary mode.
    ftp> cd /pub/OUTGOING/template-estimation/output/58ab0a3576e86818f81b361b32d7597e/
    250 Directory successfully changed.
    ftp> get Result.zip
    local: Result.zip remote: Result.zip
    200 PORT command successful. Consider using PASV.
    150 Opening BINARY mode data connection for Result.zip (130669 bytes).
    226 File send OK.
    130669 bytes received in 0.01 secs (13935.4 kB/s)
    ftp> exit
    221 Goodbye.
  10. Unpack your results from the zip file.
    $ unzip Result.zip 
    Archive:  Result.zip
    inflating: config.txt
    extracting: identity.txt
    inflating: local_address.txt
    creating: output/
    inflating: output/newtemplate.img
    inflating: output/newtemplate.hdr
    extracting: priority.txt

Example Data

Example Data for the ftp path to template-estimation is here: 58ab0a3576e86818f81b361b32d7597e.zip. Please note that this zip file CAN NOT be used as is. Unzip the file, modify identity.txt with your MRI Studio registered e-mail address, the rezip as described above.

Results from the example data are here: Result.zip.

Personal tools
Project Infrastructures