CTCeek v2:
a frozen-reference classifier for candidate circulating and disseminated tumor cells in single-cell RNA-seq data. Uploaded query cells are normalized against the trained SV2 reference model and scored by nearest-neighbor similarity to curated reference labels. C1 Scanorama two-batch is the recommended fast default; C2 multibatch is optional expert corroboration when suitable query batch metadata are available.
Query cells are visualized on the frozen
umap.sv2.pca
reference map by weighted averaging of their nearest reference neighbors; the app does not compute a new query UMAP. An optional FM/scGPT audit can be added after the main result, but it is review-only: it does not filter cells, overwrite CTCeek calls, or change C0/C1/C2/C3 outputs.
CTCeek v2 accepts an unseen Seurat query object, prepares it with the same reference-normalization logic used by the SV2 model, maps it against the frozen reference, scores each query cell by weighted nearest-reference neighbors, and exports tabular predictions plus frozen-reference UMAP placements.
The app is intentionally progressive. The main C1 result is returned first. Optional review layers can then be added without changing the main CTCeek call.
1. Input requirements
-
Upload a Seurat
.rds
object.
-
The object must contain an
RNA
assay with gene-level counts.
- Gene symbols should overlap the reference SCT/PCA feature set; low overlap will stop the run.
- C1 does not require a query metadata batch column.
-
C2 requires the configured query batch column, usually
orig.ident
.
- Large uploads or blood-dominated uploads may trigger the C0 composition guard before Scanorama mapping.
- The app performs basic upload QC but does not replace biological sample QC. Filter low-quality, doublet-rich or otherwise inappropriate cells before upload when needed.
-
The current web upload limit is
2048 MB
; larger Seurat objects should be handled on the server or by changing the deployment limit.
2. Required and optional query columns
-
Required:
a Seurat object with an
RNA
assay. No metadata column is required for C1.
-
Recommended for C2:
orig.ident
or the configured query batch column. C2 uses this to split the query into batches; if absent, C2 is skipped.
-
Optional metadata:
copy-number, cell-type or other annotations may help biological interpretation, but CTCeek v2 does not require or compute CopyKAT/aneuploidy calls in the web app.
3. Reference and normalization
- The server loads the frozen SV2 reference RDS, including the trained normalization model and reference reductions.
- Query cells are normalized against the trained reference SCT model and placed into the frozen reference geometry for scoring.
-
The reference includes
scanorama
,
pca.sv2
and
umap.sv2.pca
reductions.
-
The frozen UMAP shown by the app is
umap.sv2.pca
. Query coordinates are estimated from nearest reference neighbors; no new query UMAP is computed.
4. Mapping modes
-
Strict SV2 / A:
an internal audit baseline without Scanorama correction. It is retained in tables but is not the recommended visual mode.
-
C1 Scanorama two-batch:
the recommended routine mode. Reference cells are treated as one batch and query cells as one batch before nearest-neighbor scoring.
-
C2 Scanorama multibatch:
optional expert corroboration. Reference and query are split by configured batch columns; if the required query batch column is absent, C2 is skipped.
-
C3 Symphony:
a conservative confirmation layer, currently experimental.
5. Prediction and CTC scoring
- For each query cell, CTCeek identifies nearest reference neighbors in the selected embedding.
- Neighbor distances are converted to weights and label scores are summed across weighted neighbors.
- The top weighted label becomes the predicted label.
-
The CTC score is the combined weighted support for configured CTC-like labels, currently
CTCepiA, CTCepiB, CTCmes
.
- CTCeek reports strict CTC calls and lower-threshold CTC-like candidates for review.
6. Optional FM/scGPT audit
- FM/scGPT is an optional experimental audit layer. It embeds C0-eligible query cells with scGPT and compares them with the frozen CTCeek/SV2 reference in foundation-model embedding space.
- It can be requested when submitting the job or launched later from the completed job directory without rerunning C1.
- It does not filter cells, relabel CTCeek classifications, overwrite C1/C2/C3 calls, or change C0 composition-guard decisions.
-
CTC_supported
indicates neighborhood support from CTC-labeled reference states.
-
blood_confounded_review
indicates strong blood, immune or erythroid neighborhood support and should be interpreted cautiously.
- FM/scGPT labels are review evidence only, not diagnostic calls.
User parameters
| Parameter |
Default |
Meaning |
Maximum upload size
|
2048 MB |
Largest Seurat RDS file accepted through the web page in this deployment. Larger files should be processed on the server or require changing CTCEEKSV2_MAX_MB. |
Mapping modes
|
C1 default; C2 optional; C3 experimental confirmation |
Use C1 for routine sensitive mapping. Add C2 for multibatch corroboration when suitable batch metadata are available. C3 Symphony is a conservative experimental confirmation layer. |
Scanorama cores
|
8 |
Fixed for the web app to keep server behavior predictable; this controls CPU threads requested for Scanorama and numerical libraries. |
k nearest neighbors
|
50 |
Number of reference neighbors used for distance-weighted label scoring and UMAP coordinate placement. |
Strict CTC score threshold
|
0.65 |
Threshold used to call a conservative CTC when the top label is CTC-like and the CTC score is high enough. |
Candidate score threshold
|
0.5 |
Lower threshold used to flag CTC-like candidates for review even when they do not satisfy the conservative call. |
Optional FM/scGPT audit
|
Off |
Runs a foundation-model nearest-neighbor audit after the main CTCeek result when requested. On the validated 136-cell test query it added approximately 1-2 minutes on the current GPU server. It does not change CTCeek calls. |
Post-hoc FM audit
|
Available after the main result completes |
Lets the user launch FM/scGPT from the completed job directory without rerunning C1. |
FM/GPU lock
|
One FM audit at a time |
Serializes scGPT GPU use so concurrent FM audits cannot overload the server. |
Outputs
-
Mode summary:
number of cells, top CTC-like predictions, high CTC-score cells and median nearest-neighbor distances by mode.
-
Concordance:
agreement between C1 and C2 when both modes are run.
-
Raw output CSV:
per-cell predictions, CTC score, margin, candidate call and nearest-neighbor distance.
-
UMAP views:
reference annotations or query predicted labels on the same frozen reference coordinate system.
-
PNG/PDF downloads:
high-resolution raster or vector UMAP exports.
-
C0 composition guard report:
records whether downsampling was needed and which cells were included in Scanorama mapping.
-
FM/scGPT audit report:
optional review-only nearest-neighbor audit in scGPT embedding space.
Interpretation note:
CTCeek v2 reports candidate cell states based on transcriptomic similarity to the fixed reference. These outputs are not a standalone clinical diagnosis. Interpretation should consider sample preparation, QC, marker expression, copy-number evidence when available, epithelial/mesenchymal programs, blood/immune contamination, and biological context.
FM/scGPT interpretation:
FM/scGPT audit labels are evidence flags, not diagnostic calls. They are intended to help review CTCeek candidates and identify blood-confounded or ambiguous neighborhoods. They do not modify CTCeek classifications.
Concurrency note:
CTCeek currently allows one active main mapping job at a time on this server. FM/scGPT audits use a separate GPU lock, so only one FM audit can run at a time. If another main analysis or FM audit is active, the app will ask you to try again after the current process completes.
