Merge remote-tracking branch 'upstream/master' into enh/cifti2

* upstream/master:
  Update parrec.py
  NF: add routine to read zero-terminal strings
  DOC: more typos in BV format doc
  DOC: more small edits to PAR / REC docstrings
  DOC: fixes to bv_formats links, text
  DOC: fix link to VTC format
  DOC: small fixes to parrec docstring
  DOC: start of document on BrainVoyager formats
  MAINT: some git / .gitignore housekeeping
  Simplify idioms, delete unnecessary 'global' definition.
  Change idioms for selecting the 2nd output arg.
  Fix for #324 - use consistent syntax for have_scipy.
  DOC: more ReST markup edits to get_data docstring
  DOC: fix ReST markup error in get_data docstring
  BUG: work round int overflow in size calculation
  RF: allow extensions to be passed to `exts2pars`
  ENH: reading PAR headers from NIfTI extensions

Author: satra

.gitignore

@@ -15,9 +15,12 @@
 *.tmp
 .project
 .pydevproject
+*.py.orig
 
-# Not sure what the next two are for
+# Not sure what the next one is for
 *.kpf
+
+# Makefile target file markers
 *-stamp
 
 # Compiled source #
@@ -58,6 +61,7 @@ dist/
 .shelf
 .tox/
 .coverage
+.ropeproject/
 
 # Logs and databases #
 ######################

Makefile

@@ -284,5 +284,8 @@ tox-stale:
 refresh-readme:
 	$(PYTHON) tools/refresh_readme.py
 
-.PHONY: orig-src pylint
+rm-orig:
+	# Remove .orig temporary diff files generated by git
+	find . -name "*.orig" -print | grep -v "fsaverage" | xargs rm
 
+.PHONY: orig-src pylint

doc/source/devel/bv_formats.rst

@@ -0,0 +1,98 @@
+#########################
+BrainVoyager file formats
+#########################
+
+With notes on nibabel support.
+
+PR for some BrainVoyager support at https://github.com/nipy/nibabel/pull/216.
+
+********
+Overview
+********
+
+See :
+
+* All files are little-endian byte order regardless of byte-order on the
+  machine writing the data;
+* BV apparently provides a "BVQXtools" library for reading writing BV files in
+  MATLAB;
+
+.. _bv-internal-axes:
+
+***********************
+BV internal format axes
+***********************
+
+BV files have a internal format that has axes named `X`, `Y` and `Z`.  Quoting
+from the `VMR format definition`_::
+
+    BV X front -> back = Y in Tal space
+    BV Y top -> bottom = Z in Tal space
+    BV Z left -> right = X in Tal space
+
+Put another way |--| the correspondence of BV XYZ to Talairach axes is:
+
+* BV X -> Anterior to Posterior;
+* BV Y -> Superior to Inferior;
+* BV Z -> Left to Right.
+
+or:
+
+* BV X -> Talairach -Y;
+* BV Y -> Talairach -Z;
+* BV Z -> Talairach  X;
+
+Nice!
+
+*****************
+Types of BV files
+*****************
+
+There appear to be 38 BV file types at the time of writing of which 18 appear
+to have a page of description on the `BV file format index page`_.
+
+Here are some examples of BV formats:
+
+* FMR |--| "FMR project files are simple text files containing the information
+  defining a functional project created from raw MRI data".  This text file
+  contains meta-data about the functional time course data, stored in one or
+  more STC files.  See the `FMR format definition`_.
+* STC |--| "A STC file (STC = "slice time course") contains the functional
+  data (time series) of a FMR project."  The time-course data of a 4D
+  ("single-slice") format STC file are stored on disk in
+  fastest-to-slowest-changing order: columns, rows, time, slice.  STC files
+  can also contain the data for one single slice ("multi-slice format"), in
+  which case the data are in fast-to-slow order: columns, rows, time.  This is
+  a raw data file where the relevant meta-data such as image size come from an
+  associated FMR format file. See `STC format definition`_;
+* VTC |--| "A VTC file contains the functional data (time series) of one
+  experimental run (one functional scan) in the space of a 3D anatomical data
+  set (VMR), e.g. in Talairach space.".  See `VTC format definition`_;
+  This is a different format to the STC (raw data in native-space) format.
+  The file is a header followed by ints or floats in
+  fastest-to-slowest-changing order of: time; BV X; BV Y; BV Z; where BV X, BV
+  Y, BV Z refer to the :ref:`bv-internal-axes`, and therefore Talairach -Y,
+  -Z, X.
+* NR-VMP |--| "A native resolution volume map (NR-VMP) file contains
+  statistical results in 3D format.". See `NR-VMP format definition`_
+* AR-VMP |--| "An anatomical-resolution VMP (volume map) file contains
+  statistical results in 3D format" at anatomical scan resolution.  See
+  `AR-VMP format definition`_;
+* VMR |--| 'high-resolution anatomical MR' - see `VMR format definition`_.
+* MSK |--| mask file.  Only documentation appears to be
+  http://www.brainvoyager.com/ubb/Forum8/HTML/000087.html
+* SMP |--| 'surface map'.  See `SMP format definition`_. Contains one or more
+  "maps", where a map is a ``NrOfVertices`` (number of vertices) length vector
+  of float64 values.
+
+.. _BV file format index page: http://support.brainvoyager.com/automation-aamp-development/23-file-formats.html
+.. _AR-VMP format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/376-users-guide-23-the-format-of-ar-vmp-files.html
+.. _NR-VMP format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/377-users-guide-23-the-format-of-nr-vmp-files.html
+.. _VTC format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/379-users-guide-23-the-format-of-vtc-files.html
+.. _BV file format overview: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/382-developer-guide-26-file-formats-overview.html
+.. _FMR format definition: http://support.brainvoyager.com/installation-introduction/23-file-formats/383-developer-guide-26-the-format-of-fmr-files.html
+.. _STC format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/384-developer-guide-26-the-format-of-stc-files.html
+.. _vmr format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/385-developer-guide-26-the-format-of-vmr-files.html
+.. _SMP format definition: : http://support.brainvoyager.com/automation-aamp-development/23-file-formats/476-the-format-of-smp-files.html
+
+.. include:: ../links_names.txt

