Updated BIAPs

Author: matthew-brett

doc/source/devel/biaps/biap_0000.rst

@@ -1,4 +1,4 @@
-.. _BIAP0:
+.. _biap0:
 
 ============================
 BIAP 0 — Purpose and Process

doc/source/devel/biaps/biap_0001.rst

@@ -5,6 +5,7 @@ BIAP1 - towards immutable images
 :Author: Matthew Brett
 :Status: Rejected
 :Type: Standards
+:Created: 2011-03-23
 
 **********
 Resolution

doc/source/devel/biaps/biap_0002.rst

@@ -2,11 +2,16 @@
 BIAP2 : Slicecopy
 #################
 
+:Author: Matthew Brett
+:Status: Rejected
+:Type: Standards
+:Created: 2011-03-26
+
 ******
 Status
 ******
 
-Implemented as of Nibabel 2.0 with image proxy slicing : see
+Alternative implementation as of Nibabel 2.0 with image proxy slicing : see
 http://nipy.org/nibabel/images_and_memory.html#saving-time-and-memory
 
 **********
@@ -30,8 +35,8 @@ Questions
 Should ``slice0`` be a copy or a view?
 --------------------------------------
 
-As from the previous discussion - [[BIAP1]] - an image may be a proxy or an
-array.
+As from the previous discussion - :doc:`biap_0001` - an image may be a proxy
+or an array.
 
 If the image is an array, the most natural thing to return is a view.  That is,
 modifying ``slice0`` will modify the underlying array in ``img``.
@@ -46,18 +51,18 @@ What slices should the slicing allow?
 
 The ``img.get_slice(0)`` syntax needs us to know what slice 0 is.  In a nifti
 image of 3 dimensions, the first is fastest changing on disk.  To be useful
-``0`` will probably refer to the slowest changing on disk.  Otherwise we'll have
-to load nearly the whole image anyway.  So, for a nifti, 0 should be the first
-slice in the last dimension.
+``0`` will probably refer to the slowest changing on disk.  Otherwise we'll
+have to load nearly the whole image anyway.  So, for a nifti, 0 should be the
+first slice in the last dimension.
 
-For Minc on the other hand, you can and I (MB) think always do get C ordered arrays
-back, so that the slowest changing dimension in the image array is the first.
-Actually, I don't know how to read a minc file slice by slice, but the general
-point is that, to know which slice is worth reading, you need to know the
-relationship of the image array dimensions to fastest / slowest on disk.
+For Minc on the other hand, you can and I (MB) think always do get C ordered
+arrays back, so that the slowest changing dimension in the image array is the
+first. Actually, I don't know how to read a Minc file slice by slice, but the
+general point is that, to know which slice is worth reading, you need to know
+the relationship of the image array dimensions to fastest / slowest on disk.
 
 We could always solve this by assuming that we always want to do this for
-analyze / nifti1 files (Fortran ordered).  It's a little ugly of course.
+Analyze / Nifti1 files (Fortran ordered).  It's a little ugly of course.
 
 Note that taking the slowest changing slice in a nifti image would be the
 equivalent of taking a slice from the last dimension::
@@ -84,14 +89,18 @@ arrays.
 Option 1: fancy slice object
 ============================
 
-It's option 1 because it's the first one I thought of::
+It's option 1 because it's the first one I thought of:
+
+.. code:: python
 
     slice0 = img.slicecopy[...,0]
 
 Here we solve the copy or view problem with 'always copy'.   We solve the 'what
 slicing to allow' by letting the object decide how to do the slicing.  We could
 obviously just do the full load (deproxy the image) and return a copy of the
-sliced array, as in::
+sliced array, as in:
+
+.. code:: python
 
     class SomeImage(object):
         class Slicer(object):
@@ -106,38 +115,46 @@ sliced array, as in::
         def __init__(self, stuff):
             self.slicecopy = Slicer(self)
 
-The problem with this is that::
+The problem with this is that:
+
+.. code:: python
 
     slice0 = img.slicecopy[...,1]
 
