1

AQuA2: Activity Quantification and Analysis

User’s Guide

2

Installation and Preparation

3

Installation

ATP Ca2+

• Environment:
• MATLAB package:
• Recommend MATLAB 2022b. (Support Windows, Mac, and Linux)
• Required toolboxes:
• Image processing toolbox
• Statistics and machine learning toolbox
• Signal processing toolbox
• Curve fitting toolbox
• Download the newest AQuA2 package from https://github.com/yu-lab-vt/AQuA2
• Fiji Plugin:
• Latest version of Fiji. (Support Windows, Mac, and Linux)
• Download the newest release .jar file from https://github.com/yu-lab-vt/AQuA2-Fiji
• Download three .jar files in "lib" folder
• Move "AQuA2.jar", "MorphoLibJ_-1.6.2.jar", "jdistlib-0.4.5.jar" files into "Fiji.app\plugins"

​

4

Preparation

ATP Ca2+

• Input data:
• 2D Image + time:
• Use TIFF stack as input data
• 8, 16 or 32 bit supported
• Use .mat file (3D data matrix, with third dimension the time dimension) (for GUI only)
• 3D Image + time:
• Use .mat file (4D data matrix, with fourth dimension the time dimension)

If your data include 2+ channels, please separate them in different TIFF files.

​

• Memory requirement:
• At least 5 x data size, since there would be temporary variables used.

5

Let’s start !

6

Open the software

ATP Ca2+

• MATLAB:
• Open ‘aqua_gui.m’ and run

​

• Fiji plugin:
• Click ‘Plugins’ -> ‘AQuA2’

​

• GUI will appear!

​

​

​

In the following, we will take MATLAB version as an example to introduce AQuA2.

But don’t worry, Fiji plugin has almost the same function and interface.

7

Load Data

ATP Ca2+

1. Click ‘New project’
• If you saved an existing project file before, click ‘Load existing’
2. Select the data in the prompted dialogue
• (Optional )For dual-color data, also select the data in channel 2.
3. Select the preset parameters
• Different data type may have different parameters
4. Click ‘Open’ button
• For large dataset, it may take a while.

​

Temporal resolution and spatial resolution can be modified, but it will only impact the output features.

(Optional) You can load parameters through ‘Load presets’.

1

2

3

4

8

Formal graphical user interface

Adjust to get a better view

Jump to specific frame

Control play speed

Adjust the field of view

Data with overlay

Draw ROI and check its curve

9

(Optional) Region, landmark, mask, and direction

10

Define cell boundary/regions

• Draw cell boundaries, or regions, if you:
• Do not want events outside drawn regions to be detected (Like a mask)
• To calculate region-related features after detection if regions are drawn
• Click ‘+’ to draw a region.
• To remove a drawn region, click ‘-’ and click the region to delete.
• To drag a drawn region, click ‘->’ and drag the region to move.
• To name a drawn region, click ‘Name’ and click the region to add name.
• To save and load the region, click ‘Save’ and ‘Load’.

One region

11

Define landmarks

• Draw landmarks, if you:
• Want landmark-related features, including distances from landmarks to events, directions, etc.
• Click ‘+’ to draw a landmark.
• To remove a drawn landmark, click ‘-’ and click the landmark to delete.
• To drag a drawn landmark, click ‘->’ and drag the landmark to move.
• To name a drawn landmark, click ‘Name’ and click the landmark to add name.
• To save and load the landmark, click ‘Save’ and ‘Load’.

Landmarks

12

Draw anterior direction

• Draw anterior if you:
• Want to use some specific direction in propagation-related features.
• Click ‘Draw anterior’, left click anywhere in the movie, do not release the button, drag the mouse toward the anterior direction. Release the button when done.
• If you want to re-draw the direction, click ‘Draw anterior’ and draw again. The new one will override the old one.

Anterior direction

13

Use ‘Mask Builder’ to add cell boundaries and landmarks

• Click ‘Mask builder’, if you:
• Want to add cell boundaries and landmarks according to image itself or another image with same image size.
• You will be asked to set a threshold on the image to get the foreground regions, and apply a minimum and maximum size threshold to clean un-needed ones
• You can use multiple images and take some operations between them.

14

Mask Builder

Load mask from the opened movie itself, from a TIFF file, or from a folder.

Adjust parameters to select regions

Name and types (region, landmark) of loaded masks

