BARCODE 2.0 Tutorial Draft

1Installation

To install the required packages, you can use PIP to install them using the following command:

$ pip install -r requirements.txt

Keep in mind that this code was developed in Python 3.12. Versions of Python prior to 3.12 may not be able to run this program from the source code.

$ pip install av

The required packages for BARCODE 2.0 are:

• ImageIO ≥ 2.34.1
• Matplotlib ≥ 3.8.4
• ND2 ≥ 0.10.1
• Numpy ≥ 2.0.1
• OpenCV Python ≥ 4.10.0.84
• PyYAML ≥ 6.0.2
• Scipy ≥ 1.14.0
• Scikit-Image ≥ 0.24.0

2Data Preparation

3General Walk-through

When first using the BARCODE application, it is recommended to begin by processing a single channel from a single file. This allows the user to test the selected parameters and verify that the output is reasonable before processing an entire dataset.

To analyze a new file, select Process Data. In the Execution Settings tab, use Process File to choose a single file, or use Process Directory to choose an entire folder. The Browse File button allows the user to search the file system for acceptable microscopy files, while the Browse Folder button allows the user to select a directory for batch processing.

Then, choose whether BARCODE should analyze a specific channel or all channels in the selected data. The Choose Channel setting is used to select a single channel, while Parse All Channels scans every available channel in each video.

Selecting a channel less than 0 will result in reverse indexing of channels. For example, selecting −1 will run the program on the last channel of every video scanned, rather than the first.

In the general execution settings, it is recommended that the user turn on the three main analysis branches: Image Binarization, Optical Flow, and Intensity Distribution. These selections control which branches of the program are run on the data.

The dim data settings allow the user to choose whether BARCODE should process files or channels that may have low contrast. The Scan dim files option allows dim files to be processed, and the Scan dim channels option allows dim channels to be processed. These settings can be useful when the dataset contains low-signal videos that the user still wants to include in the analysis.

If dim data are included, BARCODE will process these files or channels, but will flag them in the summary CSV output as potentially less reliable due to low contrast.

The Verbose Output setting provides additional information while the data are being processed, including progress updates, processing time, and whether an input video was classified as dim.

The output settings control additional files generated by BARCODE besides the summary CSV file. The Save Graphs setting saves PNG visualizations of selected analysis outputs. The Save Reduced Data Structures setting saves the reduced data structures used for analysis, such as binarized images, optical flow fields, and intensity distributions, as CSV files. These reduced data structures can be used for further analysis or verification.

The Generate Dataset Barcode setting creates a color-coded BARCODE visualization for the dataset. This barcode provides a compact visual summary of the output metrics for the analyzed files and channels.

After the application is run on a file or directory, BARCODE creates output files in the selected data location. These outputs include the summary CSV file and, depending on the selected settings, visualizations, reduced data structures, a dataset barcode, timing information, and a saved YAML configuration file.

The YAML configuration file stores the selected settings from the run. This file can be loaded later using the Configuration YAML File option, allowing the same settings to be reused for future datasets.

4Adjusting Parameters

This section of the tutorial discusses how changing parameters affects the output BARCODE and why users may or may not want to adjust these parameters.

4.1  Downsampling and Averaging

4.1.1  Frame Step

To increase processing speed and reduce the data size, videos can be downsampled in time by choosing to analyze every kth frame. This Frame Step parameter, k, allows the customization of the speed and precision of each branch. We have found that k = 10 provides sufficient resolution and accuracy for all branches while maintaining rapid processing times. In BARCODE 2.0, Frame Step is set separately for the Image Binarization, Optical Flow, and Intensity Distribution branches. Increasing the frame step decreases runtime, but may reduce temporal resolution in the corresponding branch.

4.1.2  Percentage of Frames for Analyzing Changes in Metrics

The frame start and end percentage sets the percentage of frames, X, at the beginning and end of the video used to compute the change in the various metrics. By default, these metrics compare the change in values averaged over the first 5% and last 5% of frames in the video. Increasing X can reduce noise by increasing the number of frames that contribute to the quantity, but will also reduce temporal resolution.

4.1.3  Binarization Threshold

The Binarization Threshold is an important parameter that determines what pixels within the image represent material and should be set to 1, and which pixels represent background or noise and should be set to 0. The Binarization Threshold is calculated for each frame as

(1 + Offset) × Mean Pixel Intensity.

Users should take care when adjusting this value, as it can affect the results of the Binarization branch.

