[Scipy-svn] r3399 - trunk/scipy/io/nifti

Wed Oct 3 20:16:52 EDT 2007

Author: chris.burns
Date: 2007-10-03 19:16:50 -0500 (Wed, 03 Oct 2007)
New Revision: 3399

Added:
   trunk/scipy/io/nifti/README
Removed:
   trunk/scipy/io/nifti/README.html
Log:
Replace README.html with a reST version.

Added: trunk/scipy/io/nifti/README
===================================================================

--- trunk/scipy/io/nifti/README	2007-10-04 00:12:15 UTC (rev 3398)
+++ trunk/scipy/io/nifti/README	2007-10-04 00:16:50 UTC (rev 3399)
@@ -0,0 +1,310 @@
+========================================================
+PyNIfTI - Python-style access to NIfTI and ANALYZE files
+========================================================
+
+.. Contents::
+
+1. What is NIfTI and what do I need PyNIfTI for?
+------------------------------------------------
+
+NIfTI
++++++
+
+NIfTI is a new Analyze-style data format, proposed by the NIfTI Data Format Working Group as a "short-term measure to facilitate inter-operation of functional MRI data analysis software packages".
+
+Meanwhile a number of toolkits are NIfTI-aware (e.g. FSL, AFNI, SPM, Freesurfer and Brainvoyager). Additionally, dicomnifti allows the direct conversion from DICOM images into the NIfTI format.
+
+With libniftiio there is a reference implementation of a C library to read, write and manipulate NIfTI images. The library source code is put into the public domain and a corresponding project is hosted at SourceForge.
+
+In addition to the C library, there is also an IO library written in Java and Matlab functions to make use of NIfTI files from within Matlab.
+
+Python
+++++++
+
+Unfortunately, it is not that trivial to read NIfTI images with Python. This is particularly sad, because there is a large number of easy-to-use, high-quality libraries for signal processing available for Python (e.g. SciPy).
+
+Moreover Python has bindings to almost any important language/program in the fields of maths, statistics and/or engineering. If you want to use R to calculate some stats in a Python script, simply use RPy and pass any data to R. If you don't care about R, but Matlab is your one and only friend, there are at least two different Python modules to control Matlab from within Python scripts. Python is the glue between all those helpers and the Python user is able to combine as many tools as necessary to solve a given problem -- the easiest way.
+
+PyNIfTI
++++++++
+
+PyNIfTI aims to provide easy access to NIfTI images from within Python. It uses SWIG-generated wrappers for the NIfTI reference library and provides the NiftiImage class for Python-style access to the image data.
+
+While PyNIfTI is not yet complete, it already provides access to the most important features of the NIfTI-1 data format and libniftiio capabilities. The following features are currently implemented:
+
+ * PyNIfTI can read and write any file format supported by libniftiio. This includes NIfTI (single and pairs) as well as ANALYZE files.
+ * PyNIfTI provides fast and convenient access to the image data via NumPy arrays. This should enable users to process image data with most (if not all) numerical routines available for Python. The NumPy array automatically uses a datatype corresponding to the NIfTI image data -- no unnecessary upcasting is performed.
+ * PyNIfTI provides full read and write access to the NIfTI header data. Header information can be exported to a Python dictionary and can also be updated by using information from a dictionary.
+ * Instead of accessing NIfTI data from files, PyNIfTI is able to create NIfTI images from NumPy arrays. The appropriate NIfTI header information is determined from the array properties. Additional header information can be optionally specified -- making it easy to clone NIfTI images if necessary, but with minor modifications.
+ * Most properties of NIfTI images are accessible via attributes and/or accessor functions of the NiftiImage. Inter-dependent properties are automatically updated if necessary (e.g. modifying the Q-Form matrix also updates the pixdim properties and quaternion representation).
+ * All properties are accessible via Python-style datatypes: A 4x4 matrix is an array not 16 individual numbers.
+ * PyNIfTI should be resonably fast. Image data will only be loaded into the memory if necessary. Simply opening a NIfTI file to access some header data is performed with virtually no delay independent of the size of the image. Unless image resizing or datatype conversion must be performed the image data can be shared by the NIfTI image and accessing NumPy arrays, and therefore memory won't be wasted memory with redundant copies of the image data. However, one should be careful to make a copy of the image data if you intend to resize and cast the image data (see the docstring of the NiftiImage.asarray() method).
+
+Scripts
++++++++
+
+Some functions provided by PyNIfTI also might be useful outside the Python environment. Therefore I plan to add some command line scripts to the package.
+Currently there is only one: pynifti_pst (pst: peristimulus timecourse). Using this script one can compute the signal timecourse for a certain condition for all voxels in a volume at once. This might be useful for exploring a dataset and accompanies similar tools like FSL's tsplot.
+
+The output of pynifti_pst can be loaded into FSLView to simultaneously look at statistics and signal timecourses. Please see the corresponding example below.
+
+Known issues aka bugs
++++++++++++++++++++++
+
+  * PyNIfTI currently ignores the origin field of ANALYZE files - it is neither read nor written. A possible workaround is to convert ANALYZE files into the NIfTI format using FSL's avwchfiletype.
+
+2. License
+----------
+
+PyNIfTI is written by Michael Hanke as free software (both beer and speech) and licensed under the GNU Lesser General Public License.
+
+3. Download
+-----------
+
+As PyNIfTI is still pretty young, a number of significant improvements/modifications are very likely to happen in the near future. If you discover any bugs or you are missing some features, please be sure to check the SVN repository (read below) if your problem is already solved.
+Source code
+
+Since June 2007 PyNIfTI is part of the niftilibs family. The PyNIfTI source code can be obtained from the Sourceforge project site.
+
+Source code is also available from the SVN repository of the Debian Experimental Psychology Project. To checkout the latest version use this command:
+
+svn co svn://svn.debian.org/svn/pkg-exppsy/pynifti/trunk pynifti-latest
+Binary packages
+
+Binary packages for some Debian and (K)Ubuntu versions are available. Please visit this page to read about how you have to setup your system to retrieve the PyNIfTI package via your package manager and stay in sync with future releases.
+
+4. Installation
+---------------
+
+Binary packages
++++++++++++++++
+
+If you have configured your system as described on this page all you have to do to install PyNIfTI is this::
+
+
+  apt-get update
+  apt-get install python-nifti
+
+This should pull all necessary dependencies.
+
+Compile from source
++++++++++++++++++++
+
+PyNIfTI needs a few things to build and run properly:
+
+ * Python 2.3 or greater
+ * NumPy
+ * SWIG
+ * NIfTI C libraries
+
+Make sure that the compiled nifticlibs and the corresponding headers are available to your compiler. If they are located in a custom directory, you might have to specify --include-dirs and --library-dirs options to the build command below.
+
+Once you have downloaded the sources, extract the tarball and enter the root directory of the extracted sources. A simple::
+
+  python setup.py build_ext
+
+should build the SWIG wrappers. If this has been done successfully, all you need to do is install the modules by invoking::
+
+  sudo python setup.py install
+
+If sudo is not configured (or even installed) you might have to use su instead.
+
+Now fire up Python and try importing the module to see if everything is fine. It should look similar to this::
+
+  Python 2.4.4 (#2, Oct 20 2006, 00:23:25)
+  [GCC 4.1.2 20061015 (prerelease) (Debian 4.1.1-16.1)] on linux2
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>> import nifti
+  >>>  
+
+MacOS X and MacPython
++++++++++++++++++++++
+
+When you are comiling PyNIfTI on MacOS X and want to use it with MacPython, please make sure that the NIfTI C libraries are compiled as fat binaries (compiled for both ppc and i386). Otherwise PyNIfTI extensions will not compile.
+
+One can achieve this by adding both architectures to the CFLAGS definition in the toplevel Makefile of the NIfTI C library source code. Like this::
+
+  CFLAGS = $(ANSI_FLAGS) -arch ppc -arch i386
+
+Troubleshooting
++++++++++++++++
+
+If you get an error when importing the nifti module in Python complaining about missing symbols your niftiio library contains references to some unresolved symbols. Try adding znzlib and zlib to the linker options the PyNIfTI setup.py, like this::
+
+  libraries = [ 'niftiio', 'znz', 'z' ],
+
+5. Things to know
+-----------------
+
+When accessing NIfTI image data through NumPy arrays the order of the dimensions is reversed. If the x, y, z, t dimensions of a NIfTI image are 64, 64, 32, 456 (as for example reported by nifti_tool), the shape of the NumPy array (e.g. as returned by NiftiImage.asarray()) will be: 456, 32, 64, 64.
+
+This is done to be able to slice the data array much easier in the most common cases. For example, if you are interested in a certain volume of a timeseries it is much easier to write data[2] instead of data[:,:,:,2], right?.
+
+6. Examples
+-----------
+
+The next sections contains some examples showing ways to use PyNIfTI to read and write imaging data from within Python to be able to process it with some random Python library.
+
+All examples assume that you have imported the PyNIfTI module by invoking::
+
+  from nifti import *
+
+a) Fileformat conversion
+++++++++++++++++++++++++
+
+Open the MNI standard space template that is shipped with FSL. No filename extension is necessary as libniftiio determines it automatically::
+
+  nim = NiftiImage('avg152T1_brain')
+
+The filename is available via the 'filename' attribute::
+
+  print nim.filename
+
+yields 'avg152T1_brain.img'. This indicates an ANALYZE image. If you want to save this image as a single gzipped NIfTI file simply do::
+
+  nim.save('mni.nii.gz')
+
+The filetype is determined from the filename. If you want to save to gzipped ANALYZE file pairs instead the following would be an alternative to calling the save() with a new filename::
+
+  nim.filename = 'mni_analyze.img.gz'
+  nim.save()
+
+Please see the docstring of the NiftiImage.setFilename() method to learn how the filetypes are determined from the filenames.
+
+b) NIfTI files from array data
+++++++++++++++++++++++++++++++
+
+The next code snipped demonstrates how to create a 4d NIfTI image containing gaussian noise. First we need to import the NumPy module::
+
+  import numpy
+
+Now generate the noise dataset. Let's generate noise for 100 volumes with 16 slices and a 32x32 inplane matrix::
+
+  noise = numpy.random.randn(100,16,32,32)
+
+Please notice the order in which the dimensions are specified: (t, z, y, x).
+
+The datatype of the array will most likely be float64 -- which can be verified by invoking noise.dtype.
+
+Converting this dataset into a NIfTI image is done by invoking the NiftiImage constructor with the noise dataset as argument::
+
+  nim = NiftiImage(noise)
+
+The relevant header information is extracted from the NumPy array. If you query the header information about the dimensionality of the image, it returns the desired values::
+
+  print nim.header['dim'] # yields: [4, 32, 32, 16, 100, 0, 0, 0]
+
+First value shows the number of dimensions in the datset: 4 (good, that's what we wanted). The following numbers are dataset size on the x, y, z, t, u, v, w axis (NIfTI files can handle up to 7 dimensions). Please notice, that the order of dimensions is now 'correct': We have 32x32 inplane resolution, 16 slices in z direction and 100 volumes.
+
+Also the datatype was set appropriately. The expression::
+
+  nim.header['datatype'] == nifticlib.NIFTI_TYPE_FLOAT64
+
+will evaluate to True.
+
+To save the noise file to disk, just call the save() method::
+
+  nim.save('noise.nii.gz')
+
+c) Select ROIs
+++++++++++++++
+
+Suppose you want to have the first ten volumes of the noise dataset we have just created in a separate file. First open the file (can be skipped if it is still open)::
+
+  nim = NiftiImage('noise.nii.gz')
+
+Now select the first ten volumes and store them to another file, while preserving as much header information as possible::
+
+  nim2 = NiftiImage(nim.data[:10], nim.header)
+  nim2.save('part.hdr.gz')
+
+The NiftiImage constructor takes a dictionary with header information as an optional argument. Settings that are not determined by the array (e.g. size, datatype) are copied from the dictionary and stored to the new NIfTI image.
+
+d) Linear detrending of timeseries
+++++++++++++++++++++++++++++++++++
+
+Let's load another 4d NIfTI file and perform a linear detrending, by fitting a straight line to the timeseries of each voxel and substract that fit from the data. Although this might sound complicated at first, thanks to the excellent SciPy module it is just a few lines of code::
+
+  nim = NiftiImage('timeseries.nii')
+
+Depending on the datatype of the input image the detrending process might change the datatype from integer to float. As operations that change the (binary) size of the NIfTI image are not supported, we need to make a copy of the data and later create a new NIfTI image::
+
+  data = nim.asarray()
+
+Now detrend the data along the time axis. Remember that the array has the time axis as its first dimension (in contrast to the NIfTI file where it is the 4th)::
+
+  from scipy import signal
+  data_detrended = signal.detrend( data, axis=0 )
+
+Finally, create a new NIfTI image using header information from the original source image::
+
+  nim_detrended = NiftiImage( data_detrended, nim.header)
+
+e) Make a quick plot of a voxels timeseries (Gnuplot module is required)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Plotting is essential to get a 'feeling' for the data. The python interface to Gnuplot makes it really easy to plot something (e.g. when running Python interactively via IPython). Please note, that there are many other possibilities for plotting. Some examples are: using R via RPy or Matlab-style plotting via matplotlib.
+
+However, using Gnuplot is really easy. First import the Gnuplot module and create the interface object::
+
+  from Gnuplot import Gnuplot
+  gp = Gnuplot()
+
+We want the timeseries as a line plot and not just the datapoints, so let's talk with Gnuplot::
+
+  gp('set data style lines')
+
+Now load a 4d NIfTI image::
+
+  nim = NiftiImage('perfect_subject.nii.gz')
+
+and finally plot the timeseries of voxel (x=20, y=30, z=12)::
+
+  gp.plot(nim.data[:,12,30,20])
+
+A Gnuplot window showing the timeseries should popup now (screenshot). Please read the Gnuplot Manual to learn what it can do -- and it can do a lot more than just simple line plots (have a look at this page if you are interested).
+f) Show a slice of a 3d volume (Matplotlib module is required)
+
+This example demonstrates howto use the Matlab-style plotting of Matplotlib to view a slice from a 3d volume.
+
+This time I assume that a 3d nifti file is already opened and available in the nim3d object. At first we need to load the necessary Python module::
+
+  from pylab import *
+
+If everything went fine, we can now view a slice (x,y)::
+
+  imshow(nim3d.data[200], interpolation='nearest', cmap=cm.gray)
+  show()
+
+It is necessary to call the show() function one time after importing pylab to actually see the image when running Python interactively (screenshot).
+
+When you want to have a look at a yz-slice, NumPy array magic comes into play::
+
+  imshow(nim3d.data[::-1,:,100], interpolation='nearest', cmap=cm.gray)
+
+The ::-1 notation causes the z-axis to be flipped in the images. This makes a much nicer screenshot, because the used example volume has the z-axis originally oriented upsidedown.
+
+g) Compute and display peristimulus signal timecourse of multiple conditions with pynifti_pst and FSLView
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Sometimes one wants to look at the signal timecourse of some voxel after a certain stimulation onset. An easy way would be to have some fMRI data viewer that displays a statistical map and one could click on some activated voxel and the peristimulus signal timecourse of some condition in that voxel would be displayed.
+
+This can easily be done by using pynifti_pst and FSLView.
+
+pynifti_pst comes with a manpage that explains all options and arguments. Basically pynifti_pst need a 4d image (e.g. an fMRI timeseries; possibly preprocessed/filtered) and some stimulus onset information. This information can either be given directly on the command line or is read from files. Additionally one can specify onsets as volume numbers or as onset times.
+
+pynifti_pst understands the FSL custom EV file format so one can easily use those files as input.
+
+An example call could look like this:
+
+pynifti_pst --times --nvols 5 -p uf92.feat/filtered_func_data.nii.gz pst_cond_a.nii.gz uf92.feat/custom_timing_files/ev1.txt uf92.feat/custom_timing_files/ev2.txt
+
+This computes a peristimulus timeseries using the preprocessed fMRI from a FEAT output directory and two custom EV files that both together make up condition A. --times indicates that the EV files list onset times (not volume ids) and --nvols requests the mean peristimulus timecourse for 4 volumes after stimulus onset (5 including onset). -p recodes the peristimulus timeseries into percent signalchange, where the onset is always zero and any following value is the signal change with respect to the onset volume.
+
+This call produces a simple 4d NIfTI image that can be loaded into FSLView as any other timeseries. The following call can be used to display an FSL zmap from the above results path on top of some anatomy. Additionally the peristimulus timeseries of two conditions are loaded. This screenshot shows how it could look like. One of the nice features of FSLView is that its timeseries window can remember selected curves, which can be useful to compare signal timecourses from different voxels (blue and green line in the screenshot).
+
+fslview pst_cond_a.nii.gz pst_cond_b.nii.gz uf92_ana.nii.gz uf92.feat/stats/zstat1.nii.gz -b 3,5
+
+History
+
+The full changelog is here.

