importFromTif

Imports imaging data from .TIF files.

Description

This function imports imaging data stored in a multi-frame .TIF file and saves it in a .dat file to be used in umIToolbox. The function reads all valid .TIF files (see section below) inside a folder (RawFolder) and saves the output files to a SaveFolder. It supports importing sequences of files that have filenames ending in a number, with optional separators ("_" or "-") or no separator at all (e.g. red001.tif or red_001.tif or red-001.tif). Additionally, the metadata is stored in a .json file instead of the previous .txt format. This function has optional parameters that allow one to perform spatial and temporal binning on the data.

Input data format

Here are the properties of a valid .TIF file:

be an image time series with dimensions Y,X,T(ime) from a single channel
contain pixel values encoded as one of the following data types:
- uint8
- uint16
- uint32
have a .json file named info.json located in the folder, which contains metadata about the recording (see section below)

The meta data JSON file

In order to import the data from the .TIF file(s), this function uses information stored in a JSON file named info.json. This file contains both global metadata associated with the recording and individual parameters for each TIF file in the dataset.

Template of JSON file for .TIF file metadata:


    {
      "DateTime": "yyyymmdd_HHMMSS",
      "Tiffiles": [
        {
          "filename": "img_red.tif",
          "FrameRateHz": 30.0,
          "ExposureMsec": 0.1,
          "IlluminationColor": "Red"
        },
        {
          "filename": "img_fluo_475_003.tif",
          "FrameRateHz": 30.0,
          "ExposureMsec": 0.1,
          "IlluminationColor": "fluo"
        }
      ]
    }

Note
A copy of this .json template is stored in the toolbox folder in ../Umit/Analysis/Toff_data_import_info_template.json. You can use it to build your own. Notice that the file need to be renamed to info.json to be used by the import function.

The parameters are organized as follows:

DateTime: Recording timestamp (start) in the format yyyymmdd_HHMMSS (e.g. 20220101_120510 for a recording that started January 1st, 2022 at 12:05:10).

Note
This parameter is optional and can include additional metadata such as mouse ID, mouse age, etc.
Tiffiles: A list of entries, each containing metadata specific to an individual TIF file in the dataset. Each entry includes:
- filename: Name of the TIF file. If there is a file sequence, type the name of one of the existing files.
- FrameRateHz: (float) Recording frame rate in Hertz.
- ExposureMsec: (float) Illumination exposure in milliseconds.
- IlluminationColor: (char) Name of the imaging channel.

Important
Ensure that each TIF file entry includes at least the parameters listed above for proper data import. Additional metadata can be added as needed to store extra information relevant to the experiment.

Output

A .dat file will be created and stored in the SaveFolder with the channel name (located in the IlluminationColor parameter from the metadata JSON file). The associated .mat file will contain all meta data associated with the .TIF files (those inside the "Tiffiles" list). Note that the meta data in the outer section of the JSON file is not automatically stored. This section can be used to create your own protocol function, for example.

Parameters

The parameters of this function are the following:

Performs binning on each frame of the imported channels using a bicubic interpolation. The BinningSpatial values represent the scale factor that a frame is divided by. For example, for a recording with original frame size of 1024 by 1024 pixels, a BinningSpatial value of 2 will result in a frame of size 512 by 512 pixels.
A BinningSpatial value of 1 equals to no binning.

Performs binning across frames (i.e. over the time dimension) using a linear interpolation. The BinningTemp values represent the scale factor for the temporal dimension of a recording. For example, for a recording with original frame rate of 10Hz, a BinningTemp value of 2 will reduce the number of frames in half, resulting in a frame rate of 5Hz.
A BinningTemp value of 1 equals to no binning.