The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Package {PathoFMPred}


Type: Package
Title: Tumour Feature Models from Pathology Representations
Version: 0.1.0
URL: https://github.com/tkcaccia/PathoFMPred
BugReports: https://github.com/tkcaccia/PathoFMPred/issues
Description: 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) <doi:10.1016/S0169-7439(01)00155-1> and Barker and Rayens (2003) <doi:10.1002/cem.785>.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.6.0)
Imports: digest, fastPLS (≥ 0.4), ggplot2, rmarkdown, stats, utils
Suggests: knitr, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-10-27 08:40:32 UTC; stefano
Author: Aamilah Ismail [aut], Martin Ocharo [aut], Giulia Canarutto [aut], Moussa Kassim Mohamed [aut], Dalia Ahmed [aut], Brendon Price [aut], Dupe Ojo [aut], Ekene Emmanuel Nweke [aut], Alessia Vignoli [aut], Silvano Piazza [aut], Dinesh Gupta [aut], Leonardo Tenori [aut], Stefano Cacciatore [aut, cre]
Maintainer: Stefano Cacciatore <tkcaccia@gmail.com>
Repository: CRAN
Date/Publication: 2026-11-12 11:20:08 UTC

List locally available foundation-model representations

Description

List locally available foundation-model representations

Usage

available_foundation_models()

Value

A character vector. Availability means that at least one fitted research model collection is installed; it does not imply external validation or permission to redistribute the collection.


List available cancer-specific models

Description

List available cancer-specific models

Usage

available_pathofm_models(
  foundation_model = NULL,
  cancer = NULL,
  outcome_type = NULL,
  family = NULL,
  include_limited_evidence = FALSE
)

available_titan_models(
  cancer = NULL,
  outcome_type = NULL,
  family = NULL,
  include_limited_evidence = FALSE
)

Arguments

foundation_model

One or more of 'TITAN', 'GigaSSL', or 'ProvGigaPath'.

cancer

Optional TCGA cancer code or vector of codes.

outcome_type

Optional 'continuous' or 'binary' filter.

family

Optional endpoint-family filter.

include_limited_evidence

Include limited-sample models only when they crossed the representation-specific matched effect threshold. Models tested below the threshold never enter prediction or reporting. The default is 'FALSE'.

Value

A filtered model-registry data frame.


Compare representation-specific models for one cancer-endpoint task

Description

Lists fitted reference objects for the same task while distinguishing object availability from representation-specific matched-atlas effect-threshold crossing. The inventory is a partial operationalization of the multi-representation atlas. The function does not automatically select the largest internal estimate or combine representation-specific predictions.

Usage

compare_pathofm_models(cancer, endpoint, outcome_type = NULL, family = NULL,
  include_limited_evidence = FALSE)

Arguments

cancer

TCGA cancer code.

endpoint

Exact endpoint label.

outcome_type

Optional continuous or binary filter.

family

Optional endpoint-family filter.

include_limited_evidence

Include limited-sample models only when they crossed the representation-specific matched effect threshold.

Value

A registry data frame with object-availability, matched-threshold, resource-scope and selection-guidance fields.


Build a portable PathoFMPred model collection

Description

Feature and outcome tables are linked only through 'id_column'. Outcome IDs must be unique. Feature IDs may repeat, for example when a patient has more than one slide, and are pooled before model development.

Usage

create_pathofmpred_object(
  feature_table,
  outcome_table,
  id_column,
  aggregation = c("mean", "median"),
  foundation_model = "custom",
  feature_columns = NULL,
  outcome_columns = NULL,
  outcome_types = NULL,
  positive_class = NULL,
  control = pathofmpred_control(),
  output_file = NULL
)

Arguments

feature_table

Data frame, matrix, or CSV path containing identifiers and numeric foundation-model features.

outcome_table

Data frame or CSV path containing one unique row per identifier and one or more outcomes.

id_column

Name of the identifier column present in both tables.