Click ‘Apply & back’ to save the masks as region and landmarks

You can combine regions with different masks

Region marker: Each region obtained in the region mask might contain multiple regions of interest. If you have another mask that can further separate the regions, you can load it as the region marker mask.

15

Detection pipeline

16

17

Detection pipeline

• Event detection pipeline is the major part of the GUI.
• Each tab represent one step.
• In any tab:
• Adjust parameters if needed
• Click ‘Run’ button
• Check the results (overlay)
• Click ‘Next’ button if results are satisfactory, or adjust parameters

18

Step 1: Preprocessing

• Image registration (Optional):
• Select any channel to align the image frames. (Can only support rigid image registration).
• Photobleach correction (Optional):
• Select options to correct bleach effect.
• Median filter (Optional):
• If salt and pepper noise exists, use median filter to remove it.
• Gaussian filter:
• Use Gaussian smoothing to improve SNR. Increase the radius when the noise is large.

In this step, the algorithm will estimate the background and model the noise.

19

Side-by-side view

• After step 1, GUI will automatically enter side by side view.

​

• Can choose any two to visualize.

Switch between single view and side-by-side view

Check smoothed data

20

Step 2: Active region detection

• Intensity threshold:
• Adjust threshold to remove false positive voxels. For noisy data, increase it.
• Minimum duration (frames):
• Filter out the regions with small durations.
• Minimum size (pixels):
• Filter out the regions with small area sizes.
• Maximum size (pixels):
• Filter out regions with too large size.
• Circularity:
• Filter out regions with weird shapes. Range from 0 to 1. 1 is perfect circle, 0 is no limitation on shape.

In this step, the algorithm will detect the active regions that may contain signal activities

21

Step 3: Temporal segmentation

• Enable/disable temporal segmentation.
• Seed size relative to active region:
• The limitation on seed size. Range from 0 to 1. To avoid wrongly segment the region, can increase it.
• Zscore of significance:
• Increase it to avoid wrongly segmentation and remove false positives
• Maximum dissimilarity:
• The largest allowed temporal pattern dissimilarity of one activity. Range from 0 to 1. 0 requires the exactly same pattern in one activity.

In this step, the algorithm will segment the active regions temporally in case one region may contain multiple peak patterns temporally. (Seed detection, seed grow, merging seeds with similar temporal patterns).

22

Step 4: Spatial segmentation

• Enable/disable spatial segmentation.
• Source size relative to super event:
• The limitation on signal source size. Range from 0 to 1. To avoid wrongly segment the region, can increase it.
• Sensitivity to detect source:
• Range from level 1 to level 10. Level 10 is the most sensitive to do segmentation. Decrease it if wrongly segment the super events.
• Enable/disable temporal extension:
• Extent the events temporally, from the voxels above fixed threshold to a larger temporal intervals, that starts from 20% rising time to 20% decay time.

In this step, the algorithm will segment the super events spatially in case one super event may arise from multiple signal sources. (Propagation calculation, signal source, segmentation).

23

Step 5: Global signal detection

• Enable/disable global signal detection.
• Global signal duration:
• We assume global signal should have a longer duration than previous detected signals. Here is the limitation of minimum duration for the global signals.

In this step, the algorithm will detect the global signals that hidden behind the detected events before. (Remove events from dF, do previous step again)

24

Step 6: Feature extraction

• Ignore/calculate decay speed.
• Enable/disable calculating propagation-related features
• Calculate propagation metrics, like propagation direction, speed, and etc.
• This step may take a while to calculate this feature.
• Enable/disable calculating network features.
• Calculate region-related features, like the distance to the landmark, how many events occur together, and etc.
• This step may take a while to calculate this feature.

​

In this step, the algorithm will quantify the detected signals.

25

View results of previous steps

• Click ‘Type’ in feature overlay.
• Select desired overlay.
• Click ‘Update overlay’ Button.

​

26

Proofread and favorite table

27

Post-detection GUI

Curve of selected event

Favorite list

Feature overlay

Visualization related

Detection pipeline

Regions

Proofreading

Export

Proofreading

• For features listed in proofreading panel, events outside the ranges can be removed by selecting the checkbox.

​

• Features removed here will not be exported and not shown in movie

Enable features for filtering

Adjust the ranges

29

Proofreading

• Click view/favorite, then click an event in the movie to view its curve. This will also add it to the favorite list.
• An event in favorite list has a golden boundary. The event ID is also shown.

