stats_simulations

Measured data-derived simulations based on class statistics

Goal: create simulated images based on statistics from images of phantoms beyond augmentations

There are two steps to simulate images:

1. estimate intensity statistics of reference regions with semantic meanings and store the parameters in a set of CSV files with the validation accuracy metrics
2. generate simulated intensity images based on designed masks and the parametrized generative statistical models.

Assumption: reference regions are characterized by unimodal intensity distribution functions and have limited texture. There is limited or no geometric or chemical gradient over any Region mask.

I. Input Data Preparation

1. Measured images with masks defining reference regions of interests (ROIs) representing semantic classes
2. Designed masks consisting of ROIs representing semantic classes defined in measured images
3. CSV file that defines the mapping between the labels of reference ROIs and the labels in designed masks

1. Preparing masks with reference ROIs

Option A

• Use ImageJ/Fiji to load measured images and create ROIs (annotations) manually
• Convert annotations into binary masks
• Run connectivity analysis ImageJ/Fiji plugin to create a labeled mask

Option B

• Use a clustering algorithm
• Select semantically meaningful clusters and set the rest to zero (background)

Option C(for 3D sequence-of-images data)

• Use ImageJ/Fiji to load sequence of measured images and use tools such as Z-project to obtain a single cleaner (higher signal to noise ratio).
• Use processing tools such as normalization, thresholding, drawing etc to obtain masks by replacing values with known label.
• Ensure removal of all gaps by finding all labels and sizes of their connected region.

2. Preparing masks with designed ROIs

Option A

• Follow Option A for preparing masks with reference ROIs

Option B

• Write the code that generates the mask (see DesignScene.java class)

3. Preparing CSV files that define mask label mappings

• Follow the CSV example in the data folder data\Mask\DesignedROI

Note: remember to use the same numerical label for the same semantic label in all designed ROIs of multiple masks if all masks will be used for training an AI segmentation model.

II. Software Execution

1. Installation requirements

• Java 1.8
• Maven 4.0

linux java 1.8 installation: sudo apt install openjdk-8-jdk-headless

linux maven installation: sudo apt install maven see

2. Build executable jar file

• This is a maven project. Run mvn install to compile the java code into a jar file. The jar file will be in the target folder with the current main class set to data_simulation.onedim.IntensityEstimator
• Modify the pom.xml file to set the main to data_simulation.onedim.IntensityGenerator if you would like to have another jar file for running the intensity generation step.

Note: If Maven build fails giving an error message :"Some mirrors were deemed unsafe due to certain types of attacks". This may be due to newer versions of Maven [disabling or blocking some mirrors] (https://maven.apache.org/docs/3.8.1/release-notes.html#cve-2021-26291)

To overcome this issue, go to settings.xml file in maven installation and delete or comment the following code block:

"<mirror> <id>maven-default-http-blocker</id> <mirrorOf>external:http:*</mirrorOf> <name>Pseudo repository to mirror external repositories initially using HTTP.</name> <url>http://0.0.0.0/</url> <blocked>true</blocked> </mirror>"

Maven should start being able to build successfully now.

Warning:Please proceed at your own risk.

3. Run executable jar file

Depending on whether the intention is to use a single 2D image or a sequence of images, there are slight differences.

(i) Single 2D masks/images

Follow these instructions if using for individual masks/images.

Option A

• two jar files with predefined main to be

data_simulation.onedim.IntensityEstimator

and

data_simulation.onedim.IntensityGenerator

• run "estimator" jar file:

java -jar -i <project path>\\stats_simulations\\data\\Measured -m <project path>\\stats_simulations\\data\\Mask\\MeasuredROI\\reference_mask_H0.tif -o <project path>\\stats_simulations\\data\\Estimated

• run "generator" jar file:

java -jar -ip <project path>\\stats_simulations\\data\\Estimated -id <project path>\\stats_simulations\\data\Mask\\DesignedROI -im <project path>\\stats_simulations\\data\\Mask\\DesignedROI\\mapping_contrast_phantoms.csv -o <project path>\\stats_simulations\\data\\Generated

Note: use either forward slash or two backward slashes.

Option B

• one jar file

• run "estimator" jar file: java -cp .\\onedim-0.0.1-SNAPSHOT.jar data_simulation.onedim.IntensityEstimator -i <project path>\\stats_simulations\\data\\Measured -m <project path>\\stats_simulations\\data\\Mask\\MeasuredROI\\reference_mask_H0.tif -o <project path>\\stats_simulations\\data\\Estimated

• run "generator" jar file: java -cp .\\onedim-0.0.1-SNAPSHOT.jar data_simulation.onedim.IntensityGenerator -ip <project path>\\stats_simulations\\data\\Estimated -id <project path>\\stats_simulations\\data\\Mask\\DesignedROI -im <project path>\\stats_simulations\\data\\Mask\\DesignedROI\\mapping_contrast_phantoms.csv -o <project path>\\stats_simulations\\data\\Generated

Note: for more information about command line execution see.

Note

• For INFER data, where many images need to be grouped together instead of treated separately, use: ``bash batch_simulations.sh <mapping-contrast-phantoms.csv name> ''

*Note: relative-path means path relative to the data folder.

(ii) Sequence of 2D images

To run estimation or generation on a sequence of 2D images/masks, use the batch files as follows:

source INFER_simulations.sh <path-to-project> <full-path-to-sample-folder> <relative-path-to-estimated-folder> <mapping-csv-filename> <relative-path-to-generated-folder>

Contact information

• Peter Bajcsy, ITL NIST, Software and System Division, Information Systems Group
• Contact email address at NIST: [email protected]

Credits

• The contributions to the code in this repository came from:
  • Peter Bajcsy
  • Pushkar Sathe

Related Material

• URL for associated project on the NIST website: https://www.nist.gov/itl/ssd/information-systems-group

Citation

• Pushkar S. Sathe, Caitlyn M. Wolf, Youngju Kim, Sarah M. Robinson, M. Cyrus Daugherty, Ryan P. Murphy, Jacob M. LaManna, Michael G. Huber, David L. Jacobson, Paul A. Kienzle, Katie M. Weigandt, Nikolai N. Klimov, Daniel S. Hussey & Peter Bajcsy "Data-driven simulations for training AI-based segmentation of neutron images." Scientific Reports, 14(1), 6614.