aggregation

How repeated feature rows are pooled: 'mean' or 'median'.

foundation_model

Label stored in the resulting object.

feature_columns

Optional numeric feature columns. By default all columns except 'id_column' are used.

outcome_columns

Optional outcomes to fit. By default all columns except 'id_column' are considered.

outcome_types

Optional named character vector containing 'continuous' or 'binary'. Otherwise numeric two-level outcomes are binary and other numeric outcomes are continuous.

positive_class

Event-class label for binary outcomes. Supply either one value when fitting a single binary outcome or a named character vector keyed by endpoint. Zero/one and FALSE/TRUE outcomes default to one and TRUE; all other binary labels require an explicit value.

control

Settings created by [pathofmpred_control()].

output_file

Optional '.rds' destination.

Value

A 'PathoFMPredObject' containing fitted models, a registry, nested-CV summaries, and a linkage/missingness audit.


Construct a synthetic feature vector for examples and smoke tests

Description

The vector is the across-model mean of stored training-feature means for the requested cancer and is not a patient record.

Usage

example_pathofm_features(
  cancer = "COAD",
  foundation_model = "ProvGigaPath",
  include_limited_evidence = FALSE
)

example_titan_features(cancer = "BRCA", include_limited_evidence = FALSE)

Arguments

cancer

A cancer code with locally installed models.

foundation_model

One of 'TITAN', 'GigaSSL', or 'ProvGigaPath'.

include_limited_evidence

Use limited-evidence models when constructing the synthetic across-model feature mean. The default is 'FALSE'.

Value

A one-row data frame containing the named features required by the selected representation.


Download user-authorized PathoFMPred model collections

Description

The source package contains no fitted models. For 'ProvGigaPath', the default is a versioned GitHub release asset whose SHA-256 digest is pinned in the package. It is downloaded only when this function is called. Other representations require an explicit authorized URL and SHA-256 digest. TITAN-derived objects are not downloadable through this helper.

Usage

