Introduction

This document describes how to generate functional images using the jsfim command line tool.

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 or J4 Imaging Systems (recommended)

Contents:

• Overview
• Command Syntax
• Example Usage
• Comments or Questions?
  Give feedback

Overview

A JSim functional image is a data curve that maps a model parameter to some visual space. For example, a cardiac bullseye image represents the left ventricle myocardium as a multicolored circular disk where color values code model parameter values for corresponding segments of the myocardium. jsfim thinks of a functional image as a collection of values corresponding to image segments and provides the mechanism to calculate these values using JSim models and store the results. It is up to external programs (such as I4 or J4) to render the resulting data files using appropriate geometries and color scales.

jsfim operates by optimizing a specified set of JSim model parameters to match a data curve specific for each image segment. A separate functional image data curve is generated for each model parameter varied during the optimizations. jsfim requires an input project file and one or more input data files. 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 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 preconfigured. jsfim does not manipulate "Data to Match" lines beyond the 1st one. If there is more than one model in the project, you must tell jsfim which model to use via the -model switch.

The required data file must contain sample curves for each image segment. This file may also contain other curves, including input function driving data. By default, all curves in the data file are treated as sample curves. If the data file contains other curves (such as input drivers), you must use the -ref switch to specify which curves should be used as segment samples.

Upon completing the optimzations for each image segment, a data file containing functional image curves (one for each optimization parameter) is written to the standard output (or to a file, if -o is specified). By default, the output is written in columnar data format, which is appropriate for the J4 imaging system. I4 users desiring I4 bullseye output should consult the example below.

Command Syntax

The syntax of the jsfim command is as follows:

Usage: jsfim [ switches ] project datafile

Switches:
  -model name            Select named model within project
  -i v=expr              Assign input v to expression 
  -fgen [file] v=curve   Drive input v via data curve 
  -o file                Write func image(s) to specified file
  -ofit file             Write curve fits to specified file
  -log file              Save optim reports in log file
  -ofmt dataformat       Specify non-default FIM output data format
  -ofitfmt dataformat    Specify non-default model fit output data format
  -oprec integer         Specify numeric output precision
  -ref prefix            Select ref curves by prefix
  -refx name             Exclude ref curves by name
  -oproj                 Write modified project (debug only)
  -noabort               Don't abort if some segments fail
  -conflim               Calculate parm confidence limits
  -silent                Repress normal informative messages
  -usage                 Print usage synopsis
  -mp N                  Enable maximum N-processor multiprocessing  
  -server name           Connect to remote server 
  -builddirsfx suffix    Force build directory suffix (experts only!)

Switch details

-model name

Select the named model within the project file. This switch is required only when the project file contains multiple models.

-i v=expr

Assigns the value of model parameter v to an algebraic expression.

-fgen [file] v=curve

Assigns the values of model parameter v to an function generator utilizing curve from the [file] (if present) or the primary data file (if not). The curve may be specified by either name or description. This flexibility is most important for TAC file curves whose descriptions (e.g. "lacav") are usually easier to deal with than their names (e.g. "R1i1"). The file name may not contain the equals sign (=). 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

Write functional image output to file. By default, output is directed to the standard output, usually the terminal.

-ofit file

Write optimization fit data to file. By default, this data is not written anywhere. Fit data is written in JSML format.

-log file

Save a optimization results report for each image segment in the specified file.

-ofmt dataformat

Write functional image output in the specified format. The default is "column". I4 users will usually prefer "i4bull". See here for a complete list.

-ofitfmt dataformat

Write model fit output in the specified format. The default is "JSML". See here for a complete list. This switch is available in JSim releases 2.14 and above.

-oprec integer

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

-ref prefix

Treat only data curve names or descriptions beginning with the specified prefix as segment sample curves. This is useful when the data file contains other data curves. By default, all curves in the data file are treated as segment sample curves.

-refx name

