Differences between revisions 587 and 588
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
These Release Notes cover what's new in a release, and known issues. See [[PreviousReleaseNotes|previous release notes]] for older versions. These Release Notes cover what's new in a release, and known issues. See [[DownloadAndInstall|the download and install page]] for the current stable release.
Line 7: Line 7:
== Stable v5.3.0 ==
'''''2 March 2013'''''
== Stable v6.0 ==
'''''23 January 2016'''''
Line 10: Line 10:
Stable release version 5.3.0 is a bug fix release to correct the problem with pial and white surface creation affecting thickness and area measures. Stable release version 6.0 is a major release containing new features and bug fixes.
Line 13: Line 13:
 * New features:
  * 64bit version of freeview (MacOSX Lion). Note: upon opening freeview for the first time, it may display a message prompting to Allow or Deny network connections. This originates from a Qt library which manages File Open functionality. You may select Deny without affecting the functionality of freeview, except perhaps in regards to some network drive accessibility.
  * freeview contains features intended to transition to replacing tkmedit and tksurfer. Also slice scrolling speed is improved.
  * added -first_wm_peak flag to mris_make_surfaces, which may aid accurate more white matter surfaces especially in heavily myelinated areas like visual cortex on data that is higher res than 1mm. enable the flag via an expert.opts file.
 * Bug fixes:
  * fix for mris_make_surfaces to correct pial/white surface bug.
  * fix for mri_mask problem affecting edits.
  * fix for qdec problem affecting threshold entry box.
  * fix for Fedora 18, Ubuntu 13, and Gentoo 64 glibc crashes (seg-faults on any binary).
  * fix for recon-all tal-check failure-threshold sensitivity.

=== Known Issues ===
 * On Mac OSX platforms you need to install XQuartz. Pre-Yosemite versions of OS X require [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.5.dmg|XQuartz 2.7.5]], Yosemite requires [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.6.dmg|XQuartz 2.7.6]] or higher.

 * Max OSX platforms may get a ''''' mris_resample: Command not found''''' error. If so, download the [[ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/patches/mris_resample|mris_resample]], copy it into your $FREESURFER_HOME/bin directory, and try again. Make sure it is executable (chmod a+x mris_resample).

 * Opensuse platforms versions greater than 12.3 are not compatible with the !FreeSurfer licensing scheme. There are two potential solutions. The first is to copy /lib64/libcrypt-2.14.1.so from an Opensuse 12.1 installation to $FREESURFER_HOME/lib. Then make a symbolic link to it in that directory ({{{ln -s libcrypt-2.14.1.so libcrypt.so.1}}}). Or 2) just download and install the Development Version of !FreeSurfer.

 * The Talairach transform step will fail at the {{{mri_nu_correct.mni}}} command on newer Linux distributions that come with perl version 5.22 (and higher) due to an incompatibility with the mni tools shipped with !FreeSurfer and newer versions of perl. The issue has been fixed in the Development Version of !FreeSurfer.

 * freeview & Ubuntu: When you run freeview, you get the error "freeview.bin: error while loading shared libraries: libjpeg.so.62: cannot open shared object file: No suchfile or directory." Freeview will work fine if you install libjpeg62-dev and run:

{{{
sudo apt-get install libjpeg62-dev
}}}
 * freeview: on the Fedora 18 platform, when loading a surface overlaid on a volume, the surface might be misaligned. The message "Warning: !MatrixInverse failed." may also be displayed in the terminal. A fix or workaround is not yet available.
 * fsfast: on the Mac, preproc-sess might fail looking for 3dvolreg.afni. 3dvolreg.afni is just a redistributed copy of AFNIs 3dvolreg, so the workaround is to install AFNI on your own, then: {{{sudo cp 3dvolreg /Applications/freesurfer/bin/3dvolreg.afni}}} Or you can download 3dvolreg.afni [[ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/misc/macos-lion/|from here]]. (''ERROR: cannot find AFNI command 3dvolreg.afni'')
 * The -dti option in freeview will not display eigenvectors correctly if the orientation of the volumes is anything other than RAS. This will be fixed for the next release.
 * Creation of the aseg.stats table fails when only running -autorecon1 or -autorecon2 because ribbon.mgz is not present. This has been fixed. Ask for a patch.
 * mris_preproc --qdec and --qdec-long only works with unix input text files (\n newline). If you have difficulties (i.e. old mac \r or windows \r\n newline files) ask for a fixed version.
 * flirt.fsl and other fsl binaries will be missing from the MacOS snow leopard build. Download the the binaries [[ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/patches/freesurfer_fsl.tar.gz|from here]]. Extract the contents of the tar file into the $FREESURFER_HOME/bin directory. This should result in 6 new files with a .fsl extension in the $FREESURFER_HOME/bin directory.
 * recon-all/mri_segstats: when the flags -autorecon1 -autorecon2 are used with recon-all, then recon-all error exists with message about missing ribbon.mgz file. there are two workarounds: 1. include the flag -autorecon3 (or just use -all, which is the recommendation), or 2. [[ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/5.3.0-patch|get mri_segstats from here]], then:{{{cp mri_segstats $FREESURFER_HOME/bin}}}
 * LGI: issue when using Matlab 2013. the fix is to edit the file {{{$FREESURFER_HOME/matlab/SearchProjectionOnPial.m}}} and make these changes:

