BrainMap GingerALE 3.0.2 ReadMe
↓ Jump to Installation & Support
What's New in Version 3.0.2 [May 16, 2019]
Recent Changes:
- Output image value ranges in the image header now use only finite values. This will help image viewers display Z score images from GingerALE. (Thanks Flo!)
What's New in Version 3.0.1 [May 2, 2019]
Recent Changes:
- P to Z calculation has better precision - now Z images values won't round up to Infinity as quickly
What's New in Version 3.0 [February 5, 2019]
Major Changes:
- New mask support: adding MNI152 reference space
- Removing False Discovery Rate option from thresholds by default - it can be enabled in Preferences
Cluster Statistics:
- Cluster Statistics (in "clust.txt") anatomical labels now list the percentage of the volume that each label represents, instead of listing the volume by millimeters cubed
- Cluster Statistics spreadsheet ("clust.xls") renamed to Peaks Spreadsheet ("peaks.xls")
- All cluster statistics (both "clust.txt" and "peaks.xls") now show P values and Z scores along side any ALE peak values
- Changed some Preference options regarding Cluster Statistics (see below)
Preferences:
- Adding an option to re-enable False Discovery Rate thresholding for backwards compatibility
- Removed ALE Method option for union vs max from Turkeltaub et al, HBM 2012 - now always using the "max" option recommended in the publication
- Adds an option for Cluster Analysis Labels to use exclusively Gray Matter labels, or to include non-gray matter as well
- Removes an option to report only the single largest maxima or to report all maxima in Cluster Analysis - now reporing single peak in Cluster Analysis ("clust.txt") and all maxima in Peak Spreadsheet ("peaks.xls")
- Preference options related to ALE method and output files are now disabled while processing data
Minor Changes:
- Performs validity checks on the output directory (canWrite, etc) before processing starts
- Renamed "Uncorrected P value" to "P value" and "Study" (in Single/Contrast selection) to "Dataset"
- Added saving an unthresholded Z score image along side the ALE and P value images
What's New in Version 2.3.6 [April 26, 2016]
Algorithm Bug Fix:
- Cluster-level FWE changed to use the distriubtion of maximum cluster sizes instead of all cluster sizes above the cluster-forming threshold. (Thanks to Chris for reporting this on the forums)
- Get updated to algorithm-level bug fixes with our new mailing list
Other Bug Fix:
- Using Additional FWHM's "None" option in Preferences, previously it would be ignored if the Addtional FWHM value was set above zero
Improvements:
- Improving multi-threading support when creating MA and ALE images
- Adding minimum (most significant) P value to the data history
- Supports opening compressed images in Contrast analysis
What's New in Version 2.3.5 [November 19, 2015]
- Fixed a hang-up introduced in version 2.3.4 that showed up when using a thresholding method other than Cluster-Level
- Updated the splash screen to include the entire version number (Thanks, Meimei!)
What's New in Version 2.3.4 [October 12, 2015]
Includes Java!
The Mac and PC versions now include their own copy of Java 8. This increases the size of the download by about 50MB, but gets rid of all issues related to incompatable Java versions. Those using the jar version will still need a copy of Java.
Bug fixes:
- "Additional FWHM" option wasn't taking effect (thanks Paul!)
- temporary files should delete themselves more frequently
(thanks Yuhua, Cody & Beverley!) - smaller/larger (Talairach) masks getting swapped
(thanks Ruibin and Christopher!) - making sure all permutations are completed (thanks Jane and Cody!)
What's New in Version 2.3.3 [May 11, 2015]
Bug fixes:
Correction to False Discovery Rate calculations (Thanks, Chris)
Command-line interface recognizes threshold settings and saves thresholded results (reintroduced issue from 2.3.2)
What's New in Version 2.3.2 [May 7, 2014]
Various small improvements:
Renamed the included mask images to Tal_wb and MNI_wb (see command-line options) (Thanks cmcnorgan!)
Fixed getALE2Contrast command-line bug related to Cluster-Level thresholds (Thanks cmcnorgan!)
Fixed getALE2 command-line bug which interfered with threshold settings (Thanks cmcnorgan!)
Fixed conjunction xls file name bug (Thanks Matthew!)
What's New in Version 2.3.1 [September 30, 2014]
Updated Users' Manual
- new and improved GingerALE Users' Manual, including adding several figures and a section on MACM analyses
Various small improvements:
- changed threshold for Family-wise Error and Cluster-level Inference from <= to < (Thanks, Fabio!)
- added xls-style cluster analyis for conjunction data (Thanks, Isabella!)
- added cluster volume threshold options to the command line (Thanks, Matthew!)
- fixed -min and -out options in command line cluster analysis (Thanks, Crystal!)
- changed the output file names for cluster-level inference to use "C" instead of "Cli"
- added a keyboard shortcut (M) for the Merge menu item
What's New in Version 2.3 [January 11, 2013]
More Thorough Data Set Checking:
Single-study analyses will show warnings for:
- experiments without foci
- experiments without a number of subjects
- potentially duplicated experiments within the dataset
(using foci locations to determine uniqueness)
Contrast analyses will show warnings for:
- experiments in group A, but not in pooled data
- experiments in group B, but not in pooled data
- experiments in pooled data, but not in A or B
Improved Data History:
- added "Volume > Threshold" for more Thresholding methods
- added "Recommended Min. Cluster Size" for subtraction analyses using FDR (Thanks, Boeken1)
Various small improvements:
- support for Mac OS X 10.8 and Gate Keeper (Thanks, Martijn!)
- fixing minimum cluster size bug (Thanks, everybody!)
- simplified command line interface (Thanks, Michel!)
- more readable default file names in contrast analyses (Thanks again, Michel!)
What's New in Version 2.2 [May 14, 2012]
New Thresholding Methods
- Implements new permutation-based thresholding methods from Eickhoff, et al., HBM 2012
- Runs through data generated using gray matter probability map
- Family-wise Error uses the distrubtion of ALE maximum values to choose a minimum ALE value
- Cluster-Level Inference uses a "cluster forming threshold" and the distribution of cluster sizes above the threshold to choose a minimum cluster size
New Contrast Features
- Added more conjunction cluster data: conjunction cluster image and data history statistsics
- Added a Merge Foci menu item (and fixed a bug in it - Thanks Allen!)
Improved Data History:
- Added "Minimum Value above Threshold" (Thanks, Jane!)
- Changed volume statistsics to use mm^3 instead of voxels
- Fixed bug that could allow empty clusters to be listed when using a minimum cluster size of 0
Various small improvements:
- Automatically saves threshold settings (and removed preferences for default threshold settings)
- Bug fixes in command-line interface to thresholding (Thanks idewitt)
- Fix for unnecessary warnings about reference space (Thanks Ariane!)
What's New in Version 2.1.1 [October 11, 2011]
Various small improvements:
- Renamed the output files to be more clear about the types of statistcs saved, ALE vs P vs Z (Thanks boscar)
- Made the checks on the input foci data sets more lenient
- Default thresholding method is now saved separately for single dataset ALE vs when constrasting ALE images
- Improved cluster analysis of non-GingerALE images using the command line (Thanks Amy P.)
What's New in Version 2.1 [August 30, 2011]
Contrast Two Data Sets:
When comparing two data sets A & B, GingerALE will save output files for A-B, B-A and A_conj_B for contrasts and conjunction. Also updated command-line tools for contrasts.
Simplified Data History:
Removed statistics on thresholds that weren't used to make data history more clear.
Foci Rounding Bug:
Fixed rounding bug in Convert Foci when negative coordinate values ended in ".99". (Thanks, Russ Poldrack)
What's New in Version 2.0.4 [August 10, 2010]
Preferences Window bug:
Fixes a bug from GingerALE 2.0.3 which prevents the preference window from showing. (Thanks, Karvonen)
Default Browser:
Improved checking of your default browser (Thanks, Bare Bones Browser Launch)
What's New in Version 2.0.3 [August 7, 2010]
ALE FWHM bug fix:
GingerALE 2.0.1 and 2.0.2 incorrectly use the first experiment's number of subjects and FWHM for all subsequent experiments. 2.0.3 uses the appropriate FWHM values. (Thanks, Danilo!)
P value optimization:
When computing P values, GingerALE uses less memory especially for smaller data sets.
What's New in Version 2.0.2 [July 28, 2010]
New "Non-Additive" ALE Method bug fix:
GingerALE reported using the wrong ALE method in the Data History. It has now been fixed. (Thanks, briandh)
What's New in Version 2.0.1 [July 6, 2010]
New "Non-Additive" ALE Method:
In GingerALE's preferences you can choose to use a modified algorithm for computing the ALE statistic. The standard modelled activation maps are computed as the cumulative union of gaussians at each foci within the experiment. The new method uses the maximum value from nearby gaussians, which limits the effect of multiple nearby foci within an experiment. This changes the focus from concordance between foci to concordance between experiments.
FWHM & more:
- FWHM values now match Eickhoff 2009 calculations, see graph
- Foci without subject information default to using a FWHM of 19.07
- Data History reports range of FWHM used and the total number of subjects (Thanks, Dan Shaw)
- ALE statistic calculation now includes 2x2x2 voxel size (Thanks, Peter Turkeltaub)
- Added option in preferences for an additional FWHM "fudge factor"
What's New in Version 2.0 [August 24, 2009]
New Algorithm:
- Requires subject data within foci text (Supported by Sleuth 1.2)
- Temporarily saves activation maps to disk (<1MB per experiment)
- Subtraction foci are not supported in this release
- ALE and P Value images can not be loaded from file in this release
MNI Support:
- Supports MNI reference space throughout, chosen in the preferences
- Shows chosen coordinate system in Foci section
- Automatically changes reference space to match the reference space of the foci data (if using Sleuth 1.2)
- Supports MNI in coordinates by transforming them, then using talairach labels
Other New Features:
- Improved Data History with more information (mask details, experiment tables, minimum recommended cluster volume) and added the ability to save it at any time (File → Save Data History)
- Simplified the interface into 3 steps: ALE, Thresholding & Cluster Analysis
- Improved command-line support with standardized arguments & error messages, and several more options (output file, mask size, reference space)
Bug Fixes:
- Changed clustering algorithm to better match FSL & Mango (Thanks Matt C.)
- Fixed NIfTI extension data to add FSL support (Thanks Matt W.)
- Fixed a cluster analysis bug to handle 0 clusters (Thanks Synge)
- Fixed a Foci Image bug that caused the image not to be saved
- Fixed data history bugs: mask dimensions and % of voxels greater than pN now reported correctly
- Supports Spaces in Mac OS X
What's New in Version 1.1 [October 3, 2007]
Masks:
A new anatomical template is included to be used for viewing ALE results. This template corrects a small defect in the previous template and offers a better representation of Talairach space. We also updated the masks in GingerALE to match this revised template.
GingerALE automatically changes the mask to match ALE images. Thus, if you open existing ALE files that were created prior to this release, GingerALE will utilize the mask that was previously implemented. Nevertheless, to ensure that your images are as accurate as possible, we suggest that re-run your meta-analysis using the new mask/template.
Foci:
- A warning is displayed if any lines in the text file of input foci were not correctly interpreted due to improper formatting
Clusters:
- “Show all local extrema” was added to Preferences that will search the ALE clusters and report not only the maximum values of the ALE statistic, but also the submaxima values that extend along the whole volume of the cluster
- Added a preference to limit the local extrema to the just maximum and minimum values of the cluster
- Fixed a bug that stopped the Clusters step from being re-run
- Fixed a bug that caused Cluster Statistics to hang when finding labels from the Talairach Daemon
Other:
- Added "Check For Updates" in the Help menu
- File dialogs for "Open ALE Scores" and "Open P Values" now gray-out images which aren't ALE or P Value images from the list of possible input files
- Temp files created during permutations are now more reliably deleted
- Export Foci Image saves to the path chosen instead of the default output path
What's New in Version 1.0 [April 13, 2007]
New Tools:
- Added "Convert Foci" option to convert your coordinates from MNI space to Talairach space using multiple versions of the icbm2tal (Lancaster) and mni2tal (Brett) tranformations
- Added "Export Foci Image" to create a NIfTI file of your foci points. No blurring of the coordinates is performed when this image is created
Foci:
- Now included as a separate section of the interface before ALE in order to see how many coordinates and experiments are included in your meta-analysis
- Output file names are updated when foci are loaded
- Foci name is included in the window title
Preferences:
- Added option for less conservative (larger) mask of Talairach space to analyze foci on the border of the brain
- Added option to choose pN or pID as threshold value during FDR procedure
- Re-grouped the preferences and improved the interface
Other:
- GingerALE is now a stand-alone application, separate from Sleuth (previously known as Search&View)
- Many small interface changes and larger code structure changes
- Now distinguishes between ALE & P Value images when loading files
- Added "Show Manual...", "Show Read Me..." and "Show License..." to the Help menu. These options show the manual (in .pdf format), readme, and license files in your default web browser
Installation
Requirements:
- Around 256 MB memory
- Around 160 MB disk space
- Plus 2MB of disk space per experiment in your study
Java: The Mac and Windows versions include their own copy of Java 8, so Java version conflicts and updating are no longer an issue. The compromise is that it is now about 150 MB larger. The jar version is available without embedded Java as well.
Windows: Download the zip and unzip it to get a "GingerALE 3.0.2" folder which contains:
- GingerALE.exe - the main GingerALE program
- GingerALE_debug.exe - has a console window to show error messages
- GingerALE.jar - for command-line usage, but also used by both exe files
- jre - GingerALE's copy of Java Version 8
Macintosh: Download the app. It's using a Disk Image (.dmg), which is like a virtual disk.zip file, but it includes a secure signature that lets your Mac show fewer scary "Unknown Developer" warnings. If your browser doesn't automatically open the xip file, just double-click it and you should get GingerALE.app. Drag GingerALE.app to your Applications folder, or wherever you prefer, and start it up.
Other Systems: Get Java Version 8 or newer at Oracle's official site: Java.com. Download GingerALE.jar. You may be able to run GingerALE by double clicking on the jar. Alternatively, use the command:
java -cp your/path/to/GingerALE.jar org.brainmap.GingerALE
GingerALE has several other command-line options.
Support
Feedback & Help: The GingerALE Forum is available for reporting bugs, or questions about GingerALE or performing meta-analyses.
Thanks,
The BrainMap Development Team