doc/source/notebooks/.gitignore

@@ -0,0 +1 @@
+.ipynb_checkpoints/

nibabel/fileutils.py

@@ -0,0 +1,62 @@
+# emacs: -*- mode: python-mode; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+# ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
+#
+#   See COPYING file distributed along with the NiBabel package for the
+#   copyright and license terms.
+#
+# ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
+""" Utilities for reading and writing to binary file formats
+"""
+
+def read_zt_byte_strings(fobj, n_strings=1, bufsize=1024):
+    """Read zero-terminated byte strings from a file object `fobj`
+
+    Returns byte strings with terminal zero stripped.
+
+    Found strings can be of any length.
+
+    The file position of `fobj` on exit will be at the byte after the terminal
+    0 of the final read byte string.
+
+    Parameters
+    ----------
+    f : fileobj
+        File object to use.  Should implement ``read``, returning byte objects
+        (str in Python 2), and ``seek(n, 1)`` to seek from current file
+        position.
+    n_strings : int, optional
+        Number of byte strings to return
+    bufsize: int, optional
+       Define chunk size to load from file while searching for zero terminals.
+       We load this many bytes at a time from the file, but the returned
+       strings can be longer than `bufsize`.
+
+    Returns
+    -------
+    byte_strings : list
+        List of byte strings, where strings do not include the terminal 0
+    """
+    byte_strings = []
+    trailing = b''
+    while True:
+        buf = fobj.read(bufsize)
+        eof = len(buf) < bufsize  # end of file
+        zt_strings = buf.split(b'\x00')
+        if len(zt_strings) > 1:  # At least one 0
+            byte_strings += [trailing + zt_strings[0]] + zt_strings[1:-1]
+            trailing = zt_strings[-1]
+        else:  # No 0
+            trailing += zt_strings[0]
+        n_found = len(byte_strings)
+        if eof or n_found >= n_strings:
+            break
+    if n_found < n_strings:
+        raise ValueError('Expected {0} strings, found {1}'.format(
+            n_strings, n_found))
+    n_extra = n_found - n_strings
+    leftover_strings = byte_strings[n_strings:] + [trailing]
+    # Add number of extra strings to account for lost terminal 0s
+    extra_bytes = sum(len(bs) for bs in leftover_strings) + n_extra
+    fobj.seek(-extra_bytes, 1)  # seek back from current position
+    return byte_strings[:n_strings]

nibabel/imageclasses.py

@@ -15,14 +15,9 @@
 from .freesurfer import MGHImage
 from .parrec import PARRECImage
 from .volumeutils import Recoder
+from .optpkg import optional_package
+_, have_scipy, _ = optional_package('scipy')
 
-# If we don't have scipy, then we cannot write SPM format files
-try:
-    import scipy.io
-except ImportError:
-    have_scipy = False
-else:
-    have_scipy = True
 
 # mapping of names to classes and class functionality