{{{
find this line:

< for t=1:step:size(perim,2)

and change to:

> si=max(size(perim));
> for t=1:step:si
}}}
 * fslregister (and so bbregister with --init-fsl) requires that FSL be installed. This has been fixed. The fix will be in the next version. Ask for a patch if you need it before then.
 * Unpacking DICOM files from the Siemens Skyra scanner fails on MacOS. This has been fixed. Download the new version of [[ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/5.3.0-patch/mri_convert.macos|mri_convert]] and copy it to $FREESURFER_HOME/bin/mri_convert
 * Longitudinal pipeline, adding time points: there is a bug in recon-all that prevents adding time points to an existing base (usually you should not do this anyway), make these changes to fix it:

{{{
in recon-all line 6148 change:

  if ( ! $found_tpNid ) then

to

  if ( ! $found_tpNid && ! $DoAddTp ) then
}}}
 * selxavg3-sess can use a huge amount of memory when running mni305. This is mostly due to poor memory management in matlab. For the next release, selxavg3-sess has been modified to reduce the amount of memory used by a factor of 2 or more.

 * mni152reg exits with a "Permission denied" error. Use ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/5.3.0-patch/mni152reg instead. Copy it into $FREESURFER_HOME/bin

 * recon-all: two issues with using T2 to refine the pial: (1) statistics were computed before the pial surface was refined, and (2) no way to recover from registration errors. This version: ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/5.3.0-patch/recon-all fixes these problems. Copy it into $FREESURFER_HOME/bin. If the registration fails, then try using -bbr-init-header.

 * Poorly aligned data that can not be fixed by the primary talairach alignment utility will result in a {{{"Can't locate shellwords.pl in @INC}}} error on system running perl5.16 or greater. One possible solution is to use a version of perl pre-v5.16, if one is installed on your system. This is done by modifying the 1st line of file $FREESURFER_HOME/mni/bin/mritotal. For example:

{{{
< #!/usr/bin/perl
> #!/usr/bin/perl5.12
}}}
Another workaround is to use tkregister to manually align the image, such that mritotal is not run, and the rest of recon-all should run properly.

 * Entorhinal and perirhinal labels are incorrect due to a spherical warp that is too rigid. This results in the labels being shifted too medial, so that the pc is often where ec should be. This problem has been fixed for the next release (v6).
 * When using the VirtualBox version of freesurfer (freesurfer-Virtualbox-linux-x86-stable-pub-v5.3-full), the "mri_nu_correct.mni" command will fail when executed in the VirtualBox environment on a subject whose data exists on a shared folder between the host and the virtual machine. Currently, the only known solution is to import the subject data folder into the VirtualBox environment, and then run recon-all.

=== Upcoming Features (v6.0) ===
Line 98: Line 23:
  * New longitudinal pipeline for tractography
Line 100: Line 24:
 * TRACULA: see [[Tracula#Updates|TRACULA release notes]]
Line 104: Line 29:
 * recon-all now produces aseg.mgz (subcortical atlas) with Hi-Res data (<1mm). the -hires flag is still necessary to include with recon-all when hi-res data is input. changes to mri_normalize, mri_em_register and mri_watershed were made to support this feature.  * [[attachment:28.png|Improved dice scores]] between the aseg and the manual labels of 26 GE and Siemens subjects.
 * FSFAST now supports B0 distortion correction and Combined-Volume-Surface (CVS) registration
 * NEW! PETSurfer - integrated PET, Partial Volume Correction, and kinetic modeling analysis
 * mri_convert can now read gradient tables and b-value tables from the headers of DICOM diffusion data
 * mri_glmfit computes the partial Pearson correlation coefficient (pcc.mgh)
 * mri_aparc2aseg now reassigns voxels in the ribbon labeled as cerebellum ctx to cerebral ctx
 * Added -dura_thresh option to mris_make_surfaces to allow manual setting of the dura threshold instead of automatic estimation
 * recon-all now produces aseg.mgz (subcortical atlas) with Hi-Res data (<1mm). The -hires flag is still necessary to include with recon-all when hi-res data is input. Changes to mri_normalize, mri_em_register and mri_watershed were made to support this feature.
 * Improved error handling of talirach registration in recon-all: if tal-check fails, it will retry with an older atlas
 * Modified T2 registration operations to create a T2raw.auto.lta file which gets copied to T2raw.lta (as well as for FLAIR)
 * Updated fsaverage to include fixed peri/entorhinal labels
Line 107: Line 42:
 * Adding the 'fs_update' script which allows users to update binaries or other elements of the freesurfer installation.
 * Adding the 'fs_tutorial_data' script which provides a means for downloading the data for completing the Self:Tutorials.
Line 111: Line 44:
 * Bug fix in mri_ca_register that prevented unfolding of lattice and caused many hours of unecessary unfolding and also stopped warp from evolving.
 * Add code for Wash. U. HCP to settle white surface near maxima in second directional derivative if -first_wm_peak is specified (off by default).
 * Fixed the libcrypt issue with OpenSuse linux platforms
 * Parallelization: a new flag was introduced which enables two forms of compute parallelization that significantly reduces the runtime. As a point of reference, using a new-ish workstation (2015+), the recon-all -all runtime is just under 3 hours. When the {{{-parallel}}} flag is specified at the end of the recon-all command-line, it will enable 'fine-grained' parallelized code, making use of OpenMP, embedded in many of the binaries, namely affecting mri_em_register and mri_ca_register. By default, it instructs the binaries to use 4 processors (cores), meaning, 4 threads will run in parallel in some operations (manifested in 'top' by mri_ca_register, for example, showing 400% CPU utilization). This can be overridden by including the flag {{{-openmp <num>}}} after -parallel, where <num> is the number of processors you'd like to use (ex. 8 if you have an 8 core machine). Note that this parallelization was introduced in v5.3, but many new routines were OpenMP-parallelized in v6. The other form of parallelization, a 'coarse' form, enabled when the -parallel flag is specified, is such that during the stages where left and right hemispheric data is processed, each hemi binary is run separately (and in parallel, manifesting itself in 'top' as two instances of mris_sphere, for example). Note that a couple of the hemi stages (eg. mris_sphere) make use of a tiny amount of OpenMP code, which means that for brief periods, as many as 8 cores are utilized (2 binaries running code that each make use of 4 threads). In general, though, a 4 core machine can easily handle those periods. Be aware that if you enable this -parallel flag on instances of recon-all running through a job scheduler (like a cluster), it may not make your System Administrator happy if you do not pre-allocate a sufficient number of cores for your job, as you will be taking cycles from other cores that may be running jobs belonging to other cluster users.
 * Bug fix in mri_ca_register that prevented unfolding of lattice and caused many hours of unnecessary unfolding and also stopped warp from evolving.
 * Added code for Wash. U. HCP to settle white surface near maxima in second directional derivative if -first_wm_peak is specified (off by default).
 * Improved handling of enlarged ventricles when -bigventricles is specified in recon-all by performing an initial nonlinear registration of just the ventricular system using coupled region-growing in the atlas and input image, and also made the warp more flexible by default (setting l_smoothness = 0.5 instead of the default 2.0)

=== Known Issues ===
 * On Ubuntu platforms, you may encounter the error "freeview.bin: error while loading shared libraries: libjpeg.so.62: cannot open shared object file: No such file or directory." Freeview will work fine if you install libjpeg62-dev and run:

{{{
sudo apt-get install libjpeg62-dev
}}}

top

FreeSurfer Release Notes

These Release Notes cover what's new in a release, and known issues. See the download and install page for the current stable release.

Stable v6.0

23 January 2016

Stable release version 6.0 is a major release containing new features and bug fixes.

What's New

  • Brain networks (cognitive components) estimated from 10449 Experiments and 83 tasks in the Brainmap database are released in MNI152 and fsaverage space:
    • Wikipage: BrainmapOntology_Yeo2015

    • There are three sets of data (networks+auxiliary information) that are released: (1) Probability that a task would recruit a component (csv files), (2) Probability that a component would activate a voxel/vertex, (3) quantitative measures of functional specificity and flexibility (i.e., whether a voxel/vertex specializes for a specific cognitive component or supports multiple components).
    • The volumetric maps + csv files are found in average/Yeo_Brainmap_MNI152/. See Yeo_Brainmap_MNI152_README in directory for more details.
    • The surface maps are found in the subjects/fsaverage/label directory. See Yeo_Brainmap_fsaverage_README in directory for more details.
  • Substructure Segmentation:
  • Longitudinal:
  • TRACULA: see TRACULA release notes

  • Matlab Linear Mixed Effects Tools:
    • Updated Matlab LME tools to newer Matlab versions
    • Allow missing Parallel Toolbox (process sequentially)
    • minor improvements to F-test
  • Improved dice scores between the aseg and the manual labels of 26 GE and Siemens subjects.

  • FSFAST now supports B0 distortion correction and Combined-Volume-Surface (CVS) registration
  • NEW! PETSurfer - integrated PET, Partial Volume Correction, and kinetic modeling analysis
  • mri_convert can now read gradient tables and b-value tables from the headers of DICOM diffusion data
  • mri_glmfit computes the partial Pearson correlation coefficient (pcc.mgh)
  • mri_aparc2aseg now reassigns voxels in the ribbon labeled as cerebellum ctx to cerebral ctx
  • Added -dura_thresh option to mris_make_surfaces to allow manual setting of the dura threshold instead of automatic estimation
  • recon-all now produces aseg.mgz (subcortical atlas) with Hi-Res data (<1mm). The -hires flag is still necessary to include with recon-all when hi-res data is input. Changes to mri_normalize, mri_em_register and mri_watershed were made to support this feature.

  • Improved error handling of talirach registration in recon-all: if tal-check fails, it will retry with an older atlas
  • Modified T2 registration operations to create a T2raw.auto.lta file which gets copied to T2raw.lta (as well as for FLAIR)
  • Updated fsaverage to include fixed peri/entorhinal labels
  • Improved accuracy of ?h.cortex.label
  • Improved prevention of surfaces from crossing into the contralateral hemisphere
  • bbregister now uses the FS mri_coreg program by to initialize BBR. FSL or SPM/matlab are no longer needed. mri_coreg is based on spm_coreg and gives very similar results as to when spmregister is run.
  • mri_fdr -- command line program to compute and apply the false discovery rate algorithm
  • Fixed the libcrypt issue with OpenSuse linux platforms

  • Parallelization: a new flag was introduced which enables two forms of compute parallelization that significantly reduces the runtime. As a point of reference, using a new-ish workstation (2015+), the recon-all -all runtime is just under 3 hours. When the -parallel flag is specified at the end of the recon-all command-line, it will enable 'fine-grained' parallelized code, making use of OpenMP, embedded in many of the binaries, namely affecting mri_em_register and mri_ca_register. By default, it instructs the binaries to use 4 processors (cores), meaning, 4 threads will run in parallel in some operations (manifested in 'top' by mri_ca_register, for example, showing 400% CPU utilization). This can be overridden by including the flag -openmp <num> after -parallel, where <num> is the number of processors you'd like to use (ex. 8 if you have an 8 core machine). Note that this parallelization was introduced in v5.3, but many new routines were OpenMP-parallelized in v6. The other form of parallelization, a 'coarse' form, enabled when the -parallel flag is specified, is such that during the stages where left and right hemispheric data is processed, each hemi binary is run separately (and in parallel, manifesting itself in 'top' as two instances of mris_sphere, for example). Note that a couple of the hemi stages (eg. mris_sphere) make use of a tiny amount of OpenMP code, which means that for brief periods, as many as 8 cores are utilized (2 binaries running code that each make use of 4 threads). In general, though, a 4 core machine can easily handle those periods. Be aware that if you enable this -parallel flag on instances of recon-all running through a job scheduler (like a cluster), it may not make your System Administrator happy if you do not pre-allocate a sufficient number of cores for your job, as you will be taking cycles from other cores that may be running jobs belonging to other cluster users.

  • Bug fix in mri_ca_register that prevented unfolding of lattice and caused many hours of unnecessary unfolding and also stopped warp from evolving.
  • Added code for Wash. U. HCP to settle white surface near maxima in second directional derivative if -first_wm_peak is specified (off by default).
  • Improved handling of enlarged ventricles when -bigventricles is specified in recon-all by performing an initial nonlinear registration of just the ventricular system using coupled region-growing in the atlas and input image, and also made the warp more flexible by default (setting l_smoothness = 0.5 instead of the default 2.0)

Known Issues

  • On Ubuntu platforms, you may encounter the error "freeview.bin: error while loading shared libraries: libjpeg.so.62: cannot open shared object file: No such file or directory." Freeview will work fine if you install libjpeg62-dev and run:

sudo apt-get install libjpeg62-dev

ReleaseNotes (last edited 2019-08-29 11:14:12 by 172)