Skip to main content
`Ctrl`+`K`

# NumPy (NPY)

This reader supports reading and writing of numpy arrays in the `.npy` format, which is a binary file format for storing numpy arrays. This reader supports reading large `npy` files lazily and in a distributed fashion.

Note

This format doesn’t support storing metadata like scale, units, etc.

## API functions

rsciio.numpy.file_reader(filename, lazy=False, chunks='auto', navigation_axes=None, **kwargs)

  Read data from npy files.

  Parameters:
    filename `python:str`, `pathlib.Path`

      Filename of the file to read or corresponding pathlib.Path.

    lazy bool, default=False

      Whether to open the file lazily or not. The file will stay open until closed in `compute()` or closed manually. `get_file_handle()` can be used to access the file handler and close it manually.

    chunks `python:tuple` of `python:int` or `python:None`, default=None

      Define the chunking used for saving the dataset. If `None`, calculates chunks for the signal, with preferably at least one chunk per signal space.

    navigation_axes `python:list`, optional

      List of axes that should be treated as navigation axes. If not provided, all axes will be treated as signal axes.

    **kwargs `python:dict`, optional

      Pass keyword arguments to the `numpy.load()`, when lazy is False, otherwise to `rsciio.utils.file.memmap_distributed()`.

  Returns:
    `python:list` of `python:dict`

      List of dictionaries containing the following fields:

      - ‘data’ – multidimensional `numpy.ndarray` or `dask.array.Array`

      - ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

      - ‘metadata’ – dictionary containing the parsed metadata

      - ‘original_metadata’ – dictionary containing the full metadata tree from the input file

      When the file contains several datasets, each dataset will be loaded as separate dictionary.

  Notes

  This plugin does not support metadata like scale, units, etc.

  Examples

  To load a numpy file with lazy loading and specified chunks:

      >>> from rsciio.numpy import file_reader
      >>> d = file_reader('data.npy', lazy=True, chunks=("auto", "auto", 250, 250), navigation_axes=[0, 1])
      >>> d[0]['data']
      dask.array<array, shape=(1000, 1000, 500, 500), dtype=float64, chunksize=(100, 100, 250, 250)>

rsciio.numpy.file_writer(filename, signal, **kwargs)

  Write data to npy files.

  Parameters:
    filename `python:str`, `pathlib.Path`

      Filename of the file to write to or corresponding pathlib.Path.

    signal `python:dict`

      Dictionary containing the signal object. Should contain the following fields:

      - ‘data’ – multidimensional numpy array

      - ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

      - ‘metadata’ – dictionary containing the metadata tree

    **kwargs `python:dict`, optional

      Additional keyword arguments passed to `numpy.save()`.

  Notes

  This plugin does not support metadata like scale, units, etc.