tcksample: Permit 4D input image

docs/reference/commands/tcksample.rst

@@ -22,19 +22,25 @@ Usage
 Description
 -----------
 
-By default, the value of the underlying image at each point along the track is written to either an ASCII file (with all values for each track on the same line), or a track scalar file (.tsf). Alternatively, some statistic can be taken from the values along each streamline and written to a vector file.
+By default, the value of the underlying image at each point along the track is written to either an ASCII file (with all values for each track on the same line), or a track scalar file (.tsf). Alternatively, some statistic can be taken from the values along each streamline and written to a vector file, which can either be in the NumPy .npy format or a numerical text file.
+
+In the circumstance where a per-streamline statistic is requested, the input image can be 4D rather than 3D; in that circumstance, each volume will be sampled independently, and the output (whether in .npy or text format) will be a matrix, with one row per streamline and one column per metric.
+
+If the input image is 4D, and the number of volumes corresponds to an antipodally symmetric spherical harmonics function, then the -sh option must be specified, indicating whether the input image should be interpreted as such a function or whether the input volumes should be sampled individually.
 
 Options
 -------
 
--  **-stat_tck statistic** compute some statistic from the values along each streamline; (options are: mean,median,min,max)
+-  **-stat_tck statistic** compute some statistic from the values along each streamline (options are: mean,median,min,max)
 
 -  **-nointerp** do not use trilinear interpolation when sampling image values
 
--  **-precise** use the precise mechanism for mapping streamlines to voxels (obviates the need for trilinear interpolation)  (only applicable if some per-streamline statistic is requested)
+-  **-precise** use the precise mechanism for mapping streamlines to voxels (obviates the need for trilinear interpolation) (only applicable if some per-streamline statistic is requested)
 
 -  **-use_tdi_fraction** each streamline is assigned a fraction of the image intensity in each voxel based on the fraction of the track density contributed by that streamline (this is only appropriate for processing a whole-brain tractogram, and images for which the quantiative parameter is additive)
 
+-  **-sh value** Interpret a 4D image input as representing coefficients of a spherical harmonic function, and sample the amplitudes of that function along the streamline
+
 Standard options
 ^^^^^^^^^^^^^^^^
 

testing/CMakeLists.txt

