Protocol for generation, time-course imaging, and automated quality control of 3D spheroid invasion using TRACEQC

Summary

Longitudinal 3D spheroid imaging requires quality control to ensure accurate image matching across sessions. We present a protocol for embedding spheroids and implementing TRACEQC (temporal reassignment and correspondence evaluation with quality control) to correct positional displacement. We describe steps for generating spheroids, embedding them in collagen plugs, acquiring image metadata, and applying TRACEQC to align spheroid positions across time points. This approach is agnostic to spheroid type, cellular composition, and formation technique, making it broadly applicable to longitudinal 3D imaging experiments.

For complete details on the use and execution of this protocol, please refer to Cramer et al.¹

Graphical abstract

Highlights

• •Steps for spheroid formation, embedding, and image acquisition
• •Instructions for using the TRACEQC application programming interface (API)
• •Instructions for using the TRACEQC graphical user interface (GUI)
• •Guidance on quality control and interpreting TRACEQC output

Publisher’s note: Undertaking any experimental protocol requires adherence to local institutional guidelines for laboratory safety and ethics.

Longitudinal 3D spheroid imaging requires quality control to ensure accurate image matching across sessions. We present a protocol for embedding spheroids and implementing TRACEQC (temporal reassignment and correspondence evaluation with quality control) to correct positional displacement. We describe steps for generating spheroids, embedding them in collagen plugs, acquiring image metadata, and applying TRACEQC to align spheroid positions across time points. This approach is agnostic to spheroid type, cellular composition, and formation technique, making it broadly applicable to longitudinal 3D imaging experiments.

Before you begin

The protocol below describes spheroid embedding and TRACEQC-based quality control as performed with spheroids derived from fibroblast and immortalized cancer lines. As TRACEQC is agnostic to spheroid type, cellular composition, and formation technique; researchers may use alternative spheroid formation approaches (spin, drop, or magnetic field-based methods).

Setting up your imaging environment

Before you begin, we recommend that you configure your imaging system for longitudinal acquisition. Confirm your imaging platform supports positional memory or stage return to marked or recorded coordinates such as by using a Multipoint file.

Innovation

Three-dimensional (3D) in vitro models, such as tumor organoids and spheroids embedded in an extracellular matrix provide physiologically relevant models for studying cancer metastasis and invasion. Time-lapse imaging of these models enables continuous longitudinal tracking of dynamic modifications to cellular phenotypes and ongoing signaling, especially when used as co-culture systems to more physiologically recapitulate cancer behavior within the tumor microenvironment.

Utilizing the time lapse imaging to infer cellular phenotypes requires tracing individual cells or features throughout the imaging experiment. One common challenge inherent to these analyses is that 3D in vitro models are prone to matrix shifts during experimental setup or image capture. These shifts can effectively rotate, translate, or otherwise re-position the objects being imaged between image acquisitions, which can introduce technical artifacts that affect downstream analyses. Recently, we demonstrated that a Procrustes-based image-alignment algorithm can correct for technical artifacts and improve accuracy of these temporal assays.¹ Here we describe a protocol that demonstrates how to effectively use this approach to assess experimental data quality and then correct technical artifacts when applicable.

BSL-2 workspace

All cell culture work described in this protocol was conducted in accordance with institutional biosafety guidelines and regulations. The work was performed under Biosafety Level 2 (BSL-2) containment practices.

Personnel training and qualifications

All personnel performing experimental procedures described in this protocol completed the required training and laboratory-specific standard operating procedures. Personnel were authorized to work in BSL-2 facilities by the Principal Investigator and the Institutional Environmental Health and Safety office.

Key resources table