fetch_pathofmpred_models(
  foundation_model = "ProvGigaPath",
  destination = NULL,
  base_url = NULL,
  expected_sha256 = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

foundation_model

'ProvGigaPath' or 'GigaSSL'.

destination

Explicit directory in which model collections will be stored. No directory is created unless the function is called with this argument.

base_url

Optional HTTPS release directory, or a 'file://' URL for an authorized local mirror. The pinned Prov-GigaPath release is the default when this is omitted.

expected_sha256

Optional named character vector containing a 64-character SHA-256 digest for every requested representation. The pinned Prov-GigaPath digest is the default for its release.

overwrite

Replace an existing file.

quiet

Passed to [utils::download.file()].

Value

Named paths to the downloaded model collections.


Read registries from locally available model collections

Description

The public package contains no fitted-model registry. This function reads metadata from collections that the user has installed under the applicable access terms. An empty data frame is returned when none is installed.

Usage

pathofm_model_registry()

titan_model_registry()

Value

A data frame with one row per locally available fitted model.


Create a single-sample pathology-foundation-model research output

Description

Create a single-sample pathology-foundation-model research output

Usage

pathofm_sample_report(
  cancer,
  features,
  foundation_model = c("TITAN", "GigaSSL", "ProvGigaPath"),
  patient_id = NULL,
  output_file = NULL,
  format = c("html", "pdf", "both"),
  clinical_context = NULL,
  include_limited_evidence = FALSE,
  quiet = TRUE
)

titan_sample_report(
  cancer,
  features,
  patient_id = NULL,
  output_file = NULL,
  format = c("html", "pdf", "both"),
  clinical_context = NULL,
  include_limited_evidence = FALSE,
  quiet = TRUE
)

Arguments

cancer

A single TCGA cancer code.

features

One or more slide-feature rows for one patient.

foundation_model

One of 'TITAN', 'GigaSSL', or 'ProvGigaPath'.

patient_id

Optional patient/sample identifier for all rows.

output_file

Explicit file stem or '.html'/'.pdf' path. Required; no report is written unless the caller chooses a destination.

format

One of 'html', 'pdf', or 'both'.

clinical_context

Optional named list with 'shared_features', 'pathology', and 'source' character fields. This information is displayed as supplied and is not used by any prediction model.

include_limited_evidence

Explicitly opt in to limited-sample models that still crossed the matched effect threshold for the selected cancer and representation. Tested-below-threshold objects never enter reports.

quiet

Passed to [rmarkdown::render()].

Value

Invisibly, the generated file path(s).


Define model-development settings

Description

Define model-development settings

Usage

pathofmpred_control(
  components = 1:20,
  outer_folds = 5L,
  inner_folds = 5L,
  repeats = 1L,
  scaling = "centering",
  method = "plssvd",
  backend = NULL,
  binary_selection = "AUROC",
  continuous_selection = "auto",
  seed = 1L,
  minimum_continuous = 50L,
  minimum_binary_class = 20L,
  rsvd_oversample = NULL,
  rsvd_power = NULL
)

Arguments

components

Candidate PLS component counts.

outer_folds, inner_folds

Numbers of nested cross-validation folds.

repeats

Number of independently seeded nested evaluations.

scaling, method, backend

Arguments passed to fastPLS.

binary_selection

Inner-CV objective for binary outcomes. AUROC is the default because the resulting score ranking is independent of prevalence- specific class priors.

continuous_selection

Inner-CV objective for continuous outcomes.

seed

Initial random seed.

minimum_continuous

Minimum labelled patients for a continuous model.

minimum_binary_class

Minimum patients in each binary class.

rsvd_oversample, rsvd_power

Optional overrides. 'NULL' preserves the installed fastPLS defaults.

Value

A settings list for [create_pathofmpred_object()].

Examples

settings <- pathofmpred_control(
  components = 1:3, outer_folds = 3, inner_folds = 3, seed = 42
)
settings$components

Plot PathoFMPred binary outputs

Description

Representation-neutral alias for [plot_titan_binary()]. Binary score ranks remain explicitly uncalibrated ranks, not probabilities.

Usage

plot_pathofm_binary(predictions)

Arguments

predictions

Output from [predict_pathofm()] for one patient.

Value

A ggplot object.


Radar plot of PathoFMPred continuous outputs

Description

Representation-neutral alias for [plot_titan_radar()]. The selected foundation model is carried in the prediction rows returned by [predict_pathofm()]; no representation is selected inside the plotting function.

Usage

plot_pathofm_radar(predictions, max_endpoints = 12L)

Arguments

predictions

Output from [predict_pathofm()] for one patient.

max_endpoints

Maximum number of endpoints, prioritising extremes.

Value

A ggplot object.


Plot binary PLS-LDA outputs

Description

Plot binary PLS-LDA outputs

Usage

plot_titan_binary(predictions)

Arguments

predictions

Output from [predict_pathofm()] for one patient.

Value

A ggplot object. Scores are displayed as TCGA out-of-fold score ranks explicitly labelled "not probability".


Radar plot of continuous prediction percentiles

Description

Radar plot of continuous prediction percentiles

Usage

plot_titan_radar(predictions, max_endpoints = 12L)

Arguments

predictions

Output from [predict_pathofm()] for one patient.

max_endpoints

Maximum number of endpoints, prioritising extremes.

Value

A ggplot object. Endpoint names and original model predictions are placed at the outer radar corners to avoid overlap with the profile.


Apply supported models for one pathology foundation-model representation

Description

Multiple rows with the same 'patient_id' are interpreted as multiple slides and mean-pooled before prediction, matching model development.

Usage

predict_pathofm(
  cancer,
  features,
  foundation_model = c("TITAN", "GigaSSL", "ProvGigaPath"),
  patient_id = NULL,
  outcome_type = c("continuous", "binary"),
  family = NULL,
  warn_ood = TRUE,
  include_limited_evidence = FALSE
)

Arguments

cancer

One TCGA cancer code per row, or one code recycled to all rows.

features

A matrix or data frame containing the correctly named features for 'foundation_model'.

foundation_model

One of 'TITAN', 'GigaSSL', or 'ProvGigaPath'.

patient_id

Optional identifier per row. Repeated identifiers are pooled.

outcome_type

One or more of 'continuous' and 'binary'.

family

Optional endpoint-family filter.

warn_ood

Warn when over 5 percent of dimensions fall outside training ranges.

include_limited_evidence

Explicitly opt in to limited-sample models that still crossed the representation-specific matched effect threshold. Models tested below the threshold never enter prediction or reporting.

Value

A long data frame with one row per patient and applicable model. For atlas collections, fields prefixed 'matched_tss_' describe the representation-specific sensitivity analysis that held complete TCGA tissue-source-site codes apart. 'repeated_auc' and 'repeated_pr_auc' are missing when five-repeat validation was not performed for that model; they are never filled with a primary-screen estimate. These internal performance fields do not validate an individual prediction.


Apply a user-created PathoFMPred object

Description

This function applies an object returned by [create_pathofmpred_object()]. It is the supported inference route for locally constructed TITAN objects and for future foundation-model representations that are not distributed by the package. Repeated feature rows are pooled using the aggregation rule recorded when the object was created, unless 'aggregation' is supplied.

Usage

predict_pathofmpred_object(
  object,
  features,
  patient_id = NULL,
  id_column = NULL,
  outcome_type = c("continuous", "binary"),
  endpoints = NULL,
  aggregation = NULL,
  warn_ood = TRUE
)

Arguments

object

A 'PathoFMPredObject' or the path to an '.rds' file containing one.

features

A data frame or matrix containing the named features used to fit 'object'. An identifier column may be selected with 'id_column'.

patient_id

Optional identifier per feature row. Use either 'patient_id' or 'id_column', not both. Repeated identifiers are pooled.

id_column

Optional identifier-column name in 'features'.

outcome_type

One or both of 'continuous' and 'binary'.

endpoints

Optional endpoint names to apply.

aggregation

Optional 'mean' or 'median' override. By default the object's model-development aggregation is used.

warn_ood

Warn when more than 5 percent of dimensions are outside the fitted training range.

Value

A long data frame with one row per patient and fitted endpoint. Binary outputs include the original event-class label. Scores are uncalibrated and are not probabilities.


Apply the legacy TITAN model interface

Description

Backward-compatible wrapper for [predict_pathofm()] with 'foundation_model = "TITAN"'.

Usage

predict_titan(
  cancer,
  features,
  patient_id = NULL,
  outcome_type = c("continuous", "binary"),
  family = NULL,
  warn_ood = TRUE,
  include_limited_evidence = FALSE
)

Arguments

cancer

One TCGA cancer code per row, or one code recycled to all rows.

features

A matrix or data frame containing the correctly named features for 'foundation_model'.

patient_id

Optional identifier per row. Repeated identifiers are pooled.

outcome_type

One or more of 'continuous' and 'binary'.

family

Optional endpoint-family filter.

warn_ood

Warn when over 5 percent of dimensions fall outside training ranges.

include_limited_evidence

Explicitly opt in to limited-sample models that still crossed the representation-specific matched effect threshold. Models tested below the threshold never enter prediction or reporting.

Value

A 'pathofm_predictions' data frame with one row for each patient and available TITAN endpoint. Continuous rows contain predictions in the recorded outcome scale. Binary rows contain an uncalibrated discriminant score and a class call; the score is not a probability.


Validate a PathoFMPred model collection

Description

Validate a PathoFMPred model collection

Usage

validate_pathofmpred_object(object)

Arguments

object

An object created by [create_pathofmpred_object()] or a distributed PathoFMPred model collection.

Value

'TRUE', invisibly, when the object is valid.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.