The effect of the threshold offset selection can be evaluated by transforming the raw image into binary datasets based on different threshold values. As the threshold decreases, more noise may be included. As the threshold increases, material features may be lost.

4.2  Binarization Settings

4.2.1  Binning Ratio 2.0

The Binning Ratio controls the extent of spatial downsampling performed before binarization. The image is averaged over p × p pixel regions, reducing noise and decreasing data size. Larger binning ratios can improve processing speed and reduce noise, but may also remove small spatial features. The default binning ratio in BARCODE 2.0 is 2.

4.2.2  Output Unit Conversion 2.0

The Output Unit Conversion setting changes selected image binarization area metrics from field-of-view percentage units to physical area units based on the selected length unit. This uses the micron-to-pixel ratio from the Execution Settings or the metadata read from ND2 files.

4.2.3  Invert Binarization 2.0

The Invert Binarization option reverses the binarized image. This can be useful when the material and background intensities are inverted relative to the default assumption.

4.2.4  Fraction of Neighboring Islands 2.0

The Fraction of Neighboring Islands parameter is used to calculate Mean Island Separation. After binarization, BARCODE identifies each island and calculates the centroid of each island. For each island, the program then measures distances to nearby island centroids. This parameter controls how many neighboring islands are included in that distance calculation.

For example, if this default value is set to 0.10, BARCODE uses approximately the closest 10% of islands when estimating the local island separation. Smaller values emphasize local spacing between nearby islands, while larger values include more distant islands and produce a more global estimate of island separation.

4.2.5  Minimum Island Size 2.0

The Minimum Island Size parameter can be used to reduce the influence of very small islands that may represent noise. Increasing this value filters out smaller connected components during binarization-based analysis and preview.

4.3  Intensity Distribution Settings

4.3.1  Number of Distribution Bins

The Intensity Distribution branch calculates the skewness and kurtosis metrics by binning the pixel intensity values for the selected frames, and then calculating the metrics on these distributions. By default, the number of bins is set to 300. Adjusting this parameter will adjust the number and width of the bins used to create the distribution.

Increasing the number of bins may more precisely capture pixel intensity values, but may result in noisier data. Decreasing the number of bins will result in less precision in the estimation of pixel intensity counts.

4.3.2  Changing the Distribution Noise Threshold

The distribution noise threshold determines the minimum pixel intensity probability allowed within a single bin for that bin to be evaluated. All bins with a normalized probability below this threshold will be removed from the calculation, and the distribution will be renormalized to ensure that the integrated probability is equal to 1. By default, this distribution noise threshold is set to 0.0005.

Decreasing this value can result in noisier data and potential inaccuracies in the calculation of the kurtosis and skewness metrics, while increasing this value can result in fewer pixels being counted toward the Intensity Distribution branch metrics.

4.4  Optical Flow Settings

4.4.1  Window Size

The Window Size parameter defines the size of the region around each pixel that is used to compute the local motion within the optical flow algorithm. Larger window sizes result in less noise being captured by the algorithm, but will result in less resolved motion fields. Smaller window sizes are more capable of detecting smaller movement within the material, but will be more susceptible to random noise. In BARCODE 2.0, this parameter is listed as Optical Flow Window Size. The Optical Flow Settings tab also includes a dynamic preview of the optical flow field, which can be used to inspect how the window size affects the resulting flow field.

4.4.2  Downsampling

Depending on the scale of movement within the data, it is possible to spatially downsample the image array, which can drastically increase the throughput of the Optical Flow measurements. The extent of downsampling is set by averaging together p × p regions of pixels, which reduces the original m × n field of view to a downsampled array of m/p × n/p pixels. Increasing p suppresses noise and improves detection of bulk movement while also reducing spatial resolution.

Care should be taken in downsampling videos that capture the movement of many smaller areas of material, as these small-scale motions may be lost in the averaging. This spatial downsampling also increases processing speed and reduces the RDS size. We have found p = 2–8 to provide sufficient resolution and accuracy while maintaining rapid processing times. By default, the program chooses p = 8.

4.4.3  Calibration Parameters

The micron-to-pixel ratio and exposure time are determined by the image acquisition settings. Allowable values of micron-to-pixel ratio range from 0.001 to 1000 microns per pixel. Allowable values of exposure time range from 0.001 to 3600 seconds. For ND2 files, these parameters are automatically read using the file metadata. In BARCODE 2.0, the Micron to Pixel Ratio and Exposure Time settings are located in the Execution Settings tab under Specify Metadata, rather than only in the Optical Flow Settings tab. The Length Unit and Time Unit settings control output labels and physical unit conversions.