REAGENT or RESOURCE	SOURCE	IDENTIFIER
Chemicals, peptides, and recombinant proteins
RPMI-1640	Thermo Fisher Scientific	Cat# 11-875-085
DMEM	Thermo Fisher Scientific	Cat# 12430104
Fetal Bovine Serum (FBS)	GeminiBio Thermo Fisher Scientific	Cat#100-106 Cat# A3382101
Amphotericin B	Sigma	Cat# A2942
Penicillin-Streptomycin	Gibco	Cat# 5140122
UltraPure Agarose	Invitrogen	Cat# 16500100
Rat Tail Collagen I	Gibco	Cat# A10483-01
PBS (1×)	Corning	Cat# 21-040-CV
EMEM EBSS (10×)	Quality Biological Thermo Scientific	Cat# 112-018-101 Cat #BW12684F
L-glutamine	Corning	Cat# 25-005-CI
NaHCO3	Quality Biological Thermo Scientific	Cat# 118-085-721 Cat # 25080094
DMSO (Dimethyl Sulfoxide)	Sigma	Cat# 472301
Trypsin-EDTA (0.25%)	Gibco	Cat# 25200056
MEM Nonessential Amino Acids (100×)	Corning	Cat# 25-025-CI
Sodium Pyruvate	Corning	Cat# 25-000-CI
DPBS (1×)	Corning	21-031-CM
Humulin R (Regular Human Insulin)	Eli Lilly	Cat# 00002-8215-01
Commercial assays
MycoStrips	Invivogen	Cat# rep-mys-100
CytoPainter Cell Proliferation Staining Reagent (Deep Red Fluorescence)	Abcam	Cat# ab176736
CytoPainter Cell Tracking Staining Kit- Deep Red Fluorescence	Abcam	Cat # ab138894
CytoPainter Cell Proliferation Staining Reagent (Green Fluorescence)	Abcam	Cat# ab176735
Deposited data
AlignSpheroid dataset	This paper	Zenodo link: https: https://doi.org/10.5281/zenodo.17196124
Experimental models: Cell lines
Panc10.05	Jaffee et al.2 available through ATCC	Cat# CRL-2574
hT231	Dr. David Tuveson, Dr. Dennis Plenker, Dr. Amber Habowski, and Hardik Patel3,4	N/A
WM983b	Chhabra et al.5	RRID:CVCL_6809
WM164	Hüser et al.6	RRID:CVCL_7928
WM793	Webster et al.7	RRID:CVCL_8787
Human Dermal Fibroblasts	Coriell Institute	2003-071-032
Human Dermal Fibroblasts	Coriell Institute	2003-071-056
Human Dermal Fibroblasts	Coriell Institute	TP-113
Human Dermal Fibroblasts	Coriell Institute	AG13004
Human Dermal Fibroblasts	Coriell Institute	AG09157
Software and algorithms
TRACEQC	Cramer et al., 20251	GitHub link: https://github.com/emcramer/TRACEQC, Zenodo link: https://doi.org/10.5281/zenodo.16590562
SciPy	Virtanen et al.8	https://scipy.org/
NumPy	Harris et al.9	https://numpy.org/
Python	Python.org	RRID: SCR_008394
Matplotlib	Hunter et al.10	https://matplotlib.org/
Seaborn	Waskom and the seaborn development team11	https://seaborn.pydata.org/
Pandas	McKinney and the pandas development team12	https://pandas.pydata.org/
Streamlit	Streamlit, Inc.13	https://docs.streamlit.io/
NIS Elements Advanced Research (AR) software	Nikon	N/A
Other
96 Well Polypropylene Plates	Celltreat	Cat# 229576
24-well SensoPlate™	Greiner Bio-One	Cat# 662892
6-well Cell culture plates	GenClone	Cat# 25-105
PES Vacuum Filtration Systems, 500ml, 0.22 um filter	GenClone	Cat# 25-227
Cell culture flasks	GenClone	Cat# 25-209

Materials and equipment

This protocol comprises two sequential workflows: an experimental and a computational analysis component.

The experimental workflow details how to embed and image spheroids for time course or multi-session imaging suitable for quality control with TRACEQC. This protocol can be applied to spheroids produced using various techniques, such as liquid overlay, spinner, hanging drop, etc.¹⁴ After embedding of spheroids, imaging was performed in 24-well plates (Greiner Bio-One, 662892) using an inverted brightfield/fluorescence microscope (Nikon Eclipse Ti2) equipped with Hamamatsu ORCA-Flash 4.0 and DS-Ri2 camera systems. Images of spheroids were acquired using a 10× objective lens (NA 0.25), with additional objectives (1×, 4×, and 20×) available as needed. Live-cell imaging was conducted under environmental control (37 °C, 5% CO₂) using a stage-top incubator (Tokai Hit STX) and fluorescence excitation at 488 nm and 647 nm.

The following computational workflow involves extracting spheroid coordinates, formatting them as a.csv file, and performing quality control with the TRACEQC (“temporal reassignment and correspondence evaluation with quality control”) software either through its programmatic interface or by interacting with the TRACEQC web interface. Instructions for coordinate formatting and file upload are provided in the file management section. Example data are available in the TRACEQC GitHub repository under https://github.com/emcramer/TRACEQC/tree/main/gui/example_data. Researchers using their own datasets should start at the file management section and follow the workflow through either the application programming interface (API) or user-friendly graphic user interface (GUI). Those intending to reproduce the example analysis can access the reference spheroid images and coordinate files in the key resources table under TRACEQC via the Zenodo repository.

