Data Reading Functions

massphoto supports reading mass photometry movies from standard acquisition formats, including HDF5-based recordings (.mp, .mpr), multi-page TIFF (.tif, .tiff), National Instruments TDMS (.tdms), and HDF5 containers (.h5).

Tip

Need support for a new camera or file format? If you work with custom interferometric setups, non-standard cameras, or proprietary file formats, please open an issue on GitHub to request support or share a sample recording!

Movie I/O for mass photometry data.

Public entry points are read_movie(), read_mp() and read_tdms().

• MP/MPR files are HDF5-based and are read via h5py (and hdf5plugin for compressed datasets).

• TDMS support is optional and requires nptdms.

• TIFF support is optional and requires tifffile.

massphoto.read.register_reader(suffixes, reader, *, overwrite=False)

Register a reader callable for one or more file extensions.

Parameters:

• suffixes (str | Iterable[str])

• reader (Callable[[...], tuple[ndarray, dict] | tuple[ndarray, dict, ndarray]])

• overwrite (bool)

Return type:

None

massphoto.read.read_movie(filepath, convert_metadata=False)

Read a movie file and return (frames, metadata).

Note

Available as both massphoto.read_movie and massphoto.read.read_movie.

Dispatches based on file extension via the reader registry:

• .mp / .mpr -> read_mp()

• .tdms -> read_tdms()

• .tif / .tiff -> read_tiff()

Parameters:

• filepath (str or os.PathLike) – Path to the movie file.

• convert_metadata (bool, optional) – If True, convert metadata to a more readable form via massphoto.metadata.convert_metadata().

Returns:

(frames, metadata).

Return type:

tuple[np.ndarray, dict]

Raises:

• FileNotFoundError – If the specified file does not exist.

• ValueError – If the file type is not supported.

See also

read_mp, read_tdms, read_tiff, register_reader

massphoto.read.read_mp(filepath, convert_metadata=False)

Read a DiscoverMP .mp/.mpr (HDF5) file.

Parameters:

• filepath (str or os.PathLike) – Path to the MP/MPR file.

• convert_metadata (bool, optional) – If True, convert metadata to a more readable form via massphoto.metadata.convert_metadata().

Returns:

(frames, metadata).

Return type:

tuple[np.ndarray, dict]

Raises:

ValueError – If no entry for frames is found in file.

Notes

Some MP files store frames in a compressed representation. This function attempts to detect that case and will transparently decompress via _decode_compressed_movie().

massphoto.read.read_tdms(filepath, channel='', read_timestamp=False, image_size=None, convert_metadata=False)

Read image data from a TDMS file.

TDMS support is optional and requires nptdms.

Parameters:

• filepath (str or os.PathLike) – Path to the TDMS file.

• channel (str, optional) – Channel name to read (post-written TDMS). If empty, the first image channel is used.

• read_timestamp (bool, optional) – Whether to read the timestamp data. Default is False.

• image_size (list, optional) – Optional image size override as [y, x] (post-written TDMS only).

• convert_metadata (bool, optional) – Whether to convert metadata to a more readable format. Default is False.

Returns:

(frames, metadata) or (frames, metadata, timestamps) when read_timestamp=True.

Return type:

tuple

Raises:

ImportError – If the nptdms library is not installed.

See also

read_movie

massphoto.read.read_tiff(filepath, convert_metadata=False)

Read a multi-page TIFF file.

Parameters:

• filepath (str or os.PathLike) – Path to the TIFF file.

• convert_metadata (bool, optional) – Whether to convert metadata to a more readable format. Default is False.

Returns:

(frames, metadata).

Return type:

tuple[np.ndarray, dict]

Raises:

ImportError – If the tifffile library is not installed.

See also

read_movie