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. We fully appreciate that nobody wants to make a configuration file manually. Too many opportunities to misplace a number, then suddenly your analysis is borked. So, we created a graphical configuration generator that you can use to make your files. You can make them in "simple mode"- shown here- but you can also run it in an advanced mode, which shows you all possible bells, knobs, and whistles that you can adjust in the software.

Without further ado, lets walk on through. When you start config_generator.exe, you will be presented with the following:

Just select "Create New Configuration", and press "Next".

Then select "Simple Generation", and press "Next"- or, if you're feeling daring, click on "Advanced Generation" and see how far the rabbit hole goes...

At this screen, you'll be allowed to specify the version of the json file, and a description of it, as a message for your future self. Then press "Next"

Preparing your data for iORGs: The pre-analysis stage

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.

On this page, you'll first need to specify the format of your data for the alignment/pre-analysis stage, by using a mixture of fixed text (like underscores, or the file extension) and tags (essentially variables) that we use to automatically grab information from your filenames. If you click on the "Edit..." button next to any of the filename types, you can input the format of your data.

The above image is of the format editor for a filename. In this window, you can construct a filename format by adding or removing pieces of the filename that carry meaning for your lab. You can always click on each element to see what it stores, or you can refer to the tag parsing page to learn more.

Often times, we can collect data from multiple modalities simultaneously but not wish to work with all of it. So, once you've created your filename formats, you can (optionally) specify which modalities you would like to use in the alignment/pre-analysis stage.

In this window, you can specify what modalities you have by simply adding them to a list. Here we're adding both Apples and Oranges to the list, and we'll ignore all other modalities.

You can also specify how you'd like all of the output data to be grouped for purposes of alignment or analysis. This also determines the folder structure that the software uses when outputting the aligned data. In our group, we commonly group by ({LocX},{LocY}) because we want to ensure that when the data is being aligned and/or analyzed, that we can reasonably do so.

Once you've completed all these steps, you get something like this.

Clicking "Next" brings you to a similar window, except now you are specifying the format for data ready for analysis.

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.

When you specify your analysis data formats, the software brings you to a screen that summarizes all of your choices, and lets you save the data.

You might notice that we didn't give you many options with regards to the analysis parameters themselves; that's because this is Simple mode! There are numerous other parameters that can be set in ORG 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.

If you want access to all of the possible parameters, feel free to save the configuration file you made here, and re-open it with the software. This will give you access to all of the bells and whistles we have.

Happy analyzing!

For the risk-takers and intermediate users: Manually creating a 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).

Basic pre-analysis alignment stage 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.

Basic analysis stage structure:

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.