High‐Throughput Focal Adhesion Analysis Software for Automated Detection, Tracking, and Classification of Cell‐Matrix Adhesions

Abstract

Focal adhesions are dynamic multi‐protein complexes that mechanically link the actin cytoskeleton to the extracellular matrix through integrin receptors. A single migrating cell can contain >1000 adhesion structures simultaneously, exhibiting highly heterogeneous fates: only ∼3.5% of nascent adhesions mature into focal contacts or focal adhesions, while the majority turn over within minutes. Resolving this heterogeneity requires automated detection, tracking, and classification of individual adhesion trajectories at scale. Here we provide a step‐by‐step Basic Protocol for the Focal Adhesion Package, a MATLAB‐based pipeline that processes time‐lapse fluorescence images through 11 sequential steps, from sub‐pixel stage drift correction and cell masking through point source detection, particle tracking, focal adhesion segmentation, feature extraction, and machine learning‐based classification into 9 functional groups. The pipeline optionally integrates traction force microscopy and multi‐channel fluorescence data to perform event detection of significant signal rise and compute temporal cross‐correlations between protein recruitment and force generation at individual adhesions. For a typical 100‐frame movie, total runtime is ∼40 min using CPU‐parallelized optimization (∼15 min for preprocessing and detection, ∼25 min for feature extraction) on a standard workstation, with GPU acceleration reducing this to ∼27 min. We describe parameter selection criteria for each step and provide supplementary code recipes for programmatic access to outputs. The pipeline can be executed through a graphical user interface or automated using MATLAB scripts. © 2026 Wiley Periodicals LLC.

Support Protocol: Software installation and set up

Basic Protocol: Running the Focal Adhesion Package

Alternate Protocol: Batch processing multiple movies

INTRODUCTION

Focal adhesion analysis is critical for understanding how cells interact mechanically with the extracellular matrix (ECM). Cell‐matrix adhesions are dynamic multi‐protein complexes that mechanically couple the actin cytoskeleton to the ECM through integrin transmembrane receptors (Zaidel‐Bar et al., 2007). These adhesions play essential roles in cell migration, mechanosensing, and signal transduction (Han et al., 2021; Parsons et al., 2010). Automated focal adhesion analysis has become the standard approach for quantifying adhesion dynamics because: (1) a single cell can contain hundreds of adhesion structures at any given time; (2) adhesions undergo rapid assembly and disassembly on timescales of seconds to minutes; (3) nascent adhesions are diffraction‐limited structures requiring sub‐pixel detection methods; and (4) distinguishing adhesion fates (maturation vs turnover) requires tracking and classification of individual trajectories over time.

Focal adhesion analysis presents three computational challenges: (1) detection and segmentation of adhesion structures across a wide size range, from diffraction‐limited nascent adhesions (<0.5 µm in length) to large focal adhesions (>2 µm in length); (2) tracking of individual adhesions through time with gap closing for temporary disappearances; and (3) extraction of quantitative features and classification into functional groups. During cell spreading and migration, adhesions undergo a stereotypical lifecycle: nascent adhesions (NAs) form at the cell edge as diffraction‐limited structures, a small subset of which mature into larger focal contacts (FCs, 0.5 to 2 µm in length) and focal adhesions (FAs, >2 µm in length), while the majority disassemble (Bachir et al., 2014; Choi et al., 2008; Han et al., 2021). The ability to automatically distinguish these different adhesion fates is essential for understanding the molecular mechanisms governing adhesion maturation.

Understanding these maturation mechanisms requires capabilities beyond simple detection and tracking. First, force‐dependent protein recruitment at the adhesion level has emerged as a critical area of study. Super‐resolution microscopy has revealed that focal adhesions consist of distinct vertical layers: a membrane‐proximal integrin signaling layer containing FAK and paxillin, an intermediate force‐transduction layer containing talin and vinculin, and an actin‐regulatory layer (Kanchanawong et al., 2010). Quantifying how proteins such as vinculin are recruited to talin in a tension‐dependent manner, including the temporal sequence of their recruitment, therefore requires simultaneous multi‐channel analysis. Second, the relationship between adhesion dynamics and cellular traction forces has become central to understanding mechanotransduction, as traction force microscopy (TFM) studies have demonstrated that individual focal adhesions act as autonomous mechanosensors (Hur et al., 2020; Plotnikov et al., 2012), necessitating direct integration with TFM pipelines (Han et al., 2015). Third, reliable detection of nascent adhesions remains challenging because these diffraction‐limited structures are easily confounded with fluorescence noise. Fourth, distinguishing biologically meaningful adhesion subpopulations demands systematic quantification through multi‐dimensional feature extraction and supervised classification. Existing tools such as the Focal Adhesion Analysis Server (Berginski et al., 2011) provide automated, segmentation‐based detection and tracking of adhesions, but lack the sensitivity to reliably detect diffraction‐limited nascent adhesions and do not classify adhesions into functional subgroups based on their dynamic behavior.

The Focal Adhesion Package addresses these needs by providing: (1) automated multi‐channel intensity extraction at each adhesion location with temporal cross‐correlation analysis; (2) direct integration with TFM for force–adhesion correlation; (3) multiscale Gaussian fitting with statistical validation to reliably distinguish nascent adhesions from noise; (4) extraction of 22 quantitative features per adhesion track; and (5) machine learning‐based classification into 9 functional groups that distinguish distinct adhesion fates and behaviors (Han et al., 2021). Beyond its original development and application in Han et al. (2021), the Focal Adhesion Package has recently been used to classify nascent adhesion subpopulations and reveal how ERK signaling promotes a short‐lived, rapidly turning over nascent adhesion population that sustains persistent edge protrusion during cell migration (Shepherd et al., 2026).

In this article, we provide a step‐by‐step protocol for using the Focal Adhesion Package. Below, we present the overall pipeline architecture, illustrating the 11‐step workflow from raw fluorescence images to classified adhesion tracks with multi‐modal features. The Support Protocol describes software installation and setup. The Basic Protocol covers each step of the analysis pipeline in detail, including parameter selection for detection, tracking, segmentation, feature extraction, and classification, as well as optional integration with traction force microscopy (Steps 10 to 11) and multi‐channel fluorescence analysis (Steps 9 and 11). The Alternate Protocol covers batch processing of multiple movies. The pipeline can be executed using either the graphical user interface (GUI) or the object‐oriented FocalAdhesionPackage class for programmatic control. The software is built on the u‐track ecosystem (Jaqaman et al., 2008) and integrates with existing traction force microscopy pipelines (Mittal & Han, 2021).

PIPELINE OVERVIEW

The Focal Adhesion Package (Basic Protocol) consists of 11 processes (Fig. 1), organized into three tiers:

Figure 1.

Focal Adhesion Package pipeline architecture. The 11‐step pipeline consists of three main components: (1) Preprocessing (Steps 1 to 3, dashed boxes), optional image registration and cell masking; (2) Core Analysis (Steps 4 to 8, solid boxes), required detection, tracking, segmentation, feature extraction, and ML classification; (3) Multi‐modal Integration (Steps 9 to 11, orange boxes), optional integration with TFM force maps and multi‐channel fluorescence data. Arrows indicate data flow; dashed arrows indicate optional pathways.

Preprocessing (optional)

(Step 1) stage drift correction for sub‐pixel image registration, (Step 2) thresholding for cell mask creation, and (Step 3) mask refinement for morphological cleanup. Note that readers who do not have registered images or cell masks from other packages should run these steps, as they are necessary for accurate downstream analysis. They may be skipped only if pre‐processed images and masks are already available.

Core analysis (required)

(Step 4) point source detection using multiscale Gaussian fitting with statistical validation to distinguish nascent adhesions from fluorescence noise, (Step 5) tracking to link detections into trajectories across frames with gap closing, (Step 6) focal adhesion segmentation to identify mature adhesion structures (>0.5 µm) and assign each trajectory its adhesion state (NA, FC, or FA), (Step 7) adhesion analysis for extraction of 22 quantitative features per track, and (Step 8) adhesion classification using support vector machines to assign each track to one of 9 functional groups.

Multi‐modal integration (optional)

(Step 9) secondary channel reading for multi‐channel fluorescence or FRET (Förster Resonance Energy Transfer) intensity extraction at each adhesion location, (Step 10) traction force reading for TFM integration, and (Step 11) time lag calculation for temporal correlation analysis between adhesion fluorescence and traction force, or between primary and secondary fluorescence channels.

STRATEGIC PLANNING

Before beginning, consider the following experimental design decisions that determine which parts of the protocol to use.

Single‐channel vs multi‐channel imaging

