Advanced: Pre‐Analysis Pipeline

The pre-analysis pipeline is designed to co-register all of your prior, separately registered videos to a common reference, so that they can be easily analyzed in multiple dimensions. It also serves to automatically group videos based on their filename properties, for easier analysis and consideration of multiple groups. Below is an exhaustive list of the currently used configuration keys and values, where options for each are in parenthesis with the default in between dual asterisks, e.g: your_cat: (**"is fluffy and nice"**, "is the devil incarnate"):

The vast majority of steps in the pre-analysis pipeline are optional, resulting in a flow chart as follows, where optional steps are indicated by dashed lines:

flowchart TB

    AA(Load Dataset) --> BB([Parse Tags/Metadata])
    BB([Parse Tags/Metadata]) --> CC([Perform Custom Steps]) 
    CC([Perform Custom Steps]) --> DD([Trim Video]) 
    DD([Trim Video]) --> EE([Flat Field]) 
    EE([Flat Field]) --> FF([Gaussian Blur]) 
    FF([Gaussian Blur]) --> GG([Crop Video]) 
    GG([Crop Video]) --> HH([Intra-Video Torsion Removal])
    HH([Intra-Video Torsion Removal]) --> II(Data Output and Sorting)
    
   
    click BB "https://github.com/OCVL/F-Cell/wiki/Advanced:-Tag-Parsing" "Tag Parsing"
    click CC "https://github.com/OCVL/F-Cell/wiki/Advanced:-Pre%E2%80%90Analysis-Pipeline#general-parameters" "Custom Steps"
    click DD "https://github.com/OCVL/F-Cell/wiki/Advanced:-Pre%E2%80%90Analysis-Pipeline#trimming" "Trim Video"
    click EE "https://github.com/OCVL/F-Cell/wiki/Advanced:-Pre%E2%80%90Analysis-Pipeline#flat-fielding" "Flat Field"
    click FF "https://github.com/OCVL/F-Cell/wiki/Advanced:-Pre%E2%80%90Analysis-Pipeline#blurring" "Blurring"
    click GG "https://github.com/OCVL/F-Cell/wiki/Advanced:-Pre%E2%80%90Analysis-Pipeline#roi-masking" "Crop Video"
    click HH "https://github.com/OCVL/F-Cell/wiki/Advanced:-Pre%E2%80%90Analysis-Pipeline#torsion-correction" "Intra-Video Torsion Removal"

    classDef optional stroke-dasharray:4 5;
    class CC,DD,EE,FF,GG optional;

Loading

Base Key / Value pairs:

Key	Parent Key	Type	Options	Description
"image_format"	"preanalysis"	"string"	parse-augmented string	The filename format of the averaged image associated with a single acquisition. Uses parse-based tag formatting to extract file-specific metadata.
"video_format"	"preanalysis"	"string"	parse-augmented string	The filename format of the video (e.g. avi, mp4, etc) associated with a single acquisition. Uses parse-based tag formatting to extract file-specific metadata.
"mask_format"	"preanalysis"	"string"	parse-augmented string	The filename format of the video of masks associated with the video. Consists of a video of binary masks that describes the valid region in the video. Uses parse-based tag formatting to extract file-specific metadata.
"recursive_search"	"preanalysis"	boolean	(true, **false**)	If true, then 𝑓(Cell) will recursively search and include files that fit the format defined in "image_format", "video_format", and "mask_format" within the directories specified at launch.
"metadata"	"preanalysis"	JSON Object	none	A JSON object holding parameters for the metadata associated with the dataset. See the metadata page for more information.
"pipeline_params"	"preanalysis"	JSON Object	none	A JSON object holding parameters that govern how the datasets are run through the pre-analysis pipeline. See parameters.

Pipeline Parameters and Descriptions:

The pipeline has numerous parameters that govern how the data is processed. It is important to note that all parameters that act on the video data do so only for purposes of the pipeline. That is, any blur, ROI cropping, etc., is only used for the purposes of alignment.

