The significant user-visible changes in each release of TractoR are documented below.
pnt-prunescripts would previously number their output incorrectly, using the argument index rather than the data file index. When called through
plough, this could lead to a single output file being repeatedly overwritten. This has been corrected.
- Spurious errors about non-numeric arguments should no longer arise when reading a DICOM series using an implicit VR transfer syntax.
- When reading from a .trk/.trkl file pair, the metadata is now checked to ensure that the two files agree on the number of streamlines present. This should avoid potential crashes when a .trk file is updated without its partner.
- The documentation has been updated to match the new style of the TractoR website.
- Support has been added for containerised builds of TractoR using Docker.
- Tractography operations could produce “bad allocation” errors on some platforms. This should now be fixed.
- Tests requiring FSL will now be skipped if FSL doesn’t seem to be installed, rather than producing an error.
ploughself-test should no longer fail with an error about a missing executable if the
TRACTOR_HOMEenvironment variable is not set.
- The 3.0.x series of releases introduced a bug in the implementation of principal networks (accessed via
graph-decompose), which could result in nonsense output. This has now been corrected.
- Session map keys are now fully case-insensitive, as intended.
- The speed of the
dicomsortscript should now be a little better.
- Sulcus labels are allocated to some grey matter voxels by FreeSurfer, so they have been reinstated into the Destrieux parcellation lookup table.
- TractoR’s own image viewer (the
viewscript) could sometimes use incorrect colours when some regions were missing from a parcellation. This has been fixed.
dpreprocscript no longer produces errors when encountering DICOM files with no ASCII header.
- Merging multiple related DICOM series into one image could sometimes fail. This has been corrected.
compressscript previously interpreted all of its arguments as parts of a single file name. This has been corrected.
- The mean clustering coefficient reported by
graph-propsnow properly respects the “DisconnectedVertices” option.
- Encountering an empty transform directory (with an .xfmb extension) should no longer lead to an error.
- A spurious error, arising when indexing into sparse images under certain conditions, has been fixed.
- The new
TRACTOR_NOSYMLINKSenvironment variable may be set to
trueto turn symlinking operations into copies. This uses more disk space, but is required on certain file systems, notably on some network mounts.
- A transformation strategy between T1-weighted structural space and FreeSurfer space has been added explicitly.
- A problem in the calculation of metadata when writing MGH/MGZ files has been fixed. This should address problems with the results of
peekscript now also works with CSV files representing graphs.
- Graphs without vertex names (notably CSV files from non-TractoR sources) should no longer be mislabelled when visualised using
- Directories containing only a single DICOM file, and pertaining to a diffusion acquisition, should no longer cause errors.
dicomreadscript now respects echo number when reconstructing images, thereby improving results from multiecho sequences.
- Tractography pipelines (notably within
track) can now be interrupted, using the standard Ctrl-C command. This can be useful to cancel a long-running operation.
graph-buildscripts are now consistent in their treatment of the “TargetRegions” option, allowing greater flexibility. Previously,
graph-buildwould only accept parcellation labels; now, named image files may also be used.
- A mistake relating to internal indexing in sparse arrays has been corrected. This could previously have led to errors or incorrect results in
trackwhen target or seed regions overlapped, and possibly other scripts.
- Attempting to
peekat graph objects could fail under certain circumstances. This has been corrected.
- Guessing of phase-reversed volumes in
dpreprocis now more robust. Reported volumes are also numbered relative to the whole series, not just the b=0 volumes, for consistency with the “ReversePEVolumes” option.
- Remapping subdirectories within a session could lead to problems finding images. This has been corrected.
dicomsortscript’s ability to sort by series number or time has been reinstated, although sorting by UID remains the default.
- An updated version of the TractoR paper is now provided online and within the
share/doc/papersubdirectory of the package. There is also a more extensive
README.mdfile, and an updated
- Building the
tractorexecutable should no longer fail just because the
bin/execsubdirectory does not exist.
- When running
make installwith the
TRACTOR_HOMEenvironment variable pointing to a different TractoR installation, the packages would previously be installed there in error. This has been corrected.
- Creating transformations on a different filesystem to the system’s temporary directory should no longer fail.
- The package’s requirements and dependencies have been simplified somewhat. A Fortran compiler should no longer be required to install R packages, and ImageMagick is no longer needed to create images.
- The tractography systems have been completely overhauled to make them much more efficient, especially when working with large numbers of streamlines, as in connectomics. A pipeline approach is now taken to limit memory requirements, and more work is done in compiled code for speed. The interface has also been consolidated, with the old
xtrackscripts being replaced by a single, flexible
trackscript, which also offers some new features such as random seeding and length thresholding. All support for tractography using FSL
probtrackxhas been removed.
- The TrackVis file format is now used as TractoR’s native format for streamlines, which allows paths to be easily visualised. Consequently, the
streamlines2trkscript has been removed.
- A new top-level command,
plough, allows a TractoR script to be called multiple times using different sets of arguments or configuration variables, optionally parallelising across cores or using a grid engine. This is a universal alternative to piecemeal vectorisation in a handful of specialised scripts such as
pnt-data-sge. The latter two scripts have therefore been removed, while many others have been simplified by working on only one session or image at a time.
- TractoR can now work with “multishell” diffusion-weighted data, and tries to choose appropriate parameters when preprocessing and fitting such data. The
dpreprocscript also provides an interface to FSL’s
eddytools for correcting susceptibility and eddy current induced distortions, respectively.
- It is now possible to refer to standard images within a session directory using a shorthand that incorporates the
@symbol, as in
/data/subject1@FAfor the FA map from session directory
/data/subject2@functional/datafor the functional data series from
subject2. Scripts such as
mkroihave been substantially generalised, without becoming more verbose, by taking advantage of this mechanism.
- The MNI space reference brain has been updated to a newer, higher resolution and much sharper image, based on nonlinear coregistration of 152 individuals.
- Noninteractive visualisation of images, including overlays, is now handled by the
slicescript, which can create visualisations in one or more planes, including multiple views within the same image. This much-improved script subsumes the functionality of the old
contactscripts, which have been removed.
- Probabilistic neighbourhood tractography is now much faster, often by 90% or more, and is in fact now appreciably faster than the older and much less robust heuristic neighbourhood tractography (although it typically involves more steps).
- Transformation information between images and spaces is now stored as a series of text matrices and NIfTI images within a directory with an .xfmb extension (for transform bundle), rather than a flat .Rdata file. This was necessary due to upstream changes in NiftyReg, but it also has the advantage of greater transparency. The new
reg-infoscript can be used to obtain information about these directories.
- The accuracy of a registration can be visualised using the new
- The new
transformscript can be used to transform an image or point between named spaces as they relate to a particular session.
- The new
componentsscript can be used to find connected components in images.
- NIfTI files can be reduced in size, at the cost of some loss of precision, using the new
mkroiscript can now generate ROIs of different shapes, and with different widths in each dimension.
- The LEMON C++ library is now used rather than the rather complex “igraph” R package, for calculating graph metrics.
- The “MaskingMethod” option to
dpreproconce again defaults to using FSL-BET, but will fall back to k-means if the
betexecutable is not found. The k-means method itself has been improved by first finding the largest connected component, which tends to result in the removal of more non-brain tissue.
- TractoR’s image viewer now shows parcellation labels when a lookup table file (.lut) is found.
- Graphs can now be read from CSV files in all scripts, although .Rdata files contain more complete information.
reg-applyscript can now apply composite and half transforms to images.
- Registration can now be initialised from a FLIRT transformation matrix file.
applyscript gains a “Combine” mode which allows multiple images to be merged after applying the function to each in turn. This script, along with
transform, can now do the job of
gmap, which was very specialised and has been removed.
plotcorrectionsscript now plots all modes on the same device, and allows correction values to be written to a CSV file. The sense of its decomposition is now a little different, so results will differ from those in TractoR 2.x.
dicomsortscript now sorts by series UID by default.
- Configuration variables are now matched in a case-insensitive manner, and variables which are supplied on the command line but not used are reported in a warning.
- TractoR can now read and parse Siemens ASCII headers from DICOM files, and these can be shown using the
- An improved method is now used for placing knot points along tracts in
pnt-data. The output also contains the session path rather than an ID number, rendering the
identifyscript unnecessary. Therefore, the results of this script are not completely consistent with TractoR 2.x. Old output files can be converted to the new format, but it is better not to mix output from the two versions in one study.
- Default session maps are now explicitly stored within the
etc/sessionsubdirectory, and these may be used as templates for more specialised maps.
- Diffusion directions read from DICOM files are now flipped along the Y-axis by default.
- Seed points for tractography are now jittered within the voxel by default.
- Voxels containing less than the required seven strictly positive values are now handled gracefully by
tensorfit. In addition, an image called
dti_badis created, which maps the numbers of bad data points across the image volume.
- NiftyReg is now the default linear registration method.
- Image origins are now always three-dimensional.
- Camino-specific scripts
caminofileshave been removed. They were poorly maintained, and largely redundant following Camino’s support for NIfTI images.
- The “-r” flag to the main
tractorprogram is defunct.
- Extensive low-level and upstream package improvements have been incorporated.
pnt-data-sgescript will no longer specify the wrong number of array jobs to SGE when the
SessionNumbersoption is used.
- Some minor issues with the
RNiftyRegpackage have been patched.
- An error in the calculation of clustering coefficients has been corrected.
- Graphs containing only negative weights would previously be shown with an inverted colour scale. This has been corrected.
- A subtle difference between TrackVis’s voxel grid and TractoR’s is now corrected for in the
- Run times are now reported for tests.
- NIfTI format files which are endian-swapped, relative to the platform being used to read them, will now be handled correctly. Previously these would lead to a rather cryptic error.
Type:functional) will now ignore voxels with totally flat time courses, rather than producing an error. These could arise as a result of masking during preprocessing.
- Spurious errors should no longer be produced when overwriting a session subdirectory.
- Zero-length streamlines are now usually retained. Discarding these could violate the assumptions of other code, and would sometimes lead to a test failure.
- Failure to install optional packages
mmand, which generally require a Fortran compiler to build, no longer leads to outright failure to install TractoR. (More information on Fortran requirements has also been added to the documentation.)
- The TractoR distribution version is now printed alongside the
tractorprogram version when
tractor -his run. This has been a recurring source of confusion.
- TractoR now requires R version 3.0.0 (released April 2013) or later.
- TractoR now has support for handling functional (BOLD) data, including functional connectivity analysis. However, fMRI preprocessing must currently be performed using other tools.
graph-buildscript gains the ability to create functional connectivity graphs. Regionwise time courses may be obtained by simple averaging or principal components analysis, and connectivity is quantified in terms of correlation, partial correlation, covariance or precision. An optional shrinkage approach is available to regularise these measures when the number of time points is limited.
- Streamlines can now be ignored before they are stored if they do not reach targets of interest. This is used by the
ptrackscripts, and will also be used by
TruncateUnterminated:trueis given. Streamline files can be much smaller, and memory usage less, as a result.
- Further DICOM improvements. A missing “pixel data” tag (0x7fe0, 0x0010) will no longer result in a DICOM file being treated as invalid. Slice gaps are now included in the through-plane voxel dimension. And the code tries to guess when a “mosaic” DICOM file contains the per-slice rather than per-volume TR (as some do), and correct to the latter.
- The new
graph-extractscript can be used to extract a subgraph containing some of the vertices from a larger graph.
- TractoR is now more cautious about overwriting existing directories, and in particular, a directory mapped outside the session directory should never be deleted.
viewscript gains a
TimeSeriesoption, which can be used to visualise time series in 4D images.
graph2csvscript now writes vertex attributes into the CSV file, as comments.
graph-propsscript gains an
- Registration strategy files can now specify the use of FSL or NiftyReg for affine registration.
- Switching the
dpreprocwill now appropriately overwrite the result of a previous correction.
- Self-connection weights are no longer included in the default weight limits when plotting graphs with
MatrixView:false. They are often large relative to other connections, but are not visible in these plots.
- A test for reading NIfTI-2 format files has been added (the code already passed it).
- Indexing into sparse arrays is now more reliable.
graph-buildscript now accepts a comma-separated list of target regions, bringing it in line with
xtrackand intended behaviour.
make check-md5should no longer produce an error if no
- A mistake in the install script,
tractor_Rinstall, has been corrected.
- R’s facilities for checking MD5 sums are now used in preference to system ones, for portability.
- The graph decomposition test has been made less stringent.
- Author and copyright information has been updated.
- TractoR now has facilities for working with graph representations of brain connectivity, including a reference implementation of the Principal Networks approach to graph decomposition. A set of new scripts has been added to support this, including
graph2csv. Please see the new connectivity graphs tutorial for further information.
- In support of the new graph capabilities, TractoR can now work with structural (particularly T1-weighted) images, as well as diffusion data. It can also work with anatomical parcellations of the brain, and transform them between spaces. A wrapper script for Freesurfer’s
recon-alltool is also provided. New TractoR scripts relevant to structural data are
freesurf. Please see the new page on working with structural data for more information.
- A new test data set, which includes structural data, has been introduced to replace the previous test data.
- Transformation strategies between different imaging spaces are now configurable, with defaults given by the
- The new
xtrackscript can be used for tracking between parcellated regions, specified by name or type.
trimscript has been added for removing volumes from multivolume data sets.
- The new
applyscript can be used to apply an arbitrary R expression to the contents of one or more images.
pathscript has been added for identifying the path to an image within a managed session hierarchy.
splitscript can be used to split a serialised list of objects into its components.
dpreprocscript now accepts
EddyCorrectionMethod:nonefor data sets which are already well aligned and have minimal eddy current induced distortion.
mtrackscript now allows seed points to be subjected to random jitter, to move them off the regular grid.
Method:ls(the default) is now more statistically efficient in the presence of invalid or missing data.
imagestatsscript now handles missing values in images gracefully.
dicomsortscript gains an option to use series time rather than series number as the identifier. This can be more reliable if DICOM files were acquired from multiple scan sessions.
- TractoR’s internal image viewer now fixes the black and white point across a whole image for consistency.
- R’s raster plotting functionality is now used when plotting images, for speed.
- Textual output and messages should now use the full width of the terminal screen more effectively.
make installfrom the main TractoR installation directory is now equivalent to
make install-localafter the latter has been run once. In other words, the initial preference for a local install is maintained even if the
-localsuffix is missed in future invocations.
- The output format for
tractor -ohas been tweaked, and their is now support for examples.
- It should now be possible to coregister files stored in Freesurfer’s MGH format with FSL-FLIRT.
- The first and last messages printed by the main
tractorscript are now output to the standard error stream.
- Checksums for each file in the distribution are now included and can be checked using
make check-md5. This is mainly intended for checking whether local modifications have been made.
- The binary front-end program should no longer misinterpret script arguments beginning with a dash (
-). Previously it would try to interpret these as its own arguments, most likely leading to an error.
- The DICOM reading code is now more flexible with regard to the orientation of Siemens mosaic images. Credit goes to Doug Greve, among others, for information on the some of the subtleties, both in this release and in 2.4.0.
streamlines2trkscript should no longer produce a “could not find function” error.
- The installation instructions have been updated to reflect the recent system requirement for a C/C++ compiler.
- There have been minor tweaks to the R documentation for the
- The native tracker is now used in scripts which do not have an explicit
Trackeroption, such as
pnt-viz. This brings them into line with other scripts, and was the intention for TractoR 2.4 and above.
- The new TractoR interface is now compiled in a more portable way, and should build successfully on a more diverse range of platforms. A couple of small memory allocation problems have also been corrected.
- The linear registration test has been made less stringent.
- The wording of an error message in the
reshapescript has been clarified.
- A C/C++ compiler, such as
g++, is now required to install TractoR. A suitable compiler can be installed using an appropriate package manager (
yum, etc.) on Linux, or with Xcode (from the Mac App Store) on OS X. R handles all the details of actually compiling code.
- TractoR now offers tools for linear and nonlinear image registration, and the entire infrastructure for transforming images and points between different spaces has been totally reworked. A new family of scripts (
reg-viz) has been added for direct registration. Implicit registration, whereby points or images are transformed between spaces as part of another operation such as neighbourhood tractography, behaves as before by default, but the new NiftyReg back-end can be used by setting the
TRACTOR_REG_METHODenvironment variable to
niftyreg. The new
tractor.regpackage supports all registration and transformation, and supporting packages
RNiftyReghave been added to the TractoR distribution.
dpreprocscript gains a new
EddyCorrectionMethodoption, which allows NiftyReg to be used for volume-to-volume coregistration.
- TractoR now uses its own command-line front-end, rather than the standard R interface. This allows for greater flexibility, and removes the need for ugly hacks to get R to behave as required. The main user-visible effect of this change is that error and warning messages will now appear in colour, if supported by your terminal emulator.
- A new
consolescript has been added, which starts an interactive R session using TractoR’s front-end, in a context where all TractoR-related R packages have been loaded.
- The new
reshapescript can be used to reshape the data in an image.
Trackeroption is deprecated everywhere it occurs. Now that a compiler is required, the internal tracker should always be available.
tractor.nativepackage is now called
tractor.track, to more specifically indicate its purpose.
- Calls to scripts whose function is purely informative (
view, etc.) are no longer recorded in the “tractor-history.log” file.
- Further improvements have been made to DICOM processing. Transfer syntaxes, and slope and intercept values, are now respected; and image origins are now extracted from the metadata.
- TractoR R packages can now be installed within the TractoR file hierarchy using
make install-local. This can be convenient to avoid permissions issues, or when running multiple versions of TractoR in parallel.
platformscript now additionally reports the main R package library in use. This will differ between “local” and “nonlocal” installs.
- The main
tractorprogram gains a “-f” option, which can be used to profile the performance of a script. Information on the time spent in each function will be written to a file named “(script name).Rprof” in the working directory. This is intended for advanced users only.
- The data type of an image file is no longer stored internally, and instead a suitable type is chosen when the image is written to a file. The
TypeCodeoption in the
chfiletypescript is therefore defunct.
cal_minfields of a NIfTI image are now written using appropriate values.
- Image data can now be stored without reordering to LAS internally, and writing non-LAS images is supported for NIfTI format (only).
- There have been significant changes to
MriImage, one of TractoR’s key internal data structures, but this should only affect those who use TractoR packages from within R.
- X11 should no longer be started as a side effect when a TractoR script is called on Mac OS X. This could cause a delay of several seconds.
- Voxel locations are now rounded after being converted to R indexing, rather than before, in the
- Handling of sparse images has been improved slightly.
- The origin would sometimes be read incorrectly from MGH-format files. This has been corrected.
- The “dti_SSE” image created by
tensorfitcould sometimes contain large numbers of
NAvalues. This has been corrected.
- Empty DICOM tags no longer cause spurious errors.
- The debug-level message describing the orientation of an image being read should now always be accurate.
- The tests should no longer fail after a clean install of the package.
- TractoR now includes a simple interactive image viewer, which is used by default unless the
TRACTOR_VIEWERenvironment variable is set to
fslview(for FSLview, as in earlier releases) or
freeview(to use FreeSurfer’s FreeView, for which a new interface has also been added). The new TractoR viewer remains work in progress, and FSLview is still favoured by scripts for showing 4D or vector-valued images.
SortBySubjectFirstoption has been replaced by a more general
SortOnoption, which allows the files to be sorted by series, subject and/or date in any order. The script is also more careful to avoid deleting files which are not moved because they are already in the right place.
mtrackscript now allows the user to specify “termination” masks, which cause truncation of streamlines. It is possible to specify a single mask as both a waypoint and a termination mask. Likewise,
- TractoR’s internal tractography algorithm is now the default for
- If the
gradrotatescript is applied to a session, the original (unrotated) gradient directions are first copied to the file
tractor/diffusion/directions-orig.txt. This makes it much easier to tell whether rotation has been performed, and is used by the code to make sure that the gradients are not rotated twice.
gmapscript gains a
UseReferencePlanesoption: if it is “false” then the plane of the maximum in the image is used for visualisation. In addition, the script should no longer produce an error when the reference seed point is not in the centre of a voxel.
dirvizscript gains a
ScaleFactoroption to control the size of the PNG image produced.
pnt-data-sgescript now captures SGE/OGE job numbers more robustly, thereby avoiding spurious errors.
- PNT reference tracts (including those provided with TractoR) should now have smaller file sizes.
- Code which reads from DICOM files should no longer produce an error while checking if a very small file is a DICOM file or not, or when handling oblique images.
- The PNT reference tract test has been tweaked to avoid spurious failures.
- Using the FSL tracker with FSL versions containing more than three parts (e.g. 126.96.36.199) no longer fails.
pnt-prunescript would sometimes misinterpret the median streamline which is used as a baseline, resulting in a far less tightly pruned final tract than expected for some data sets. This has now been corrected.
- TractoR now has the ability to perform kernel-based image processing operations. The new
morphscripts can be used to smooth an image, or to apply a mathematical morphology operation such as erosion or dilation.
- The masking stage of the
MaskingMethod:kmeansonly) now uses a morphological closing operation to remove small “holes” in the segmentation.
- The new
ptrackscript can be used to perform connectivity “profiling”, generating a table of streamline counts connecting each voxel in a seed region to each of a set of target regions.
mtrackscript now supports the use of so-called “exclusion masks” (using the internal tracker only). Streamlines passing through any such exclusion region will be removed from the result.
mtrackscripts now allow the set of streamlines that they generate to be stored in a binary file. This may be converted to the format used by TrackVis for visualisation using the new
- The new
imagestatsscript can be used to obtain a series of statistics about part or all of an image, such as volume, intensity range and mean intensity.
- Experimental support for auto-updating a TractoR installation has been added, via the new
updatescript. This attempts to check the project web site for new versions of the package. See
tractor -o updatefor usage.
- The newly-added
upgradescript can be used to convert objects stored in “.Rdata” files from TractoR 1.x formats to their TractoR 2.x equivalents.
- The code underlying the
dicomreadscript has been substantially reworked to improve speed (in some cases substantially) and reliability in determining the orientation of the data. The script also gains an option to inhibit the untiling of DICOM files which appear to use the Siemens “mosaic” format.
viewscript no longer requires the user to press Enter to quit, and does not spend time converting images to Analyze format when not necessary.
- Substantial additions to the package’s support for sparse images have been made, and the
valuesscript now takes advantage of these.
TRACTOR_HOMEenvironment variable is now guessed if it is not set, although routine reliance on this mechanism is not advised.
- Support for scripts in
/etc/tractorhas been removed. These have been deprecated since TractoR 1.0.0.
- Interrelationships between the various TractoR packages have now been more explicitly declared. This may avoid occasional problems when using them within R.
- Marginally invalid quaternion parameters in NIfTI headers are now handled more gracefully.
dpreprocscript now warns if the diffusion subdirectory already exists within the session, rather than just if the session’s root directory exists.
- Spurious errors, about images not having been created yet, should no longer occur when TractoR updates the structure of a session directory created with version 1.x.
- An issue with installing the “tractor.native” package on some Linux systems has been addressed. The package’s “configure” process has been somewhat simplified at the same time. (Reported by Mark Bastin.)
- A significant memory leak has been corrected in the new tracking code, which resulted in scripts which run lots of tractography (such as
pnt-data) using very large amounts of memory.
mtrackscript allows multiple waypoint masks to be specified from the command line, comma separated, in line with the syntax used in various other scripts. The
ShowSeedPointoption is ignored when no seed mask is specified (i.e. when the seed region is the whole brain).
Tracker:tractorno longer produces an error if no streamlines pass through all of the waypoints.
- Occasional spurious errors, saying that “all seed points must be the same”, should no longer be generated by the
pnt-datascript. (Reported by Clare Gibbard.)
dicomreadscript now correctly uses the TR as the fourth voxel dimension when individual files represent slices, rather than volumes.
- The HTML documentation has been updated to match the latest version of the TractoR web site. (This will be standard practice in future releases.)
- The internal tracking code has been substantially reworked, and can now be used in the
mtrackscripts. (Results should, however, be comparable with previous versions.) The
mtrackscript can now also be used to perform whole-brain tractography.
- TractoR now properly handles temporal units in NIfTI files. The
dicomreadscript will set the temporal resolution of a 4D image series to the repetition time (TR) stored in the DICOM metadata. (The voxel dimension for dimensions above three was previously fixed to 1, so this will result in some differences in output.)
- A full set of HTML-based documentation is now included in the TractoR distribution, and can be found at
- HNT and PNT reference tracts for the ventral cingulum and inferior longitudinal fasciculus have been added.
- A top-level session directory map can now be used to redefine the location of subdirectories within the TractoR hierarchy. This mechanism can also be used to allow sessions to share some data. All session maps are now also cached internally.
- TractoR now tries harder to work with images stored in a rotated coordinate system (although warnings will be generated).
- The number of clusters used by the k-means algorithm in
dpreproccan now be set using the new
KMeansClustersoption. This option can be refined interactively, or the user can switch to using BET if required.
- TractoR can now read only selected volumes from an image file. The
dpreprocscript takes advantage of this to reduce memory usage.
- Stage 2 of
dpreprocwill now only visualise b=0 volumes, rather than all data.
- The brain mask generated in stage 3 of
dpreprocis now displayed semitransparently for ease of evaluation.
dicomsortscript can now sort a directory by subject as well as series. It also handles missing identifiers better.
- The option to threshold seed points on metrics other than anisotropy in the
rtrackscripts is deprecated (meaning that it will still work, but a warning will be generated).
tensorfitscript now handles negative data values more gracefully. An sum of squared errors (SSE) image is now created irrespective of the fitting method used.
imageinfoscript can now be used with a directory of DICOM files as well as an Analyze/NIfTI/MGH image file.
gmapscript gains an option to create a colour bar.
plotcorrectionsscript now allows
Mode:alland can be run noninteractively. (Requested by Mark Bastin.)
- The “fslview” viewer is now run quietly to suppress spurious warnings.
- TractoR now uses the “quartz” R device by default on Mac OS X systems. This should result in smoother on-screen graphics.
- TractoR run in debug mode will now print stack traces for warnings as well as errors.
dicomsortscript now avoids copying files onto themselves.
tensorfitscript now handles negative data values more gracefully.
hnt-reftest has been made a bit more robust (i.e. less likely to fail for spurious reasons).
- Fixes to TractoR’s handling of images stored using nondiagonal xforms (or the equivalent) have been made.
- Thread-safe temporary files are now used more widely.
- Somewhat cryptic errors about an “incorrect number of dimensions” should no longer appear when performing tractography. These occurred rarely, when a tract was extremely short.
- An incompatibility between masks generated by
dpreprocin its default mode and the internal tractography code has been corrected.
- Running the
mtrackscript with one or more waypoint masks should no longer fail.
gmeanscripts now handle “NaN” more sensibly, giving useful output even when they occur.
- A bug related to reading Analyze-format image files has been fixed.
- The “reportr” R package has been upgraded to version 1.0.0.
- References to the TractoR JSS paper have been added in the package documentation.
- An error about a missing “dti_eigval1” image should no longer appear when calling
Metric:axialdiffon data originally preprocessed with TractoR 1.x. (Reported by Mark Bastin.)
- Errors about “no loop to break from” should no longer be generated by
pnt-prunewhen a data set with no match data is encountered. (Reported by Michael Yoong.)
- The error “object ‘nullPosterior’ not found” should no longer appear when calling
- Further refinements for the upcoming R 2.14.0 have been made. All tests now pass on that platform.
- The TractoR R packages are now byte-compiled on versions of R which support this (2.13.0 and later). This should provide a general speed-up that should be more substantial in R 2.14.0 and later, in which the core packages are also byte-compiled by default.
- The voxel unit of an image is now correctly set to “unknown” where appropriate.
- A bug, which could result in spurious “image not found” errors when working with tractography on datasets processed for two fibre populations per voxel, has now been fixed. (Reported by Mark Bastin.)
gradcheckscript gains an option to allow the user to circumvent use of the internal image viewer.
- The “objects” subdirectory of a session is now deleted when updating the hierarchy to TractoR 2.x format. This avoids errors of the form “X is not a defined class” which were previously occurring due to the lack of forward-compability between stored objects in TractoR 1.x and 2.x.
dpreprocnow expects comma-separated axis letters, rather than unseparated numbers, for consistency with
- The wrapper function for FSL
probtrackxhas been made more “thread-safe”, making parallelised code which uses it (such as
Tracker:fsl) more reliable.
- The session status report test has been updated and should no longer fail.
- R packages are now installed more cleanly, leaving fewer intermediate files lying around.
- Various corrections have been made to script descriptions.
- Several other R-level tweaks and fixes have also been made, including some changes to the semantics of indexing and replacement for
- Support for changes upcoming in R 2.14.0 (expected 31 October 2011) has been added.
- The third and fourth stages of the
dpreprocscript have been swapped around. This was the intended order for version 2.0.x.
- A test image file has been renamed for consistency with other similar files.
- This is a major new release with many significant changes. The main intention has been to broaden the scope of the package and make it more flexible, laying the foundations for future development. The package’s dependence on FSL has also been lessened substantially. It is not fully backwards compatible with TractoR 1.x, so it is recommended that the two not be mixed within a single study.
- TractoR’s internals have changed substantially, and make use of features relatively recently added to R. Therefore, R 2.12.1 (released December 2010) or later is required to install TractoR 2.0.
- The session hierarchy has been revamped. The primary directory for diffusion-weighted data is now called “diffusion”, although an “fdt” directory will still be created for interoperability with FSL if needed. The image file names within the “diffusion” directory are also different by default, although greater flexibility on these names is now available through so-called “session maps”. TractoR 2.0 will automatically update a session hierarchy created with TractoR 1.x when it first encounters it, but the image file names in the new “diffusion” (old “fdt”) directory will be left alone, and a map file will be created to allow TractoR 2.0 find what it needs. NB: Using TractoR 1.x with a session directory updated in this way is not guaranteed to work correctly, and is not recommended.
- Two scripts have been renamed in light of the broader scope of the new version:
mkbvecsis now called
preprocis now called
dpreproc, since it is specific to diffusion-weighted data.
- The functionality of the former
dpreproc) has been split up for flexibility, and to avoid confusion. It now only handles functions which are truly preprocessing operations, so diffusion tensor fitting is now performed by the new
tensorfitscript, gradient direction checking (and flipping if necessary) by
gradcheck, gradient rotation by
gradrotate, and FSL-BEDPOSTX by
bedpost. Run “tractor -o tensorfit”, and so on, to see the options for these new scripts. DICOM to NIfTI conversion, eddy current distortion correction and brain extraction remain in
dpreproc, and it now has four stages rather than five. The progress of that pipeline can be shown using the StatusOnly option.
- Some script options have new defaults, in line with current best practices, or to use TractoR-internal functionality where possible. For example, MaskingMethod in
dpreprocnow defaults to “kmeans”, while BetIntensityThreshold defaults to 0.3 because experience has suggested that this value produces more successful results.
- The default value of any option in any script can now be overridden on a per-user basis by creating a config file corresponding to the script in ~/.tractor, and setting the default value there. For example,
dpreprocwill use FSL-BET for brain masking (as in TractoR 1.x) if you put the text “MaskingMethod: bet” into the file ~/.tractor/dpreproc.yaml. See the man page for details.
- TractoR can now read and write the MGH image file format used by the FreeSurfer package. These files have extension “.mgh” (uncompressed) or “.mgz” (compressed).
- An iterative weighted least-squares fitting process for diffusion tensors is now available through the
dicomsortscript now stops reading each file once the series number is encountered, producing a typical speedup of around 25%. Directory names created by this script now include leading zeroes to ensure that they are always displayed in the right order.
platformscript now additionally prints the TractoR home directory.
viewscript now allows multiple files to be specified.
- The default verbosity level is now 1, rather than 0. Users may therefore see much more output than before. The default can be switched back by setting up ~/.tractor/config appropriately: see the man page for details.
- A warning is now raised if series descriptions are not consistent when reading a DICOM directory.
- The “-r” flag to the main
tractorprogram is deprecated.
- The package installation process is now less verbose.
- Many R-level changes and enhancements have been made, including tweaks to support changes upcoming in R 2.14.0, due in October.
pnt-prunescript would sometimes misinterpret the median streamline which is used as a baseline, resulting in a far less tightly pruned final tract than expected for some data sets. This has now been corrected. (Back-ported from version 2.2.1.)
- A number of improvements have been made relating to TractoR’s handling of very short tracts. (Partly back-ported from version 2.0.7.)
- A number of fixes have been back-ported from TractoR 2.x, specifically relating to compatibility with R 2.14.0 and thread safety.
- Citations to the TractoR JSS paper have been added.
- A bug causing problems when reading 2D NIfTI files has been corrected.
- A spurious warning was previously produced when reading a NIfTI file with more than 3 dimensions. This has been fixed.
- The simple “hello world” test should no longer fail on some platforms due to whitespace differences.
platformscript now always displays its output, irrespective of the verbosity level set.
- The NIfTI file reading code in TractoR is now substantially more flexible, and supports images stored using conventions other than the LAS arrangement which is used internally.
- Read support for the proposed new NIfTI-2 file format has been added.
- Image origins are now adjusted appropriately when image data are flipped on reading, and negative and noninteger values are allowed for. The result of the
imageinfoscript may therefore differ from previous versions for some files, but the new output is more consistent with TractoR’s conventions.
- Any gradient flip specified with the FlipGradientAxes option is now performed during stage 2 of the
preprocscript, to avoid problems with doing it after rotating the directions.
- When installing the “tractor.native” package, a greater effort is now made to find “zlib” on the user’s system. If it is not available, the package is compiled without support for reading gzipped NIfTI files. Previously the compilation would simply fail. (Reported by Mark Bastin.)
- TractoR now contains its own tractography algorithm, provided in the new “tractor.native” R package. The bulk of the tracker is written in C for speed, so this package requires compilation. Use of this tracker is optional and currently only supported in scripts which use one seed point at a time (i.e.
pnt-prune). However, the speed gains can be considerable: in testing,
trackran up to 30% faster using the TractoR tracker, and
pnt-dataran 50-70% faster. Results from the FSL and TractoR trackers should be similar but will not be identical, so it may be wise not to mix the two within studies. FSL remains the default for now.
- The main
tractorprogram now supports a “-a” flag, which can be used to select between subarchitectures on R platforms that support them, such as Mac OS X. This allows users to select between, for example, 32-bit and 64-bit versions of R for running TractoR scripts.
- In TractoR version 1.5.0 and later,
pnt-datano longer collated its output into a single file. This was unintentional and has now been corrected: collation will now happen automatically unless the SessionNumbers option is used to select a subgroup of sessions to process. (Reported by Ping-Hong Yeh.)
- The full data set image for the example session used by TractoR’s self-tests is now included in the distribution.
preprocscript now offers two alternatives to BET for masking in the region for further processing. These are selected using the new MaskingMethod option. The “kmeans” option will apply k-means clustering, which is faster than BET and requires no parameters to be set, but will usually leave some non-brain voxels within the mask. The “fill” option will simply mask in the whole image region, and therefore all voxels will undergo all subsequent processing. These alternatives are particularly useful to simplify the preprocessing, or when FSL is not available, or when processing non-brain data.
- MNI standard space images representing the brain and regions of grey matter, white matter and CSF have been added to the distribution in the
share/mnidirectory. TractoR therefore no longer relies on versions of these images supplied with FSL. We are grateful to the International Consortium for Brain Mapping (ICBM) for making these available.
- New scripts have been added for cloning session hierarchies (
clone), extracting the voxel values of an image within a mask (
values), and viewing an image in
fslviewin a way that avoids an incompatibility between that viewer and certain NIfTI data types (
- Mask-based tractography (using the
mtrackscript) now reports the number of nonzero voxels in the mask, and the number of streamlines retained after applying waypoint masks. (This output is produced at the “info” level, so
-v1must be given to
tractorto see it.)
dicomsortscript will now handle data sets with duplicate file names within a series. In addition, this script’s functionality is now available at the R level.
dicomtagsscript will now look in subdirectories for a DICOM file if its argument is a directory, rather than just in the directory itself.
- Tests that fail will now be rerun, rather than skipped, if
make testis run again from the main TractoR directory.
- The way that diffusion encoding schemes are handled within the core code of TractoR has been changed to improve consistency and portability. However, this change should not have any effect for those using only the
tractorprogram to perform standard tasks.
- 2D images written out to NIfTI files now have their “sform” and “qform” codes set to zero, since TractoR does not keep track of their orientations.
- An adjustment has been made to avoid problems with the gradient rotation part of the
preprocscript, which in some circumstances could try to read the brain-extracted b=0 image before it had been created.
xfmconvertscript is now defunct and has been removed. The new transformation storage format has been in place since TractoR 1.0.
- A few other minor improvements and fixes have been implemented.
- TractoR now offers a simple method for parallelising code, which uses the “multicore” package for R by Simon Urbanek. Users can now take advantage of multicore systems by simply specifying the “-p” option (with a parallelisation factor) to the main “tractor” program. The man page has more details. This option is only supported by certain scripts: at present these are
- In addition to lightweight multicore parallelisation, there is now a version of the
pnt-datascript which supports parallelisation on a grid using the Sun Grid Engine (SGE). This version of the script is called
pnt-data-sge, and can be used like
pnt-data, with a few extra options specific to SGE. Another supporting script,
pnt-collatehas also been added.
- A new script,
dirviz, can be used to visualise principal fibre orientations within each voxel of a data set.
- The new
platformscript reports various details of the software platform that TractoR is being run on.
plotrotationsscript has been replaced by the more general
plotcorrections, which can display rotation angles, translations, scales or skews.
- The text files produced by
pnt-datanow include the seed point associated with each row, for greater flexibility downstream. Scripts are still compatible with the old format however.
- The DICOM reading code no longer immediately rejects non-MR images, although it has not been tested with CT or other data.
preprocscript now lets the user know when the gradient cache has been updated. It also gains an option to force this update.
- An adjustment has been made to allow for some Siemens DICOM files which report zero image slices.
pnt-vizscript gains a NumberOfSamples option.
- X11 libraries are no longer used to create images in the
- The R package “tractor.base” has now been split into “tractor.base” and “tractor.utils”.
- Gradient caching code used by the
preprocscript will no longer fail if no “.tractor” directory exists in the user’s home directory. The directory will now be created if it is missing.
- The TractoR NIfTI file reader now accepts files with negative qform elements, as intended.
- An incompatibility with FSL 4.1.5, due to a change in the behaviour of FSL
probtrackx, has been corrected.
- DICOM tests have been updated to work with the read code change introduced in TractoR version 1.4.2.
- The “tractor -o” test is now a bit more robust.
- An internal problem in some HNT reference tracts has been corrected, so spurious errors should no longer be generated when running
- An adjustment to the DICOM reading code has been made to avoid an incompatibility with the recently released R 2.11.0.
- The “avscale” test previously failed on some Linux installations due to a slight platform dependence in the FSL program’s output. This issue has been avoided in this release, so the tests should run successfully on these platforms.
- Unneeded files which were accidentally included in the version 1.4.0 release (“filter.R” and the “multicore” directory) have been removed.
- TractoR now supports B-matrix/gradient vector rotation to compensate for the motion/eddy current distortion correction applied. Just set the RotateGradients option to “true” for stage 2 of the
preprocscript. The new experiment script
plotrotationscan be used to get a set of how big the effect will be for a particular data set.
- Gradient directions (before rotation) for diffusion MRI acquisitions are now cached in the user’s ~/.tractor directory and automatically placed into a session directory if the series description matches and no gradient direction information is found in the DICOM files. This facility can save a lot of time manually copying bvals and bvecs files into session directories. Its use is determined by the UseGradientCache option to the
- Group mapping, in particular of tracts produced by
pnt-prune, is now available through the new
gmapscript. A set of images are transferred into standard (MNI) space and overlaid to visualise spatial consistency. Run “tractor -o gmap” for options.
- Contact sheet style visualisation is now available for Analyze/NIfTI volumes, wherein all slices of an image along a particular direction are shown in a grid. The new
contactscript is the interface to this functionality.
- The new
agescript can be used to determine a subject’s age to the day from a DICOM file.
- The new
binarisescript can be used to binarise Analyze/NIfTI volumes, with an optional threshold.
- Options such as RunStages in
preprocand SessionNumbers in
pnt-prunenow allow number ranges (e.g. 1-10) as input, for convenience and conciseness.
- The HowRunBedpost option in the
preprocscript now defaults to “fg” (running in the foreground). The use of “screen” was confusing for several users, but can be forced if required. The “auto” value is no longer used or supported.
pnt-refscript gains a MaximumAngle option, to avoid sharp turns near the ends of the created reference tract.
- The output file name in the
dicomreadscript now defaults to the same as the name of the source directory.
- The window limits (black and white points) for images produced by the
gmapscripts can now be set using the new WindowLimits option.
dicomsortscript now creates subdirectories containing the relevant series descriptions in their names, for greater clarity.
- Various improvements have been made to DICOM reading code for Philips and Siemens files, and for images acquired obliquely.
rtrackscript unintentionally ignored the NumberOfSamples option. This has been corrected.
- Various other minor enhancements.
- Support for a new approach to rejecting false positive connections in probabilistic neighbourhood tractography has been added through the
pnt-pruneexperiment script. This script can be run instead of
pnt-viz, and uses the PNT modelling framework to substantially clean up tract segmentations. Details can be found on the PNT tutorial page). Run “tractor -o pnt-prune” for options.
- A set of tests have been added to the package, to ensure that installation went successfully and everything is working as expected. These can be run from the main TractoR directory with the command “make test”.
- A specific PNT model can now be specified directly for the
pnt-interpretscripts, allowing substantially greater flexibility.
hnt-evalscripts now support a NumberOfSamples option, to set the number of streamlines used by the underlying tractography algorithm.
mtrackscripts now have a CreateVolumes option, for consistency with other similar scripts. The behaviour of the
rtrackscript has also been brought into line with other related scripts.
chfiletypescript can now be used with multiple files.
tractorprogram now supports a “-i” flag to suppress the user’s default configuration file.
- Running “tractor -o (script)” no longer requires
- The DICOM reading code should no longer incorrectly identify non-Siemens images as mosaic volumes.
- Duplicated stack traces were sometimes produced when
tractorwas run in debug mode. This has been corrected.
extractscript no longer fails when the CreateImages option is on and the OverlayOnBrain option is off.
- Some minor adjustments to output messages have been made.
- HNT and PNT reference tracts have been added for the corpus callosum splenium (forceps posterior), arcuate fasciculi, uncinate fasciculi and anterior thalamic radiations. (Credit to Dr Susana Muñoz Maniega.)
- Significant performance improvements have been made to the DICOM reading code, decreasing read times by up to 50%. Users should find that performance is even better with R 2.9.2, which is planned for release on 2009-08-24.
- A new mechanism is now behind “tractor -o (script)”, and as a result the program displays the available options for those configuration variables, like “PointType”, which can only take certain values. This change finally closes issue #2.
statusscript defaults to the current directory if none is specified. It will also no longer create an empty camino subdirectory.
dicomtagsscript now accepts a directory name instead of a file name, in which case it will look for a DICOM file in that directory and print the tags for that file. If nothing is specified, the current directory is used by default.
- If an experiment script is not found, the
tractorprogram now prints the name of the missing file.
- Minor documentation changes.
- The TractoR implementation of probabilistic neighbourhood tractography now supports “asymmetric” models, which have more degrees of freedom than normal symmetric models, but potentially fit the data better. Use of this option is now recommended in medium and large data sets.
caminofilesscript now creates version 2 Camino scheme files, and therefore there is no longer any need to specify a diffusion time. In addition, a spurious warning about an existing directory is no longer generated.
gmeanscripts now accept the new values “Lax” and “Lrad” for axial and radial diffusivity, respectively. These are passed to the “Metric” option.
- DICOM code now handles images whose slices are slightly oblique, with a warning. No reslicing is performed.
- Error messages for missing and multiple image files are now different, to avoid confusion.
- The FSLOUTPUTTYPE environment variable is no longer used to set the internal default file type for TractoR. If the TRACTOR_FILETYPE environment variable is not set, the file type defaults to NIFTI_GZ. (Given that TractoR now supports more file types than FSL, this synchronisation makes less sense than it used to.)
- The data preprocessing script,
preproc, no longer returns information about the state of the session. This information (and more) can be obtained using the new
dicomtagsscripts now support filenames containing spaces (although these are generally not recommended).
- All messages, including warnings, are now reported in the order that they are raised by the code.
- The tractor.base R package is now fully documented at the R level.
dicomreadscript now uses the FSLOUTPUTTYPE environment variable to decide on a file format to use if TRACTOR_FILETYPE is not set. This was always the intended behaviour.
- Fixing an issue that would produce an error when reading a 2D NIfTI image file.
pnt-evalscript will now find standard reference tracts as intended.
caminofilesscript would previously always ask for confirmation, even if the camino directory didn’t previously exist.
- A set of standard reference tracts for five major pathways are now included with the TractoR distribution.
- New neighbourhood tractography functionality has been added, for “unsupervised” tract segmentation (using the new
pnt-emexperiment) and extracting parameters of interest from NT results (
- The new
listexperiment lists all available TractoR experiment scripts.
- The new
dicomreadexperiment has been added to convert any directory of DICOM files into an Analyze/NIfTI volume. DICOM read support is now more flexible, and can read images with nonaxial slices.
- The format and name of the file which stores the transform from MNI space to each session’s diffusion space (in the tractor/objects directory) has changed. As a result the registration will be repeated the first time it is needed. The new
xfmconvertscript can be used to convert existing files to the new format (
tractor -o xfmconvertfor usage information).
preprocexperiment now shows the principal directions of the diffusion tensor in FSLview during stage 4. It also interprets its DicomDirectory parameter as representing a full path if it begins with a “/” character.
chfiletypeexperiment can now be used to change the datatype of an image as well as the file format.
- Warning messages that occur multiple times are now generally shown only once – along with the number of occurrences. Warnings from R core code are also reported in this way.
- Log files created with the “-l” flag are now named for the script that was run.
- Some scripts handle missing data or files more gracefully.
- The main
tractorscript now requires the
bashshell specifically (not
Beta 3.1 (2008-08-18)
- A mistake in the
peekexperiment scripts meant that they produced errors about missing functions. This has been corrected.
- Following the dropping of support for the Analyze file format by FSL 4.1, this beta provides some extra tools for those who wish to continue using the format. Specifically, the environment variable TRACTOR_FILETYPE can be set to ANALYZE if the user wishes TractoR to output Analyze files by default. (This is no longer a legal value for FSL’s environment variable FSLOUTPUTTYPE, which was previously used for TractoR’s default.) The
chfiletypescript has also been created for converting between formats as required: please run
tractor -o chfiletypefor details.
Beta 3.0 (2008-08-11)
- The way in which TractoR looks for its scripts has changed somewhat. This should make installation both simpler and more flexible in most cases.
- Three new utility scripts have been added. The
caminofilesexperiment converts a data set into file formats suitable for use with the Camino diffusion MRI toolkit;
mkbvecsassists with the creation of valid “bvals” and “bvecs” files for use with FSL; and
dicomsortsorts a directory of DICOM files into subdirectories by series number. The latter is useful for separating diffusion data from structural acquisitions.
- The time-consuming
pnt-dataexperiment script now writes partial output as it goes and supports resuming a partially completed run. This makes interruptions to this process, such as major errors or power loss, far less painful in terms of the time lost. The script also allows a single seed point to be specified on the command line with the new SeedPoint option.
preprocexperiment checks more robustly to make sure that its first stage has been completed properly. The script also more faithfully obeys its Interactive flag.
- TractoR will now use R’s batch mode if requested. This is not that useful under most usual circumstances, but can occasionally be helpful.
- More minor tweaks and fixes.
Beta 2.0 (2008-04-29)
- Entities which are stored in “.Rdata” files are now saved in a different way. This means that objects such as reference tracts created with beta 1.0 will not directly work with beta 2.0. However, this new arrangement should generally be forward-compatible with future releases. The new
peekexperiment script can be used to inspect these stored R objects.
- The main
tractorscript has had some tweaks. The log file, “tractor_output.log” will now receive output from the experiment script in real time rather than all at the end. Multiple configuration files (specified with the “-c” flag) are now permitted, and paths to these files are now relative to the current working directory rather than the experiment’s working directory (which was a bit counterintuitive).
tractor -onow reports “None” if no options are available.
- The user can set up default options for TractoR experiments using a ~/.tractor/config file. See the
tractorman page for more details.
- History log files (“tractor_history.log”) now include the date and time that the experiment script completed.
- Added the
gmeanexperiment script, a companion to
meanaimed at applying the same calculation to a group of images. Run
tractor -o gmeanfor details.
- The interface of the
preprocscript has changed a little. It also supports a new option specifying a particular subdirectory to search for DICOM files.
mkroiexperiment no longer returns the names of the files it created.
- The TractoR makefile now assumes that R is installed at /usr/local/bin/R by default.
- An adjustment to the NIfTI file reading code has been made for compatibility with R 2.7.0.
- Various minor changes and fixes.
Beta 1.0 (2008-03-03)
- First public release.