1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
=============================
Volumetrique data structures
=============================
Volumetric data structures expose numerical values embedded in a world
space. For instance, a volume could expose the T1 intensity, as acquired
in scanner space, or the BOLD signal in MNI152 template space. The values
can be multi-dimensional, in the case of a BOLD signal, the fMRI signal
would correspond to a time series at each position in world space.
.. currentmodule:: nipy.neurospin.datasets.volumes.volume_img
The image structure: :class:`VolumeImg`
=======================================
The structure most often used in neuroimaging is the :class:`VolumeImg`.
It corresponds, for instance, to the structure used in the Nifti files.
This structure stores data as an n-dimensional array, with n being at
least 3, alongside with the necessary information to map it to world
space.
:definition:
A volume-image (class: :class:`VolumeImg`) is a volumetric datastructure
given by data points lying on a regular grid: this structure is a
generalization of an image in 3D. The voxels, vertices of the grid, are
mapped to coordinnates by an affine transformation. As a result, the grid
is regular and evenly-spaced, but may not be orthogonal, and the spacing
may differ in the 3 directions.
.. image:: datasets/volume_img.jpg
The data is exposed in a multi dimensional array, with the 3 first axis
corresponding to spatial directions. A complete description of this
object can be found on the page: :class:`VolumeImg`.
Useful methods on volume structures
====================================
.. currentmodule:: nipy.neurospin.datasets.volumes.volume_field
Any general volume structures will implement methods for querying the
values and changing world space (see the :class:`VolumeField`
documentation for more details):
.. autosummary::
:toctree: generated
VolumeField.values_in_world
VolumeField.composed_with_transform
Also, as volumes structure may describe the spatial data in various way,
you can easily to convert to a :class:`VolumeImg`, ie a regular grid, for
instance to do implement an algorithm on the grid such as spatial
smoothing:
.. autosummary::
:toctree: generated
VolumeField.as_volume_img
Finally, different structures can embed the data differently in the same
world space, for instance with different resolution. You can resample one
structure on another using:
.. autosummary::
:toctree: generated
VolumeField.resampled_to_img
**FIXME:** Examples would be good here, but first we need io and template
data to be wired with datasets.
More general data structures
===============================
.. currentmodule:: nipy.neurospin.datasets.volumes.volume_img
The :class:`VolumeImg` is the most commonly found volume structure, and
the simplest to understand, however, volumetric data can be described in
more generic terms, and for performance reason it might be interesting to
use other objects.
Here, we give a list of the nipy volumetric data structures, from most
specific, to most general. When you deal with volume structures in your
algorithms, depending on which volume structure class you are taking as
an input, you can assume different properties of the data. You can always
use :meth:`VolumeImg.as_volume_img` to cast the volume structure in a
:class:`VolumeImg` that is simple to understand and easy to work with,
but it may not be necessary.
Implemented classes
--------------------
Implemented classes (or `concrete` classes) are structures that you can
readily use directly from nipy.
.. currentmodule:: nipy.neurospin.datasets.volumes.volume_grid
:class:`VolumeGrid`
In a :class:`VolumeGrid`, the data points are sampled on a 3D grid, but
unlike for a :class:`VolumeImg`, grid may not be regular. For instance,
it can be a grid that has been warped by a non-affine transformation.
Like with the :class:`VolumeImg`, the data is exposed in a multi
dimensional array, with the 3 first axis corresponding to spatial
directions.
.. image:: datasets/volume_grid.jpg
Abstract classes
------------------
.. currentmodule:: nipy.neurospin.datasets.volumes.volume_data
Abstract classes cannot be used because they are incompletely
implemented. They serve as to define the interface: the type of objects
that you can use, or how you can extend nipy by exposing the same
set of methods and attributes (the `interface`).
:class:`VolumeData`
In this volumetric structure, the data is sampled for some points in
the world space. The object knows how to interpolate between these
points. The underlying values are stored in a multidimensional array-like
object that can be indexed and sliced.
.. image:: datasets/volume_data.jpg
This is an abstract base class: it defines an interface, but is not
fully functional, and can be used only via its children class (such as
:class:`VolumeGrid` or :class:`VolumeImg`).
.. currentmodule:: nipy.neurospin.datasets.volumes.volume_field
:class:`VolumeField`
This is the most general volumetric structure (base class): all the
nipy volume expose this interface. This structure does not make any
assumptions on how the values are internal represented, they may, for
instance, be represented as a function, rather than as data points, or
as a data structure that is not an array, such as a graph.
.. image:: datasets/volume_field.jpg
This is also an abstract base class: it defines the core nipy
volumetric data structure interface: you can rely on all the methods
documented for this class in any nipy data structure.
|