-might unproxy the image.  At the moment, it's rather hidden whether the image is
-proxied or not on the basis that it's an optimization that should be
+might unproxy the image.  At the moment, it's rather hidden whether the image
+is proxied or not on the basis that it's an optimization that should be
 transparent.
 
 Option 2: not-fancy method call
 ===============================
 
-::
+.. code:: python
 
     slice0 = img.get_slice(0, copy=True)
 
 'slice or view' solved with explicit keyword.  'which slice' solved by assuming
-you always mean one slice in the last dimension.  Or we could also allow::
+you always mean one slice in the last dimension.  Or we could also allow:
+
+.. code:: python
 
     slices = img.get_slices(slice(0,3), copy=True)
 
-This is ugly, but fairly clear. This simple 'I mean the last dimension' might be
-annoying because it assumes the last dimension is the slowest changing, and it
-does not get to optimize the more complex contiguous cases above.  So we could
-even allow full slicing with stuff like::
+This is ugly, but fairly clear. This simple 'I mean the last dimension' might
+be annoying because it assumes the last dimension is the slowest changing, and
+it does not get to optimize the more complex contiguous cases above.  So we
+could even allow full slicing with stuff like:
+
+.. code:: python
 
     slice = img.get_slices((slice(None), slice(None), slice(3)), copy=True)
 
 Again - this looks a lot more ugly than the ``slicecopy`` syntax above.
 
 Now, when would you choose ``copy=True``?  I think, when the image is a proxy.
 Otherwise you'd want a view.  Probably.  So what you mean, probably, is
-something like this::
+something like this:
+
+.. code:: python
 
     slices = img.get_slices(slicedef, copy_if='is_proxy')
 

doc/source/devel/biaps/biap_0003.rst

@@ -2,11 +2,17 @@
 BIAP3 - a JSON nifti header extension
 #####################################
 
-******
-Status
-******
+:Author: Matthew Brett, Bob Dougherty
+:Status: Draft
+:Type: Standards
+:Created: 2011-03-26
 
-Ongoing
+The following Wiki documents should be merged with this one:
+
+* `JSON header extension
+  <https://github.com/nipy/nibabel/wiki/json-header-extension>`_.
+* `NIfTI metadata extension
+  <https://github.com/nipy/nibabel/wiki/NIfTI-metadata-extension>`_
 
 **********
 Background

doc/source/devel/biaps/biap_0004.rst

@@ -2,6 +2,11 @@
 BIAP4 - merging nibabel and dcmstack
 ####################################
 
+:Author: Brendan Moloney, Matthew Brett
+:Status: Draft
+:Type: Standards
+:Created: 2012-11-21
+
 In which we set out what dcmstack_ does and how it might integrate with the
 nibabel objects and functions.
 
@@ -14,10 +19,11 @@ Nifti, before doing any image processing. The Nifti format is significantly
 easier to work with and has wide spread compatibility. However, the vast 
 amount of meta data stored in the source DICOM files will be lost.
 
-After implementing this proposal, users will be able to preserve all of the meta 
-data from the DICOM files during conversion, including meta data from private 
-elements. The meta data will then be easily accessible through the `SpatialImage`
-API::
+After implementing this proposal, users will be able to preserve all of the
+meta data from the DICOM files during conversion, including meta data from
+private elements. The meta data will then be easily accessible through the
+`SpatialImage` API::
+
     >>> nii = nb.load('input.nii')
     >>> data = nii.get_data()
     >>> print data.shape

doc/source/devel/biaps/biap_0005.rst

@@ -2,6 +2,11 @@
 BIAP5 - a streamlines converter
 ###############################
 
+:Author: Marc-Alexandre Côté
+:Status: Draft
+:Type: Standards
+:Created: 2013-09-03
+
 The first objective of this proposal is to add support to other streamlines
 format. The second objective is to be able to easily convert from one file
 format to another.

doc/source/devel/biaps/biap_0006.rst

@@ -2,11 +2,10 @@
 BIAP6 - identifying image axes
 ##############################
 