Exclude ref curves by name. This is useful when the data file contains curves that should be excluded from modeling. This switch is available in JSim release 2.13 and above.

-oproj

Write the current project file state and exit. No optimizations are performed, and no functional image data is written. This project output can then be run interactively using the JSim GUI to diagnose various configuration and scientific problems.

-noabort

Do not abort entire run if optimizer fails for some segments. Functional image values will be NaN's at values in segments where the optimizer fails. Without this switch, the entire run aborts if the optimzer fails on any segment.

-conflim

Calculate parameter confidence limits after each optimization. This require P*S additional model evaluations, where P is the number of parameters to be optimized and S in the number of image segments.

-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.

-server name

Connects to a remote computational server. By default, a local server is used. This switch available in JSim version 2.07 and above.

-builddirsfx SUFFIX

Specify the temporary build directory as $HOME/.jsim/workSUFFIX. The specified build directory must NOT EXIST, or else JSim will exit with an error. This switch is for expert use only. It was added to prevent large numbers of simultaneous JSim jobs getting confused about whose build directory is whose. When using this switch, the user is responsible that no two JSim jobs are using the same build directory at the same time, lest unexpected (read bad) results occur. This switch is available in JSim 2.09 and above.

-usage

Print jsfim syntax synopsis and exit.

Example Usage

Suppose the following: You wish to generate functional images for parameter P1 and P2 in model example.mod. The model contains extern variable Cin(t) that must be driven by samples from a left atrial ROI. The model output Cout will be match against sample curves for each image sector during optimization.

First, generate an appropriate jsfim project file as follows:

1. Install JSim on your system, if it's not already there.

    

2. Start jsim, load the model and compile it;
3. 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.
4. Save the project as fim.proj.

Now use the J4 or I4 system instructions below to generate jsfim input files, depending on which system you're using.

J4 Example Instructions

The J4 system is still under development. As currently envisioned, it will generate separate data files (columnar data format) for the input and segment sample curves. Suppose we have an input file RestCav.cdata containing a single curve named "cav" and an LV samples file RestLVMyo.cdata containing curves segment_1 through segment_20.

Generate a functional image file (results.cdata) via the command:

      jsfim -log fim.log -fgen RestCav.cdata Cin=cav fim.proj RestLVMyo.cdata > results.cdata

results.cdata now contains 2 curves "P1" and "P2", each with 20 data points. The results may be examined in a editor or other data analysis tools. The means by which the J4 system will display this data is still under development.

I4 Example Instructions

Let's assume you have a 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) to generate jsfim data files. Proceed as follows.

1. Install I4 on your system, if it's not already there.
2. Use I4 to generate appropriate jsfim input data files:

         // generate sample lacav
         //   the input curve is named "R1i1" with description "lacav"
         i4samp -tacin heart cardio.roi lacav > lacav.tac
   
         // generate samples for each ring/sector
         //   the sample curves are named "R1s*" with descriptions "rs*_*"
         i4samp -bull -tac heart cardio.roi lv div > lv.tac
   
         // you may wish to combine above tac files
         cattac -a lv.tac lacav.tac > combined.tac
   

3. Run jsfim to generate bullseye file results.bul one of two ways:

         // this command uses two input files (lacav.tac and lv.tac)
         jsfim -log fim.log -fgen lacav.tac Cin=R1i1 -ofmt i4bull fim.proj lv.tac > results.bul
   
         // this command uses the combined file (combined.tac) instead
         //  the -ref switch is required since data file contains both the input and sample curves
         jsfim -log fim.log -fgen Cin=R1i1 -ref rs -ofmt i4bull fim.proj combined.tac >  results.bul
   
         // Note that the -fgen curve may be specified in the above commands
         // as either "R1i1" or "lacav"
   

4. Examine results in i4view:

         i4view results.bul
   

I4 Input Data File Specifications

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. For those interested in the technical details, 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".

Comments or Questions?

Give feedback

 

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; 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.