​

• Click ‘delete/restore’, then click an event in the movie to delete that event. If it is already deleted, it will be restored.
• A removed event has a red boundary.

view/favorite

delete/restore

30

Favorite event

Basic features

Clicked event

31

Favorite event

32

Check rising map

• To view rising map of each event:
• Enable side-by-side view
• Choose ‘Rising map’ in the dropdown menu. (Three options: 20%, 50%, 80%)

​

• The rising map use color to indicate the rising time, with the color bar below showing the detailed frame.

​

• Only the rising maps of events added in the favorite list can be shown.

33

View features

34

View features

• Visualize specific features/overlay:
• Select desired overlay type, feature, and color map in the dropdown menu.
• Then click ‘Update overlay’ button to visualize the results.

​

• ‘Update features’:
• Recalculate the features under current condition.

35

View features

• Choose overlay type to visualize

• Choose which feature to visualize

• Choose color map for visualization

For a complete list of features that can be used as well as their description, see online document. https://aqua-doc.readthedocs.io

36

Example: 50%-50% duration

• Select 50%-50% duration feature.

​

• Choose green-red color map.

37

CFU module

38

39

Enter CFU GUI

• After detecting all events, click ‘CFU detect’ button.

​

• CFU GUI will appear.

40

CFU GUI

Visualization control

CFU detection

CFU relationship analysis

CFU group

We use another dataset as example

41

CFU detection

42

CFU detection

• Overlap threshold:
• The allowed minimum overlap for grouping events into CFU.
• A larger value will be strict on CFU detection (hard to cluster the events).
• Minimum number of event in CFU:
• Filter out the CFUs with fewer events.
• Enable/Disable to use weighted map of event for clustering.
• Check: use weighted map. Not check: use footprint.

​

43

Operations

• View/favorite:
• Similar to the button in previous GUI.
• Can add favorite CFU into favorite CFU list.
• The curve of CFU will be visualized in the bottom.
• Selected CFU will be surrounded by golden boundaries.

​

• Favorite CFU manager:
• Similar to favorite event table in previous GUI.

44

Operations

• Window size:
• The window size for judging whether two events cooccur.
• Large value will consider a loose criteria for cooccurring pair of events.

​

• Shift:
• Shift the time window center to allow a flexible dependence measurement.

cooccur

window size

cooccur

shift

45

Operations

• Pick CFUs:
• Click two CFUs on the image panel.
• A new figure window will plot the curves of selected CFUs, and their interaction.
• Selected CFU will be surrounded by red boundary.

​

• All dependencies:
• Calculate dependencies of all potential CFU pairs.

46

CFU group

• p-Value threshold:
• The allowed maximum p-value for grouping CFU.
• A smaller value will be strict on grouping CFUs.

​

• Minimum number of CFU in group:
• Filter out the groups with fewer CFUs.

​

• ‘Run’ Button:
• Cluster CFUs into groups

47

CFU group manager

• When a group is selected, the image panel will only show the CFU in that group.

​

• ‘Show relative delay’ button will be enabled, for visualization the activating order of CFUs.
• CFUs with blue color are activated earlier.
• CFUs with yellow color are activated later.

Early

Late

48

Export and load projects

49

Export results

• To export results, click ‘Export/save’ and you will be asked to choose the place for exporting.
• A dialogue will appear and ask you to give a postfix to the export file name. The movie name will be automatically included.
• We will save the results in the ‘res’ data structure in the exported ‘mat’ file.

​

• To export the movie overlay as well, check ‘Movie with overlay’.
• To export the features of events, check ‘Feature Table’.

50

Load projects

• You can load the results later. After opening the GUI, select ‘Load existing’ and select the saved ‘.mat’ experiment file
• Alternatively, you can load the ‘.mat’ to MATLAB, and launch the GUI with: aqua_gui(res), or aqua_gui(YOUR_PATH_FOR_MAT_FILE)

51

Load CFU projects

• After loading your res file, you may load your CFU results as well
• Click ‘CFU detect’ button like before, and then click ‘Load CFU Results’ to import the .mat file of CFU (It’s different from your .mat of the detection pipeline!)

52

Load CFU projects, view only

• Use this viewer, if you:
• Only have saved cfu res file
• Want to view CFU results directly
• Run ‘CFU_Viewer_Standalone.m’, and then choose your cfu res file.

Thank you

53