data

Utilities to find files from NIPY data packages

Bomber(name, msg)

Class to raise an informative error when used

BomberError

Error when trying to access Bomber instance

DataError

Datasource(base_path)

Simple class to add base path to relative path

VersionedDatasource(base_path[, config_filename])

Datasource with version information in config file

datasource_or_bomber(pkg_def, **options)

Return a viable datasource or a Bomber

find_data_dir(root_dirs, *names)

Find relative path given path prefixes to search

get_data_path()

Return specified or guessed locations of NIPY data files

make_datasource(pkg_def, **kwargs)

Return datasource defined by pkg_def as found in data_path

Bomber

class nibabel.data.Bomber(name, msg)

Bases: object

Class to raise an informative error when used

__init__(name, msg)

BomberError

class nibabel.data.BomberError

Bases: DataError, AttributeError

Error when trying to access Bomber instance

Should be instance of AttributeError to allow Python 3 inspect to do various hasattr checks without raising an error

__init__(*args, **kwargs)

DataError

class nibabel.data.DataError

Bases: Exception

__init__(*args, **kwargs)

Datasource

class nibabel.data.Datasource(base_path)

Bases: object

Simple class to add base path to relative path

Initialize datasource

Parameters:
base_pathstr

path to prepend to all relative paths

Examples

>>> from os.path import join as pjoin
>>> repo = Datasource(pjoin('a', 'path'))
>>> fname = repo.get_filename('somedir', 'afile.txt')
>>> fname == pjoin('a', 'path', 'somedir', 'afile.txt')
True
__init__(base_path)

Initialize datasource

Parameters:
base_pathstr

path to prepend to all relative paths

Examples

>>> from os.path import join as pjoin
>>> repo = Datasource(pjoin('a', 'path'))
>>> fname = repo.get_filename('somedir', 'afile.txt')
>>> fname == pjoin('a', 'path', 'somedir', 'afile.txt')
True
get_filename(*path_parts)

Prepend base path to *path_parts

We make no check whether the returned path exists.

Parameters:
*path_partssequence of strings
Returns:
fnamestr

result of os.path.join(*path_parts), with ``self.base_path prepended

list_files(relative=True)

Recursively list the files in the data source directory.

Parameters:
relative: bool, optional

If True, path returned are relative to the base path of the data source.

Returns:
file_list: list of strings

List of the paths of all the files in the data source.

VersionedDatasource

class nibabel.data.VersionedDatasource(base_path, config_filename=None)

Bases: Datasource

Datasource with version information in config file

Initialize versioned datasource

We assume that there is a configuration file with version information in datasource directory tree.

The configuration file contains an entry like:

[DEFAULT]
version = 0.3

The version should have at least a major and a minor version number in the form above.

Parameters:
base_pathstr

path to prepend to all relative paths

config_filanameNone or str

relative path to configuration file containing version

__init__(base_path, config_filename=None)

Initialize versioned datasource

We assume that there is a configuration file with version information in datasource directory tree.

The configuration file contains an entry like:

[DEFAULT]
version = 0.3

The version should have at least a major and a minor version number in the form above.

Parameters:
base_pathstr

path to prepend to all relative paths

config_filanameNone or str

relative path to configuration file containing version

datasource_or_bomber

nibabel.data.datasource_or_bomber(pkg_def, **options)

Return a viable datasource or a Bomber

This is to allow module level creation of datasource objects. We create the objects, so that, if the data exist, and are the correct version, the objects are valid datasources, otherwise, they raise an error on access, warning about the lack of data or the version numbers.

The parameters are as for make_datasource in this module.

Parameters:
pkg_defdict

dict containing at least key ‘relpath’. Can optionally have keys ‘name’ (package name), ‘install hint’ (for helpful error messages) and ‘min version’ giving the minimum necessary version string for the package.

data_pathsequence of strings or None, optional
Returns:
dsdatasource or Bomber instance

find_data_dir

nibabel.data.find_data_dir(root_dirs, *names)

Find relative path given path prefixes to search

We raise a DataError if we can’t find the relative path

Parameters:
root_dirssequence of strings

sequence of paths in which to search for data directory

*namessequence of strings

sequence of strings naming directory to find. The name to search for is given by os.path.join(*names)

Returns:
data_dirstr

full path (root path added to *names above)

get_data_path

nibabel.data.get_data_path()

Return specified or guessed locations of NIPY data files

The algorithm is to return paths, extracted from strings, where strings are found in the following order:

  1. The contents of environment variable NIPY_DATA_PATH

  2. Any section = DATA, key = path value in a config.ini file in your nipy user directory (found with get_nipy_user_dir())

  3. Any section = DATA, key = path value in any files found with a sorted(glob.glob(os.path.join(sys_dir, '*.ini'))) search, where sys_dir is found with get_nipy_system_dir()

  4. If sys.prefix is /usr, we add /usr/local/share/nipy. We need this because Python 2.6 in Debian / Ubuntu does default installs to /usr/local.

  5. The result of get_nipy_user_dir()

Therefore, any paths found in NIPY_DATA_PATH will be searched before paths found in the user directory config.ini

Parameters:
None
Returns:
pathssequence of paths

Notes

We have to add /usr/local/share/nipy if sys.prefix is /usr, because Debian has patched distutils in Python 2.6 to do default distutils installs there:

Examples

>>> pth = get_data_path()

make_datasource

nibabel.data.make_datasource(pkg_def, **kwargs)

Return datasource defined by pkg_def as found in data_path

data_path is the only allowed keyword argument.

pkg_def is a dictionary with at least one key - ‘relpath’. ‘relpath’ is a relative path with unix forward slash separators.

The relative path to the data is found with:

names = pkg_def['name'].split('/')
rel_path = os.path.join(names)

We search for this relative path in the list of paths given by data_path. By default data_path is given by get_data_path() in this module.

If we can’t find the relative path, raise a DataError

Parameters:
pkg_defdict

dict containing at least the key ‘relpath’. ‘relpath’ is the data path of the package relative to data_path. It is in unix path format (using forward slashes as directory separators). pkg_def can also contain optional keys ‘name’ (the name of the package), and / or a key ‘install hint’ that we use in the returned error message from trying to use the resulting datasource

data_pathsequence of strings or None, optional

sequence of paths in which to search for data. If None (the default), then use get_data_path()

Returns:
datasourceVersionedDatasource

An initialized VersionedDatasource instance