If imaging a single adhesion marker (e.g., GFP‐paxillin), run Basic Protocol through Steps 1 to 8. For dual‐color experiments (e.g., talin‐GFP and vinculin‐mCherry), additionally run step 9 (Other Channel Reading) and step 11 (Time lag calculation) to quantify temporal recruitment differences between proteins.

With or without traction force microscopy

If bead images and a reference frame are available from a TFM experiment, run Steps 10 to 11 after completing the TFM Package pipeline separately. This enables force–fluorescence correlation at individual adhesions (see TFM Integration in Basic Protocol).

Single movie vs batch processing

For exploratory analysis of one movie, use the GUI (Basic Protocol). For systematic studies comparing conditions across many movies, use the programmatic batch workflow (Alternate Protocol).

Computational resources

Step 7 (feature extraction) is the computational bottleneck. On a standard workstation with CPU parallelization, expect ∼1 hr per movie (100 frames). GPU acceleration reduces this to ∼30 min but uses approximate fitting for Step 7.

SOFTWARE INSTALLATION AND SET UP

This protocol describes how to install the Focal Adhesion Analysis Package and its dependencies.

Necessary Resources

Hardware

• A computer with ≥16 GB RAM (32 GB recommended for large datasets), a multi‐core processor (CPU parallelization scales with core count), and ∼500 MB additional storage per movie for analysis outputs

  Optionally, an NVIDIA GPU with CUDA support enables GPU‐accelerated optimization.

Software

• MATLAB R2019b or later (R2021a+ recommended) with the following toolboxes:

  • Image Processing Toolbox
  • Statistics and Machine Learning Toolbox
  • Curve Fitting Toolbox
  • Parallel Computing Toolbox (for CPU/GPU optimization).
  • To verify that all required toolboxes are installed, run ver in the MATLAB command window before proceeding. Git is required for downloading packages from GitHub.

Files

• Input data

  Time‐lapse fluorescence microscopy movies with at least one channel showing focal adhesion markers (e.g., GFP‐paxillin, GFP‐vinculin, mCherry‐zyxin). For multi‐channel analysis, additional channels may include other adhesion proteins or FRET biosensors. For TFM integration, a separate bead channel and a reference (cell‐free) bead image are required. The TFM pipeline must be run separately prior to Steps 10 to 11.

• 1
  Open a terminal and navigate to your desired installation directory:

  
  
  cd ~/matlab/applications
  

• 2
  Clone the Focal Adhesion Package repository:

  
  
  git clone https://github.com/HanLab‐BME‐MTU/focalAdhesionPackage.git
  

• 3
  Launch MATLAB and add the Focal Adhesion Package to the MATLAB path:

  
  
  addpath(genpath('~/matlab/applications/focalAdhesionPackage'));
  savepath;
  

  Alternatively, add these lines to your startup.m file for automatic loading on each MATLAB launch. For parallelized optimization using multiple CPU cores, the parallel pool will use the number of physical cores by default. To override this (for example, to reserve cores for other processes), open MATLAB preferences, navigate to Parallel Computing Toolbox, and manually set the number of workers. Enabling “Automatically create parallel pool” avoids the need to call parpool manually before Step 7.

• 4Verify the installation by running movieSelectorGUI in the MATLAB command window. The Movie Selector GUI should open (Fig. 2), and "Focal Adhesion Package" should appear in the available packages list.

Figure 2.

Movie Selector window. Launched by the movieSelectorGUI command. The interface consists of a movies section (left) and an analysis packages section (right). (A) Movies panel; (B) New; (C) Open; (D) Prepare; (E) Detail; (F) View; (G) Delete; (H) Delete All; (I) Save as movie list; (J) Open (movie list); (K) Delete (movie list); (L) Analysis Packages panel.

RUNNING THE FOCAL ADHESION PACKAGE

This protocol describes the complete 11‐step analysis pipeline using the graphical user interface. The pipeline processes time‐lapse fluorescence images to detect, track, and classify focal adhesions. Also see Supporting Information below for supplementary Notes, Tables, and pipeline Figures.

Necessary Resources

Hardware

• A computer with ≥16 GB RAM (32 GB recommended for large datasets), a multi‐core processor (CPU parallelization scales with core count), and ∼500 MB additional storage per movie for analysis outputs

  Optionally, an NVIDIA GPU with CUDA support enables GPU‐accelerated optimization.

Software

• MATLAB R2019b or later (R2021a+ recommended) with the following toolboxes:

  • Image Processing Toolbox
  • Statistics and Machine Learning Toolbox
  • Curve Fitting Toolbox
  • Parallel Computing Toolbox (for CPU/GPU optimization).
  • To verify that all required toolboxes are installed, run ver in the MATLAB command window before proceeding. Git is required for downloading packages from GitHub.

Files

• Input data

  Time‐lapse fluorescence microscopy movies with at least one channel showing focal adhesion markers (e.g., GFP‐paxillin, GFP‐vinculin, mCherry‐zyxin). For multi‐channel analysis, additional channels may include other adhesion proteins or FRET biosensors. For TFM integration, a separate bead channel and a reference (cell‐free) bead image are required. The TFM pipeline must be run separately prior to Steps 10 to 11.

Launching the software

To launch the Focal Adhesion Package, start MATLAB and run movieSelectorGUI in the command window. This opens the Movie Selector window (Fig. 2), which consists of two main sections: a movies panel on the left (Fig. 2A) for managing image datasets, and an analysis packages panel on the right (Fig. 2L) for selecting processing pipelines.

The movies panel displays the list of movies to be processed. To create a new movie database, click New (Fig. 2B), which opens the movie edition interface (see Creating a Movie Database below). To open an existing movie or movie list, click Open (Fig. 2C) and select the corresponding MAT file. The Prepare button (Fig. 2D) enables batch creation of movie databases for image sets that have not yet been organized into channel‐specific folders (one folder per channel, one TIFF file per frame). Additional controls include Details (Fig. 2E) to review movie metadata, View (Fig. 2F) to visualize images and overlay processing results, Delete (Fig. 2G) to remove individual movies, and Save as Movie List (Fig. 2I) to save the current collection for later use.

Once movies are loaded, select “Focal Adhesion Package” in the analysis packages panel (Fig. 2) by clicking on its name, then click Continue to open the package control panel.

Creating a movie database

To create a new movie database, click New in the Movie Selector window to open the movie edition interface (Fig. 3). This interface allows the user to set up a database containing links to raw images, metadata, and stored analysis results.

Figure 3.

Movie edition window. For setting up the movie database. (A) Bio‐Formats import; (B) Import movie using Bio‐Formats; (C) Channels; (D) Delete; (E) Add Channel; (F) Advanced Channel Settings; (G) Output Path; (H) Movie Information; (I) Pixel Size; (J) Time Interval; (K) Numerical Aperture; (L) Camera Bit Depth; (M) Notes.

For proprietary image formats supported by Bio‐Formats (e.g., ND2, CZI, LIF), click Import movie using Bio‐Formats. If “Import metadata using Bio‐Formats reader” is checked, the software will automatically populate movie and channel information from the file metadata. For multi‐position acquisitions, one movie database will be created per position.

Alternatively, for TIFF sequences organized by channel, use the Add Channel button to select folders containing images for each channel. Each channel (wavelength) must be in a separate folder with one file per frame, and all channels should have the same number of images with identical dimensions.

After adding channels, click Advanced Channel Settings to open the channel configuration window (Fig. 4). Here, specify channel‐specific information including the imaging mode, fluorophore, excitation and emission wavelengths, and exposure time. The standard deviation of the point‐spread function is automatically calculated from the emission wavelength, pixel size, and numerical aperture; note that the emission wavelength is required for this calculation.

Figure 4.

Channel settings window. For configuring channel‐specific parameters. (A) Channel; (B) Channel information; (C) Imaging mode; (D) Fluorophore; (E) Excitation Wavelength; (F) Emission Wavelength; (G) Exposure Time; (H) PSF Standard Deviation, automatically calculated from emission wavelength, pixel size, and numerical aperture; emission wavelength is required for this calculation.

In the movie edition interface, fill in the required metadata: Pixel Size (camera pixel size in the object domain, in nm), Time Interval (seconds between frames), Numerical Aperture (objective NA), and Camera Bit Depth (typically 16 for sCMOS cameras). Note that these fields are automatically entered if the Bio‐Formats file is successfully imported with metadata. Optionally, add notes describing the experimental conditions.

Click Select Path in the Output panel to specify where analysis results will be saved. Each movie should have its own output folder to prevent results from being overwritten. Finally, click Save to create the movie database, which is stored as a MAT file that can be reloaded later using the Open button in the Movie Selector.

Running the analysis pipeline

With the movie database created and the Focal Adhesion Package selected, the package control panel displays all 11 processing steps (Fig. 5). Each step can be configured by clicking its settings icon (gear). Steps can be run individually or in sequence using the Run button. The following sections describe the configuration of each step.

