core.reference.coordinate_system

Module: core.reference.coordinate_system

Inheritance diagram for nipy.core.reference.coordinate_system:

digraph inheritance3f48cb85d6 { rankdir=LR; size="8.0, 12.0"; "reference.coordinate_system.CoordSysMaker" [URL="#nipy.core.reference.coordinate_system.CoordSysMaker",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Class to create similar coordinate maps of different dimensions"]; "reference.coordinate_system.CoordSysMakerError" [URL="#nipy.core.reference.coordinate_system.CoordSysMakerError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top"]; "reference.coordinate_system.CoordinateSystem" [URL="#nipy.core.reference.coordinate_system.CoordinateSystem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="An ordered sequence of named coordinates of a specified dtype."]; "reference.coordinate_system.CoordinateSystemError" [URL="#nipy.core.reference.coordinate_system.CoordinateSystemError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top"]; }

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

CoordSysMaker

class nipy.core.reference.coordinate_system.CoordSysMaker(coord_names, name='', coord_dtype=<class 'float'>)[source]

Bases: object

Class to create similar coordinate maps of different dimensions

__init__(coord_names, name='', coord_dtype=<class 'float'>)[source]

Create a coordsys maker with given axis coord_names

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

>>> cmkr = CoordSysMaker('ijk', 'a name')
>>> print(cmkr(2))
CoordinateSystem(coord_names=('i', 'j'), name='a name', coord_dtype=float64)
>>> print(cmkr(3))
CoordinateSystem(coord_names=('i', 'j', 'k'), name='a name', coord_dtype=float64)
coord_sys_klass

alias of CoordinateSystem

CoordSysMakerError

class nipy.core.reference.coordinate_system.CoordSysMakerError[source]

Bases: Exception

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

CoordinateSystem

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

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 names and the same name.

>>> another_cs = CoordinateSystem(names, 'not irrelevant', np.float)
>>> cs == another_cs
False
>>> cs.dtype == another_cs.dtype
True
>>> cs.name == another_cs.name
False
__init__(coord_names, name='', coord_dtype=<class 'float'>)[source]

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')
name = 'world-LPI'
coord_names = ('x', 'y', 'z')
coord_dtype

alias of numpy.float64

ndim = 3
dtype = dtype([('x', '<f8'), ('y', '<f8'), ('z', '<f8')])
index(coord_name)[source]

Return the index of a given named coordinate.

>>> c = CoordinateSystem('ij', name='input')
>>> c.index('i')
0
>>> c.index('j')
1
similar_to(other)[source]

Similarity is defined by self.dtype, ignoring name

Parameters

other : CoordinateSystem

The object to be compared with

Returns

tf: bool

CoordinateSystemError

class nipy.core.reference.coordinate_system.CoordinateSystemError[source]

Bases: Exception

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Functions

nipy.core.reference.coordinate_system.is_coordsys(obj)[source]

Test if obj has the CoordinateSystem API

Parameters

obj : object

Object to test

Returns

tf : bool

True if obj has the coordinate system API

Examples

>>> is_coordsys(CoordinateSystem('xyz'))
True
>>> is_coordsys(CoordSysMaker('ikj'))
False
nipy.core.reference.coordinate_system.is_coordsys_maker(obj)[source]

Test if obj has the CoordSysMaker API

Parameters

obj : object

Object to test

Returns

tf : bool

True if obj has the coordinate system API

Examples

>>> is_coordsys_maker(CoordSysMaker('ikj'))
True
>>> is_coordsys_maker(CoordinateSystem('xyz'))
False
nipy.core.reference.coordinate_system.product(*coord_systems, **kwargs)[source]

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

name : str

Name of ouptut coordinate system

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)

>>> print(product(c1, c2, name='another name'))
CoordinateSystem(coord_names=('i', 'j', 'k', 'l'), name='another name', 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)[source]

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 int, uint, float, complex or object

>>> # 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 int, uint, float, complex or object