Attention

This documentation is for the older Mesmerize legacy desktop application. Please see the home page or GitHub repo for information on the latest packages. https://github.com/kushalkolar/MESmerize

Tiff file module¶

To open a tiff file go to Modules -> Load Images -> Tiff files.

Note

You can also use this module through the console and scripts. See Tiff module API.

To open tiff files first click the “Select file” button and choose your file. You can also drag and drop a tiff file (drag and drop doesn’t work properly on Windows).

Next, you must select an appropriate Image Load Method (see next section). You can also import meta data associated with your recording.

Certain meta data, such as the sampling rate of the data, are necessary for some downstream analysis procedures. There are a few ways to import your meta data into the Viewer Work Environment:

Simple JSON files, see json_minimal under the table in the Meta data section

Define your own Custom functions to open meta in other file formats

Manually create a meta data dictionary using the Console

Load Method¶

The options for “Load Method” correspond to the tifffile library method that is used for loading the images.

If you are not sure which method you should use, try all of them and see which one loads your data appropriately. If none of them work, create an issue on GitHub.

asarray: Should work for most tiff files, fast method

asarray - multi series: Also fast. Use this if it is a multi-page tiff. For example if the tiff file was created by a program that appends each frame to a file as they are being acquired by the camera.

imread: Usually slower, should work for most tiff files.

Axes order¶

Choose the default axes order or manually enter the axes order if your tiff file uses a different order.

Meta data¶

Check the “Load meta data” checkbox if you want to load meta data. Alternatively, you can uncheck this box and create a meta data dictionary manually using the console (see the Console section)

You can select a meta data format from the list. This list of formats correspond to the functions available in the module: mesmerize.viewer.core.organize_meta. When you select a meta data format, it will automatically try to find a file with the extension specified by the selected format if it has the same name as the selected tiff file.

If you have questions on meta data formats feel free to drop a message in the Gitter room

Default list of formats that are recognized:

Name

extension

Description

json_minimal

.json

Recognizes a json file that contains at least the minimal set of necessary keys: origin, fps and date.

All other keys in the JSON file are placed in a sub-dictionary with the key orig_meta

See Minimal dict below for more info.

AwesomeImager

.json

Used for 1p imaging in the Chatzigeorgiou group at the Sars Center

ome_tiff

.tiff

Imports OME XML meta data stored within the tiff file. Specification is described here: https://docs.openmicroscopy.org/ome-model/6.2.2/ome-tiff/specification.html

The following values are computed and added to the meta data for the Viewer Work Environment, and can be accessed through get_meta() in the Viewer Console

fps - mean sampling rate in Hz, volumetric sampling rate if 3D, frame-to-frame sampling rate if 2D

fps_std - standard deviation of the sampling rate

fps_max_dev - maximum deviation from the mean sampling rate

A warning box is shown if fps_std > 0.01 or fps_max_dev > 0.1

Custom functions¶

You may define your own function to organize your meta data. It MUST return a dict which has at least the following keys: origin, fps and date.

origin is a str describing the software or microscope the recording comes from. This is for your own record.

fps is the sampling rate of the recording as a float or int

date is the date & time represented by a str in the following format: "YYYYMMDD_HHMMSS"

In addition to these 3 keys, you may include any additional keys as you wish.

If you think your meta data organizing function will be useful for others I’ll be happy to review a pull request and it can be included by default in Mesmerize. We’re happy help you create a meta data function, just contact us on Gitter or create an issue on GitHub.

Minimal dict¶

Example of a minimal meta data dict.

{
    "origin": "microscope or software origin",  # must be a str
    "fps":     10.0,                            # must be a int or float
    "date":    "20201123_172345"                # must be a str formatted as "YYYYMMDD_HHMMSS"
}

Function outline¶

Basic outline of a function that you can add to mesmerize.viewer.core.organize_meta for organizing your meta data:

The function can only take the path to the meta data file as the argument.

The expected file extension for the meta data must be specified. The files of a single format are allowed to have multiple different file extension but you must only specify the most common one.

The function would generally open the meta data file specified by the path, using any python libraries or other code of your choice, and finally return a dictionary that contains the minimal complement of keys, i.e. origin, fps and date with values of the appropriate types (see previous section).

def my_meta_organizer(path: str) -> dict:
    """.ext""" # define the file ext in the docstring

    raw_meta = function_to_load_my_file(path)

    # do stuff to organize the raw_meta

    meta = ... # stuff to organize raw meta
    return meta
    # return the organized meta data dict
    # that mesmerize can use

Console/Script usage¶

You can also load tiff files through the Viewer Console or Script Editor.

This example can be run line-by-line through the Viewer Console, or from the Script Editor.

image_path = # path to tiff file
meta_path = # path to json meta data file

clear_workEnv() # Prevents a confirmation dialog from appearing

# Get the tiff module
tio = get_module('tiff_io', hide=True)

# Load the tiff file
tio.load(image_path, method='imread', axes_order='txy', meta_path=meta_path, meta_format='json_minimal)

Alternatively, you may manually create a meta data dictionary after loading a tiff file:

image_path = # path to tiff file

clear_workEnv() # Prevents a confirmation dialog from appearing

# Get the tiff module
tio = get_module('tiff_io', hide=True)

# Load the tiff file
tio.load(image_path, method='imread', axes_order='txy')

meta_dict = \
    {
        "origin":   "my_microscope_software",   # must a str
        "fps":      17.25,                      # must be a int or float
        "date"      "20201123_172345"           # must be a str formatted as "YYYYMMDD_HHMMSS"/
    }

get_workEnv().imgdata.meta = meta_dict