Figure 5.

Focal Adhesion Package control panel. Showing all 11 processing steps. Each step has a settings icon (gear) to configure parameters. Steps are organized into preprocessing (Steps 1 to 3), core analysis (Steps 4 to 8), and multi‐modal integration (Steps 9 to 11). Green checkmarks indicate completed steps.

• 1(Optional) Stage drift correction.

  Stage drift correction compensates for sub‐pixel movements of the microscope stage during time‐lapse acquisition using efficient subpixel registration (Fig. 6). Select all channels to be corrected, choose Frame 1 as the reference frame, and set the upsampling factor (usfac) to 100 for highest accuracy or 20 for faster processing. This step can be skipped if stage drift is minimal (<1 pixel over the acquisition period).

Figure 6.

Stage drift correction settings. Configure channels for registration, reference frame number, and upsampling factor (usfac) for sub‐pixel accuracy.

• 2Thresholding.

  Thresholding creates a binary mask identifying the cell area; this is for cell segmentation, not adhesion segmentation (Fig. 7). Choose the channel that best represents the cell body. Four thresholding methods are available: MinMax uses the intensity range; Otsu minimizes intra‐class variance and works well for bimodal intensity distributions; Rosin is suited for unimodal distributions with a low‐intensity tail; and Percentile thresholds by intensity percentile and is recommended when significant photobleaching occurs, as it is less sensitive to global intensity shifts.

  To illustrate how these methods differ in practice, Figure 8 compares the four thresholding methods applied to the same cell image at multiple threshold levels. For the three automatic methods (MinMax, Otsu, and Rosin), results are shown at 0.8×, 1.0×, and 1.2× the automatically determined threshold. For the Percentile method, the 90th, 95th, and 99th percentiles are shown. Lower thresholds produce larger cell masks that may include background, while higher thresholds yield tighter masks that may exclude dimmer cell regions. In general, the 1.0× automatic threshold provides a reasonable starting point for most images; users should use the Preview button to verify mask quality and adjust the method or threshold accordingly.

  Automatic thresholding may fail when cell body fluorescence is non‐uniform or when background is high; use the Preview button to check segmentation quality across multiple frames, including later frames where photobleaching may reduce signal. If automatic methods fail, manual segmentation can be used. Note that the cell mask produced here is required for edge motion estimation in Step 7 and is also required for adhesion classification in Step 8. Expected output is shown in Fig. 9A.

Figure 7.

Thresholding settings. For cell mask creation. Select the channel representing the cell body and choose the thresholding method appropriate for the image characteristics (MinMax, Otsu, Rosin, or Percentile). The cell mask produced here is required for edge motion estimation (Step 7) and adhesion classification (Step 8).

Figure 8.

Thresholding method comparison. Four thresholding methods applied to the same GFP‐vinculin image at varying threshold levels. Rows correspond to the four available methods (MinMax, Otsu, Rosin, Percentile). For MinMax, Otsu, and Rosin, columns show the refined cell mask at 0.8×, 1.0×, and 1.2× the automatically computed threshold. For Percentile, columns show the 90th, 95th, and 99th percentile thresholds. Red contours indicate the detected cell boundary after mask refinement (Step 3). The first column displays the raw fluorescence image for reference.

Figure 9.

Expected outputs from core analysis Steps 2 to 8. All images show a ChoK1 cell expressing GFP‐vinculin on a 5 kPa substrate. (A) Step 2 (Thresholding): binary mask identifying the cell area. (B) Step 3 (Mask Refinement): morphological operations remove disconnected regions. (C) Step 4 (Point Source Detection): detected nascent adhesions overlaid on the fluorescence image. (D) Step 5 (Tracking): adhesion trajectories colored by individual track. (E) Step 6 (FA Segmentation): segmented FCs (0.5 to 2 µm) and FAs (>2 µm) overlaid on fluorescence. (F) Step 8 (Classification): trajectories colored by group (G1 to G9).

• 3Mask refinement.

  Mask refinement applies morphological operations to clean up the thresholded mask, particularly useful when there are multiple disconnected regions (Fig. 10). Key parameters include: MinimumSize, i.e., the minimum area in pixels that will be retained (10 pixels corresponds to ∼1 µm² with a 60 × objective); ClosureRadius, i.e., the distance for morphological closing (dilation followed by erosion); and ObjectNumber, i.e., the final number of segmented objects to retain (set to 1 if analyzing a single cell). Do not use Mask Edge Refinement unless specifically needed for fine boundary correction. Expected output is shown in Fig. 9B.

Figure 10.

Mask refinement settings. Configure minimum object size, closure radius, and number of objects to retain.

• 4Point source detection.

  Point source detection identifies diffraction‐limited nascent adhesions in each frame using multiscale Gaussian fitting with statistical validation (Fig. 11). Select only the “master” adhesion channel; if imaging two adhesion proteins (e.g., talin and vinculin), choose the protein known to be recruited earlier (e.g., talin is recruited before vinculin). Also select the mask within which point sources will be detected. Expected output is shown in Fig. 9C.

  Critical parameters for Step 4:

  • a.
    PSF Sigma. The expected standard deviation of the PSF in pixels, used to initialize the Gaussian fitting model. Since pointSourceDetection operates entirely in pixel units, the user must compute this value as:

    $${\sigma }_{\mathrm{pixels}}=\frac{{\lambda }_{\mathrm{em}}}{2·\mathrm{NA}·\mathrm{pixel}\_\mathrm{size}(\mathrm{nm})}$$
    For example, for GFP (λ_em = 510 nm) imaged with NA = 1.49 and pixel size = 67 nm: σ = 510 ÷ (2 × 1.49 × 67) ≈ 2.55 pixels. The theoretical value is a good starting point; increase σ slightly if too many noise detections appear or decrease it if true adhesions are being missed.
  • b.
    Alpha. The significance level for statistical acceptance of a Gaussian fit (default: 0.05). Lower values are more stringent and reduce false positives at the cost of missing faint adhesions.
  • c.
    Fit Model. Use “xyAc” to fit position (x,y), amplitude (A), and background (c) with fixed standard deviation (more robust for noisy data), or “xyAsc” to additionally fit the standard deviation (more accurate for high‐SNR data).
  • d.
    Max # Mixtures. The maximum number of overlapping Gaussians fitted within a single window (default: 5). Set to 1 for sparse adhesion fields; increase only if adhesions are densely packed and overlapping detections are expected.
  • e.
    Redundancy Radius. Removes duplicate detections within a given radius after fitting (default: 0.25 pixels). Keep as default unless detections appear artificially doubled.
  • f.
    Fit Window Size. The half‐width of the fitting window in pixels (default: 4σ). Increase only if adhesion PSFs are unusually large.

Figure 11.

Point source detection settings. Configure the detection channel, mask selection, PSF sigma, significance level (alpha), and Gaussian fitting parameters.

• 5Tracking.

  Tracking links detections across frames into coherent trajectories using the tracking algorithm (Fig. 12). Set Problem Dimensionality to 2 for 2D tracking.

  For gap closing, set Maximum Gap to Close to 2 frames: adhesions are relatively stable structures compared to rapidly diffusing receptors or virus particles, so gaps longer than 2 frames most likely indicate a lost detection rather than a genuine disappearance. Set Minimum Length of Track Segments to 1 to include all track segments in gap closing and maximize trajectory recovery. Do not enable segment merging or splitting, as adhesions do not typically merge or split. Optionally, enable “Plot histogram of gap lengths” to assess whether the maximum gap parameter is appropriate; the histogram should decay monotonically and not plateau at longer gaps, which would indicate that the gap parameter is too permissive. Enable “Show calculation progress in command line” to monitor progress. The frame‐to‐frame linking runs in three iterations (forward, backward, forward): the backward pass refines the Kalman filter state estimates learned during the forward pass, and the second forward pass uses those improved estimates to produce the final track segments. In the gap closing window (Fig. 13), there is an exponent entry field that controls how the search radius scales with gap length; this value should be set lower than the default, as adhesions move slowly and a tight search is preferred.

  • a.
    Frame‐to‐frame linking (Fig. 14). Enable directed motion to account for the slow rearward sliding of nascent adhesions at the cell edge; this asymmetrically expands the search area in the direction of recent displacement within each frame pair, improving linking for sliding NAs. The Search Radius should be kept low (1 to 1.8 pixels for a 60× objective with ∼67 nm/pixel and ∼5 s frame interval); scale proportionally for different pixel sizes or frame rates. For the Brownian Search Radius bounds (Lower Bound and Upper Bound), smaller values are recommended because focal adhesions move slowly compared to other tracked particles; values of 1 and 2 pixels are appropriate starting points. For gap closing (Fig. 13), set both scaling powers low: Scaling Power in Fast Expansion Phase to 0.11 and Scaling Power in Slow Expansion Phase to 0.01. These parameters control how rapidly the search radius expands as a function of gap length; low values keep the search tight and reduce false connections across longer gaps.
  • b.
    Kalman filtering. Select “None of the two above” to use a purely Brownian motion model. Although adhesions slide rearward, this sliding lacks the persistent unidirectional velocity of motor‐driven particles, i.e., the directed motion search expansion above handles short‐term sliding at the frame‐pair level, while the Brownian Kalman model correctly reflects the absence of long‐range directional persistence. Expected output is shown in Fig. 9D.