Complete DMEM medium

Reagent	Final concentration	Amount (mL)
DMEM	N/A	450
FBS	10.0%	50
Penicillin-Streptomycin	1.0%	5
Total	—	500 mL

Note: Store at 4 C, and warm at 37 C before use. Can be stored at 4 C for three months. N/A = Not applicable.

Complete RPMI 1640 medium

Reagent	Final concentration	Amount (mL)
RPMI	N/A	440
FBS	10.0%	50
Amphotericin B	0.1%	0.5
Penicillin-Streptomycin	1.0%	5
L-Glutamine	1.0%	5
Total	—	500 mL

Note: Store at 4 C, and warm at 37 C before use. Can be stored at 4 C for three months. N/A = Not applicable.

Collagen embedding mix

Reagent	Stock concentration	Final concentration	Amount (μL)
DPBS	1×	0.38×	225.3
FBS	100%	10.0% (v/v)	59.8
EMEM (EBSS)	10×	0.89×	53.2
L-glutamine	200 mM	1.62 mM	4.9
NaHCO3	7.5%	0.39%	31.5
Collagen I (rat tail)	4 mg/mL	1.50 mg/mL	225.3
Total	—	—	600μL

CRITICAL: Keep collagen on ice at all times (4°C) and add it last after pre-cooling the remaining components to prevent premature polymerization.

Note: The collagen embedding mix must be prepared immediately prior to use.

Step-by-step method details

TRACEQC can be applied to any experiments involving embedding of multiple 3D objects in a single well. This protocol describes the specific steps for analyzing single and co-culture spheroids composed of cancer cells (e.g., Panc10.05, WM793) and fibroblasts (e.g., ht231, AG13004) using TRACEQC (see key resources table for details).

Spheroid formation

Timing: Up to 9 days

This section describes methods for generating compact spheroids prior to embedding. Various formation techniques can be employed depending on cell type and experimental requirements.

• 1.Prepare cell lines for spheroid generation. Panc10.05 and hT231 were cultured in complete RPMI 1640 medium, and WM983b, WM793, WM164, and dermal fibroblast lines cultured in complete DMEM medium.

Note: Adjust cell media and growth conditions to accommodate for cell types used.

• 2.Generate spheroids using standard techniques (e.g., liquid overlay, spinner flask, hanging drop).¹⁴

Note: In this protocol we used a liquid overlay with agarose,¹⁵ but any standardized method is suitable dependent on the cell line used.

Note: Successful spheroid formation typically ranges from several hours to 9 days depending on the cell type used.^16,17

• 3.After compact spheroids have been generated (see Figure 1¹⁵), transfer the spheroids from each condition into a 1.5 mL microcentrifuge tube (one tube per imaging per well) and proceed to the collagen plug embedding.

Figure 1.

Representative melanoma spheroids suitable for TRACEQC analysis

(A) Representative mono-culture melanoma spheroids (WM164, WM793, WM983b).

(B) Images depicting fluorescent labeling of co-culture spheroids relative to phase.