5Analyze Existing Barcodes 2.0

BARCODE 2.0 introduces a new workflow for analyzing previously generated BARCODE outputs. Instead of rerunning the full image-processing pipeline, users can select Analyze Existing Barcodes from the home screen to work directly with existing BARCODE summary CSV files and reduced data structures. This workflow is especially useful for larger studies where image analysis has already been completed. Users can revisit the output files, generate aggregate summaries, compare datasets using consistent color limits, or export selected metric comparisons for further statistical analysis.

5.1  Barcode Generator & CSV Aggregator 2.0

The Barcode Generator & CSV Aggregator tab allows users to select one or more BARCODE summary CSV files and combine them into a single aggregate CSV file. This is useful when results from multiple files, folders, experimental conditions, or replicates need to be assembled into one dataset. Users can choose an output location for the aggregate CSV file and optionally generate an aggregate barcode visualization. The aggregate barcode provides a compact color-coded representation of the selected metrics across all included samples.

BARCODE 2.0 also allows users to generate comparison barcodes from multiple CSV files. When Generate Barcodes for Comparison is selected, BARCODE creates barcode visualizations for each input CSV using consistent metric limits, which makes it easier to visually compare datasets because the same colors correspond to the same metric ranges across all generated barcodes.

Users can also choose whether barcodes should be separated by channel, and can select a Sort Parameter to order samples by a chosen metric. If the sort parameter is left as Default, the barcode follows the original file order. The Select Metrics to Visualize in BARCODE option allows users to choose which metrics are included in the barcode visualization, when a user wants to focus on a subset of metrics rather than displaying all available BARCODE 2.0 metrics.

5.2  Barcode Metric Comparison 2.0

The Barcode Metric Comparison tab allows users to compare two selected BARCODE metrics from a summary CSV file. After selecting a CSV file, users choose Metric 1 and Metric 2. BARCODE then generates a dynamic preview plot showing the relationship between the two selected metrics across the samples in the CSV. This feature is useful for quickly checking relationships between BARCODE outputs. The selected metric pair can also be exported as a new CSV file for further plotting or statistical analysis.

5.3  Reduced Data Structure Visualization 2.0

The Reduced Data Structure Visualization tab allows users to inspect saved reduced data structure files generated by BARCODE. These files may include binarized images, optical flow fields, intensity distributions, spatial autocorrelation data, velocity correlation data, and related intermediate outputs.

After selecting a reduced data structure CSV file, users can move through frames using the preview frame slider. Depending on the selected RDS type, BARCODE displays the corresponding image, vector field, intensity distribution, or correlation distribution. This allows users to visually inspect intermediate outputs and verify that the analysis results are reasonable. This tool is also useful for quality control and troubleshooting. For example, users can check whether binarization accurately captures material structures, whether optical flow vectors are reasonable, or whether correlation functions behave as expected.

The preview can also be saved as a single frame or as a video using the right-click menu. For correlation data, users can also save all correlation distributions together for easier comparison across frames.

6Reading Barcodes

After generating the barcode for a dataset, how should it be interpreted? BARCODE visualizations provide a compact way to compare the output metrics across videos, channels, and datasets. In a barcode visualization, each row corresponds to an analyzed file or file-channel entry, and each column corresponds to one BARCODE metric. The color in each cell represents the normalized value of that metric for that entry.

The barcode is intended to give a quick visual summary of the dataset. Samples with similar color patterns across the metric columns have similar BARCODE profiles, while samples with different color patterns may represent different material structures or dynamics.

The color scale is applied separately to each metric. This means that colors should be interpreted column by column, rather than as absolute values across different columns. For example, a bright color in one metric column indicates a relatively high value for that metric, but it should not be directly compared to the same color in a different metric column unless the colorbars are considered.

When interpreting barcodes, users should also consider whether all analysis branches were run. If a branch was not selected during processing, the metrics from that branch will be saved as NaN values in the summary CSV file and may appear as missing or black cells in the barcode visualization.

In general, barcode visualizations are most useful for identifying broad trends, comparing samples, and selecting datasets or conditions for closer inspection. For more detailed interpretation, users should examine the corresponding summary CSV file, saved visualizations, and reduced data structures.

7Frequent QA

No BARCODE 2.0-specific changes are currently planned for this section. This section can be updated later if new common questions arise during testing or release preparation.