Figure 12.

Tracking settings. For linking detections into trajectories. Configure gap closing parameters and motion model options.

Figure 13.

Gap closing settings. Configure gap closing parameters for trajectory recovery across missed detections. The exponent entry field controls how the search radius scales with gap length and should be set lower than the default value, as focal adhesions move slowly and a tight search radius is preferred.

Figure 14.

Frame‐to‐frame linking settings. Configure search radius and directed motion parameters for linking detections between consecutive frames. Brownian Search Radius Lower and Upper Bounds should be set to small values (e.g., 1 and 2 pixels) because focal adhesions move slowly compared to other tracked particles.

• 6Focal adhesion segmentation.
  Focal adhesion segmentation (segmentMovieFocalAdhesions) identifies larger, mature adhesion structures by combining initial blob segmentation with steerable filtering and spatiotemporal morphological post‐processing (Fig. 15).

  • a.
    Split Filter Sigma (nm). Despite its GUI label, this parameter sets the sigma of a 2nd‐order steerable filter (hardcoded in the function) that detects intensity troughs between adjacent adhesions and uses them to separate closely apposed FAs. The order is fixed and not user‐controllable. The value must exceed the diffraction limit: values below ∼200 nm (e.g., 70 nm) introduce artifacts by responding to sub‐resolution noise rather than genuine inter‐adhesion troughs. A value of 300 nm is appropriate when FAs are large and clearly separated; use 200 to 250 nm when FAs are smaller or more closely packed. The parameter is entered in nm and converted to pixels internally.
  • b.
    Min Vol*Time (µm²·s). Treats the 3D mask (area × time) as a volume and removes objects below the specified threshold using bwareaopen. This eliminates small and/or short‐lived segmentation artifacts while retaining genuine adhesions. A value of 1 µm²·s is typically sufficient. The parameter is entered in physical units and converted to pixels²·frames internally using pixel size and frame interval.
  • c.
    Opening Radius XY (nm) and Opening T (s). These perform a 3D morphological opening on the combined spatial‐temporal mask. Opening Radius XY splits adhesions that are connected only by thin pixel strips in space, while Opening T removes connections that are thicker in space but persist only briefly in time. Both are entered in physical units (nm and s, respectively) and converted to pixels and frames internally. Expected output is shown in Fig. 9E.

Figure 15.

Focal adhesion segmentation settings. Configure steerable filter sigma for FA separation and spatiotemporal filtering parameters.

• 7Adhesion analysis.
  Adhesion analysis (analyzeAdhesionMaturation) extracts 22 quantitative features per track and integrates all trajectories with their adhesion state (NA, FC, FA) (Fig. 16). Key parameters include:

  • a.
    Bandwidth of Nas. Width in µm of the band from the cell boundary within which nascent adhesions are filtered. This reduces the number of NAs to analyze and only takes effect when “Analyze only edge” is checked.
  • b.
    Minimum track lifetime. Minimum lifetime in frames to retain a track as a meaningful adhesion trajectory. A value of 3 frames is recommended.
  • c.
    Minimum length for FAs. Size threshold in µm for classifying a segmentation as a focal adhesion. FCs are automatically defined as structures >0.5 µm in length; this parameter sets the threshold above which structures are classified as FAs.
  • d.
    Match with FAs. Forces colocalization of all trajectories with segmentations from Step 6. Always enable this option.
  • e.
    Re‐track. Forces re‐tracking based on initial trajectories using intensity information, refining track assignments.
  • f.
    Calculate Adhesion Boundary Related Features. Computes adhesion area, distance to the cell edge, and related spatial features. Must be enabled for the classification step (Step 8) to work correctly.

  This is the most computationally intensive step; the optimization_method parameter controls the speed/accuracy trade‐off. Three options are available: “cpu” is recommended for routine analysis (∼25 min, results identical to “none”); “gpu” is fastest (∼2 min) and suitable for exploratory work, though results differ slightly numerically; “none” serves as a reference but is impractically slow (∼4 hr). Ensure the parallel pool is active before running CPU mode [parpool('local')]; if no GPU is detected the software falls back to CPU mode automatically.

Figure 16.

Adhesion analysis settings. Configure NA bandwidth, minimum track lifetime, FA length threshold, and optimization method for feature extraction.

• 8Adhesion classification.
  Adhesion classification (classifyMovieNascentAdhesions) uses the 22 features extracted in Step 7 to assign each track to one of 9 functional groups (Table 1, Fig. 17). Expected output is shown in Fig. 9F. Three classification approaches are available:

  • a.
    Automatic labeling (default). The classifier uses rule‐based criteria to identify seed examples of each group, trains a quadratic support vector machine on those seeds, and then predicts the class of all remaining tracks. As a final step, tracks that share the same FA segmentation from Step 6 are harmonized to a single representative class (adhesion boundary homogenization). This is the recommended approach for most analyses.
    To improve classification accuracy, pre‐trained datasets for Paxillin and Vinculin cell lines are available at: https://doi.org/10.5281/zenodo.19026532 (see Internet Resources). To use them: (1) download and unzip trainedData.zip from the above link; (2) in the classification settings window (Fig. 18), click the “Select” button under “External training data from other cells”; (3) navigate into the desired protein folder (e.g., Paxillin1/Colocalization/analysis1/data/); (4) select the selectedGroups.mat file and click Open. The required tracksNA.mat and movieData.mat files are automatically read from the same folder and its parent directories; no additional selection is needed. Repeat for additional analysis folders (e.g., analysis2) or the second protein (Vinculin5) to expand the training pool.
  • b.
    Manual labeling. Enable “Manual labeling after initial classification” to launch an interactive window for refining classifications (Fig. 17). Note that loading stacks and trajectories takes time with no status bar. Click “Data Tips” to select trajectories, then type the appropriate group number (1 to 9) to relabel. Markers indicate track start (yellow), initial rise (green), track end (blue), and peak intensity (white). Close the window to update the classifier with your corrections.
  • c.
    Simple labeling. Uses rule‐based filtering (via the distinguishFocalAdhesions function) instead of machine learning, distinguishing: G1 (non‐maturing NAs at edge), G2 (maturing NAs to FAs), G4 (FAs decaying in area), G5 (FAs further growing from an existing FA state), and G6 (all others). G3 is left empty by design to maintain a consistent 9‐class output structure, as identifying G3 (NAs moving along a protruding edge) requires dynamic edge tracking that rule‐based filtering cannot perform.

Table 1.

Adhesion Classification Groups

Group a	Short Name	Description	Typical % b
G1	Turn‐over	NAs that form at edge, stay/slide rearward, then turn over without maturation	25‐35
G2	Maturing	NAs that form at edge, stay/slide rearward, then mature to FC/FA	2‐5
G3	Moving along protruding edge	NAs that form at edge and move forward with the protruding cell edge	10‐15
G4	Retracting	FAs or FCs at the retracting cell edge	5‐10
G5	Stable at the edge	Stable FAs at the static cell edge	5‐10
G6	Noise or very transient	Insignificant tracks: short lifetime, low intensity, or random movement	5‐15
G7	NAs at stalling edge	NAs at an initially protruding edge that becomes stalling	10‐15
G8	Strong stable inside	FAs with high intensity and long lifetime at the cell interior	5‐10
G9	Weak stable inside	NAs or FCs with low intensity at the cell interior	5‐10

^a Note on naming convention: The group labels (G1‐G9) used in this protocol and the Focal Adhesion Package follow a different ordering than those in the original eLife publication (Han et al., 2021). In the eLife article, G1‐G5 are NA classes, G6‐G8 are FA classes, and G9 is noise. In the package, the 9 groups are ordered to reflect adhesion fate and functional behavior as listed above. Users comparing results with the eLife article should be aware of this difference.

^b Typical proportions for ChoK1 cells on 5 kPa substrates; proportions shift with substrate stiffness, cell type, and experimental conditions.

Figure 17.

Manual classification interface. For refining adhesion group assignments. Trajectories are displayed with markers indicating key time points. Users can relabel tracks by typing group numbers (1 to 9).

