Skip to main content
`Ctrl`+`K`

# Gatan Digital Micrograph

RosettaSciIO can read both `.dm3` and `.dm4` files, but the reading features are not complete (and probably they will remain so, unless Gatan releases the specifications of the format). That said, we understand that this is an important feature and if loading a particular Digital Micrograph file fails for you, please report it as an issue in the issues tracker to make us aware of the problem.

Some of the tags in the DM-files are added to the metadata of the signal object. This includes, microscope information and certain parameters for EELS, EDS and CL signals.

Warning

It has been reported that in some versions of Gatan Digital Micrograph, any binned data stores the _averages_ of the binned channels or pixels, rather than the _sum_, which would be required for proper statistical analysis. We therefore strongly recommend that all binning is performed using python, e.g. HyperSpy, where possible.

See the original bug report here.

## API functions

rsciio.digitalmicrograph.file_reader(filename, lazy=False, order=None, optimize=True, chunks='auto')

  Read a DM3/4 file and loads the data into the appropriate class.

  If more than one dataset is contained in the `.dm3/4` file, a list of signals is returned.

  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.

    order `python:str`

      One of ‘C’ or ‘F’. Define the ordering of the data.

    optimize bool, Default=True

      If `True`, the data is replaced by its during loading to speed up operations, e.g. iteration over navigation axes. The cost of this speed improvement is to double the memory requirement during data loading, which for large data sets can lead to a slow down on machines with limited memory. When operating on lazy signals, if `True`, the chunks are optimised for the new axes configuration.

    chunks `python:tuple`, `python:int`, `python:dict` or `python:str`, default=”auto”

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

  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.