NIPY logo

Site Navigation

NIPY Community

Table Of Contents

This Page

core.reference.coordinate_system

Module: core.reference.coordinate_system

Inheritance diagram for nipy.core.reference.coordinate_system:

CoordinateSystems are used to represent the space in which the image resides.

A CoordinateSystem contains named coordinates, one for each dimension and a coordinate dtype. The purpose of the CoordinateSystem is to specify the name and order of the coordinate axes for a particular space. This allows one to compare two CoordinateSystems to determine if they are equal.

Classes

CoordinateSystem

class nipy.core.reference.coordinate_system.CoordinateSystem(coord_names, name='', coord_dtype=<type 'float'>)

Bases: object

An ordered sequence of named coordinates of a specified dtype.

A coordinate system is defined by the names of the coordinates, (attribute coord_names) and the numpy dtype of each coordinate value (attribute coord_dtype). The coordinate system can also have a name.

>>> names = ['first', 'second', 'third']
>>> cs = CoordinateSystem(names, 'a coordinate system', np.float)
>>> cs.coord_names
('first', 'second', 'third')
>>> cs.name
'a coordinate system'
>>> cs.coord_dtype
dtype('float64')

The coordinate system also has a dtype which is the composite numpy dtype, made from the (names, coord_dtype).

>>> dtype_template = [(name, np.float) for name in cs.coord_names]
>>> dtype_should_be = np.dtype(dtype_template)
>>> cs.dtype == dtype_should_be
True

Two CoordinateSystems are equal if they have the same dtype and the same name. The CoordinateSystem names may be different.

XXX This is changed now: the “name” indicates the origin

>>> another_cs = CoordinateSystem(names, 'not irrelevant', np.float)
>>> cs == another_cs
False
>>> cs.dtype == another_cs.dtype
True
>>> cs.name == another_cs.name
False

Methods

coord_dtype
index
__init__(coord_names, name='', coord_dtype=<type 'float'>)

Create a coordinate system with a given name and coordinate names.

The CoordinateSystem has two dtype attributes:

  1. self.coord_dtype is the dtype of the individual coordinate values
  2. self.dtype is the recarray dtype for the CoordinateSystem which combines the coord_names and the coord_dtype. This functions as the description of the CoordinateSystem.
Parameters :

coord_names : iterable

A sequence of coordinate names.

name : string, optional

The name of the coordinate system

coord_dtype : np.dtype, optional

The dtype of the coord_names. This should be a built-in numpy scalar dtype. (default is np.float). The value can by anything that can be passed to the np.dtype constructor. For example np.float, np.dtype(np.float) or f8 all result in the same coord_dtype.

Examples

>>> c = CoordinateSystem('ij', name='input')
>>> print c
CoordinateSystem(coord_names=('i', 'j'), name='input', coord_dtype=float64)
>>> c.coord_dtype
dtype('float64')
coord_dtype

alias of float64

index(coord_name)

Return the index of a given named coordinate.

>>> c = CoordinateSystem('ij', name='input')
>>> c.index('i')
0
>>> c.index('j')
1

CoordinateSystemError

class nipy.core.reference.coordinate_system.CoordinateSystemError

Bases: exceptions.Exception

__init__()

x.__init__(...) initializes x; see help(type(x)) for signature

args
message

Functions

nipy.core.reference.coordinate_system.product(*coord_systems)

Create the product of a sequence of CoordinateSystems.

The coord_dtype of the result will be determined by safe_dtype.

Parameters :coord_systems : sequence of CoordinateSystem
Returns :product_coord_system : CoordinateSystem

Examples

>>> c1 = CoordinateSystem('ij', 'input', coord_dtype=np.float32)
>>> c2 = CoordinateSystem('kl', 'input', coord_dtype=np.complex)
>>> c3 = CoordinateSystem('ik', 'in3')
>>> print product(c1,c2)
CoordinateSystem(coord_names=('i', 'j', 'k', 'l'), name='product', coord_dtype=complex128)
>>> product(c2,c3)
Traceback (most recent call last):
   ...
ValueError: coord_names must have distinct names
nipy.core.reference.coordinate_system.safe_dtype(*dtypes)

Determine a dtype to safely cast all of the given dtypes to.

Safe dtypes are valid numpy dtypes or python types which can be cast to numpy dtypes. See numpy.sctypes for a list of valid dtypes. Composite dtypes and string dtypes are not safe dtypes.

Parameters :dtypes : sequence of np.dtype
Returns :dtype : np.dtype

Examples

>>> c1 = CoordinateSystem('ij', 'input', coord_dtype=np.float32)
>>> c2 = CoordinateSystem('kl', 'input', coord_dtype=np.complex)
>>> safe_dtype(c1.coord_dtype, c2.coord_dtype)
dtype('complex128')
>>> # Strings are invalid dtypes
>>> safe_dtype(type('foo'))
Traceback (most recent call last):
...
TypeError: dtype must be valid numpy dtype bool, int, uint, float or complex
>>> # Check for a valid dtype
>>> myarr = np.zeros(2, np.float32)
>>> myarr.dtype.isbuiltin
1
>>> # Composite dtypes are invalid
>>> mydtype = np.dtype([('name', 'S32'), ('age', 'i4')])
>>> myarr = np.zeros(2, mydtype)
>>> myarr.dtype.isbuiltin
0
>>> safe_dtype(mydtype)
Traceback (most recent call last):
...
TypeError: dtype must be valid numpy dtype bool, int, uint, float or complex