Figure 18.

Adhesion classification settings. Select automatic labeling, manual labeling, or simple rule‐based classification.

Steps 9 to 11: Multi‐modal integration (optional)

The final three steps enable integration with additional data modalities: secondary fluorescence channels (Step 9), traction force microscopy (Step 10), and temporal correlation analysis (Step 11). The workflow differs depending on whether the experiment involves TFM, multi‐channel fluorescence, or both.

• 9Other Channel Reading extracts intensity measurements from additional fluorescence channels at each adhesion location (Fig. 19). This is useful for analyzing protein colocalization (e.g., talin‐vinculin interactions) or FRET biosensor signals. The process reads registered images from the secondary channel and stores ampTotal2 and amp2 fields for each tracked adhesion.

Figure 19.

Other channel reading settings. For extracting intensity measurements from additional fluorescence channels at adhesion locations.

• 10Traction Force Reading extracts traction magnitude values at each adhesion location from pre‐computed TFM force maps. This requires that TFM analysis has been performed separately using the TFM Package. Step 10 reads the force field output from the ForceFieldCalculationProcess, applies stage drift correction to align the traction maps with the fluorescence images, and stores the interpolated traction magnitude (forceMag) for each tracked adhesion at every time frame.
• 11
  Initial Rise Time Lag Calculation performs temporal correlation analysis between the primary adhesion signal and a secondary signal, either traction force (from Step 10) or a secondary fluorescence channel (from Step 9). The mainSlave parameter in Step 11 settings (Fig. 20) selects which secondary signal to correlate:

  • 0 = no secondary signal (master channel only)
  • 1 = traction force
  • 2 = secondary fluorescence channel
  • 3 = tertiary channel.

  For each adhesion track, Step 11 computes: (1) initial rise time lag, i.e., the delay between primary and secondary signal onset; (2) peak time lag, i.e., the delay between peak amplitudes; (3) ending time lag, i.e., the delay between signal decline in each channel; and (4) cross‐correlation score and lag between the two time series. These metrics are computed for each of the 9 adhesion classes separately.

Figure 20.

Initial rise time calculation settings. ChannelIndex specifies the primary adhesion channel. mainSlave selects the secondary signal for correlation (0 = no secondary signal, master channel only; 1 = traction force, 2 = secondary fluorescence channel, 3 = tertiary channel).

TFM integration (Steps 10 to 11)

For experiments with TFM data, the workflow is: run Step 10 (Traction Force Reading), then run Step 11 with mainSlave = 1 (traction force).

After running Step 10, clicking Result in the control panel opens the Viewer window (Fig. 21), which provides comprehensive visualization controls. The left panel allows selection of the base image layer (raw channels, drift‐corrected images, displacement maps, or traction maps), while the right panel provides overlay options for all processing steps, from detected point sources and tracks to classified adhesion groups and strain energy outputs. By selecting “Traction map unshifted” on the left and enabling the desired adhesion class overlays on the right, users can visually inspect the spatial relationship between traction forces and adhesion populations (Fig. 22).

Figure 21.

Results Viewer window. Accessible after running Step 10. The left panel selects the base image (e.g., traction map), while the right panel enables overlays of tracked adhesions, classified groups (Classes 1 to 9), focal adhesion boundaries, and strain energy outputs.

Figure 22.

Overlay of traction force field and classified focal adhesions. The traction magnitude map (colorbar in Pa) is shown with classified adhesion tracks overlaid as colored circles. Each color corresponds to one of the 9 adhesion classes.

Upon completion, Step 11 automatically saves a comprehensive set of figures and data files in the output directory (InitialRiseTimeLagCalculation/). These include:

• Force–fluorescence plots (eps/ampForcePlotG*.eps). Combined amplitude and traction time series for G1 (turn‐over), G2 (maturing), and G4 (retracting) adhesions, with cohort and color‐coded variants.

• Time lag box plots (figs/initialLag Class*.fig, peakLag Class*.fig, ccLag Class*.fig). Initial rise, peak, and cross‐correlation time lags per adhesion class.

• Bivariate cross‐covariance (Bcc) (figs/zeroBcc*.fig, halfBcc*.fig, oneBcc*.fig). Time‐resolved Bcc analysis for G1 and G2 adhesions.

• Per‐group feature comparisons. Force slope, early amplitude slope, starting amplitude, starting traction, distance to edge, advance distance, assembly/disassembly rates, and edge advance distance change across all 9 groups.

• Fraction force‐transmitting (figs/fractionForceTransmitting.fig). Bar plot showing the fraction of adhesions that transmit force in each class.

After Step 11 completes, individual adhesion tracks can be inspected interactively using showMostRepresentativeAssemblingAdhesion. To launch the interactive viewer with all adhesion classes displayed:

MD = MovieData.load('path/to/movieData.mat');
showMostRepresentativeAssemblingAdhesion(MD, . . .
'RepClass', 0, 'PickManually', true, 'iSlave', 1)

This opens an interactive figure window (Fig. 23) showing the cell image with all tracked adhesions color‐coded by their classified group (G1 to G9, see legend). Clicking on any adhesion with the Data Tips cursor displays its quantitative features (ID, lifetime, mean intensity, distance to edge, edge advance, etc.). The bottom toolbar allows users to type an adhesion ID and click “Inspect” to generate a detailed summary figure.

Figure 23.

Interactive adhesion track selection window. Tracked adhesions are displayed as colored dots on the cell image, with colors corresponding to the 9 classified groups. Clicking on an adhesion with the Data Tips cursor reveals its quantitative features.

The resulting summary figure (Fig. 24) provides a comprehensive view of a single adhesion's dynamics: (1) fluorescence image montage showing the adhesion at selected time points with the tracked position marked; (2) corresponding traction map montage at the same time points with a zoomed inset around the adhesion; (3) fluorescence intensity time series; (4) traction magnitude time series; and (5) bivariate cross‐covariance (Bcc) between fluorescence and force, with the time of peak Bcc annotated.

Figure 24.

Single adhesion track summary (TFM integration). Top row: Fluorescence image montage at representative time points with the tracked adhesion marked. Second row: Zoomed fluorescence montage. Third row: Traction magnitude map at the same time points. Fourth row: Zoomed traction montage. Bottom row: Fluorescence intensity time series, traction magnitude time series, and bivariate cross‐covariance Bcc with peak time annotated.

Multi‐channel fluorescence analysis (Steps 9 to 11)

For experiments with multiple fluorescence channels (e.g., talin‐GFP and vinculin‐mCherry), the workflow is: run Step 9 (Other Channel Reading) to extract the secondary channel intensity at each adhesion location, then run Step 11 with mainSlave = 2 (secondary fluorescence channel).

Step 9 reads the registered images from the secondary channel and stores the intensity values as ampTotal2 and amp2 fields in each adhesion track. After Step 9 completes, Step 11 computes the same temporal correlation metrics (initial rise time lag, peak time lag, cross‐correlation, Bcc) between the primary and secondary fluorescence channels instead of between fluorescence and traction force.

To launch the interactive viewer for multi‐channel data, use iSlave = 2:

MD = MovieData.load('path/to/movieData.mat');
showMostRepresentativeAssemblingAdhesion(MD, . . .
'RepClass', 0, 'PickManually', true, 'iSlave', 2)

This opens the same interactive selection window as in the TFM case (Fig. 23). The resulting summary figure (Fig. 25) now displays both fluorescence channels: the primary channel (e.g., talin) and the secondary channel (e.g., vinculin), along with their temporal cross‐covariance. The time lag Δt_F.I‐F.I. between the two channels indicates the delay between protein recruitment at the primary and secondary channels.

Figure 25.

Single adhesion track summary (multi‐channel analysis). For a talin‐GFP/vinculin‐mCherry two‐channel experiment. Top half: Primary channel (talin) image montage. Bottom half: Secondary channel (vinculin) image montage. Right panels: Secondary channel amplitude, bivariate cross‐covariance Bcc, and primary channel fluorescence intensity. The time lag Δt reports the delay between talin and vinculin recruitment.

Cross‐condition comparison of multiple movies

After completing the analysis pipeline for all movies in an experiment, the package provides a dedicated comparison script, postAdhAnalysisPackBatch.m, that aggregates results across experimental conditions (e.g., wild type vs mutant, soft vs stiff substrate, control vs drug treatment). The script iterates through each condition's MovieList, loads previously computed results from the FocalAdhesionPackage process outputs of Steps 7, 8, 9, and 11, and produces side‐by‐side box plots with corresponding CSV exports for every metric. All movies within each condition must have completed at least Steps 1 to 8; Steps 9 to 11 are optional, and their associated plots are automatically skipped when not available.

Collected metrics

