Quick Start

How to obtain ORGs from your data:

1. Align each of your videos using your favorite processing software- can be strip registration, full frame, whatever!
2. Download and unzip the most recent version of 𝑓(Cell) here.
3. Create a configuration file that both describes the filename format of your data, and how you would like to align and analyze the datasets.
4. Put all of the data you want to analyze in one folder, and run the pre-analysis pipeline program pipeline.exe.
5. To extract and analyze ORGs, run the ORG analysis program iORG_summary_analysis.exe.

The configuration file:

At present, all user-facing functionality of 𝑓(Cell) depends on a json-based configuration file. The version that we cover here can be found in the config_files directory, or on Github here:

The base format of the configuration json has the following structure:

{
  "version": "0.2",
  "description": "An example configuration JSON for F(Cell).",
  "preanalysis": { 
  }
  "analysis": { 
  }
}

This corresponds to the following key/value pairs, where options for each are in parenthesis with the default in bold, e.g: your_mom: (**"is lovely"**, "wears combat boots"):

Key	Parent Key	Type	Options	Description
"version"	none	"string"	version string	The version of the configuration file used.
"description"	none	"string"	text	The description of the configuration. Useful if multiple configurations are used for your particular analysis, if you have multiple devices, or if you want to test multiple pipeline/analysis combinations.
"preanalysis"	none	JSON Object	none	A JSON object holding parameters for the pre-analysis pipeline. Expects video data that has been co-registered (self-aligned).
"analysis"	none	JSON Object	none	A JSON object holding parameters for the analysis portion of F(Cell).

Preparing your data for iORGs: The pre-analysis pipeline

To facilitate iORG analyses, we highly recommend running your dataset through our pre-analysis pipeline. The 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. Basic configuration keys/values for this section are as follows:

Basic pre-analysis keys and values:

Key	Parent Key	Type	Options	Description
"video_format"	"preanalysis"	"string"	parse-augmented string	The filename format of the video (e.g. avi, mp4, etc) associated with a single acquisition. Uses 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 tag formatting to extract file-specific metadata.

For advanced keys and their corresponding values, please see the advanced section on the preanalysis pipeline.

Time for Analysis:

Generally, when you are ready to analyze your dataset, you will want to mark the locations that you want to analyze. You can do this using any cone-marking software. When you have your coordinates, make sure they are in a file that matches the format described in the "queryloc_format" line of your configuration- otherwise they won't be detected by the software.

There are numerous other parameters that can be used in iORG analysis, many of them may be unique to your particular model system (human/macaque/tree shrew/squirrel), but most of them are fairly well conserved across species. The default values we use for analyses are published in Gaffney et. al; or, if you prefer to sift through it yourself, the meao_before_2024.json configuration file.

A basic analysis json section will contain a few json objects that look like the following:

"analysis": {
  "metadata": {
    "fields_to_load": {
    }
  },   
  "analysis_params": {
    "display_params": {
    }
  }
}

Basic analysis keys and values:

Key	Parent Key	Type	Options	Description
"video_format"	"analysis"	"string"	parse-augmented string	The filename format of the video (e.g. avi, mp4, etc) associated with a single acquisition. Uses tag formatting to extract file-specific metadata.
"image_format"	"analysis"	"string"	parse-augmented string	The filename format of the super-average image associated with the co-aligned datasets. Uses tag formatting to extract file-specific metadata.
"queryloc_format"	"analysis"	"string"	parse-augmented string	The filename format of the coordinate files (e.g. csv, txt, dat, etc) that you want to use to analyze your datasets. Uses tag formatting to extract file-specific metadata.
"metadata"	"analysis"	JSON Object	none	A JSON object holding parameters for the metadata associated with the dataset.
"analysis_params"	"analysis"	JSON Object	none	A JSON object holding parameters determining how the provided video data is analyzed by F(Cell). Our default values come from the values described in Gaffney et. al (2024)
"display_params"	"analysis_params"	JSON Object	none	A JSON object inside "analysis_params" that defines what data will be displayed and how.

Basic metadata keys and values:

Key	Parent Key	Type	Options	Description
"metadata_format"	"metadata"	"string"	parse-augmented string	The filename format, or database path of the metadata associated with a single acquisition. Uses tag formatting to extract file-specific metadata.
"stimulus_sequence"	"metadata"	[list]	integer frame numbers	The number of frames corresponding to the stimulus delivery pattern, in off/on sequence, that total to the total number of frames in the video. So, for a 150 frame video with a stimulus delivered at the 50th frame for 3 frames, this value would be [50, 3, 97].
"fields_to_load"	"metadata"	JSON Object	none	A JSON object holding key/value pairs of column headers useful for iORG analysis. If not specified, the software will load all columns within the file.
"framestamps"	"fields_to_load"	"string"	column string	The column name of the frame indices, or "framestamps" of the processed video data. Included to track which frames were dropped from the original video; if the data has been run through F(Cell)'s pipeline, then this value should be "FrameStamps".

Basic display keys and values:

Key	Parent Key	Type	Options	Description
"pause_per_folder"	"display_params"	boolean	(**true** / false)	Pauses the script after each folder, to allow you to review the data.
"saveas"	"display_params"	list	string of extensions	If defined, saves the figures as the specified extensions. Default: ["png","svg"]
"pop_summary_overlap"	"display_params"	JSON Object	none	F(Cell) performs a cross query point summary of all iORG signals, or a "population summary", showing all videos in the analysis location overlapping. This section controls how the population summarized iORG signals from each video are displayed.
"stimulus"	"pop_summary_overlap"	boolean	(**true** / false)	Displays all the iORG summary signals associated with a stimulus delivery.
"control"	"pop_summary_overlap"	boolean	(**true** / false)	Displays all the iORG summary signals associated with a no stimulus delivery.
"relative"	"pop_summary_overlap"	boolean	(**true** / false)	Displays all the iORG summary signals with the control summary subtracted from the stimulus.

For advanced keys and their corresponding values, please see the advanced section on analysis.