# NiBabel

### Access a cacophony of neuro-imaging file formats

# `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_path str

      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_path str

        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_parts sequence of strings
    Returns:
      fname str

        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_path str

      path to prepend to all relative paths

    config_filaname None 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_path str

        path to prepend to all relative paths

      config_filaname None 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_def dict

      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_path sequence of strings or None, optional
  Returns:
    ds datasource 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_dirs sequence of strings

      sequence of paths in which to search for data directory

    *names sequence of strings

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

  Returns:
    data_dir str

      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:
    paths sequence 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:

  - https://www.debian.org/doc/packaging-manuals/python-policy/ap-packaging_tools.html#s-distutils

  - https://www.mail-archive.com/debian-python@lists.debian.org/msg05084.html

  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_def dict

      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_path sequence of strings or None, optional

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

  Returns:
    datasource `VersionedDatasource`

      An initialized `VersionedDatasource` instance