JSim Functional Imaging Manual

Introduction

This document describes how to generate functional images using the jsfim command line tool for JSim versions 1.6.67 to 1.6.78. Users of JSim version 1.6.79 and above should see documentation for the latest version.

Prerequisites:

Introduction to the JSim GUI (required)
JSim Projects (required)
Data Files and Project Data Sets (required)
Using Function Generators in JSim (required)
Introduction to the JSim Optimizer (required)
Familiarity with the I4 Imaging System (recommended)

Contents:

Overview
Command Syntax
Example Usage
Input Data File Specifications

Overview

Functional images here refer to JSim data sets whose values map to visual space. Currently, the only supported mapping is to cardiac bullseye (aka polar) maps. Other mappings may be supported in the future. A cardiac bullseye maps physiological values to a nested series of rings, each of which is divided into a fixed number of radial sectors. Each ring corresponds to a z-plane in a reoriented cardiac tomographic image. Bullseye images are typically rendered using various colorscales to represent the values for each plane/ring and sector. A bullseye image in JSim is simply a 2D data curve that takes a value for each plane(z) and sector(s). jsfim calculates one or more such curves and saves them to a variety of file formats. Most useful for I4 users will be the i4bull format .

jsfim operates by optimizing a specified set of JSim model parameters to match a data curve specific for each plane and sector. A separate bullseye image is generated for each model parameter varied during the optimizations. jsfim takes two input files, a project file and a data file. It is designed so that a properly configured project file can be reused with many different data files without modification.

The project file must contain a single JSim model whose optimization tab is mostly set up. The "Parameters to Vary" must be complete. One output bullseye will be generated for each of these parameters. In the "Data to Match" section, the 1st line must contain valid entries in the Par/Expr Pwgt and Cwgt columns. The DataSet and Curve columns are controlled by jsfim, and need not be preset manually. jsfim does not manipulate "Data to Match" lines beyond the 1st one.

The input data file contains sample curves for each ring and sector along with input function driving curves, if any. For a complete specification, see below . However, I4 users usually need not concern themselves with details since "i4samp -bull -tac" automatically generates a JSim readable TAC file that conforms to these specifications.

Command Syntax

The syntax of the jsfim command is as follows:

Usage: jsfim [ switches ] project datafile

Switches:
  -fgen v=curve      Assign v to funcgen using curve from datafile 
  -o file            Direct output to specified file    
  -log file          Save optim reports in log file
  -ofmt dataformat   Specify non-default output data format
  -oprec integer     Specify numeric output precision
  -stopAfter integer Stop after specified # of curves (debug only)
  -oproj             Write modified project (debug only)
  -silent            Repress normal informative messages
  -usage             Print usage synopsis
  -mp N              Enable maximum N-processor multiprocessing

Switch details

-fgen v=curve

Assigns the values of model parameter v to an function generator utilizing curve from the input datafile. If v is already assigned to a function generator, that function generator is used. If not, a new function generator is created. This switch may be used multiple times if more than one assignment is desired.

-o file

Direct jsfim output to file. By default, output is directed to the standard output, usually the terminal.

-log file

Save a optimization results report for each ring and sector in the specified file.

-ofmt dataformat

Write bullseye output in the specified format. The default is "i4bull". Useful alternatives are "line" and "pretty". See here for a complete list.

-oprec integer

Write output data to the specified number of digits of precision. The default is 8, which is appropriate for single-precision numbers.

-stopAfter integer

Stop after integer optimizations. Uncalculated ring/sectors will be output as NaNs. This option is useful in debugging problems with large datasets and/or long model runs.

-oproj

Just before starting 1st optimization, write the current project file state and exit. No bullseye data is written. This project output can then be run interactively using the JSim GUI to diagnose various configuration and scientific problems.

-silent

Repress the processing messages that are normally generated as jsfim runs.

-mp N

Use a maximum of N processors for parallizable run-time calculations. If N is greater that the number of system processors, the lower number is used. By default, only one processor is used. This feature is available in JSim versions 1.6.67 and above.

-usage

Print jsfim syntax synopsis and exit.

Example Usage

This example assumes familiarity with I4 and cardiac image analysis.

Suppose the following: You have an dynamic cardiac image file "heart" (I4 image format) and associated ROI file "cardio.roi" containing ROIs lacav (left atrial cavity), lv (left ventricle myocardium) and div (lv radial divider). Using samples from this image, you will generate bullseye functional images for parameters P1 and P2 in a model "mhed". The model contains extern variable Cin that must be driven by a samples from the left atrial ROI. The model output Cout will be matched against lv samples for each ring/sector during optimization.

Proceed as follows.

Install JSim and I4 on your system, if they're not already there. Be sure to set JSIMHOME appropriately.

Generate an appropriate jsfim input data file (input.tac):

      // generate samples for each ring/sector
      i4samp -bull -tac heart cardio.roi lv div > lv.tac

      // generate sample lacav
      i4samp -tacin heart cardio.roi lacav > lacav.tac

      // combine above tac files
      cattac -a lv.tac lacav.tac > input.tac

Generate an appropriate jsfim project file by:

Start jsim, load the model and compile it;
Select the model optimization tab. Adjust overall optimizer parameters (e.g. algorithm, #calls, etc.) as appropriate. Put P1 and P2 in the "Parameters to Vary" section and set appropriate starting values and bounds for each. In the 1st line under "Data to Match", set the Par/Expr column value to Cout and set the Pwgt and Cwgt columns appropriately.
Save the project file in fim.proj.

Run jsfim to generate bullseye file results.bul:

      jsfim -log fim.log -fgen Cin=lacav fim.proj input.tac > results.bul

Examine results in i4view:

      i4view results.bul

Input Data File Specifications

The jsfim input dataset must contain the following items:

z.ct : 0D curve containing the # of rings (Z planes) in the bullseye;
z.offset : 0D curve containing the Z offset from 0 of the 1st ring;
s.ct : 0D curve containing the # of sectors in the bullseye;
rsR_S where R varies from 1 to z.ct and S varies from 1 to s.ct : these contain reference data to match for the optimizer for each sector. These curves are 1D in most cases, although this is not strictly necessary.

Note that JSim's TAC format data reader generates z.ct, z.offset and s.ct from a FIM_FORMAT clause in the auxiliary data section. The FIM_FORMAT clause is automatically generated via "i4samp -bul -tac".

[This page was last modified 03Mar08, 3:11 pm.]

Model development and archiving support at physiome.org provided by the following grants: NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.