Skip to main content
`Ctrl`+`K`

# Quantum Detector

The `mib` file format is the format from the Quantum Detector software to acquired with the Quantum Detector Merlin camera. It is typically used to store a series of diffraction patterns from scanning transmission electron diffraction measurements. It supports reading data from camera with one or four quadrants.

## API functions

rsciio.quantumdetector.file_reader(filename, lazy=False, chunks='auto', mmap_mode=None, navigation_shape=None, first_frame=None, last_frame=None, distributed=False, print_info=False)

  Read a Quantum Detectors `mib` file.

  If a `hdr` file with the same file name was saved along the `mib` file, it will be used to read the metadata.

  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=”auto”

      The chunks used when reading the data lazily. This argument is passed to the `chunks` of the `dask.array.from_array()` function.

    mmap_mode{`python:None`, “r+”, “r”, “w+”, “c”}, default=None

      Argument passed to `numpy.memmap`. A memory-mapped array is stored on disk, and not directly loaded into memory. However, it can be accessed and sliced like any ndarray. Lazy loading does not support in-place writing (i.e lazy loading and the `"r+"` mode are incompatible). If `None` (default), the value is `"r"` when `lazy=True`, otherwise it is `"c"`.

    navigation_shape `python:tuple` or `python:None`, default=None

      Specify the shape of the navigation space. If `None`, the navigation shape will be infer from metadata and if not possible, the data will be loaded as a stack with a navigation dimension equal to one.

    first_frame, last_frame `python:int` or `python:None`, default=None

      The first/last frame to load. It follows python indexing syntax, i.e. negative integer means reverse indexing. If `None`, it uses first/last index.

    distributed bool, default=False

      Whether to load the data using memory-mapping in a way that is compatible with dask-distributed. This can sometimes improve performance when reading large files. And splitting the data loading/processing over multiple workers.

    print_info bool

      Display information about the mib file.

  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

  In case of interrupted acquisition, only the completed lines are read and the incomplete line are discarded.

  When the scanning shape (i. e. navigation shape) is not available from the metadata (for example with acquisition using pixel trigger), the timestamps will be used to guess the navigation shape.

  Examples

  In case, the navigation shape can’t read from the data itself (for example, type of acquisition unsupported), the `navigation_shape` can be specified:

      >>> from rsciio.quantumdetector import file_reader
      >>> s_dict = file_reader("file.mib", navigation_shape=(256, 256))

rsciio.quantumdetector.load_mib_data(path, lazy=False, chunks='auto', mmap_mode=None, navigation_shape=None, first_frame=None, last_frame=None, distributed=False, mib_prop=None, return_headers=False, print_info=False, return_mmap=True)

  Load Quantum Detectors MIB file from a path or a memory buffer.

  Parameters:
    path `python:str` or `bytes`

      The path to the `mib` file, otherwise the memory buffer of the `mib` file. Lazy loading is not supported with memory buffer.

    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=”auto”

      The chunks used when reading the data lazily. This argument is passed to the `chunks` of the `dask.array.from_array()` function.

    mmap_mode{`python:None`, “r+”, “r”, “w+”, “c”}, default=None

      Argument passed to `numpy.memmap`. A memory-mapped array is stored on disk, and not directly loaded into memory. However, it can be accessed and sliced like any ndarray. Lazy loading does not support in-place writing (i.e lazy loading and the `"r+"` mode are incompatible). If `None` (default), the value is `"r"` when `lazy=True`, otherwise it is `"c"`.

    navigation_shape `python:tuple` or `python:None`, default=None

      Specify the shape of the navigation space. If `None`, the navigation shape will be infer from metadata and if not possible, the data will be loaded as a stack with a navigation dimension equal to one.

    first_frame, last_frame `python:int` or `python:None`, default=None

      The first/last frame to load. It follows python indexing syntax, i.e. negative integer means reverse indexing. If `None`, it uses first/last index.

    distributed bool, default=False

      Whether to load the data using memory-mapping in a way that is compatible with dask-distributed. This can sometimes improve performance when reading large files. And splitting the data loading/processing over multiple workers.

    mib_prop `MIBProperties`, default=None

      The `MIBProperties` instance of the file. If None, it will be parsed from the file.

    return_headers bool, default=False

      If True, also return headers.

    print_info bool, default=False

      If True, display information when loading the file.

    return_mmap bool

      If True, return the `numpy.memmap` object. Default is True.

  Returns:
    `numpy.ndarray` or `dask.array.Array` or `numpy.memmap`

      The data from the mib reshaped according to the `navigation_shape` argument.

rsciio.quantumdetector.parse_exposures(headers, max_index=10000)

  Parse the exposure time from the header of each frames.

  Parameters:
    headers `bytes` `python:str` or python:iterable of `bytes` `python:str`

      The headers as a bytes string.

    max_index `python:int`

      Define the maximum index of the frame to be considered to avoid reading the header of all frames. If -1 (default), all frames will be read.

  Returns:
    `python:list`

      The exposure in ms of each frame.

  Examples

  Use `load_mib_data` function to the headers and parse the exposures from the headers. By default, reads only the first 10 000 frames.

      >>> from rsciio.quantumdetector import load_mib_data, parse_exposures
      >>> data, headers = load_mib_data(path, return_headers=True, return_mmap=True)
      >>> exposures = parse_exposures(headers)

  All frames can be parsed by using `max_index=-1`:

      >>> data, headers = load_mib_data(path, return_headers=True)
      >>> timestamps = parse_exposures(headers, max_index=-1)
      >>> len(timestamps)
      65536

rsciio.quantumdetector.parse_timestamps(headers, max_index=10000)

  Parse the timestamp time from the header of each frames.

  Parameters:
    headers `bytes` `python:str` or python:iterable of `bytes` `python:str`

      The headers as a bytes string.

    max_index `python:int`

      Define the maximum index of the frame to be considered to avoid reading the header of all frames. If -1 (default), all frames will be read.

  Returns:
    `python:list`

      The timestamp of each frame.

  Examples

  Use `load_mib_data` function to get the headers and parse the timestamps from the headers. By default, reads only the first 10 000 frames.

      >>> from rsciio.quantumdetector import load_mib_data, parse_exposures
      >>> data, header = load_mib_data(path, return_headers=True)
      >>> timestamps = parse_timestamps(headers)
      >>> len(timestamps)
      10000

  All frames can be parsed by using `max_index=-1`:

      >>> data, headers = load_mib_data(path, return_headers=True)
      >>> timestamps = parse_timestamps(headers, max_index=-1)
      >>> len(timestamps)
      65536