General Parameters

Key	Parent Key	Type	Options	Description
"alignment_reference_modality"	"pipeline_params"	"string"	(**null**)	The reference modality used for alignment of all modalities. If the Modality dataset tag is not defined in video_format, then this field is ignored.
"modalities"	"pipeline_params"	["string list"]	(**null**)	A list of modality names to include in the pre-analysis pipeline. Example: ["Confocal", "Split-Detector", "Dark-Field"]. If the Modality dataset tag is not defined in video_format, then this field is ignored.
"output_folder"	"pipeline_params"	"string"	(**Functional Pipeline**, any)	The folder that all results of the pipeline are placed in. The date and time that the processing pipeline was run will automatically be appended to this string.
"group_by"	"pipeline_params"	"string"	(**null**)	A string that defines data groups, in terms of dataset tags. These also correspond to the subfolders that are created within the output_folder. Example 1: "({LocX},{LocY})" (this would make subfolders corresponding to the X and Y locations embedded into dataset tags). Example 2: "{Modality}" (this would separate data into folders based on their modality).
"custom"	"pipeline_params"	JSON Object	none	A JSON object used to submit custom commands to 𝑓(Cell). If you are interested in adding a algorithm that is custom to YOUR lab, please either submit an issue to this repository, or email Rob Cooper directly, detailing your request.

Trimming

Key	Parent Key	Type	Options	Description
"start_idx"	"trim"	integer	(**0**)	The starting frame number of the trim (inclusive).
"end_idx"	"trim"	integer	(**-1**)	The last frame number of the trim (exclusive).

Blurring

Occasionally, adding blur can help with robustness in datasets that consist of multi-modal photoreceptors or other complex structures that change from acquisition to acquisition.

Key	Parent Key	Type	Options	Description
"gaus_blur"	"pipeline_params"	float	0.0	The amount of Gaussian blur in sigmas to apply to each frame of a video and to each average image before alignment.

Flat fielding

Like blurring, performing flat-fielding, especially before alignment, can be helpful in some datasets, especially ones that were obtained with a subject out-of-plane. This is typically observed as a "flashlighting" effect that is deleterious to most registration approaches.

Key	Parent Key	Type	Options	Description
"flat_field"	"pipeline_params"	boolean	(true, **false**)	This key controls whether or not to flat-field the video data before performing registration.

ROI Masking

In some instances, the videos may have features that cause alignment errors, such as: edges of lesions, or video/image/edge artifacts. 𝑓(Cell) allows you to select an ROI that will be used only for alignment if you observe instability in the pipeline outputs.

Key	Parent Key	Type	Options	Description
"mask_roi"	"pipeline_params"	JSON Object	none	A JSON object holding the row, column, width, and height of the ROI used for video registration.
"r"	"mask_roi"	integer	(**0**)	The starting row of the ROI crop.
"c"	"mask_roi"	integer	(**0**)	The starting column of the ROI crop.
"width"	"mask_roi"	integer	(**-1**)	The width of the ROI crop. -1 specifies the remaining width of the image.
"height"	"mask_roi"	integer	(**-1**)	The height of the ROI crop. -1 specifies the remaining height of the image.

Torsion Correction

Especially in ORG data collection, the eye/participant may flinch in response to stimulus delivery. In some individuals, this manifests as a torsion (rotation) in the images. F(Cell) is able to correct this torsion both within and between videos during the pipeline step.

Key	Parent Key	Type	Options	Description
"correct_torsion"	"pipeline_params"	boolean	(**true**, false)	Determines if F(Cell) attempts to correct any residual torsion in the video data before co-registering it to other videos.
"intra_stack_xform"	"pipeline_params"	"string"	(affine, **rigid**)	The transform used to correct torsion within a video.
"inter_stack_xform"	"pipeline_params"	"string"	(affine, **rigid**)	The transform used to align between videos.