Cells were stained with CytoPainter Cell Tracking Staining Kit- Deep Red and Green Fluorescence (Abcam, Cat # ab138894, ab176735). The merged image includes phase and both fluorescent channels.

(C) Representative co-culture Panc10.05 + hT231 spheroids. Scale bars = 200 μm.

Collagen plug embedding of spheroids

Timing: 1–4 h

This section describes the process of embedding spheroids within collagen matrices to create an in vitro 3D microenvironment. Where appropriate for your cell type, a different protein matrix (e.g., matrigel, Collagen IV) may be substituted to serve as the basement membrane.

• 4.Prepare collagen embedding mix on ice in a 15 mL conical tube. Each well requires a total of 600 μL collagen mix (300 μL base layer + 300 μL top layer).
• 5.Add 300 μL of collagen mix to each well of a clear 24-well plate.
• 6.Spread the collagen evenly across the well bottom using a pipette tip, avoiding air bubbles.
• 7.Incubate the plate at 37°C for 10–15 min until the collagen base layer polymerizes and turns pink.
• 8.While the base layer is polymerizing, carefully remove excess agarose supernatant, leaving spheroids in a minimal volume.
• 9.Gently resuspend the spheroids for each condition in 300 μL of collagen mixture per well. Mix gently by pipetting.

Note: It is recommended to prepare duplicate wells for each spheroid condition (i.e., two independent wells per condition) to account for possible collagen plug dissociation.

• 10.To embed spheroids in collagen, first remove the 24-well plate (from step 7) from the incubator.
• 11.Dispense the 300 μL of spheroid–collagen suspension dropwise onto the pre-polymerized collagen base layer, avoiding air bubbles.

CRITICAL: Use wide-bore or cut pipette tips and pipette slowly and gently to minimize air bubble formation in the viscous collagen mix.

Note: Ensure spheroids are embedded at least 1–2 mm apart to prevent them from merging during growth or invasion assays- we recommend embedding 3–6 spheroids per well in a 24-well plate format, with these guidelines dependent also on cell type and imaging duration.

• 12.After plating three wells, allow the collagen to polymerize at 37°C for 15 minutes.

Note: Embed no more than three wells at a time and allow each set to polymerize fully before proceeding. This prevents spheroid aggregation toward the center of the well.

• 13.Once all wells have been plated, incubate at 37°C for an additional 30 minutes to ensure complete collagen polymerization.¹⁸
• 14.Carefully overlay each well with 1 mL of complete culture media, taking care not to disturb the collagen layer, and proceed with downstream applications as appropriate.

Image position acquisition

Timing: Up to 7 days

This section describes the process of recording spheroid positions within the imaging plate and imaging of each spheroid across multiple timepoints.

Day 1: Initial time-point imaging (t = 0)

• 15.Turn on the CO₂ incubated microscope stage and allow 10 minutes for the chamber to stabilize at 37°C and 5% CO₂.
• 16.Install the appropriate plate holder and place the 24-well plate on the microscope live-cell stage. Ensure the plate sits securely.
• 17.Set transmitted light and begin with a 1× or 4× objective to check overview imaging.
• 18.Acquire a large scan of the entire plate at the initial time point (t = 0) at low magnification using the 1× objective.

Note: Acquiring a full-plate scan at each timepoint is recommended for exhaustive data documentation; however, this generates several large datasets. Such scans are not required for TRACEQC functionality.

• 19.Using the large scan, locate and focus on each spheroid. Record each spheroid’s positions and save them within an XY Multipoint file.

Note: Most commercial microscope systems allow for the export and import of XYZ stage positions (e.g., as.txt, .csv, or.xml files).

• 20.For each spheroid, acquire z-stack images (five slices across a 60 μm range) using imaging channels of interest (e.g., brightfield, phase, or fluorescence).

Note: For multiple spheroids within the same field of view, treat each as an independent acquisition and center individually in the XY Multipoint file.

Day 2–7

• 21.
  For subsequent time points (24, 48, 72, 168 hours):

  • a.
    Load the XY Multipoint file from t = 0.
  • b.
    Center each spheroid in the field of view using the 10× objective.
  • c.
    Refocus the Z-plane while keeping the Perfect Focus System (PFS) active.
• 22.
  If spheroids shift outside the predefined field of view:

  • a.
    Scan with the 4× objective to locate the nearest spheroid.
  • b.
    Update and save the XY Multipoint position as a new file before acquisition. We recommend keeping filenames unique and descriptive to indicate time of acquisition and retake status.

File management

This section describes the process of extracting, naming, and storing the files and metadata needed for downstream TRACEQC analysis.

• 23.Generate a new directory for the files from each acquisition time point.
• 24.Save each time point’s images as an image file with corresponding metadata (i.e., Nikon.nd2 or Carl Zeiss Image.czi file).
• 25.
  For downstream analysis:

  • a.
    Extract X and Y coordinate tables from the image file (i.e., .nd2, .czi, .ome.tiff, etc.) metadata and export as CSV files (.csv).
  • b.
    Split multipoint files into single-frame images and store in corresponding directories.
• 26.Merge the CSV files for each subsequent time point into a single CSV dataset.

CRITICAL: Ensure that each row corresponds to a unique spheroid ID and that X, Y, and Z coordinate columns are consistently named and aligned across all time points.

Quality control with TRACEQC

This section describes the process of using TRACEQC to evaluate and correct spheroid positioning errors throughout longitudinal imaging experiments. This protocol uses TRACEQC version 1.0.0 available on GitHub at https://github.com/emcramer/TRACEQC with the commit hash c0ef14a.

Option A: Using the TRACEQC application programming interface with Python

Install Python 3.8 or later from python.org.

Install TRACEQC via pip:

>pip install “TRACEQC @git+ https://github.com/emcramer/TRACEQC”

Verify installation

>import TRACEQC

>print(TRACEQC.__version__)

This approach is recommended for users comfortable with Python scripting, batch processing multiple datasets, or integrating TRACEQC into existing analysis pipelines.

Basic alignment workflow

Timing: 5–10 min

• 27.Load your coordinate data:

import pandas as pd

from traceqc import align2d, Aligner2D

# Load data (wide format)

data = pd.read_csv('spheroid_coordinates.csv')

# Extract X and Y coordinate matrices

# Columns: x_0h, x_24h, x_48h, …

# Rows: individual spheroids

dataX = data[['x_0h', 'x_24h', 'x_48h']].values

dataY = data[['y_0h', 'y_24h', 'y_48h']].values

time_points = ['0h', '24h', '48h']

• 28.Run alignment using the functional API:

# Quick analysis using default parameters

registered_df, best_orders, ordered_points, reg_dataX, reg_dataY, timepoint_errors = align2d(

  dataX=dataX,

  dataY=dataY,

  well_id='WellA',well_name='Experiment_1')

• 29.Examine quality control metrics:

# Set normalized Fréchet distance threshold

qc_threshold = 1.0 # adjustable threshold, default value = 1.0

# Check normalized Fréchet distance for each time point

for i, (tp, error) in enumerate(zip(time_points[1:], timepoint_errors)):

print(f"{time_points[0]} → {tp}: Normalized Fréchet distance = {error:.3f}"

  if error > qc_threshold:

  print(f" ⚠ Warning: High error suggests possible alignment failure")

• 30.Inspect alignment results:

# View corrected labels

print(registered_df.head())

# Columns: raw_x, raw_y, registered_x, registered_y, timepoint,

  # original_label, aligned_label

# Compare original vs. corrected labels at each time point

for tp in time_points[1:]:

  tp_data = registered_df[registered_df['timepoint'] == tp]

  n_corrected = (tp_data['original_label'] != tp_data['aligned_label']).sum()

  print(f"{tp}: {n_corrected}/{len(tp_data)} labels corrected")

• 31.Export results:

# Save corrected coordinates

registered_df.to_csv('corrected_trajectories.csv', index=False)

# Save permutation mappings

import json

with open('label_mappings.json', 'w') as f:

  json.dump(best_orders, f, indent=2)

CRITICAL: Always inspect timepoint_errors before proceeding with downstream analysis. Values > threshold value (default is 1.0) indicate potential alignment failure (see troubleshooting 1).

Option B: Using the TRACEQC graphical user interface

This approach is recommended for users without programming experience or for exploratory analysis with immediate visual feedback.

Accessing GUI and uploading data

Timing: 5 min

• 32.Navigate to the TRACEQC Web application: https://traceqc.streamlit.app/
• 33.Start with the Upload tab.
• 34.Drag and drop your CSV/TXT file onto the upload area, or click “Browse files” (Figure 2).

CRITICAL: Ensure file size is <50 MB. For larger datasets, use the Python package or split data by well.

• 35.
  Review the data preview table and format detection (Figure 3):

  • a.
    The GUI automatically detects wide vs. long format.
  • b.
    Verify that columns are correctly identified.
  • c.
    Check that the number of detected spheroids and time points is correct.
• 36.
  If format detection fails, manually specify:

  • a.
    Column prefix for X coordinates (e.g., “x_” for x_0h, x_24h,.)…
  • b.
    Column prefix for Y coordinates (e.g., “y_”).
  • c.
    Time point column name (for long format only.

Note: The GUI supports automatic conversion between wide and long formats.

Figure 2.

Start up page for the TRACEQC graphical user interface (GUI)

Figure 3.

Success page rendered after loading properly formatted data

Configuration and analysis

Timing: 5–10 min

• 37.Navigate to the Configure tab (Figure 4).
• 38.
  Set analysis parameters:

  • a.
    Well/Sample name: Descriptive identifier for this dataset.
  • b.
    Time point labels: Comma-separated list matching your data (e.g., “0h,24h,48h,72h”).
  • c.
    QC threshold: Normalized Fréchet distance threshold (default: 1.0).
  • d.
    Click the “Configuration Complete” button (Figure 4).

Note: The QC threshold was determined through perturbation testing over 200,000 simulations of different technical artifacts and validated empirically on a biological data set. If you have reason to believe that the embedding matrix has shifted significantly without causing meaningful change to the biological conditions experienced by the spheroids (e.g. rupture of the embedding matrix itself) then you may increase the threshold value. If you desire a higher level of confidence, then you may lower the QC threshold. We recommend keeping the threshold for the Normalized Fréchet distance at 1.0.

• 39.Click “Run Analysis”

Note: The algorithm run time depends on the number of spheroids

Note: A success page will be displayed after the algorithm has finished (Figure 5)

Figure 4.

Configuration parameters for TRACEQC

It is strongly recommended not to alter the default settings for the algorithm unless necessary for your data set.

Figure 5.

Success page indicating the TRACEQC program has completed its run

Interpreting results

Timing: 5–10 min

• 40.Navigate to the Results tab (Figure 6).
• 41.
  Review the Quality Control Dashboard on the Results tab:

  • a.
    Normalized Fréchet Distance plot: Shows QC metric for each time point.

    • i.
      Green bars (≤ QC threshold): Successful alignment.
    • ii.
      Red bars (> QC threshold): Potential alignment failure.
  • b.
    Correction Summary: Number of labels corrected at each time point.
  • c.
    Overall Status: Pass/Fail based on QC threshold (Figure 6A and 6C). Example images for each well are shown in Figure 6B and 6D.
  • d.
    Quality Control Metric: The distribution of the quality control metrics for the inputted data set (Figure 7A).
  • e.
    Alignment Visualization:

    • i.
      Spheroid locations after alignment algorithm at each time point (red) relative to the reference time point (blue) at t=0 (Figure 7B).
  • f.
    Trajectory Visualization:

    • i.
      Each spheroid is shown in a unique color with locations at each point in time connected by a line, and the total displacement each spheroid experienced ranked (Figure 7C).
• 42.
  Inspect the Before/After Comparison Table:

  • a.
    Shows original vs. corrected labels for each spheroid (Figure 8).

Figure 6.

The results tab of the TRACEQC GUI

(A) Example results page header showing successful assignment of the spheroids to their correct identities and pass for quality control.

(B) Example images of spheroids (mixture of Panc10.05 and hT231) correctly aligned after correction with TRACEQC, Scale bars = 100 μm.

(C) Example results tab showing failed assignment and failed quality control. If more than one of the spheroids cannot be aligned, then the experimenter should not consider the data to have passed quality control.

(D) Example images of spheroids (mixture of Panc10.05 and hT231) from a well with failed alignment post-TRACEQC, Scale bars = 100 μm.

Figure 7.

Assignment results tab from TRACEQC GUI

(A) Quality control metrics for the completed alignment from TRACEQC showing failure and pass rate by spheroid.

(B) Visualization of the alignment output from TRACEQC.

(C) Trajectory results for the well evaluated with TRACEQC showing the amount and direction of displacement experienced by each spheroid over the course of imaging.

Figure 8.

Formatted output from TRACEQC showing the corrected image labels after running the algorithm

Expected outcomes

Spheroids embedded using this workflow support TRACEQC by serving as stable reference structures and enabling imaging conditions suitable for reliable, longitudinal quality control and analysis. Time-course imaging of individual spheroids enables capturing fine levels of detail suitable for spatial analysis, but risks technical artifacts. Extracting the coordinate metadata from the individual images and organizing it by time point in a single comma separated value (CSV) file consolidates each spheroid’s movement within the well over the course of an experiment and formats the data appropriately for quality control analysis with TRACEQC. The overall expected outcome of this protocol is output from TRACEQC, which is one of pass or fail depending on whether the program is able to match the images to their associated spheroid at each time point with the error metric below the user-defined threshold.

When TRACEQC successfully corrects mislabeling, you should observe: low QC metrics: Normalized Fréchet distances ≤ QC threshold (default = 1.0) for all time points (Figure 7A), matched alignment: Corrected positions show touching/overlapping spheroid positions relative to the reference without ambiguity (Figure 7B), and consistent nearest neighbors: Spheroids maintain spatial relationships across time.

Alignment may fail when normalized Fréchet distance > QC threshold (default = 1.0) (Figure 6B) or if spheroids/points are mismatched relative to the reference time point. Common causes may be due to spheroid fusion or dissolution between time points, perfectly symmetrical initial arrangement (e.g., square grid), variable number of spheroids across time points, and rupture, tearing, wrinkling, or folding of collagen/matrigel plugs.

Note: TRACEQC failure itself is the quality control indicator, suggesting fundamental experimental issues (see limitations).

Output file formats

corrected_trajectories.csv

raw_x,raw_y,registered_x,registered_y,timepoint, original_label,aligned_label

245.3,512.7,0.23,0.45,0h,1,1

792.5,237.3,-0.31,0.12,24h,2,3

459.3,681.2,0.08,-0.28,48h,3,2

Quantification and statistical analysis

Quantification and analysis are performed automatically by TRACEQC. A “pass” from the program indicates that the data meet quality control standards set by the user. A “fail” from the program indicates that a critical issue has occurred during the experiment, and the data should not be used. TRACEQC will attempt to align images of objects across all time points and propose a best match for objects whose labels were inadvertently swapped during imaging due to matrix rotation and translation artifacts.

Limitations

The reliability of the TRACEQC protocol depends on the quality and consistency of longitudinal imaging data acquired during 3D cell culture experiments. Spatial misalignment arising from matrix detachment or deformation may exceed the correction capacity of the method, resulting in incomplete spheroid alignment. The protocol assumes that spheroids remain sufficiently separated and retain their spatial relationships across time points. High spheroid density within a well, fusion events, or substantial migration of a single spheroid within the matrix, such as displacement greater than the distance between any two nearest neighbors, may compromise alignment accuracy.¹ Environmental factors such as temperature or pH fluctuations during setup, variability in the cell lines used, or inconsistencies in microscope performance may introduce positional variability not fully corrected by the workflow, but may be optimized using the troubleshooting section. In addition, differences in imaging acquisition or metadata formatting across platforms may limit the direct applicability of the protocol without experimental or file modification.

TRACEQC relies primarily on positional metadata and geometric transformations to evaluate correspondence and correct misalignment across time points, without incorporating image-based features such as spheroid morphology. As a result, robustness is reduced when abrupt biological changes occur between imaging intervals. Missing, incomplete, or inaccurately recorded metadata can further reduce the reliability of temporal reassignment. Large datasets with high spheroid counts or frequent imaging may increase processing time and computational resource requirements. If spheroids are positioned in a perfectly symmetrical polygonal configuration (e.g., a square or regular hexagon), rotational symmetry can lead to ambiguities in alignment, making it difficult to correctly permute objects across time points. Furthermore, if two spheroids are embedded too closely together, then TRACEQC may not be able to correctly assign points depending on the amount of displacement for each spheroid (note: in this situation, it is likely the two spheroids have been embedded such that their environments are influencing each other; see troubleshooting problem 2). This protocol was validated using specific 3D tumor spheroid datasets, and its generalizability to other culture systems or imaging frameworks may require experimental optimization and additional validation.

Troubleshooting

Problem 1

Failed collagen plug polymerization (related to Step 7). For visual reference: see Figure 9B and 9C for examples of spheroid drift caused by matrix instability.

Figure 9.

Common experimental problems and troubleshooting examples

(A) Common technical problems that compromise TRACEQC analysis. Left to right: fragmented spheroid resulting from mechanical damage during embedding or transfer (Problem 3); spheroid aggregation or inadequate spacing preventing individual cell tracking (Problem 2); spheroid dissociation caused by incomplete collagen polymerization (Problem 1); poor image contrast or excessive background noise due to suboptimal acquisition parameters.

(B) Individual spheroid displacement (red arrow) between 24 and 72 hours. Excessive movement may indicate failed collagen polymerization (troubleshooting, problem 1) rather than true cell migration.

(C) Whole collagen plug rotation (red curved arrow) between timepoints due to stage drift or environmental disturbance. This global movement affects all spheroids uniformly and is computationally corrected during TRACEQC analysis.

∗Note: Panels B and C show whole-well images for demonstration purposes only. Standard TRACEQC workflow uses individual field-of-view images, as whole-well imaging at each timepoint is impractical due to increased acquisition time and data storage requirements. TRACEQC automatically handles plug rotation and positional artifacts without requiring whole-well imaging. (A-C) Scale bars = 500 μm.

Potential solution

• •Verify that the collagen mix was prepared correctly according to the protocol.
• •Check reagent quality and lot numbers; expired or faulty reagents can prevent proper gelation.
• •Confirm that the pH of the collagen mix is between 7.2–7.4 (optimal for polymerization).
• •Avoid disturbing the plug after placing the matrix in the incubator; pipetting or touching it prematurely before it sets can disrupt fiber formation.
• •Remove air bubbles from the collagen mix before allowing it to set.

Problem 2

Spheroids are positioned too close to each other or have merged (related to step 11). For visual reference: see Figure 9A for an example of inadequate spheroid spacing.

Potential solution

• •Handle spheroids gently using wide-bore pipette tips to prevent damage and maintain spacing (purchase commercially or create by cutting standard tips with scissors).
• •Reduce the number of spheroids per well to allow adequate space between individual spheroids (no more than 6 spheroids recommended in one well of a 24-well plate).
• •Extend the incubation time between embedding spheroids in sequential wells to allow initial gelation, preventing spheroid movement and aggregation.

Problem 3

Spheroids appear fragmented or dissociated (related to Step 11 and Step 20). For visual reference: see Figure 9A for an example of inadequate spheroid spacing.

Potential solution

• •Verify spheroid integrity under microscope before embedding.
• •Optimize initial spheroid formation conditions such as cell seeding density, sufficient time for spheroid compaction and maturation, and pipetting technique to minimize shear forces.

Note: If multiple spheroids appear within the same field of view, DO NOT USE these samples for downstream TRACEQC analysis.

Problem 4

TRACEQC Fails to Load Data (related to Step 34).

Potential solution

Check to see that the input data file is formatted for TRACEQC compatibility. The file should be a comma separated values (csv) file in either the wide (rows as spheroids and columns as X and Y position values are each time point) or long format (rows as spheroids and positions at each point in time). See the example on the first page of the GUI (Figure 2). TRACEQC will not be able to run on data formatted incompatibly. Try re-uploading or re-processing your data after reconfiguring it to the appropriate wide/long format (Step 25).

Resource availability

Lead contact

Further information and requests for resources and reagents should be directed to and will be fulfilled by the lead contact, Jacquelyn W. Zimmerman (jzimme27@jhmi.edu).

Technical contact

Technical questions regarding the use of TRACEQC in this protocol should be directed to and will be answered by the technical contact, Dr. Young Hwan Chang (chanyo@ohsu.edu).

Materials availability

No new unique reagents were generated.

Data and code availability

The software code together with detailed instructions can be found on Zenodo (https://doi.org/10.5281/zenodo.16590562) and GitHub (https://github.com/emcramer/TRACEQC). The GUI for TRACEQC is available to use as a Streamlit web application at https://traceqc.streamlit.app/. No datasets beyond those for the initial publication of TRACEQC, which are included in the Zenodo repository (https://doi.org/10.5281/zenodo.17196124), were generated for this protocol.

Acknowledgments

We thank Dr. David Tuveson, Dr. Dennis Plenker, Dr. Amber Habowski, and Hardik Patel for kindly sharing the hT231 cell line and Dr. Elizabeth Jaffee and Dr. Richard Burkhart for their mentorship. We acknowledge Genevieve Stein-O’Brien and Paul Macklin and thank them for their feedback. This work was supported by the Jayne Koskinas Ted Giovanis Foundation for Health and Policy grant awarded to L.M.H. E.J.F. was supported by NIH/NCI U24CA284156. V.W. is supported by the T32CA153952. E.M.C. was supported by the NIH/NCI 1T32CA254888-01 and by the NIH/NIGMS 5T32GM141938-04. J.W.Z. and T.L.-V. report funding for the spheroid and CAF experiments from the Charles and Margaret Levin Family Foundation and the Dana & Albert R. Broccoli Charitable Foundation. A.T.W. is supported by a Team Science Award from the Mark Foundation, the Melanoma Research Alliance, and the Samuel Waxman Cancer Research Foundation. A.T.W. is also supported by P01CA114046 (NCI), U01CA227550 (NCI), R01CA232256 (NCI), R01CA207935 (NCI), a Bloomberg Distinguished Professorship, and the EV McCollum Endowed Chair. The research reported in this publication used computational infrastructure supported by the Office of Research Infrastructure Programs, Office of the Director, of the National Institutes of Health under award no. S10OD034224. The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.

Author contributions

E.M.C.: conceptualization, data curation, formal analysis, methodology, project administration, software, validation, visualization, writing – original draft, and writing – review and editing. T.L.-V.: conceptualization, data curation, investigation, methodology, visualization, writing – original draft, and writing – review and editing. V.W.: conceptualization, data curation, formal analysis, methodology, project administration, validation, visualization, writing – original draft, and writing – review and editing. J.J.: writing – review and editing. D.R.B.: writing – review and editing. A.T.W.: funding acquisition and supervision. J.W.Z.: funding acquisition, supervision, and writing – review and editing. E.J.F.: funding acquisition, supervision, project administration, and writing – review and editing. L.M.H.: funding acquisition, supervision, project administration, and writing – review and editing. Y.H.C.: conceptualization, methodology, funding acquisition, supervision, project administration, and writing – review and editing.

Declaration of interests

A.T.W. is on the boards of reGAIN Therapeutics and the Melanoma Research Foundation and the scientific advisory committee of the V Foundation. J.W.Z. reports grant funding support (to Johns Hopkins) and travel from Roche/Genentech outside the submitted work, and honoraria from Sermo and ZoomRx. E.J.F. is on the scientific advisory committee to the V Foundation, was on the scientific advisory board of Resistance Bio/Viosera Therapeutics, and is a consultant for Mestag Therapeutics.