Tumour Feature Models from Pathology Representations

Builds and applies portable cancer-specific partial least squares (PLS) regression and partial least squares with linear discriminant analysis (PLS-LDA) model collections from pathology foundation-model representations. Feature and outcome tables are linked by explicit patient identifiers, repeated slide rows are pooled at patient level, and model development uses nested cross-validation before final fitting. The source package contains no fitted foundation-model parameters, embeddings, patient-level data, or atlas registry. Users may download a separately licensed, checksum-verified Prov-GigaPath collection after installation, or load authorized collections from local files. Outputs are research estimates without external-validation or clinical-use claims. The methods build on Wold et al. (2001) and Barker and Rayens (2003) .

PathoFMPred

PathoFMPred builds and applies portable collections of cancer-specific PLS regression and PLS-LDA models from pathology foundation-model slide representations. It links feature and outcome tables by an explicit patient identifier, pools repeated slide rows at patient level, performs nested cross-validation, and fits a final model for each eligible outcome.

The source code is available under the MIT license. The CRAN-oriented source package contains no fitted model collection, atlas registry, slide embedding, or patient-level data. Fitted collections obtained separately are governed by their own terms; the package MIT license does not cover them.

These models provide internally derived TCGA research estimates. They have not been externally validated and are not intended for diagnosis or treatment. Binary scores and reference ranks are not probabilities.

See inst/licenses/MODEL_ACCESS.md for the package boundary. An optional Prov-GigaPath collection is available as a separate, checksum-verified GitHub release. TITAN and Giga-SSL fitted objects are not publicly distributed. Existing collaborators retain access through the separate private repository.

Install

install.packages("fastPLS", repos = "https://cloud.r-project.org")
remotes::install_github("tkcaccia/PathoFMPred", dependencies = TRUE)

PathoFMPred checks the fastPLS version recorded with each fitted model. The current matched-atlas analysis uses fastPLS 0.4. A model built under an older version should not be mixed silently with the refreshed atlas results.

Download the optional Prov-GigaPath collection

library(PathoFMPred)
model_dir <- file.path(tempdir(), "pathofmpred-models")
fetch_pathofmpred_models("ProvGigaPath", destination = model_dir)
options(PathoFMPred.model_dir = model_dir)
available_pathofm_models("ProvGigaPath", cancer = "COAD")

The function downloads the separately licensed, fastPLS 0.4 fitted collection only when called. The release URL and SHA-256 digest are pinned in the package. The collection contains 620 cancer-specific Prov-GigaPath models and aggregate metadata, but no slide embeddings, patient records, or patient-level reference scores. Reference ranks are therefore unavailable from this public collection. Two CHOL objects were fitted under an exploratory exception requiring at least 10 labelled patients for continuous outcomes or 10 patients per binary class. They are excluded from default inference and require an explicit limited-evidence opt-in. The usual eligibility limits were not changed for other cancers. Nothing is downloaded during installation, package loading, checking, or vignette construction. The caller chooses where the verified object is stored. TITAN and Giga-SSL collections require separate authorized access or local construction from the published source tables.

Build a model collection

The first three arguments are mandatory. Outcome IDs must be unique. Feature IDs may repeat and are pooled by patient mean or median. The function stops when 100 or fewer unique IDs match and reports unmatched IDs plus missingness for every outcome.

features <- read.csv("slide_features.csv", check.names = FALSE)
outcomes <- read.csv("patient_outcomes.csv", check.names = FALSE)

object <- create_pathofmpred_object(
  feature_table = features,
  outcome_table = outcomes,
  id_column = "patient_id",
  aggregation = "mean",
  foundation_model = "my_representation",
  control = pathofmpred_control(
    components = 1:20,
    outer_folds = 5,
    inner_folds = 5,
    repeats = 5,
    method = "plssvd",
    binary_selection = "AUROC"
  ),
  output_file = file.path(tempdir(), "pathofmpred_my_representation.rds")
)

new_features <- read.csv("new_slide_features.csv", check.names = FALSE)
prediction <- predict_pathofmpred_object(
  object = object,
  features = new_features,
  id_column = "patient_id"
)

rsvd_oversample and rsvd_power remain NULL unless explicitly supplied, so the installed fastPLS defaults are used.

For a binary outcome encoded with labels other than 0/1 or FALSE/TRUE, define the event class explicitly. This prevents an alphabetical factor order from silently reversing the scientific meaning:

object <- create_pathofmpred_object(
  features, outcomes, "patient_id",
  outcome_types = c(KEAP1 = "binary"),
  positive_class = c(KEAP1 = "mutated")
)

Rebuild the three representation collections locally

The package vignette gives non-running examples for TITAN, Giga-SSL and Prov-GigaPath, including the official embedding sources, conversion script, patient-ID linkage and fitting calls. You must acquire each input under its own terms and prepare a patient-level outcome table from the cited molecular sources. The function create_pathofmpred_object() accepts any future slide representation with the same ID and numeric-feature rules. A newly fitted collection is not necessarily identical to the atlas reference collection unless its input snapshot, target definitions, eligibility rules and fitting settings also match.

TITAN policy

The CRAN source package does not distribute pathofmpred_titan.rds. Users may obtain the official TCGA slide representations from the gated MahmoodLab/TITAN repository and build their own object with create_pathofmpred_object(). The vignette documents the feature conversion and molecular, immune, pathway, aneuploidy, fusion, and MSI sources. The resulting local object can be applied with predict_pathofmpred_object(). Locally built TITAN objects should not be redistributed without permission from the upstream rights holder.

The access-controlled tkcaccia/PathoFMPred-private repository contains the project's research reference objects. Its access terms are separate from the CRAN package licence.

Apply the downloaded Prov-GigaPath collection

library(PathoFMPred)

model_dir <- file.path(tempdir(), "pathofmpred-models")
fetch_pathofmpred_models("ProvGigaPath", destination = model_dir)
options(PathoFMPred.model_dir = model_dir)
available_pathofm_models("ProvGigaPath", "COAD")
x <- example_pathofm_features("COAD", "ProvGigaPath")
pred <- predict_pathofm(
  cancer = "COAD",
  features = x,
  foundation_model = "ProvGigaPath",
  patient_id = "software_example"
)
pred[, c("endpoint", "outcome_type", "prediction",
         "predicted_class", "lda_score")]

No model is available in a fresh CRAN installation. To run a fully local example without any third-party model, use create_pathofmpred_object() with your own feature and outcome tables, then predict_pathofmpred_object(). See vignette("PathoFMPred-workflow") for the workflow and licensing boundary.