-******
-Status
-******
-
-Ongoing
+:Author: Matthew Brett
+:Status: Draft
+:Type: Standards
+:Created: 2015-07-11
 
 **********
 Background
@@ -16,13 +15,17 @@ Image axes can have meaningful labels.
 
 For example in a typical 4D NIfTI file, as we move along the 4th dimension in
 the image array, we are also moving in time.  For example, this would be the
-first volume (in time)::
+first volume (in time):
+
+.. code:: python
 
     img = nibabel.load('my_4d.nii')
     data = img.get_data()
     vol0 = data[..., 0]
 
-and this would be second volume in time::
+and this would be second volume in time:
+
+.. code:: python
 
     vol1 = data[..., 1]
 
@@ -36,7 +39,9 @@ dimension.
 
 It is common to acquire MRI images one slice at a time.  In a 3D or 4D NIfTI,
 the 3rd axis often contains these slices.  So this these would be the first
-and second slices of data collected by the scanner::
+and second slices of data collected by the scanner:
+
+.. code:: python
 
     slice0 = vol0[:, :, 0]
     slice1 = vol0[:, :, 1]
@@ -84,7 +89,9 @@ length > 1.  Quoting from the standard::
 
 This arrangement happens in practice.  For example, SPM deformation fields
 have three values for each voxel (x, y, z displacement), and have shape (I, J,
-K, 1, 3)::
+K, 1, 3):
+
+.. code:: python
 
     In [7]: img = nib.load('y_highres001.nii')
     In [8]: img.shape

doc/source/devel/biaps/biap_0007.rst

@@ -2,11 +2,10 @@
 BIAP7 - loading multiple images
 ###############################
 
-******
-Status
-******
-
-In discussion
+:Author: Matthew Brett
+:Status: Draft
+:Type: Standards
+:Created: 2015-07-18
 
 **********
 Background
@@ -112,4 +111,4 @@ Next steps:
 * Make sure there are use-cases where you could wish to call `load` vs. `load_multi` on the same image (perhaps a Nifti image with different affines for each volume)
 * Investigate AFNI file formats as a use-case for this.
 * Check the `nilearn` codebase, see if `iter_img` and `slice_img` functions might offer a post-`load` alternative. Also check if those functions could be deprecated in favor of slicing / iterating on `dataobj`
-* Create a new issue to implement getting an iterator on `dataobj`?
+* Create a new issue to implement getting an iterator on `dataobj`?

doc/source/devel/biaps/biap_0008.rst

@@ -2,9 +2,10 @@
 BIAP8 - always load image data as floating point
 ################################################
 
-******
-Status
-******
+:Author: Matthew Brett
+:Status: Accepted
+:Type: Standards
+:Created: 2018-04-18
 
 ``get_fdata`` shipped as of nibabel 2.2.0.
 
@@ -29,7 +30,9 @@ the image data after loading into memory.
 In detail
 =========
 
-At the moment, if you do this::
+At the moment, if you do this:
+
+.. code:: python
 
     img = nib.load('my_image.nii')
     data = img.get_data()
@@ -43,7 +46,9 @@ data type - here ``np.int16``.
 This is very efficient in terms of memory, but it can be a real trap unless
 you are careful.
 
-For example, let's say you had a pipeline where you did this::
+For example, let's say you had a pipeline where you did this:
+
+.. code:: python
 
     sum = img.get_data().sum()
 
@@ -57,7 +62,9 @@ image arrays to floating point to get sensible answers.
 Current implementation
 ======================
 
-``get_data`` has the following implementation, at time of writing::
+``get_data`` has the following implementation, at time of writing:
+
+.. code:: python
 
     def get_data(self):
         """ Return image data from image with any necessary scalng applied
@@ -90,7 +97,9 @@ The future default behavior of nibabel should be to do the thing least likely
 to trip you up by accident.  But - we do not want the result of ``get_data``
 to change silently between nibabel versions.
 
-* step 1: now - add ``get_fdata`` method::
+* step 1: now - add ``get_fdata`` method:
+
+.. code:: python
 
     def get_fdata(self, dtype=np.float64):
         """ Return floating point image data with necessary scalng applied.