The script extracts six categories of measurements from each movie:

• Cell‐level morphometrics (from Step 7). Cell spread area (µm²), NA density (#/µm²), FA density (#/µm²), FA area (µm²), FA length (µm), and number of pure FAs per cell.

• Classification group statistics (from Steps 7 to 8). For each of the 9 groups: absolute track count (numG1 to numG9), relative population fraction, and per‐frame adhesion density (#/µm²). The G2/G1 ratio (maturing‐to‐turnover) is computed as a key summary metric. Maturation ratios (NA→FC, NA→FA, FC→FA) and the stable NA/FC ratio are also extracted.

• Adhesion dynamics (from Steps 7 and 11). Lifetimes of all NAs, non‐maturing NAs (G1), maturing NAs (G2), and FAs; assembly and disassembly rates for all adhesions and per classification group; nucleating NA ratio; and amplitude time‐series profiles for maturing, failing, and emerging NAs.

• Temporal correlation metrics (from Step 11, optional). Per‐group initial rise, peak, and ending time lags; half‐Bcc time; early amplitude slope per group; and bivariate cross‐covariance (Bcc) peak values and time‐to‐peak for G1 and G2.

• Force metrics (from Steps 10 to 11, optional). Fraction of force‐transmitting adhesions per group and early traction force slope per group.

• Multi‐channel metrics (from Step 9, optional). Secondary channel fluorescence intensity and background‐subtracted amplitude at NAs, FCs, and FAs; secondary channel assembly/disassembly rates.

Comparison outputs

For each metric, the script generates box plots comparing conditions side by side using boxPlotCellArray and exports CSV files. The full output set includes: group population counts and relative fractions (all 9 groups); per‐group adhesion density; G2/G1 maturation ratio; cell area, FA area (including top‐percentile), FA length, NA and FA density; maturation ratios (NA→FC, NA→FA, FC→FA); lifetime distributions for all NAs, G1, G2, and FAs; assembly and disassembly rates per group and G1 vs G2; amplitude profiles (maturing, failing, emerging NAs); stacked fraction bar chart (G1 to G9); and, when available, force‐transmitting fractions, force slopes, time lags, Bcc metrics, and secondary channel intensities. All figures are saved in EPS, FIG, and TIFF formats. The complete MATLAB workspace is saved as allData.mat for subsequent custom analysis.

Example usage

This walkthrough demonstrates the full workflow from organizing processed movies into MovieList objects through generating comparison plots.

• a.
  Step 1: Create MovieList objects. Suppose you have processed 3 WT movies and 3 KO movies through Steps 1 to 8. Create a MovieList for each condition and save it in a dedicated analysis folder:

  
  
  % Condition 1: WT on 5 kPa
  MD1 = MovieData.load('/data/experiment/WT_movie1/MD.mat');
  MD2 = MovieData.load('/data/experiment/WT_movie2/MD.mat');
  MD3 = MovieData.load('/data/experiment/WT_movie3/MD.mat');
  ML_WT = MovieList([MD1 MD2 MD3], '/data/experiment/WT_5kPa');
  ML_WT.save(); % saves movieList.mat in WT_5kPa/
  % Condition 2: KO on 5 kPa
  MD4 = MovieData.load('/data/experiment/KO_movie1/MD.mat');
  MD5 = MovieData.load('/data/experiment/KO_movie2/MD.mat');
  MD6 = MovieData.load('/data/experiment/KO_movie3/MD.mat');
  ML_KO = MovieList([MD4 MD5 MD6], '/data/experiment/KO_5kPa');
  ML_KO.save(); % saves movieList.mat in KO_5kPa/
  Step 2: Run the comparison script:
  >> cd /data/experiment
  >> postAdhAnalysisPackBatch
  

• b.
  Step 3: Select conditions via chooseSelectedFolders dialogs. The script calls chooseSelectedFolders, which guides the user through a sequence of dialogs:

  • i.
    A file dialog asks for a previously saved selection file; for a first run, click Cancel to skip.
  • ii.
    A folder‐selection dialog opens repeatedly; navigate to /data/experiment/WT_5 kPa/ and click OK, then navigate to /data/experiment/KO_5 kPa/ and click OK, then click Cancel to indicate all conditions have been added. Each folder name (WT_5 kPa, KO_5 kPa) becomes the default condition label. Alternatively, if Cancel is clicked immediately, a file‐selection dialog opens to select individual movieList*.mat files.
• c.
  Step 4: Rename conditions (optional). The script displays the detected names and offers a prompt to rename them. For example:

  
  
  The current names are:
  'WT_5kPa' 'KO_5kPa'
  Do you want to rename your condition names? (y/n) n
  

• d.
  Step 5: Automatic collection and plotting. The script iterates through all movies, collects metrics from their FocalAdhesionPackage outputs, and generates ∼40 comparison plots. Force‐related plots are automatically skipped for conditions without TFM data, and multi‐channel plots are skipped without Step 9 output. Results are saved in:

  
  
  /data/experiment/
  AnalysisSummary_AdhesionDynamic_WT_5kPa_KO_5kPa/
  Figs/ % All comparison plots (EPS, FIG, TIFF)
  Data/ % All CSV tables
  Data/allData.mat % Workspace for custom re‐analysis
  

  A selectedFolders_WT_5 kPa_KO_5 kPa.mat file is also saved in the current directory, so that subsequent runs can reload the same selection by choosing this file in step 3 instead of re‐selecting folders.

Sample data

Figures 2 to 23 provide representative outputs from each processing step for a ChoK1 cell expressing GFP‐vinculin on a 5 kPa substrate. See Figure Legends for detailed descriptions.

BATCH PROCESSING MULTIPLE MOVIES

This protocol describes automated processing of multiple movies for high‐throughput studies. After individual movies are processed, the postAdhAnalysisPackBatch script can aggregate results across all movies and generate summary statistics for downstream analysis.

Necessary Resources

Hardware

• A computer with ≥16 GB RAM (32 GB recommended for large datasets), a multi‐core processor (CPU parallelization scales with core count), and ∼500 MB additional storage per movie for analysis outputs

  Optionally, an NVIDIA GPU with CUDA support enables GPU‐accelerated optimization.

Software

• MATLAB R2019b or later (R2021a+ recommended) with the following toolboxes:

  • Image Processing Toolbox
  • Statistics and Machine Learning Toolbox
  • Curve Fitting Toolbox
  • Parallel Computing Toolbox (for CPU/GPU optimization).
  • To verify that all required toolboxes are installed, run ver in the MATLAB command window before proceeding. Git is required for downloading packages from GitHub.

Files

• Input data

  Time‐lapse fluorescence microscopy movies with at least one channel showing focal adhesion markers (e.g., GFP‐paxillin, GFP‐vinculin, mCherry‐zyxin). For multi‐channel analysis, additional channels may include other adhesion proteins or FRET biosensors. For TFM integration, a separate bead channel and a reference (cell‐free) bead image are required. The TFM pipeline must be run separately prior to Steps 10 to 11.

• 1
  Create a batch processing script. Create a new MATLAB script with movie paths:

  
  
  % Define movie paths
  basePath = '/path/to/experiment';
  movies = {
  fullfile(basePath, 'condition1', 'movie1.tif');
  fullfile(basePath, 'condition1', 'movie2.tif');
  fullfile(basePath, 'condition2', 'movie1.tif');
  % . . . add more movies
  };
  conditions = {'Control', 'Control', 'Treatment'};
  

• 2
  Initialize results storage. Create structures to store metrics:

  
  
  results = struct();
  results.control = initMetricsStruct();
  results.treatment = initMetricsStruct();
  
  

• 3
  Process each movie in a loop. Use the FocalAdhesionPipeline wrapper class:

  
  
  for i = 1:length(movies)
  try
  pkg = FocalAdhesionPipeline(movies{i}, . . .
  'optimizationMode', 'cpu', . . .
  'pixelSize', 108, . . .
  'timeInterval', 5);
  pkg.run();
  metrics = pkg.getMetrics();
  % Store metrics by condition
  catch ME
  warning('Movie %d failed: %s', i, ME.message);
  end
  end
  

• 4
  Generate comparison plots. After processing, create statistical comparisons:

  
  
  figure;
  subplot(1,3,1);
  boxplot([results.control.assemblyRate, . . .
  results.treatment.assemblyRate]);
  ylabel('Assembly Rate');
  title('NA Assembly');
  % Add statistical tests
  [~, p] = ttest2(results.control.assemblyRate, . . .
  results.treatment.assemblyRate);
  

COMMENTARY

Background Information

Adhesion biology and heterogeneity

Cell‐matrix adhesions are hierarchical structures ranging from transient nascent adhesions (NAs) at the lamellipodial edge to stable focal adhesions (FAs) in the cell body. NAs form within seconds as integrin clusters recruit cytoplasmic proteins including talin, paxillin, and vinculin. Mechanical tension from the actomyosin cytoskeleton drives maturation of a subset of NAs into focal complexes (FCs) and FAs, while the majority disassemble (Parsons et al., 2010; Zaidel‐Bar et al., 2007).

Importantly, adhesion populations are highly heterogeneous. Using the classification approach implemented in this package, we have identified that only ∼3.5% of NAs mature into FAs (G2 class), while ∼28.8% turn over without maturation (G1 class) (Han et al., 2021). This heterogeneity reflects fundamental differences in molecular recruitment, mechanical engagement, and ultimate adhesion fate. Figure 26 shows an example of the classification output overlaid on a cell expressing GFP‐vinculin.

Figure 26.

Classification of adhesion trajectories (eLife grouping). SVM‐based classification assigns each tracked adhesion to one of nine groups, overlaid on a GFP‐vinculin image. In the eLife study, five NA classes (G1 to G5), three FA classes (G6 to G8), and one noise class (G9) are distinguished. Different colors represent different classes. Scale bar: 5 µm. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Understanding the nine adhesion groups

Note that the group numbering in this section follows the convention used in the original eLife study (Han et al., 2021), where G1 to G5 are NA classes, G6 to G8 are FA classes, and G9 is noise. The Focal Adhesion Package uses a different ordering (Table 1), where G4 to G9 are reassigned. When interpreting the figures and biological results below, refer to the eLife group definitions listed here rather than the package group numbers.

The nine classification groups in the eLife study capture distinct adhesion behaviors based on kinetic, kinematic, and mechanical properties (Fig. 27):

Figure 27.

Comparison of feature values among the five NA groups (G1 to G5, eLife grouping). (A) Edge protrusion speed. (B) Adhesion movement speed. (C) Mean fluorescence intensity. (D) Lifetime. All features show significant shifts, demonstrating the distinct kinetic and kinematic properties captured by the classification. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Nascent adhesion classes (G1 to G5)

G1 (NAs turn‐over). NAs that form at the cell edge, stay at their positions, or slide rearward as the edge protrudes forward, and eventually turn over without maturation. These NAs can transmit traction forces but do not progress to FCs or FAs.

G2 (NAs maturing). NAs that form at the cell edge, stay at their positions, or slide rearward as the edge protrudes forward, and mature into FCs and FAs. These have the highest intensity and longest lifetime among NA classes. All G2 NAs mature to FCs, and ∼32% mature into FAs.

G3 (NAs advancing with edge). NAs that form at the cell edge and move forward with the protruding edge. These have the lowest fluorescence intensity and exhibit insignificant traction, suggesting they may not interact with the retrogradely flowing F‐actin cytoskeleton.

G4 (NAs at stalling edge). NAs that form at an initially protruding edge and stay at the edge as it becomes stalling or retracting.

G5 (NAs inside). NAs with low fluorescence intensity located at the cell interior, away from the cell edge.

Focal adhesion classes (G6 to G8) and noise

G6 (FAs retracting). FAs or FCs located at the retracting cell edge, often associated with cell rear retraction.

G7 (FAs stable at edge). Stable focal adhesions located at the static (non‐protruding, non‐retracting) cell edge.

G8 (FAs stable inside). FAs with high fluorescence intensity and long lifetime located at the cell interior.

G9 (Noise/transient). Insignificant tracks with short lifetime (<5 s), low intensity, or large random movement representing detection artifacts or very transient signals.

Machine learning classification

The classification algorithm uses quadratic support vector machines (SVM) trained on 22 features extracted from each track. Features fall into three categories:

• (1)Intensity dynamics (Features 1 to 9): assembly rate, peak intensity, time to peak, disassembly rate, mean intensity.
• (2)Spatial properties (Features 10 to 15): distance from cell edge, area, eccentricity, overlap with FA segmentation.
• (3)Behavioral features (Features 16 to 22): lifetime, edge association, movement speed, edge protrusion speed.

The classifier achieves validation accuracy of 70% to 80% when trained with ∼10 manually labeled tracks per class from ∼10,000 total tracks per movie. To address class imbalance, minority classes are oversampled and majority classes are under sampled based on the mean number of labels. Separate classifiers are built for talin‐, vinculin‐, and paxillin‐tagged adhesions, as the fluorescence properties differ between markers.

Interpreting Quantitative Outputs

Traction force measurements

A key advantage of this software is its ability to correlate adhesion dynamics with traction force measurements when combined with TFM. The maturing NA subgroup (G2) exhibits the highest traction magnitude shortly after initial assembly, consistent with tension‐mediated maturation (Fig. 28). In contrast, G3 adhesions exhibit insignificant traction throughout their lifetime.

Figure 28.

Average traction magnitude at individual NA trajectories per group. Maturing NAs (G2) show the highest traction shortly after assembly, while advancing NAs (G3) exhibit minimal traction. The number of samples per group is shown in the lower right corner. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Assembly rate analysis

The assembly rate, quantified as the slope of fluorescence intensity over the initial 10 to 30 s after detection, reveals important differences between adhesion classes (Fig. 29). Notably, only vinculin shows a significant difference in assembly rate between non‐maturing (G1) and maturing (G2) NAs, while talin and paxillin show no such differences. This suggests that the concurrent arrival of talin and vinculin in maturing NAs primes talin to expose additional vinculin‐binding sites (VBS), which accelerates vinculin recruitment and promotes adhesion maturation.

Figure 29.

Assembly rates and traction development in non‐maturing vs maturing NAs. (A) Assembly rates of talin, vinculin, and paxillin to G1 (non‐maturing) or G2 (maturing) NAs; only vinculin shows significantly faster recruitment in maturing NAs. (B) Traction growth rate for initial 10 s shows no significant difference. (C) Traction growth rate over 2 min shows significantly faster force development in maturing NAs. * = p <.01, *** = p <10⁻¹⁰, **** = p <10⁻³⁰ by Mann‐Whitney U test. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Temporal recruitment analysis

The time lag between protein recruitment and traction force onset provides mechanistic insights into adhesion assembly (Fig. 30). Representative examples show fluorescence intensity (top traces) and traction magnitude (bottom traces) extracted at each adhesion position, with colored circles marking key events: initial signal rise (green), initial traction rise (yellow), and peak amplitude (white). In non‐maturing NAs, talin, vinculin, and paxillin are recruited ∼18 s, ∼8 s, and ∼4 s before the onset of force transmission, respectively, a sequential recruitment pattern. In contrast, in maturing NAs, all three proteins are recruited concurrently, ∼4 s before force onset (Fig. 31). This concurrent recruitment suggests that maturing NAs may be initiated by pre‐formed talin–vinculin complexes that more efficiently engage with integrins and F‐actin.

Figure 30.

Representative traces of protein recruitment and traction generation. (A‐F) Non‐maturing NAs showing talin, vinculin, and paxillin recruitment with associated traction. (G‐L) Maturing NAs showing the same proteins. Note the concurrent recruitment of all proteins and immediate traction development in maturing NAs. Blue and red arrows mark the first intensity increase (FII) and first traction increase (FTI). Scale bars = 1 µm. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Figure 31.

Distinct temporal patterns of protein recruitment in non‐maturing vs maturing NAs. (A) In non‐maturing NAs, talin, vinculin, and paxillin are recruited sequentially before traction development. (B) In maturing NAs, all three proteins are recruited concurrently, briefly before the initial traction rise. * = p <.01, **** = p <10⁻¹⁰ by Mann‐Whitney U test. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Biological model

Based on the quantitative analysis enabled by this software, we have proposed a mechanistic model for differential NA maturation (Fig. 32). In non‐maturing NAs, talin binds to integrin before vinculin recruitment; talin stretching is limited, which restricts exposure of vinculin‐binding sites (VBS). Inefficient vinculin binding limits the number of F‐actin connections, allowing only low tension across the complex. Insufficient loading reduces the lifetime of catch‐bond‐like associations, resulting in NA turnover. In contrast, for maturing NAs, talin and vinculin interact before engagement with integrin. Upon concurrent recruitment, traction force builds immediately; pre‐associated vinculin and talin's own binding to F‐actin accommodate faster, more efficient recruitment of additional vinculin. High loading levels stabilize molecular bonds, facilitating NA maturation into stable focal adhesions.

Figure 32.

Proposed mechanism of differential recruitment of talin and vinculin determining maturation of nascent adhesions. Top: Non‐maturing NAs; sequential recruitment leads to limited talin stretching, inefficient vinculin binding, low tension, and eventual turnover. Bottom: Maturing NAs; concurrent recruitment enables immediate force development, efficient VBS exposure, accelerated vinculin recruitment, and maturation to stable FAs. Note. Reproduced from Han et al. (2021), eLife 10:e66151, https://doi.org/10.7554/eLife.66151, licensed under CC BY 4.0.

Limitations

The segmentation and classification pipeline has several known limitations that users should consider when interpreting results. First, the pipeline may fail to segment linear adhesions as single structures. Super‐resolution studies have revealed that focal adhesions are built from integrin nanoclusters that align into linear substructures (Jain et al., 2025), and when these nanoclusters are loosely arranged, the intensity gaps between them can cause the segmentation algorithm to fragment what is biologically a single adhesion into multiple smaller objects. This can inflate adhesion counts and reduce measured adhesion lengths.

Second, when adhesions form at high spatial density, for example in highly contractile cells or on stiff substrates, the segmentation may merge neighboring adhesions into a single large object, underestimating adhesion number and overestimating individual adhesion area. Adjusting the Split Filter Sigma parameter in Step 6 can partially mitigate this, but closely apposed adhesions separated by distances below the diffraction limit cannot be resolved.

Third, segmentation accuracy depends on the microscopy modality and the achieved spatial resolution. Diffraction‐limited imaging (e.g., widefield or spinning‐disk confocal) may not resolve closely spaced or small adhesions that would be distinguishable with techniques offering finer resolution such as TIRF or structured illumination microscopy. Users should therefore validate segmentation results against their raw images, particularly when working with cell types or conditions that produce dense or morphologically atypical adhesion patterns.

Critical Parameters

PSF Sigma (Step 4) must be calibrated for each imaging setup using the formula σ = λ_em ÷ (2 × NA × pixel_size). An incorrect PSF sigma is the most common cause of poor detection results.

Split Filter Sigma (Step 6) must exceed the diffraction limit (∼200 nm). Values <200 nm introduce segmentation artifacts by responding to sub‐resolution noise.

Match with FAs (Step 7) must always be enabled to correctly assign adhesion states.

Calculate Adhesion Boundary Related Features (Step 7) must be enabled for Step 8 (classification) to function correctly.

Optimization method (Step 7) should use cpu for production analysis. The gpu mode uses approximate fitting and may produce slightly different numerical results.

Troubleshooting

Table 2 summarizes common problems, possible causes, and solutions for running the Focal Adhesion Package.

Table 2.

Troubleshooting Guide for Running the Focal Adhesion Package

Problem	Possible Cause	Solution
Too few detections	alpha too stringent	Increase alpha to 0.1
	Signal too weak	Check image quality; increase exposure
Too many detections	alpha too permissive	Decrease alpha to 0.01
	Background noise	Improve thresholding/masking
Tracking failures	Search radius too small	Increase maxSearchRadius
	High adhesion density	Decrease timeWindow
Memory errors	Large dataset	Process fewer frames; increase RAM
	Many tracks	Use “cpu” optimization
Slow processing	Original algorithm	Switch to “cpu” optimization
	No parallel pool	Start parpool before running
Classification errors	Default training data	Retrain with manually labeled data
	Different cell type	Adjust startingDist parameter
Low G2 fraction	Normal biology	G2 typically represents only 3‐5% of NAs
	Soft substrate	Stiffer substrates increase FA formation
GPU not detected	Driver issues	Update NVIDIA drivers
	CUDA mismatch	Check MATLAB CUDA compatibility

Time Considerations

Table 3 summarizes typical processing times for a movie with 500 frames and ∼5000 tracked adhesions. The dominant bottleneck is Step 7 (Adhesion Analysis), where readIntensityFromTracks performs ∼1.5 million individual Gaussian fits. With CPU parallelization (recommended for production use), Step 7 completes in ∼25 min; GPU mode reduces this to ∼2 min but uses moment‐based estimation rather than iterative fitting. Steps 1 to 6 are I/O‐bound and take ∼15 min regardless of optimization mode. Step 5 (Tracking) runtime depends strongly on the maxGapLength parameter; for movies with many tracks (>10,000), setting maxGapLength = 1 can significantly reduce gap‐closing time due to the O(n²) cost‐matrix computation. For batch studies processing >10 movies, consider running overnight with the programmatic workflow (Alternate Protocol).

Table 3.

Typical Processing Times (500 frames, ∼5000 tracked adhesions)

Step	No optimization (min)	CPU (recommended) (min)	GPU a (min)
Steps 1‐6 (I/O‐bound)	15	15	15
Step 7 (Adhesion Analysis)	240	25	2
Step 8 (Classification)	10	10	10
Total	265	50	27

^a GPU mode uses moment‐based estimation rather than iterative fitting; CPU mode is recommended for production analysis.

Author Contributions

Majid Rostami: Conceptualization; data curation; formal analysis; investigation; methodology; software; visualization; writing—original draft. Sangyoon Han: Conceptualization; funding acquisition; methodology; project administration; software; supervision; validation; writing—review and editing.

Conflict of Interest

The authors declare no competing financial interests or other conflicts of interest related to this work.

Supporting information

Supplementary Files and Notes 1 to 3.

Figure S1 AdhesionAnalysisProcess pipeline. The main function analyzeAdhesionMaturation(MD) coordinates five sequential blocks: Track Loading via loadChannelOutput(), Intensity Reading via readIntensityFromTracks(), FA Matching via refineAdhesionSegmentation(), Feature Extraction via getFeaturesFromTracksNA() (which calls getAssemRate() and getDisassemRate()) and Save Tracks.

Figure S2 InitialRiseTimeLagCalculationProcess pipeline. The function calculateInitialRiseTimeLagFromTracks(MD) proceeds through five phases: (I) Data Assembly via loadChannelOutput (Steps 7–10); (II) Time Series Analyses via calculateFirstIncreaseTimeTracks, calculatePeakTimeLagFromTracks, calculateEndingTimeLagFromTracks, and nanCrossCorrelation; (III) Group Filtering via getForceTransmittingG1 and getForceTransmittingG2; (IV) Feature Statistics; (V) Visualization via boxPlotCellArray.

Figure S3 Detailed sub‐steps within analyzeAdhesionMaturation. Starting from tracks produced in Step 5, the function performs eight internal operations: load and filter tracks by minimum lifetime, build a master cell mask stack, remove out‐of‐cell tracks, read intensities via Gaussian fitting, match tracks with FA segmentation, compute edge distances per frame, extract 22 features per track, and run maturation analysis and statistics. Output is saved to trackIndividual/*.mat.

Figure S4 Classification pipeline for adhesion maturation prediction. The process consists of five stages: Phase 1, rule‐based auto‐labeling; Phase 2, class balancing; Phase 3, feature extraction and SVM training; Phase 4, prediction on all tracks; and post‐processing with redemption and harmonization.

Figure S5 Adhesion group definitions. Tracks are classified into five groups: G1 (BA→NA state, not at image border, assembling and disassembling, not maturing), G2 (NA→FC/FA transition, close to edge at start, assembling but not disassembling), G4 (always FA/FC state, area decreasing), G5 (always FA/FC state, area increasing), and G6 (everything else, unclassified).

Figure S6 FA segmentation pipeline. The four‐step process includes: (1) initial segmentation via blobSegmentThreshold; (2) steerable filter splitting (2nd‐order) to detect ridge‐like structures and remove intensity troughs between adjacent adhesions; (3) morphological post‐processing via 3D opening using bwareaopen and imopen; (4) 3D connected component labeling.

Figure S7 Watershed‐based FA splitting logic. For each connected component in the FA mask, the algorithm checks whether it contains more than one NA. If no, the region is kept as is. If yes, seed points are created at NA locations, a distance transform is computed from those seeds, watershed segmentation is applied to split the region, and boundaries are validated by local intensity.

Figure S8 Assembly rate estimation algorithm. The procedure: (1) smooth the intensity trace with a spline (p = 0.01) to find the peak; (2) per‐window normalize as A_norm,j:i = A(t) ÷ A(t_j); (3) for each valid start j and end i (≥15 frames), fit a linear model to log‐normalized amplitude and store adjR², slope, and p‐value; (4) select the best fit by max(adjR²) or min(p) if longer; (5) validate that the slope is >0. Total fits: n(n+1) ÷ 2 where n = t_peak − t_min + 1.

Rostami, M. , & Han, S. J. (2026). High‐throughput focal adhesion analysis software for automated detection, tracking, and classification of cell‐matrix adhesions. Current Protocols, 6, e70420. doi: 10.1002/cpz1.70420

Data Availability Statement

The Focal Adhesion Package software, which includes the u‐track tracking engine, is freely available at: https://github.com/HanLab‐BME‐MTU/focalAdhesionPackage. Sample data used to generate figures in this protocol are available upon request from the corresponding author.