Deleted: trunk/scipy/io/nifti/README.html
===================================================================
--- trunk/scipy/io/nifti/README.html	2007-10-04 00:12:15 UTC (rev 3398)
+++ trunk/scipy/io/nifti/README.html	2007-10-04 00:16:50 UTC (rev 3399)
@@ -1,391 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-
-<head>
-  <title>PyNIfTI - Python bindings to NIfTI</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-  <link rel="stylesheet" type="text/css" href="nifti.css" />
-</head>
-
-<body>
-
-<h1>PyNIfTI - Python-style access to NIfTI and ANALYZE files</h1>
-
-
-<h2>1. What is NIfTI and what do I need PyNIfTI for?</h2>
-
-<h3>NIfTI</h3>
-<p><a href="http://nifti.nimh.nih.gov">NIfTI</a> is a new Analyze-style data
-format, proposed by the
-<a href="http://nifti.nimh.nih.gov/dfwg/beyond-nifti-1">NIfTI Data Format Working Group</a>
-as a <em>"short-term measure to facilitate inter-operation of functional MRI data
-analysis software packages"</em>.</p>
-<p>Meanwhile a number of toolkits are NIfTI-aware (e.g. FSL, AFNI, SPM,
-Freesurfer and a to a certain degree also Brainvoyager).
-Additionally, <a href="http://cbi.nyu.edu/software/dinifti.php">dicomnifti</a>
-allows the direct conversion from DICOM images into the NIfTI format.</p>
-<p>With <a href="http://niftilib.sourceforge.net/niftilib_overview.html">libniftiio</a>
-there is a reference implementation of a C library to read, write and manipulate
-NIfTI images. The library source code is put into the public domain and a
-corresponding project is hosted at
-<a href="http://sourceforge.net/projects/niftilib">SourceForge</a>.</p>
-<p>In addition to the C library, there is also an IO library written in Java and
-Matlab functions to make use of NIfTI files from within Matlab.</p>
-
-
-<h3>Python</h3>
-<p>Unfortunately, it is not that trivial to read NIfTI images with Python. This is
-particularly sad, because there is a large number of easy-to-use, high-quality
-libraries for signal processing available for Python (e.g. SciPy).</p>
-<p>Moreover Python has bindings to almost any important language/program
-in the fields of maths, statistics and/or engineering. If you want to use
-<a href="http://www.r-project.org">R</a> to calculate
-some stats in a Python script, simply use <a href="http://rpy.sourceforge.net/">RPy</a>
-and pass any data to R. If you don't care about R, but Matlab is your one and
-only friend, there are at least two different Python modules to control Matlab
-from within Python scripts. Python is the glue between all those helpers and the Python user is
-able to combine as many tools as necessary to solve a given problem
--- the easiest way.</p>
-
-
-<h3>PyNIfTI</h3>
-<p>PyNIfTI aims to provide easy access to NIfTI images from within Python. It
-uses <a href="http://www.swig.org">SWIG</a>-generated wrappers for the NIfTI
-reference library and provides the <code>NiftiImage</code> class for
-Python-style access to the image data.</p>
-<p>While PyNIfTI is not yet complete (i.e. doesn't support everything the
-C library can do), it already provides access to the most
-important features of the NIfTI-1 data format and <em>libniftiio</em>
-capabilities. The following features are currently implemented:</p>
-<ul>
-
-<li>PyNIfTI can read and write any file format supported by libniftiio. This
-includes NIfTI (single and pairs) as well as ANALYZE files.</li>
-<li>PyNIfTI provides fast and convenient access to the image data via
-<a href="http://numpy.scipy.org">NumPy</a> arrays. This should enable users to
-process image data with most (if not all) numerical routines available for
-Python. The NumPy array automatically uses a datatype corresponding to the NIfTI image data -- no
-unnecessary upcasting is performed.</li>
-<li>PyNIfTI provides full read and write access to the NIfTI header data. Header information can
-be exported to a Python dictionary and can also be updated by using information
-from a dictionary.</li>
-<li>Instead of accessing NIfTI data from files, PyNIfTI is able to create NIfTI
-images from NumPy arrays. The appropriate NIfTI header information is determined
-from the array properties. Additional header information can be optionally
-specified -- making it easy to clone NIfTI images if necessary, but with minor
-modifications.</li>
-<li>Most properties of NIfTI images are accessible via attributes and/or accessor
-functions of the <code>NiftiImage</code>. Inter-dependent properties are
-automatically updated if necessary (e.g. modifying the Q-Form matrix also updates
-the pixdim properties and quaternion representation).</li>
-<li>All properties are accessible via Python-style datatypes: A 4x4 matrix is
-an array not 16 individual numbers.</li>
-<li>PyNIfTI should be resonably fast. Image data will only be loaded into the memory
-if necessary. Simply opening a NIfTI file to access some header data is
-performed with virtually no delay independent of the size of the image. Unless image
-resizing or datatype conversion must be performed the image data can be
-shared by the NIfTI image and accessing NumPy arrays, and therefore memory won't be wasted
-memory with redundant copies of the image data. However, one should be careful to make a
-copy of the image data if you intend to resize and cast the image data (see the
-docstring of the <code>NiftiImage.asarray()</code> method).</li>
-</ul>
-
-<h4>Scripts</h4>
-<p>Some functions provided by PyNIfTI also might be useful outside the Python
-environment. Therefore I plan to add some command line scripts to the package.</p>
-</p>Currently there is only one: <em>pynifti_pst</em> (pst: peristimulus
-timecourse). Using this script one can compute the signal timecourse for a
-certain condition for all voxels in a volume at once. This might be useful for
-exploring a dataset and accompanies similar tools like FSL's <em>tsplot</em>.</p>
-<p>The output of <em>pynifti_pst</em> can be loaded into FSLView to simultaneously
-look at statistics and signal timecourses. Please see the corresponding example below.</p>
-
-<h3>Known issues aka bugs</h3>
-<ul>
-  <li>PyNIfTI currently ignores the origin field of ANALYZE files - it is neither read
-  nor written. A possible workaround is to convert ANALYZE files into the NIfTI format
-  using FSL's <em>avwchfiletype</em>.</li>
-</ul>
-
-
-<h2>2. License</h2>
-<p>PyNIfTI is written by <a href="http://apsy.gse.uni-magdeburg.de/hanke">Michael Hanke</a>
-as free software (both beer and speech) and licensed under the
-<a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>.
-</p>
-
-
-<h2>3. Download</h2>
-<p>As PyNIfTI is still pretty young, a number of significant
-improvements/modifications are very likely to happen in the near future. If you
-discover any bugs or you are missing some features, please be sure to check the
-SVN repository (read below) if your problem is already solved.</p>
-
-</p>
-<h3>Source code</h3>
-<p>Since June 2007 PyNIfTI is part of the
-<a href="http://niftilib.sourceforge.net">niftilibs family</a>. The PyNIfTI
-source code can be obtained from the
-<a href="http://sourceforge.net/projects/niftilib">Sourceforge project site</a>.
-</p>
-
-<h3>Binary packages</h3>
-<h4>GNU/Linux</h4>
-<p>PyNIfTI is available in recent versions of the Debian (since lenny) and
-Ubuntu (since gutsy in universe) distributions. The name of the binary package
-is <em>python-nifti</em> in both cases.</p>
-<ul>
-<li><a href="http://packages.debian.org/python-nifti">PyNIfTI versions in Debian</a>
-<li><a href="http://packages.ubuntu.com/python-nifti">PyNIfTI versions in Ubuntu</a>
-</ul>
-<p>Binary packages for some additional Debian and (K)Ubuntu versions are also
-available. Please visit
-<a href="index.php?sec=1&page=hanke/debian&lang=en">this page</a> to read
-about how you have to setup your system to retrieve the PyNIfTI package via
-your package manager and stay in sync with future releases.</p>
-
-<h4>Windows</h4>
-<p>A binary installer for a recent Python version is available from the
-<a href="http://sourceforge.net/projects/niftilib">Sourceforge project site</a>.
-
-
-<h4>Macintosh</h4>
-<p>Unfortunately, no binary packages are available. I have no access to such
-a machine at the moment. But it is possible to build PyNIfTI from source on
-Mac OS X (see below for more information).</p>
-
-
-
-<h2>4. Installation</h2>
-
-<h3>Compile from source: General instructions</h3>
-<p>PyNIfTI needs a few things to build and run properly:</p>
-<ul>
-  <li><a href="http://www.python.org">Python</a> 2.4 or greater</li>
-  <li><a href="http://numpy.scipy.org">NumPy</a></li>
-  <li><a href="http://www.swig.org">SWIG</a></li>
-  <li><a href="http://niftilib.sourceforge.net">NIfTI C libraries</a></li>
-</ul>
-<p>Make sure that the compiled nifticlibs and the corresponding headers are
-available to your compiler. If they are located in a custom directory, you
-might have to specify <code>--include-dirs</code> and
-<code>--library-dirs</code> options to the build command below.</p>
-<p>Once you have downloaded the sources, extract the tarball and enter the root
-directory of the extracted sources. A simple</p>
-<p><code>python setup.py build_ext</code></p>
-<p>should build the SWIG wrappers. If this has been done
-successfully, all you need to do is install the modules by invoking</p>
-<p><code>sudo python setup.py install</code></p>
-<p>If sudo is not configured (or even installed) you might have to use
-<code>su</code> instead.</p>
-<p>Now fire up Python and try importing the module to see if everything is
-fine. It should look similar to this:</p>
-<pre>
-Python 2.4.4 (#2, Oct 20 2006, 00:23:25)
-[GCC 4.1.2 20061015 (prerelease) (Debian 4.1.1-16.1)] on linux2
-Type "help", "copyright", "credits" or "license" for more information.
->>> import nifti
->>> 
-</pre>
-<h4>Windows</h4>
-<p>It should be pretty straightforward to compile PyNIfTI for win32. The most
-convenient way seems to be using the
-<a href="http://www.bloodshed.net/devcpp.html">Dev-Cpp IDE</a>
-and the DevPak of the nifticlibs. Have a look into the toplevel Makefile of the
-PyNIfTI source distribution for some hints.</p>
-
-
-<h4>MacOS X and MacPython</h4>
-<p>When you are comiling PyNIfTI on MacOS X and want to use it with MacPython,
-please make sure that the NIfTI C libraries are compiled as fat binaries
-(compiled for both <em>ppc</em> and <em>i386</em>). Otherwise
-PyNIfTI extensions will not compile.</p>
-<p>One can achieve this by adding both architectures to the <code>CFLAGS</code>
-definition in the toplevel Makefile of the NIfTI C library source code. Like
-this</p>
-<p><code>CFLAGS = $(ANSI_FLAGS) -arch ppc -arch i386</code></p>
-
-
-<h3>Binary packages</h3>
-<h4>GNU/Linux</h4>
-<p>If you have configured your system as described on
-<a href="index.php?sec=1&page=hanke/debian&lang=en">this page</a> all you
-have to do to install PyNIfTI is this:</p>
-<p><code>apt-get update</code><br /><code>apt-get install python-nifti</code></p>
-<p>This should pull all necessary dependencies. If it doesn't, it's a bug that
-should be reported.</p>
-<h4>Windows</h4>
-<p>As always: click <em>Next</em> as long as necessary and finally <em>Finish</em>.
-
-<h4>Troubleshooting</h4>
-<p>If you get an error when importing the <em>nifti</em> module in Python
-complaining about missing symbols your niftiio library contains references to
-some unresolved symbols. Try adding <em>znzlib</em> and <em>zlib</em> to the
-linker options the PyNIfTI <code>setup.py</code>, like this:</p>
-
-<p><code>libraries = [ 'niftiio', 'znz', 'z' ],</code></p>
-
-<h2>5. Things to know</h2>
-<p>When accessing NIfTI image data through NumPy arrays the order of the
-dimensions is reversed. If the <em>x, y, z, t</em> dimensions of a NIfTI image
-are 64, 64, 32, 456 (as for example reported by <em>nifti_tool</em>), the shape
-of the NumPy array (e.g. as returned by <code>NiftiImage.asarray()</code>) will
-be: 456, 32, 64, 64.</p>
-<p>This is done to be able to slice the data array much easier in the most
-common cases. For example, if you are interested in a certain volume of a timeseries
-it is much easier to write <code>data[2]</code> instead of
-<code>data[:,:,:,2]</code>, right?.
-
-<h2>6. Examples</h2>
-<p>The next sections contains some examples showing ways to use PyNIfTI to
-read and write imaging data from within Python to be able to process it with
-some random Python library.</p>
-<p>All examples assume that you have imported the PyNIfTI module by invoking:</p>
-<p><code>from nifti import *</code></p>
-
-<h3>a) Fileformat conversion</h3>
-<p>Open the MNI standard space template that is shipped with FSL. No filename
-extension is necessary as libniftiio determines it automatically:</p>
-
-<p><code>nim = NiftiImage('avg152T1_brain')</code></p>
-
-<p>The filename is available via the 'filename' attribute:</p>
-<p><code>print nim.filename</code></p>
-<p>yields 'avg152T1_brain.img'. This indicates an ANALYZE image. If you want to
-save this image as a single gzipped NIfTI file simply do:</p>
-<p><code>nim.save('mni.nii.gz')</code></p>
-<p>The filetype is determined from the filename. If you want to save to gzipped
-ANALYZE file pairs instead the following would be an alternative to calling the
-<code>save()</code> with a new filename.</p>
-<p><code>nim.filename = 'mni_analyze.img.gz'<br />nim.save()</code></p>
-<p>Please see the docstring of the <code>NiftiImage.setFilename()</code> method
-to learn how the filetypes are determined from the filenames.</p>
-
-<h3>b) NIfTI files from array data</h3>
-<p>The next code snipped demonstrates how to create a 4d NIfTI image containing
-gaussian noise. First we need to import the NumPy module</p>
-<p><code>import numpy</code></p>
-<p>Now generate the noise dataset. Let's generate noise for 100 volumes with 16
-slices and a 32x32 inplane matrix.</p>
-<p><code>noise = numpy.random.randn(100,16,32,32)</code></p>
-<p>Please notice the order in which the dimensions are specified:
-(t, z, y, x).</p>
-<p>The datatype of the array will most likely be <em>float64</em> -- which can
-be verified by invoking <code>noise.dtype</code>.</p>
-<p>Converting this dataset into a NIfTI image is done by invoking the
-NiftiImage constructor with the noise dataset as argument:</p>
-<p><code>nim = NiftiImage(noise)</code></p>
-
-<p>The relevant header information is extracted from the NumPy array. If you
-query the header information about the dimensionality of the image, it returns
-the desired values:</p>
-<p><code>print nim.header['dim']  # yields: [4, 32, 32, 16, 100, 0, 0, 0]</code></p>
-First value shows the number of dimensions in the datset: 4 (good, that's what
-we wanted). The following numbers are dataset size on the x, y, z, t, u, v, w
-axis (NIfTI files can handle up to 7 dimensions). Please notice, that the order
-of dimensions is now 'correct': We have 32x32 inplane resolution, 16 slices in z
-direction and 100 volumes.</p>
-<p>Also the datatype was set appropriately. The exprression:</p>
-<p><code>nim.header['datatype'] == nifticlib.NIFTI_TYPE_FLOAT64</code></p>
-<p>will evaluate to <em>True</em>.</p>
-<p>To save the noise file to disk, just call the <code>save()</code> method:</p>
-<p><code>nim.save('noise.nii.gz')</code></p>
-
-
-<h3>c) Select ROIs</h3>
-<p>Suppose you want to have the first ten volumes of the noise dataset we have
-just created in a separate file. First open the file (can be skipped if it is
-still open):</p>
-<p><code>nim = NiftiImage('noise.nii.gz')</code></p>
-<p>Now select the first ten volumes and store them to another file, while
-preserving as much header information as possible:</p>
-<p><code>
-nim2 = NiftiImage(nim.data[:10], nim.header)<br />
-nim2.save('part.hdr.gz')
-</code></p>
-<p>The NiftiImage constructor takes a dictionary with header information as an
-optional argument. Settings that are not determined by the array (e.g. size,
-datatype) are copied from the dictionary and stored to the new NIfTI image.</p>
-
-
-<h3>d) Linear detrending of timeseries (SciPy module is required for this
-example)</h3>
-<p>Let's load another 4d NIfTI file and perform a linear detrending, by fitting
-a straight line to the timeseries of each voxel and substract that fit from the
-data. Although this might sound complicated at first, thanks to the excellent
-SciPy module it is just a few lines of code.</p>
-<p><code>nim = NiftiImage('timeseries.nii')</code></p>
-<p>Depending on the datatype of the input image the detrending process might
-change the datatype from integer to float. As operations that change the
-(binary) size of the NIfTI image are not supported, we need to make a copy
-of the data and later create a new NIfTI image.</p>
-<p><code>data = nim.asarray()</code></p>
-<p>Now detrend the data along the time axis. Remember that the array has the
-time axis as its first dimension (in contrast to the NIfTI file where it is
-the 4th).</p>
-<p><code>
-from scipy import signal<br />
-data_detrended = signal.detrend( data, axis=0 )</code></p>
-<p>Finally, create a new NIfTI image using header information from the original
-source image.</p>
-<p><code>nim_detrended = NiftiImage( data_detrended, nim.header)</code></p>
-
-<h3>e) Make a quick plot of a voxels timeseries (Gnuplot module is required)</h3>
-<p>Plotting is essential to get a 'feeling' for the data. The
-<a href="http://gnuplot-py.sourceforge.net">python interface</a>
-to <a href="http://www.gnuplot.info">Gnuplot</a> makes it really easy to plot
-something (e.g. when running Python
-interactively via <a href="http://ipython.scipy.org">IPython</a>). Please
-note, that there are many other possibilities for plotting. Some examples are:
-using <a href="http://www.r-project.org">R</a> via
-<a href="http://rpy.sourceforge.net">RPy</a> or Matlab-style plotting via
-<a href="http://matplotlib.sourceforge.net/">matplotlib</a>.</p>
-<p>However, using Gnuplot is really easy. First import the Gnuplot module
-and create the interface object.</p>
-<p><code>
-from Gnuplot import Gnuplot<br />
-gp = Gnuplot()</code></p>
-<p>We want the timeseries as a line plot and not just the datapoints, so
-let's talk with Gnuplot.</p>
-<p><code>gp('set data style lines')</code></p>
-<p>Now load a 4d NIfTI image</p>
-<p><code>nim = NiftiImage('perfect_subject.nii.gz')</code></p>
-<p>and finally plot the timeseries of voxel (x=20, y=30, z=12):</p>
-<p><code>gp.plot(nim.data[:,12,30,20])</code></p>
-<p>A Gnuplot window showing the timeseries should popup now (<a href="http://apsy.gse.uni-magdeburg.de/main/pics/hanke/pynifti/gnuplot_ts.png">screenshot</a>). Please read the
-Gnuplot Manual to learn what it can do -- and it can do a lot more than just
-simple line plots (have a look at <a href="http://gnuplot.sourceforge.net/demo_4.3/index.html">this</a>
-page if you are interested).</p>
-
-<h3>f) Show a slice of a 3d volume (Matplotlib module is required)</h3>
-<p>This example demonstrates howto use the Matlab-style plotting of <a href="matplotlib.sourceforge.net">Matplotlib</a> to view a slice from a 3d volume.</p>
-<p>This time I assume that a 3d nifti file is already opened and available in the <code>nim3d</code> object. At first we need to load the necessary Python module.</p>
-<p><code>from pylab import *</code></p>
-<p>If everything went fine, we can now view a slice (x,y):</p>
-<p><code>imshow(nim3d.data[200], interpolation='nearest', cmap=cm.gray)<br />
-show()</code></p>
-<p>It is necessary to call the <code>show()</code> function one time after importing pylab to actually see the image when running Python interactively (<a href="http://apsy.gse.uni-magdeburg.de/main/pics/hanke/pynifti/matplotlib_xyslice.png">screenshot</a>).</p><p>When you want to have a look at a yz-slice, NumPy array magic comes into play.</p>
-<p><code>imshow(nim3d.data[::-1,:,100], interpolation='nearest', cmap=cm.gray)</code></p>
-<p>The <code>::-1</code> notation causes the z-axis to be flipped in the images. This makes a much nicer <a href="http://apsy.gse.uni-magdeburg.de/main/pics/hanke/pynifti/matplotlib_yzslice.png">screenshot</a>, because the used example volume has the z-axis originally oriented upsidedown.</p>
-
-<h3>g) Compute and display peristimulus signal timecourse of multiple conditions with <em>pynifti_pst</em> and <em>FSLView</em></h3>
-<p>Sometimes one wants to look at the signal timecourse of some voxel after a certain stimulation onset. An easy way would be to have some fMRI data viewer that displays a statistical map and one could click on some activated voxel and the peristimulus signal timecourse of some condition in that voxel would be displayed.</p>
-<p>This can easily be done by using <em>pynifti_pst</em> and <em>FSLView</em>.</p>
-<p><em>pynifti_pst</em> comes with a manpage that explains all options and arguments. Basically <em>pynifti_pst</em> need a 4d image (e.g. an fMRI timeseries; possibly preprocessed/filtered) and some stimulus onset information. This information can either be given directly on the command line or is read from files. Additionally one can specify onsets as volume numbers or as onset times.</p>
-<p><em>pynifti_pst</em> understands the FSL custom EV file format so one can easily use those files as input.</p>
-<p>An example call could look like this:</p>
-<p><code>pynifti_pst --times --nvols 5 -p uf92.feat/filtered_func_data.nii.gz pst_cond_a.nii.gz uf92.feat/custom_timing_files/ev1.txt uf92.feat/custom_timing_files/ev2.txt</code></p>
-<p>This computes a peristimulus timeseries using the preprocessed fMRI from a FEAT output directory
-and two custom EV files that both together make up condition A. <code>--times</code> indicates that
-the EV files list onset times (not volume ids) and <code>--nvols</code> requests the mean peristimulus
-timecourse for 4 volumes after stimulus onset (5 including onset). <code>-p</code> recodes the
-peristimulus timeseries into percent signalchange, where the onset is always zero and any following
-value is the signal change with respect to the onset volume.</p>
-<p>This call produces a simple 4d NIfTI image that can be loaded into FSLView as any other timeseries. The following call can be used to display an FSL zmap from the above results path on top of some anatomy. Additionally the peristimulus timeseries of two conditions are loaded. <a href="http://apsy.gse.uni-magdeburg.de/main/pics/hanke/pynifti/fslview_pst.png">This screenshot</a> shows how it could look like. One of the nice features of FSLView is that its timeseries window can remember selected curves, which can be useful to compare signal timecourses from different voxels (blue and green line in the screenshot).</p>
-<p><code>fslview pst_cond_a.nii.gz pst_cond_b.nii.gz uf92_ana.nii.gz uf92.feat/stats/zstat1.nii.gz -b 3,5</code></p>
-
-<h2>History</h2>
-<p>The full changelog is <a href="Changelog">here</a>.</p>
-</body>
-</html>


