pkgs/fsl.rst

   1 Packages for the complete FSL suite
   2 ===================================
   3
   4 Since FSL covers a very broad range of analysis techniques the suite is split
   5 into a number of separate packages to allow a more fine-grained selection of
   6 the functionality provided by FSL. The following related packages are available:
   7
   8 :ref:`pkg_fsl`
   9   This packages provides the FSL binaries. This includes everything one needs
  10   to run a basic fMRI analysis. However, it is recommend to also at least
  11   install the :ref:`fsl-atlases <pkg_fsl-atlases>` package.
  12
  13 :ref:`pkg_fslview`
  14   Almost everybody should install this package.
  15
  16 :ref:`pkg_fsl-doc`
  17   Contains the FSL documentation in HTML format as included in the official FSL
  18   sources. This package should be installed to use the online help capabilities
  19   of FSL.
  20
  21 :ref:`pkg_fslview-doc`
  22   The FSLView documentation in HTML format. This package is necessary for the
  23   online help system of FSLView.
  24
  25 :ref:`pkg_fsl-atlases`
  26   Contains the standard space brain templates and brain atlases. Almost
  27   everybody should install this package.
  28
  29 :ref:`pkg_fsl-possum-data`
  30   This package provides the templates for the MR sequence simulator POSSUM.
  31   If one does not use POSSUM this package is not necessary.
  32
  33 :ref:`pkg_fsl-first-data`
  34   This package provides model data for FIRST subcortical brain segmentation.
  35   This package is almost 1GB! It is only required if one wants to use FIRST
  36   or run the FSL FEEDS suite.
  37
  38 :ref:`pkg_fsl-feeds`
  39   This package provides the `FSL Evaluation and Example Data Suite`_. This
  40   package performs two functions -- it tests whether the FSL tools are working
  41   properly and it provides example data to try running FSL on. Additionally the
  42   :command:`fsl-selftest` command is avaliable. This is a little script that
  43   runs all tests (or a selected one) in a temporary directory and reports the
  44   results. A manpage is included. This package can be used to perform
  45   `FSL benchmarks`_.
  46
  47 .. _FSL Evaluation and Example Data Suite: http://www.fmrib.ox.ac.uk/fsl/fsl/feeds.html
  48
  49
  50 Report bugs
  51 ===========
  52
  53 If you discover any bugs please report them. The best way to get quick and
  54 professional help is to post to the `FSL mailing list`_. If you send a
  55 bugreport please include detailed information about the problem. This should at
  56 least be a description how the bug can be reproduced as well as information
  57 concerning you environment (for example the operation system). You might also
  58 want to have a look at the mailing list archive whether the problem has been
  59 discovered before.
  60
  61 .. _FSL mailing list: http://www.jiscmail.ac.uk/lists/fsl.html
  62
  63 If you use the package on a Debian system (not Ubuntu) you can simply use the
  64 :command:`reportbug` tool to send a bug report to the `Debian bug tracking
  65 system`_. The bug tracker provides a public list of all reported `bugs of FSL`_
  66 and `bugs of FSLView`_
  67
  68 .. _bugs of FSL: http://bugs.debian.org/src:fsl
  69 .. _bugs of FSLVIEW: http://bugs.debian.org/src:fslview
  70 .. _Debian bug tracking system: http://bugs.debian.org
  71
  72
  73 Additional information
  74 ======================
  75
  76 Since December 2007 the FSL package is officially part of the non-free
  77 section of Debian. The latest package version will always be available
  78 from http://packages.debian.org/sid/fsl in the Debian archive.
  79 However, this only applies to the packages of the FSL and FSLView
  80 binaries. FSL data packages (first, possum, atlases and feeds) are not
  81 yet official Debian packages and will be available from here, as well
  82 as backports for Debian and recent Ubuntu releases.
  83
  84 .. note::
  85
  86   Please be sure to `read the information`_ about the differences
  87   between the Debian packaging and the official FSL releases.
  88
  89 .. _read the information: http://git.debian.org/?p=pkg-exppsy/fsl.git;a=blob_plain;f=debian/README.Debian;hb=HEAD
  90
  91
  92 Usage information
  93 -----------------
  94
  95 FSL requires a config file to be sourced before it can be used. For the Debian
  96 packages this config file is in `/etc/fsl/fsl.sh`. Open a terminal where you
  97 want to start FSL and source it like this::
  98
  99   . /etc/fsl/fsl.sh
 100
 101 Note the dot at the beginning. If you want to have this done automatically, you
 102 could add those line to e.g. your `$HOME/.bashrc` file (or a corresponding
 103 config file of another POSIX-compatible shell). Once you have done that, you
 104 can start using FSL.
 105
 106
 107
 108 Upgrading from FSL 3.x
 109 ----------------------
 110
 111 The FSL configuration file has changed significantly. Please be sure to
 112 (re)source it.
 113
 114 .. note::
 115
 116   There seem to be some remaining incompatibilities of FSL scripts with the
 117   *dash* shell. This is the default shell on Ubuntu systems. If you discover any
 118   problems, please make sure to read `a related posting on the FSL mailing
 119   list`_.
 120
 121 .. _a related posting on the FSL mailing list: http://www.jiscmail.ac.uk/cgi-bin/webadmin?A2=ind0709&L=fsl&T=0&F=&S=&P=19638
 122
 123
 124 Building binary packages yourself
 125 ---------------------------------
 126
 127 If no binary packages for your distribution/platform are available, you can
 128 still build your own. All you need to do is to add this line to your
 129 `/etc/apt/sources.list`::
 130
 131   deb-src http://apsy.gse.uni-magdeburg.de/debian #distro# main non-free
 132
 133 Choose the value of `#distro#` like described in the binary package section. Be
 134 sure to update your package list after that (Remember: :command:`aptitude
 135 update`). To build FSL packages, do this (no superuser privileges required,
 136 but you might have to install `apt-src` first)::
 137
 138   apt-src install fsl
 139   apt-src build fsl
 140
 141 Be patient as this will take some time. All packages will be created in the
 142 directory where the commands are executed. Please note, that you might need to
 143 download or even compile other packages that FSL depends on.
 144
 145 If you are done, you can install the packages with::
 146
 147   dpkg -i fsl*.deb
 148
 149 After you have repeated this procedure for the `fslview` source package, you
 150 should be ready to use FSL.
 151
 152 Advanced: Arch-dependend compiler flags
 153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 154
 155 If you have some experience with compiler flags and you also care for speed,
 156 you might want to have the FSL binaries optimized for every detail of your
 157 platform. To take advantage of all special features of your favorite processor
 158 you can specify custom compiler flags that are used when building binary
 159 packages from the source package of FSL. To achieve this, simply define them in
 160 a variable called :envvar:`DEB_ARCH_OPT_FLAGS` in the environment. In its
 161 simplest form, building an optimized package could be done like this::
 162
 163   DEB_ARCH_OPT_FLAGS="-march=opteron" apt-src build fsl
 164
 165 Note that not all flags are available with every compiler. The above example
 166 does not work with the standard compiler of Debian sarge (gcc 3.3) and you
 167 obviously need an AMD Opteron processor.
 168
 169
 170 FSL benchmarks
 171 --------------
 172
 173 Here is a list of some benchmarking results that demonstrate how fast FSL runs
 174 on several different platforms and distributions. The :command:`fsl-feeds`
 175 package is used for benchmarking FSL. The listed time for a complete
 176 fsl-selftest run is the user time as reported by :command:`time -p`. If you are
 177 also interested in benchmarking results of the non-Debian FSL distribution, you
 178 can visit the `FSL-FEEDS timing website`_.
 179
 180 .. _FSL-FEEDS timing website: http://www.fmrib.ox.ac.uk/fsl/feeds/doc/timings.html
 181
 182 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 183 |Distribution|CPU            |Arch. |Memory|Compiler |Flags             |Version |Time|Submitted     |
 184 +============+===============+======+======+=========+==================+========+====+==============+
 185 |Ubuntu      |Intel Core i7  |x86_64|12GB  |gcc 4.3  |                  |4.1.3-1 |1236| Jiří Keller  |
 186 |jaunty      |8 cores 3.4 Ghz|      |      |         |                  |        |    |              |
 187 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 188 |Ubuntu      |Intel Core 2   |x86_64|4GB   |gcc 4.1.2|                  |4.0.2-1 |1377| Jiří Keller  |
 189 |gutsy       |Quad Q6700 3Ghz|      |      |         |                  |        |    |              |
 190 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 191 |Debian sid  |2x Dual Opteron|amd64 |12GB  |gcc 4.1.1|                  |3.3.7-2 |1560|Yaroslav      |
 192 |            |275 2.2 Ghz    |      |      |         |                  |        |    |Halchenko     |
 193 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 194 |Ubuntu edgy |2x Dual Opteron|i686  |3GB   |gcc 4.1.2|                  |3.3.8-1 |2096|Jeff          |
 195 |            |275 2.2 GHz    |      |      |         |                  |        |    |Stevenson     |
 196 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 197 |Debian lenny|Intel Core2    |i686  |2GB   |gcc 4.3.1|                  |4.1.0-1 |2108|Michael       |
 198 |            |E8400 3Ghz     |      |      |         |                  |        |    |Hanke         |
 199 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 200 |Debian etch |Quad Opteron   |amd64 |32GB  |gcc 3.4.6|-O3 -m64          |3.2b-4  |2152|Antti         |
 201 |            |850 2.4 GHz    |      |      |         |-march=opteron    |        |    |Korvenoja     |
 202 |            |               |      |      |         |-mfpmath=sse      |        |    |              |
 203 |            |               |      |      |         |-msse2            |        |    |              |
 204 |            |               |      |      |         |-ffast-math       |        |    |              |
 205 |            |               |      |      |         |-funroll-all-loops|        |    |              |
 206 |            |               |      |      |         |-fpeel-loops      |        |    |              |
 207 |            |               |      |      |         |-ftracer          |        |    |              |
 208 |            |               |      |      |         |-funswitch-loops  |        |    |              |
 209 |            |               |      |      |         |-funit-at-a-time  |        |    |              |
 210 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 211 |Debian lenny|Athlon X2      |amd64 |4GB   |gcc 4.3  |                  |4.0.4-1 |2268|Petr          |
 212 |            |4800 2.5 GHz   |      |      |         |                  |        |    |Hluštík       |
 213 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 214 |Ubuntu      |Quad Core2     |amd64 |4GB   |gcc 4.1  |                  |4.0-1   |2500|Vincent       |
 215 |feisty      |2.4 GHz        |      |      |         |                  |        |    |Ferrera       |
 216 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 217 |Debian etch |Quad Opteron   |amd64 |32GB  |gcc 4.0.2|-O3 -m64          |3.2b-4  |2619|Antti         |
 218 |            |850 2.4 GHz    |      |      |         |-march=opteron    |        |    |Korvenoja     |
 219 |            |               |      |      |         |-mfpmath=sse      |        |    |              |
 220 |            |               |      |      |         |-msse2            |        |    |              |
 221 |            |               |      |      |         |-ffast-math       |        |    |              |
 222 |            |               |      |      |         |-funroll-all-loops|        |    |              |
 223 |            |               |      |      |         |-fpeel-loops      |        |    |              |
 224 |            |               |      |      |         |-ftracer          |        |    |              |
 225 |            |               |      |      |         |-funswitch-loops  |        |    |              |
 226 |            |               |      |      |         |-funit-at-a-time  |        |    |              |
 227 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 228 |Debian etch |Quad Opteron   |amd64 |32GB  |gcc 4.0.2|-O3               |3.2b-4  |2652|Antti         |
 229 |            |850 2.4 GHz    |      |      |         |                  |        |    |Korvenoja     |
 230 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 231 |Debian etch |2x Opteron     |amd64 |12GB  |gcc 4.1.2|                  |4.0.2-3 |2847|Michael       |
 232 |            |270 2.2 GHz    |      |      |         |                  |        |    |Hanke         |
 233 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 234 |Ubuntu gutsy|Athlon 64X2    |amd64 |2GB   |gcc 4.1.3|                  |4.0.1   |3605|Nicholas P.   |
 235 |            |5200+ 2.6 GHz  |      |      |         |                  |        |    |Holmes        |
 236 +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 237
 238 .. Template
 239  |            |               |      |      |         |                  |        |    |              |
 240  |            |               |      |      |         |                  |        |    |              |
 241  +------------+---------------+------+------+---------+------------------+--------+----+--------------+
 242
 243
 244 If you want to have your system included in this list, please send an email
 245 with the logfile of the benchmark. You can run the benchmark (and create the
 246 logfile) by running (fsl-feeds-3.2beta-3 or higher is required)::
 247
 248   (time -p fsl-selftest -c) > benchmark.log 2>&1
 249
 250 And include the following information in your message:
 251
 252 * Which distribution are you using?
 253
 254 * CPU-type (as specific as possible)
 255
 256 * How much physical memory has the machine? If you don't know this, send the
 257   output of::
 258
 259     free | head -n2 | tail -n1 | awk '{print $2}' -
 260
 261 * If you compiled the binary packages yourself, which compiler did you use?
 262   (hint: `gcc --version`)
 263
 264 * Which custom compiler flags did you use when building the package (if any)?
 265
 266 * Which version of the Debian FSL package was used?