Automatic atlas queries in FSL

Posted on by

The fmrib Software Library (fsl) provides a tool to query whether regions belong or not to one of various atlases available. This well-known tool is called atlasquery, and it requires one region per image per run. To run for multiple separate regions on a single image image (e.g., a thresholded statistical map), a separate call to fsl‘s cluster command (not to be confused with the homonym cluster command that is part of the GraphViz package) is needed.

In order to automate this task, a small script called autoaq is available (UPDATE: the script is no longer supplied here; it has been incorporated into fsl). Usage information is provided by calling the command without arguments. This is the same script we posted recently to the fsl mailing list (here). Obviously, it does not run in Microsoft Windows. To use it, you need any recent Linux or Mac computer with fsl installed.

An example call is shown below:

./autoaq -i pvals.nii.gz -t 0.95 -o report.txt -a "JHU White-Matter Tractography Atlas"

The command will write temporary files to the directory from where it is called, hence it needs to be called from a directory to which the user has writing permissions. The atlas name can be any of the atlases available in fsl, currently being the ones listed below (note the quotes, ” “, that need to be provided when calling autoaq):

  • “Cerebellar Atlas in MNI152 space after normalization with FLIRT”
  • “Cerebellar Atlas in MNI152 space after normalization with FNIRT”
  • “Harvard-Oxford Cortical Structural Atlas”
  • “Harvard-Oxford Subcortical Structural Atlas”
  • “JHU ICBM-DTI-81 White-Matter Labels”
  • “JHU White-Matter Tractography Atlas”
  • “Juelich Histological Atlas”
  • “MNI Structural Atlas”
  • “Oxford Thalamic Connectivity Probability Atlas”
  • “Oxford-Imanova Striatal Connectivity Atlas 3 sub-regions”
  • “Oxford-Imanova Striatal Connectivity Atlas 7 sub-regions”
  • “Oxford-Imanova Striatal Structural Atlas”
  • “Talairach Daemon Labels”

The list can always be obtained through atlasquery --dumpatlases. Information about these atlases is available here.

The output is divided in three sections. In the first, a table containing the cluster indices, size and coordinates of the peaks and centres of mass is provided. In the second part, the structures to which the cluster peaks belong are presented, along with the associated probabilities. In the third part, probabilities for each cluster as a whole is presented. If the atlas is a binary label atlas, the number shown is in fact the overlap percentage between the cluster and the respective atlas label. If the atlas is probabilistic, the value is the mean probability in the overlapping region.

Version history:

  • 03.Oct.2012: Update – Fixed issue with the md5 command under a different name in vanilla Mac.
  • 25.Jan.2014: Update – Added options -u (to update/append a previous report) and -p to show peak coordinates instead of center of mass.
  • 10.Dec.2014: The autoaq has been integrated into the freely available fmrib Software Library (fsl) and is no longer provided here. Hope you enjoy using it directly into fsl! :-)

13 thoughts on “Automatic atlas queries in FSL”

  2. This looks very helpful! Does the script file need to be placed in a particular directory to be able to run it from the terminal? Thanks!

    Reply ↓

    • Hi Mike,
      The script can be saved anywhere. Just make it executable. To be able to run it from any directory, add the path to where you saved it to your PATH variable. A suggestion is to create a directory called “bin” in your home, and put all your scripts there, then add this to the PATH.
      All the best,
      Anderson

      Reply ↓

      • Many thanks! It appears to me that in part 2 of the output, the structures listed correspond to the center of mass coordinates. Is there any way to change this so that they structures correspond to the peak intensity coordinates? Thanks!
        Mike

        Reply ↓

        • Hi Mike,
          I just updated to add this option. It’s now the “-p”. Please, try downloading it again and see if it’s what you need.
          All the best,
          Anderson

  4. Hi there,

    Somewhat of an extreme beginner here. I have DTI (FA/DTI) data for disease groups vs controls. I was hoping to use the thresholded SPMs to query a atlas in order to get labels for the clusters, % involvement, etc. It seems your query can do this, but I’m somewhat lost as to how to get from my output files (.img/.hdr) in SPM to a point where I can use this FSL query?

    I don’t know if you are familiar with the ‘Anatomy’ toolbox in SPM, but I’m looking for a similar thing for white matter data.

    Any help would be much appreciated.

    Hugo

    Reply ↓

    • Hi Hugo,

      FSL can read .hdr/.img pairs so this shouldn’t be a concern. The subjects must be in the same space as the FSL atlases, which are used by autoaq/atlasquery.

      There is, however, a more serious issue I’m afraid: analyses using DTI scalars as FA should use TBSS, because differences in tract positions can be incorrectly interpreted as significant FA differences. Please, see Smith et al (2006) paper that introduces TBSS.

      Also, subscribe to the FSL list (on jiscmail) if you need help to run that.

      All the best,

      Anderson

      Reply ↓

  5. Hi Anderson,
    Great tool, thanks!!
    I’d like to hear your thoughts on how to best report the output. The tool gives us ‘Structures to which each cluster peak belongs to’ with a list of regions and their percentages (I use Harvard-Oxford atlas) as well as ‘Structures to which each cluster belongs to’ with a list of regions. Now I want to get from this list to a nice publishable table (as you already partly give us in the top part of the output) including a column with the region(s) specified rather than this list. I’d like to automatize this (partly because I’m lazy and have a lot of maps, but mostly) because it seems to me that this would make the process more objective than going through the list and selecting the regions which best fit previous literature or my ideas. So… would you for instance go with the cluster peak list and then only report the region(s) above a certain percentage? I understand it’s probably not that black and white, but I’d like to know how you might go about this.
    Again, thanks for sharing. Kind regards, Johannes

    Reply ↓

    • Hi Johannes,
      I think this could be automated with grep on the outputs, i.e., a script around the script.
      All the best,
      Anderson

      Reply ↓

  6. Hi again,
    just a little additional question: I keep getting the warning/error message below when running the script. This happens when no clusters are present. It isn’t a big issue as it just keeps running and produces output, but just wondering whether there is a quick fix (tried it my self but failed…).
    Thanks. Kind regards, Johannes

    dc: register ‘=’ (075) is empty
    dc: stack empty
    /home/Scripts/autoaq.sh: line 77: ((: r<=========================================== : syntax error: operand expected (error token is "========================================== ")
    Warning: The number of clusters in the report table isn't the same as in the image.
    /home/Scripts/autoaq.sh: line 103: ((: c=========================================== : syntax error: operand expected (error token is "============

    Reply ↓

Leave a reply to A. M. Winkler Cancel reply