Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated UKF code with addtional seeding and stopping options #161

Merged
merged 3 commits into from
Jun 21, 2024
Merged

Updated UKF code with addtional seeding and stopping options #161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
de43caf
Add WM/GM/CSF masks
zhangfanmark Jan 13, 2022
235edc9
UI change and I/O check
zhangfanmark Jan 18, 2022
048b203
Description update for CLI usage
zhangfanmark Jan 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions UKFTractography/UKFTractography.cxx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,14 @@ int ModuleEntryPoint(int argc, char **argv)
try
{
if (tract->LoadFiles(ukf_settings.dwiFile,
ukf_settings.seedsFile,
ukf_settings.maskFile,
normalizedDWIData, outputNormalizedDWIData) == EXIT_FAILURE)
normalizedDWIData,
outputNormalizedDWIData == EXIT_FAILURE,
ukf_settings.seedsFile,
ukf_settings.stopFile,
ukf_settings.wmFile,
ukf_settings.gmFile,
ukf_settings.csfFile))
{
itkGenericExceptionMacro(<< "::LoadFiles failed with unknown error.");
}
Expand Down
174 changes: 133 additions & 41 deletions UKFTractography/UKFTractography.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
<contributor>Yogesh Rathi, Stefan Lienhard, Yinpeng Li, Martin Styner, Ipek Oguz, Yundi Shi, Christian Baumgartner, Kent Williams, Hans Johnson, Peter Savadjiev, Carl-Fredrik Westin, Lauren O'Donnell, Jessica Lee.</contributor>
<acknowledgements><![CDATA[The development of this module was supported by NIH grants R01 MH097979 (PI Rathi), R01 MH092862 (PIs Westin and Verma), U01 NS083223 (PI Westin), R01 MH074794 (PI Westin) and P41 EB015902 (PI Kikinis), U01 CA199459 (PI O'Donnell), and P41 EB015898 (NCIGT).]]></acknowledgements>


<parameters>
<label>IO</label>
<description>Input/output parameters</description>
Expand All @@ -27,26 +26,10 @@
<description>Input diffusion weighted (DWI) volume</description>
</image>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>seedsFile</name>
<longflag alias="seedsData">seedsFile</longflag>
<label>Input Label Map</label>
<channel>input</channel>
<description>Seeds for diffusion. If not specified, full brain tractography will be performed, and the algorithm will start from every voxel in the brain mask where the Generalized Anisotropy is bigger than 0.18</description>
</image>

<integer-vector>
<name>labels</name>
<longflag>labels</longflag>
<label>ROI label to use for seeding</label>
<description>A vector of the ROI labels to be used. There are the voxel values where tractography should be seeded. </description>
<default>1</default>
</integer-vector>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>maskFile</name>
<longflag alias="maskData">maskFile</longflag>
<label>Input brain mask</label>
<label>Input Brain Mask</label>
<channel>input</channel>
<description>Brain mask for diffusion tractography. Tracking will only be performed inside this mask.</description>
</image>
Expand All @@ -62,30 +45,17 @@
</parameters>

<parameters>
<label>Tractography Options</label>
<description>Basic Parameters</description>

<integer>
<name>seedsPerVoxel</name>
<longflag>seedsPerVoxel</longflag>
<label>Seeding: Number of seeds per voxel</label>
<description> Tractography parameter used in all models. Each seed generates a fiber, thus using more seeds generates more fibers. In general use 1 or 2 seeds, and for a more thorough result use 5 or 10 (depending on your machine this may take up to 2 days to run). Default: 1. Range: 0-50.
</description>
<default>1</default>
<constraints>
<minimum>0</minimum>
<maximum>50</maximum>
<step>1</step>
</constraints>
</integer>

<label>Seeding Options (pick one option)</label>
<description>Options for seeding tractography. Only one of the three provided options will be used. Option 1 (Minimum Seed FA) is the default.</description>

<double>
<name>seedingThreshold</name>
<longflag deprecatedalias="seedFALimit">
seedingThreshold
</longflag>
<label>Seeding: Minimum seed FA</label>
<description>Tractography parameter used in all models. Seed points whose fractional anisotropy (FA) or mean signal are below this value are excluded. Default: 0.18. Range: 0-1.</description>
<label>Option 1: Minimum Seed FA</label>
<description>(Seeding Option 1) Tractography parameter used in all models. Seed points whose fractional anisotropy (FA) are below this value are excluded. This seeding option is default and will not be used if Seeding Option 2 or 3 is used. Default: 0.18. Range: 0-1.</description>
<default>0.18</default>
<constraints>
<minimum>0</minimum>
Expand All @@ -94,13 +64,57 @@
</constraints>
</double>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>wmFile</name>
<longflag alias="wmData">wmFile</longflag>
<label>Option 2: WM Segmentation Map</label>
<channel>input</channel>
<description>(Seeding Option 2) A probabilistic segmentation map of the White Matter (WM). The values in the map should be between 0 and 1. Voxels with a probability over WM Probability Threshold (--wmProbThreshold) will be used for seeding. This seeding option will not be used if Seeding Option 3 is used.</description>
</image>

<double>
<name>wmProbThreshold</name>
<longflag>wmProbThreshold</longflag>
<label>Option 2: WM Probability Threshold</label>
<description>(Seeding Option 2) When a WM Segmentation Map (--wmFile) is provided, tracking will be seeded in voxels with values over this threshold. Default: 0.3. Range: 0-1.</description>
<default>0.3</default>
<constraints>
<minimum>0</minimum>
<maximum>1</maximum>
<step>0.01</step>
</constraints>
</double>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>seedsFile</name>
<longflag alias="seedsData">seedsFile</longflag>
<label>Option 3: Seeding Label Map</label>
<channel>input</channel>
<description>(Seeding Option 3) Voxels in this map with a label defined in ROI Labels (--seedLabels) for Seeding will be used for seeding. If this option is used, Seeding Options 1 and 2 will not be used.</description>
</image>

<integer-vector>
<name>seedLabels</name>
<longflag>seedLabels</longflag>
<label>Option 3: ROI Labels for Seeding</label>
<description>(Seeding Option 3) A list of the ROI labels to be used when Seeding Label Map (--seedsFile) is provided. There are the voxel values where tractography should be seeded.</description>
<default>1</default>
</integer-vector>

</parameters>

<parameters>

<label>Stopping Options (pick one option)</label>
<description>Options for stopping tractography. Only one of the three provided options will be used. Option 1 (Terminating Mean Signal) is the default.</description>

<double>
<name>stoppingFA</name>
<longflag deprecatedalias="minFA">
stoppingFA
</longflag>
<label>Stopping Criterion: Terminating FA</label>
<description>Tractography parameter used in tensor model. Tractography will stop when the fractional anisotropy (FA) of the tensor being tracked is less than this value. Note: make sure to also decrease the GA to track through lower anisotropy areas. This parameter is used only in tensor models. Default: 0.15. Range: 0-1.</description>
<label>Option 1: Terminating FA</label>
<description>(Stopping Option 1) Tractography parameter used only in tensor models. Tractography will stop when the fractional anisotropy (FA) of the tensor being tracked is less than this value. Note: make sure to also decrease the Terminating Mean Signal (--stoppingThreshold) to track through lower anisotropy areas. This option will not be used if Stopping Option 2 or 3 is provided. Default: 0.15. Range: 0-1.</description>
<default>0.15</default>
<constraints>
<minimum>0</minimum>
Expand All @@ -112,8 +126,8 @@
<double>
<name>stoppingThreshold</name>
<longflag>stoppingThreshold</longflag>
<label>Stopping Criterion: Terminating mean signal</label>
<description>Tractography parameter used in all models. Tractography will stop when the mean signal is below this value. Default: 0.1. Range: 0-1. </description>
<label>Option 1: Terminating Mean Signal</label>
<description>(Stopping Option 1) Tractography parameter used by default in all models. Tractography will stop when the mean signal is below this value. This option will not be used if Stopping Option 2 or 3 is provided. Default: 0.1. Range: 0-1.</description>
<default>0.1</default>
<constraints>
<minimum>0</minimum>
Expand All @@ -122,6 +136,84 @@
</constraints>
</double>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>gmFile</name>
<longflag alias="gmData">gmFile</longflag>
<label>Option 2: GM Segmentation Map</label>
<channel>input</channel>
<description>(Stopping Option 2) A probabilistic segmentation map of the Gray Matter (GM). The values in the map should be between 0 and 1. Tracking will stop in the voxels with a probability over GM Probability Threshold (--gmProbThreshold). This option will not be used if Stopping Option 3 is used.</description>
</image>

<double>
<name>gmProbThreshold</name>
<longflag>gmProbThreshold</longflag>
<label>Option 2: GM Probability Threshold </label>
<description> (Stopping Option 2) When a GM Segmentation Map (--gmFile) is provided, tracking will stop in voxels with values over this threshold. Default: 0.99. Range: 0-1.</description>
<default>0.99</default>
<constraints>
<minimum>0</minimum>
<maximum>1</maximum>
<step>0.01</step>
</constraints>
</double>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>csfFile</name>
<longflag alias="csfData">csfFile</longflag>
<label>Option 2: CSF Segmentation Map</label>
<channel>input</channel>
<description> (Stopping Option 2) A probabilistic segmentation map of the Cerebrospinal Fluid (CSF). The values in the map should be between 0 and 1. Tracking will stop in voxels with a probability over CSF Probability Threshold (--csfProbThreshold). This option will not be used if Stopping Option 3 is used.</description>
</image>

<double>
<name>csfProbThreshold</name>
<longflag>csfProbThreshold</longflag>
<label>Option 2: CSF Probability Threshold</label>
<description>(Stopping Option 2) When a CSF Segmentation Map (--csfFile) is provided, tracking will stop in voxels with values over this threshold. Default: 0.5. Range: 0-1.</description>
<default>0.5</default>
<constraints>
<minimum>0</minimum>
<maximum>1</maximum>
<step>0.01</step>
</constraints>
</double>

<image type="scalar" fileExtensions=".nhdr,.nrrd">
<name>stopFile</name>
<longflag alias="stopData">stopFile</longflag>
<label>Option 3: Input Stopping Label Map</label>
<channel>input</channel>
<description>(Stopping Option 3) Label map that defines where tracking should stop. Voxels in this map with a label listed in ROI Labels for Stopping (--stopLabels) will be used for stopping. If this option is provided, Stopping Options 1 and 2 will not be used.</description>
</image>

<integer-vector>
<name>stopLabels</name>
<longflag>stopLabels</longflag>
<label>Option 3: ROI Labels for stopping</label>
<description>(Stopping Option 3) A list of the ROI labels to be used when Stopping Label Map (--stopFile) is provided. There are the voxel values where tractography should stop. </description>
<default>1</default>
</integer-vector>

</parameters>

<parameters>
<label>Tractography Options</label>
<description>Basic Parameters</description>

<integer>
<name>seedsPerVoxel</name>
<longflag>seedsPerVoxel</longflag>
<label>Seeding: Number of seeds per voxel</label>
<description> Tractography parameter used in all models. Each seed generates a fiber, thus using more seeds generates more fibers. In general use 1 or 2 seeds, and for a more thorough result use 5 or 10 (depending on your machine this may take up to 2 days to run). Default: 1. Range: 0-50.
</description>
<default>1</default>
<constraints>
<minimum>0</minimum>
<maximum>50</maximum>
<step>1</step>
</constraints>
</integer>

<integer>
<name>numThreads</name>
<longflag>numThreads</longflag>
Expand Down Expand Up @@ -211,7 +303,7 @@
<name>freeWater</name>
<longflag>freeWater</longflag>
<label>Tensor Model: Estimate term for free water</label>
<description>Adds a term for free water diffusion to the model. The free water model is a tensor with all 3 eigenvalues equal to the diffusivity of free water (0.003). To output the free water fraction, make sure to use the "save free water" parameter. </description>
<description>Adds a term for free water diffusion to the model. The free water model is a tensor with all 3 eigenvalues equal to the diffusivity of free water (0.003). To output the free water fraction, make sure to use the "save free water" parameter.</description>
<default>false</default>
</boolean>

Expand Down
14 changes: 11 additions & 3 deletions ukf/ISignalData.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,14 @@ class ISignalData
/** Checks if a certian position is still within the brain mask. */
virtual ukfPrecisionType ScalarMaskValue(const vec3_t& pos) const = 0;

/** Gets stopping mask value at a certain position, from stop label map, GM segmentation, and CSF segmentation */
virtual ukfPrecisionType ScalarStopValue(const std::vector<int>& labels, const ukfPrecisionType gm_prob_threshold, const ukfPrecisionType csf_prob_threshold, const vec3_t& pos) const = 0;

/** Check if GM or CSF masks are provided for stopping */
virtual ukfPrecisionType isGMCSFProvided() const = 0;

/** Get all the seed points. */
virtual void GetSeeds(const std::vector<int>& labels, stdVec_t& seeds) const = 0;
virtual void GetSeeds(const std::vector<int>& labels, const ukfPrecisionType prob_threshold, stdVec_t& seeds) const = 0;

/** Returns the gradients. */
virtual const stdVec_t & gradients() const = 0;
Expand All @@ -72,8 +78,10 @@ class ISignalData
*
* Loads all the data necessary to perform tractography
*/
virtual bool LoadData(const std::string& data_file, const std::string& seed_file, const std::string& mask_file,
const bool normalizedDWIData, const bool outputNormalizedDWIData) = 0;
virtual bool LoadData(const std::string& data_file, const std::string& mask_file,
const bool normalizedDWIData, const bool outputNormalizedDWIData,
const std::string& seed_file, const std::string& stop_file,
const std::string& wm_file, const std::string& gm_file, const std::string& csf_file) = 0;

/** Returns the dimensions of the image */
virtual vec3_t dim() const = 0;
Expand Down
Loading
Loading