@@ -16,7 +16,7 @@ include(ExternalProject)
 ExternalProject_Add(BinariesTestData
     PREFIX ${CMAKE_CURRENT_BINARY_DIR}/binaries_data
     GIT_REPOSITORY ${mrtrix_binaries_data_url}
-    GIT_TAG 3eef5c1a18370f5800a1fa2c3bd3bd5bfeb1f778
+    GIT_TAG e5291be5d7cf3b7aa294a50d4940162c758f62d8
     GIT_PROGRESS TRUE
     CONFIGURE_COMMAND ""
     BUILD_COMMAND ""

testing/binaries/CMakeLists.txt

@@ -418,14 +418,30 @@ add_bash_binary_test(tckresample/num_points)
 add_bash_binary_test(tckresample/step_size)
 add_bash_binary_test(tckresample/upsample)
 
-add_bash_binary_test(tcksample/precise)
-add_bash_binary_test(tcksample/statmax)
-add_bash_binary_test(tcksample/statmean)
-add_bash_binary_test(tcksample/statmedian)
-add_bash_binary_test(tcksample/statmin)
-add_bash_binary_test(tcksample/statnone_text)
-add_bash_binary_test(tcksample/statnone_tsf)
-add_bash_binary_test(tcksample/tdifraction)
+add_bash_binary_test(tcksample/input3d_interplinear_statmax)
+add_bash_binary_test(tcksample/input3d_interplinear_statmean)
+add_bash_binary_test(tcksample/input3d_interplinear_statmedian)
+add_bash_binary_test(tcksample/input3d_interplinear_statmin)
+add_bash_binary_test(tcksample/input3d_interplinear_statnone_text)
+add_bash_binary_test(tcksample/input3d_interplinear_statnone_tsf)
+add_bash_binary_test(tcksample/input3d_interpnearest_statmean)
+add_bash_binary_test(tcksample/input3d_interpnearest_statnone_text)
+add_bash_binary_test(tcksample/input3d_interpnearest_statnone_tsf)
+add_bash_binary_test(tcksample/input3d_interp_tdifrac_statnone)
+add_bash_binary_test(tcksample/input3d_precise_statmean)
+add_bash_binary_test(tcksample/input3d_precise_statnone)
+add_bash_binary_test(tcksample/input3d_precise_tdifrac)
+add_bash_binary_test(tcksample/input4d_interp_statmean)
+add_bash_binary_test(tcksample/input4d_precise)
+add_bash_binary_test(tcksample/input4d_precise_tdifrac)
+add_bash_binary_test(tcksample/input4d_statnone)
+add_bash_binary_test(tcksample/input4dx1_noshoption)
+add_bash_binary_test(tcksample/inputnotsh)
+add_bash_binary_test(tcksample/inputsh_interp_statmean)
+add_bash_binary_test(tcksample/inputsh_interp_statnone)
+add_bash_binary_test(tcksample/inputsh_noshoption)
+add_bash_binary_test(tcksample/inputsh_precise)
+add_bash_binary_test(tcksample/interp_tdifrac)
 
 add_bash_binary_test(tcksift/default)
 

testing/binaries/tests/tcksample/input3d_interp_tdifrac_statnone

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Verify that command suitably errors out when using:
+# - A *3D* input image
+# - *Nearest-neighbour* interpolation
+# - The "-use_tdi_fraction" command-line flag
+# - *No* track-wise statistic
+tcksample tracks.tck afdtotal.mif tmp.csv -use_tdi_fraction -force 2>&1 | \
+    grep "Cannot use \-use_tdi_fraction option unless a per\-streamline statistic is used"

testing/binaries/tests/tcksample/input3d_interplinear_statmax

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Linear* interpolation
+# - The *maximum* track-wise statistic
+# Outcome is verified against that generated using a prior software version
+tcksample tracks.tck tcksample/fa.mif tmp.csv -stat_tck max -force
+testing_diff_matrix tmp.csv tcksample/input3d_interplinear_statmax.csv -frac 1e-5

testing/binaries/tests/tcksample/input3d_interplinear_statmean

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Linear* interpolation
+# - The *mean* track-wise statistic
+# Outcome is verified against that generated using a prior software version
+tcksample tracks.tck tcksample/fa.mif tmp.csv -stat_tck mean -force
+testing_diff_matrix tmp.csv tcksample/input3d_interplinear_statmean.csv -frac 1e-5

testing/binaries/tests/tcksample/input3d_interplinear_statmedian

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Linear* interpolation
+# - The *median* track-wise statistic
+# Outcome is verified against that generated using a prior software version
+tcksample tracks.tck tcksample/fa.mif tmp.csv -stat_tck median -force
+testing_diff_matrix tmp.csv tcksample/input3d_interplinear_statmedian.csv -frac 1e-5

testing/binaries/tests/tcksample/input3d_interplinear_statmin

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Linear* interpolation
+# - The *minimum* track-wise statistic
+# Outcome is verified against that generated using a prior software version
+tcksample tracks.tck tcksample/fa.mif tmp.csv -stat_tck min -force
+testing_diff_matrix tmp.csv tcksample/input3d_interplinear_statmin.csv -frac 1e-5

testing/binaries/tests/tcksample/input3d_interplinear_statnone_text

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Ensure that command runs successfully with:
+# - A *3D* input image
+# - Using *Linear* interpolation
+# - *No* track-wise statistic, therefore writing a value per vertex
+# - The per-vertex values are written to a text file
+# The "testing_diff_matrix" command *cannot* be used to verify the output of this invocation,
+#   as the content is not a regular matrix
+#   (different number of vertices per streamline = different number of columns per row);
+#   this test therefore just ensures that the command completes without error
+tcksample tracks.tck tcksample/fa.mif tmp.txt -force

testing/binaries/tests/tcksample/input3d_interplinear_statnone_tsf

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Ensure that command runs successfully with:
+# - A *3D* input image
+# - Using *linear* interpolation
+# - *No* track-wise statistic, therefore writing a value per vertex
+# - The per-vertex values are written to a Track Scalar File (TSF)
+tcksample tracks.tck tcksample/fa.mif tmp.tsf -force
+testing_diff_tsf tmp.tsf tcksample/input3d_interplinear_statnone.tsf -frac 1e-5

testing/binaries/tests/tcksample/input3d_interpnearest_statmean

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Nearest-neighbour* interpolation
+# - A track-wise statistic *is* used
+#   (the mean is used here merely as an exemplar)
+# Outcome is verified against that generated using a prior software version
+tcksample tracks.tck tcksample/fa.mif tmp.csv -nointerp -stat_tck mean -force
+testing_diff_matrix tmp.csv tcksample/input3d_interpnearest_statmean.csv -frac 1e-5

testing/binaries/tests/tcksample/input3d_interpnearest_statnone_text

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Ensure that command runs successfully with:
+# - A *3D* input image
+# - Using *Nearest-neighbour* interpolation
+# - *No* track-wise statistic, therefore writing a value per vertex
+# - The per-vertex values are written to a text file
+# The "testing_diff_matrix" command *cannot* be used to verify the output of this invocation,
+#   as the content is not a regular matrix
+#   (different number of vertices per streamline = different number of columns per row);
+#   this test therefore just ensures that the command completes without error
+tcksample tracks.tck tcksample/fa.mif -nointerp tmp.txt -force

testing/binaries/tests/tcksample/input3d_interpnearest_statnone_tsf

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Ensure that command runs successfully with:
+# - A *3D* input image
+# - Using *Nearest-neighbour* interpolation
+# - *No* track-wise statistic, therefore writing a value per vertex
+# - The per-vertex values are written to a Track Scalar File (TSF)
+tcksample tracks.tck tcksample/fa.mif -nointerp tmp.tsf -force
+testing_diff_tsf tmp.tsf tcksample/input3d_interpnearest_statnone.tsf -frac 1e-5

testing/binaries/tests/tcksample/input3d_precise_statmean

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Precise* streamline-to-voxel mapping mechanism
+# - A track-wise statistic *is* used
+#   (mean is used merely as the exemplar)
+# Outcome is verified against that generated using a prior software version
+tcksample tracks.tck tcksample/fa.mif tmp.csv -precise -stat_tck mean -force
+testing_diff_matrix tmp.csv tcksample/input3d_precise_statmean.csv -frac 1e-5

testing/binaries/tests/tcksample/input3d_precise_statnone

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Ensure that command *does not* run successfully with:
+# - Using *precise* streamline-to-voxel mapping mechanism
+# - *No* track-wise statistic, therefore writing a value per vertex
+# The precise mapping mechanism by definition does not provide information per vertex,
+#   and so this combined usage does not make sense
+tcksample tracks.tck tcksample/fa.mif -precise tmp.txt -force 2>&1 | \
+    grep "Cannot combine per\\-vertex values with precise mapping mechanism$"

testing/binaries/tests/tcksample/input3d_precise_tdifrac

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *3D* input image
+# - *Precise* streamline-to-voxel mapping mechanism
+# - *-use_tdi_fraction* option is specified
+# - A track-wise statistic *is* used
+#   (mean is used as an exemplar but this is arbitrary)
+# Outcome is verified against that generated using a prior software version
+# More lenient threshold found to be necessary to pass tests on MacOS
+tcksample tracks.tck afdtotal.mif tmp.csv -precise -stat_tck mean -use_tdi_fraction -force
+testing_diff_matrix tmp.csv tcksample/input3d_precise_tdifrac.csv -frac 2e-5

testing/binaries/tests/tcksample/input4d_interp_statmean

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *4D* input image
+# - *Interpolation* is used
+#   (Linear interpolation is used merely as the exemplar)
+# - A track-wise statistic *is* used
+#   (the mean is chosen here merely as an exemplar)
+# Outcome is verified against that generated using a prior software version
+mrcat tcksample/fa.mif tcksample/adc.mif -axis 3 - | \
+    tcksample tracks.tck - tmp.csv -stat_tck mean -force
+
+testing_diff_matrix tmp.csv tcksample/input4d_interplinear_statmean.csv -frac 1e-5

testing/binaries/tests/tcksample/input4d_precise

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *4D* input image
+# - The *precise* streamline-to-voxel mapping mechanism is used
+# - A track-wise statistic *is* used
+#   (compulsory given the use of -precise)
+# Outcome is verified against that generated using a prior software version
+mrcat tcksample/fa.mif tcksample/adc.mif -axis 3 - | \
+    tcksample tracks.tck - tmp.csv -stat_tck mean -precise -force
+
+testing_diff_matrix tmp.csv tcksample/input4d_precise_statmean.csv -frac 1e-5

testing/binaries/tests/tcksample/input4d_precise_tdifrac

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *4D* input image
+# - The *precise* streamline-to-voxel mapping mechanism is used
+# - The "-use_tdi_fraction" option is used
+# Outcome is verified against that generated using a prior software version
+# More lenient threshold found to be necessary to pass tests on MacOS
+mrcat tcksample/fa.mif tcksample/adc.mif -axis 3 - | \
+    tcksample tracks.tck - tmp.csv -stat_tck mean -precise -use_tdi_fraction -force
+
+testing_diff_matrix tmp.csv tcksample/input4d_precise_tdifrac_statmean.csv -frac 2e-5

testing/binaries/tests/tcksample/input4d_statnone

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Verify that command *does not* execute if attempting to combine:
+# - A *4D* input image
+# - *No* track-wise statistic (ie. save one value per vertex)
+# This does work as:
+# - For text files, would need to decide on a format
+#   by which to store for each streamline multiple values per vertex
+#   (could theoretically be done, but no motivation to do so)
+# - The Track Scalar File (TSF) format does not support multiple values per vertex
+mrcat tcksample/fa.mif tcksample/adc.mif -axis 3 - | \
+    tcksample tracks.tck - tmp.csv -force 2>&1 | \
+    grep "Cannot export per\\-vertex values for more than one contrast$"
+
+mrcat tcksample/fa.mif tcksample/adc.mif -axis 3 - | \
+    tcksample tracks.tck - tmp.tsf -force 2>&1 | \
+    grep "Cannot export per\\-vertex values for more than one contrast$"

testing/binaries/tests/tcksample/input4dx1_noshoption

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Ensure that command yields an appropriate error message
+#   if the input image is a 4D image with 1 volume,
+#   and the -sh option is not specified
+# This case is ambiguous because it is not possible to determine
+#   whether to interpret the image intensities as a singular scalar contrast,
+#   or as an SH decomposition with lmax=0;
+#   these two interpretations would result in the output data differing
+#   by a factor of sqrt(4pi).
+# Extended regular expressions was found to be necessary
+#   in order to match the round brackets within the error string
+mrconvert afdtotal.mif -axes 0,1,2,-1 - | \
+    tcksample tracks.tck - tmp.tsf -force 2>&1 | \
+    grep -E "Input image could plausibly be interpreted as spherical harmonics; must specify the \\-sh option to inform command whether to interpret image in this way \\(this is due to being a 4D image with 1 volume rather than a 3D image\\)$"

testing/binaries/tests/tcksample/inputnotsh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Verify that command terminates gracefully when:
+# - Input image is *not* a Spherical Harmonics image
+# - User attempts to manually specify that it is
+mrcat tcksample/fa.mif tcksample/adc.mif -axis 3 - | \
+    tcksample tracks.tck - tmp.csv -sh true -force 2>&1 |
+    grep "Cannot sample spherical harmonic function amplitudes, as input image cannot be interpreted as such$"

testing/binaries/tests/tcksample/inputsh_interp_statmean

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Ensure that command runs successfully with:
+# - A *Spherical Harmonics* input image
+# - Using *interpolation*
+#   (linear interpolation is used merely as an exemplar)
+# - *Including( use of a track-wise statistic
+#   (mean is used here merely as an exemplar)
+tcksample tracks.tck fod.mif tmp.csv -stat_tck mean -sh true -force
+
+testing_diff_matrix tmp.csv tcksample/inputsh_interplinear_statmean.csv -frac 1e-5

testing/binaries/tests/tcksample/inputsh_interp_statnone

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Ensure that command runs successfully with:
+# - A *Spherical Harmonics* input image
+# - Using *interpolation*
+#   (linear interpolation is used merely as an exemplar)
+# - *No* track-wise statistic, therefore writing a value per vertex
+#   These values are written to TSF rather than text file
+#   to facilitate comparison against expectation
+tcksample tracks.tck fod.mif tmp.tsf -sh true -force
+
+testing_diff_tsf tmp.tsf tcksample/inputsh_interplinear_statnone.tsf -frac 1e-5

testing/binaries/tests/tcksample/inputsh_noshoption

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Ensure that command exists gracefully
+#   if provided with a Spherical Harmonics image,
+#   but user neglects to include the -sh option
+# In the absence of use of that option,
+#   there is no way to know for sure whether the image intensities
+#   should be interpreted as coefficients in a spherical harmonics decomposition,
+#   or as individual volumes containing independent contrasts
+#   from which to sample
+tcksample tracks.tck fod.mif tmp.csv -stat_tck mean -force 2>&1 | \
+    grep "Input image could plausibly be interpreted as spherical harmonics; must specify the \-sh option to inform command whether to interpret image in this way"

testing/binaries/tests/tcksample/inputsh_precise

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Verify command operation when using:
+# - A *Spherical Harmonics (SH)* input image
+# - *Precise* streamline-to-voxel mapping mechanism
+# More lneient threshold found to be necessary to pass tests on MacOS
+tcksample tracks.tck fod.mif tmp.csv -sh true -precise -stat_tck mean -force
+testing_diff_matrix tmp.csv tcksample/inputsh_precise_statmean.csv -frac 5e-5

testing/binaries/tests/tcksample/interp_tdifrac

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Ensure that command exists gracefully if the user attempts to simultaneously use:
+# - *Interpolation*
+# - The "-use_tdi_fraction" command-line flag
+# This combination does not make sense.
+# The way that "-use_tdi_fraction" works is to take the intensity in each voxel,
+#   and sub-divide it to attribute fractions of it proportionally
+#   among the intersecting streamlines.
+# This can't work trivially if the mechanism
+#   by which values underlying streamline vertices are sampled
+#   is just a simple linear or nearest-neighbour interpolation.
+# It may be possible to do a sensible computation in this instance,
+#   but it would require greater care and motivation.
+tcksample tracks.tck afdtotal.mif tmp.csv -stat_tck mean -use_tdi_fraction -force 2>&1 |
+    grep "\\-use_tdi_fraction can only be used in conjunction with precise mapping$"
+tcksample tracks.tck afdtotal.mif tmp.csv -stat_tck mean -use_tdi_fraction -nointerp -force 2>&1 |
+    grep "\\-use_tdi_fraction can only be used in conjunction with precise mapping$"