| Title: | Append CPTAC Proteomics Data to MultiAssayExperiment Objects |
|---|---|
| Description: | Integrates proteomic data from the Clinical Proteomic Tumor Analysis Consortium (CPTAC) into existing MultiAssayExperiment objects containing The Cancer Genome Atlas (TCGA) patient barcodes. The package queries the Proteomic Data Commons (PDC) GraphQL API to resolve studies by disease type and fetch quantitative protein log2 ratio matrices and biospecimen identifiers. It harmonizes TCGA barcodes with CPTAC case identifiers, constructs SummarizedExperiment objects whose colData holds the matched biospecimen identifiers and sample types, and appends the proteomic assays to the MultiAssayExperiment. It also downloads the CPTAC-3 and CPTAC-2 Prospective cohorts, which use their own patients, as MultiAssayExperiment objects with one experiment per PDC study and the PDC clinical data as colData. |
| Authors: | Marcel Ramos [aut, cre] (ORCID: <https://orcid.org/0000-0002-3242-0582>), Claude Haiku 5.5 [ctb] |
| Maintainer: | Marcel Ramos <[email protected]> |
| License: | Artistic-2.0 |
| Version: | 0.99.10 |
| Built: | 2026-11-18 17:40:53 UTC |
| Source: | https://github.com/BiocStaging/CPTACdata |
Takes a MultiAssayExperiment from curatedTCGAData, finds the CPTAC
studies in the Proteomic Data Commons (PDC) that were run on the same TCGA
tumors, and adds them as new experiments with a correct sampleMap.
appendCPTAC( mae, project = NULL, fraction = c("Proteome", "Phosphoproteome", "Glycoproteome"), replicates = c("all", "first"), dry_run = FALSE )appendCPTAC( mae, project = NULL, fraction = c("Proteome", "Phosphoproteome", "Glycoproteome"), replicates = c("all", "first"), dry_run = FALSE )
mae |
A |
project |
TCGA project, e.g. |
fraction |
The assay type to add: one of |
replicates |
How to handle technical replicates, which the PDC marks
with a |
dry_run |
If |
Only patients already in colData(mae) are added. Specimens are kept if
they carry a TCGA barcode, are "Qualified" and not pooled. Each new
experiment has one column per column of the PDC matrix, including every
technical replicate unless replicates = "first". Missing values are
NA. The quantification is the PDC Common Data Analysis Pipeline value
given by the data_type column of cptacProjects (log2 ratios to a common
reference).
Biospecimen tables are cached for the R session, so a dry_run followed by
a real run downloads them only once.
If dry_run = FALSE, the input mae with one new experiment per
PDC study, named as in the experiment column of cptacProjects. Each
experiment is a SummarizedExperiment with:
One assay, named after the data_type of the study (e.g.
"log2_ratio"), holding the PDC quantification matrix for the matched
samples. Rows are genes or protein sites, and missing values are NA.
Columns named by the PDC matrix label, with TCGA- added where the PDC
leaves it out. Proteome labels are sample barcodes (e.g.
TCGA-BH-A18U-01A) and phosphoproteome labels are aliquot barcodes
(e.g. TCGA-24-1555-01A-32-2224-29). The PDC marks technical
replicates with a .1, .2 suffix, which is kept (e.g.
TCGA-C8-A131-01A.1 and TCGA-C8-A131-01A.2).
colData with case_submitter_id (TCGA patient barcode),
sample_submitter_id (TCGA sample barcode, shared by the replicates
of a sample), aliquot_submitter_id, sample_type, and pdc_column
(the column label in the PDC matrix).
metadata with pdc_study_id, pdc_name, data_type, source (the
PDC GraphQL URL), pdc_study_version and pdc_study_uuid (the PDC
version of the study and its identifier, which pins that version),
retrieved (the time the matrix was downloaded) and
CPTACdata_version (the package version that downloaded it). Read them
with S4Vectors::metadata(mae[["CPTAC_Proteome"]]).
The new sampleMap links every new column to its TCGA patient. Studies
that are skipped, because they have no matrix, no matching patients or
are already in mae, add no experiment and give a warning or message.
If dry_run = TRUE, a data.frame with one row per study in
cptacProjects for the requested project and fraction, and these
columns:
experiment: experiment name the study would be added as.
pdc_study_id: PDC study ID.
quant_available: TRUE if the PDC has a quantification matrix for
the study.
mae_patients: number of patients in colData(mae). Same value for
every row.
pdc_patients: number of distinct TCGA patients in the PDC study that
pass the specimen filters. NA if there is no matrix.
matched_patients: number of those patients that are also in
colData(mae). NA if there is no matrix.
## The example queries the PDC API, so it runs only after you have accepted ## the PDC Data Use Agreement with options(CPTACdata.acceptDUA = TRUE). ## A small object stands in for a curatedTCGAData object here. if (isTRUE(getOption("CPTACdata.acceptDUA"))) { patients <- c("TCGA-BH-A18U", "TCGA-BH-A0C0", "TCGA-A8-A08Z") mae <- MultiAssayExperiment::MultiAssayExperiment( experiments = list( RNA = SummarizedExperiment::SummarizedExperiment( matrix( 0, nrow = 1L, ncol = 3L, dimnames = list("gene", patients) ) ) ), colData = S4Vectors::DataFrame( admin.disease_code = rep("brca", 3L), row.names = patients ), sampleMap = S4Vectors::DataFrame( assay = factor(rep("RNA", 3L)), primary = patients, colname = patients ) ) appendCPTAC(mae, fraction = "Proteome", dry_run = TRUE) mae <- appendCPTAC(mae, fraction = "Proteome") }## The example queries the PDC API, so it runs only after you have accepted ## the PDC Data Use Agreement with options(CPTACdata.acceptDUA = TRUE). ## A small object stands in for a curatedTCGAData object here. if (isTRUE(getOption("CPTACdata.acceptDUA"))) { patients <- c("TCGA-BH-A18U", "TCGA-BH-A0C0", "TCGA-A8-A08Z") mae <- MultiAssayExperiment::MultiAssayExperiment( experiments = list( RNA = SummarizedExperiment::SummarizedExperiment( matrix( 0, nrow = 1L, ncol = 3L, dimnames = list("gene", patients) ) ) ), colData = S4Vectors::DataFrame( admin.disease_code = rep("brca", 3L), row.names = patients ), sampleMap = S4Vectors::DataFrame( assay = factor(rep("RNA", 3L)), primary = patients, colname = patients ) ) appendCPTAC(mae, fraction = "Proteome", dry_run = TRUE) mae <- appendCPTAC(mae, fraction = "Proteome") }
The CPTAC patient cohorts in the Proteomic Data Commons (PDC) that
getCPTAC() can download, with one row per PDC study. A cohort, such as
the CPTAC-3 clear cell renal cell carcinoma discovery cohort, is profiled
in several PDC studies, one for each experiment (proteome,
phosphoproteome, acetylome, ...). getCPTAC() combines them in one
MultiAssayExperiment.
data(cptacCohorts)data(cptacCohorts)
A data.frame with one row per PDC study and 8 columns:
cohort: Cohort name, the PDC study name without the experiment
(e.g. "CPTAC CCRCC Discovery Study"), or a curated name for the
CPTAC-2 Prospective studies (e.g. "Prospective Breast").
experiment: Name of the experiment in the MultiAssayExperiment,
from the rest of the study name (e.g. "Proteome",
"DIA_Proteome").
pdc_study_id: PDC study ID.
pdc_name: PDC study name.
pdc_project: PDC project.
analytical_fraction: PDC analytical fraction, e.g. Proteome or
Phosphoproteome.
experiment_type: PDC experiment type, e.g. "TMT10" or
"Label Free".
data_type: quantDataMatrix data type that is downloaded; NA if
the PDC has no matrix for the study.
The table covers the PDC projects "CPTAC3 Discovery and Confirmatory" and
"CPTAC-2" (the Prospective collections). Studies of reference samples
only ("CompRef") and method studies are left out. Cohorts run on TCGA
tumors are in cptacProjects and are added to TCGA data with
appendCPTAC().
Some studies, such as most metabolome and lipidome studies, have no
quantification matrix available through the PDC API. They are listed with
data_type = NA and are skipped by getCPTAC().
Built from the PDC GraphQL API (https://pdc.cancer.gov/graphql)
by data-raw/cptacCohorts.R in the package sources. The cohort and
experiment names of the CPTAC-2 studies, and the excluded studies, are
curated in that script.
data("cptacCohorts", package = "CPTACdata") unique(cptacCohorts[["cohort"]]) cptacCohorts[ cptacCohorts[["cohort"]] == "CPTAC CCRCC Discovery Study", c("experiment", "pdc_study_id", "data_type") ]data("cptacCohorts", package = "CPTACdata") unique(cptacCohorts[["cohort"]]) cptacCohorts[ cptacCohorts[["cohort"]] == "CPTAC CCRCC Discovery Study", c("experiment", "pdc_study_id", "data_type") ]
A crosswalk between TCGA projects (e.g. "TCGA-BRCA") and the
Proteomic Data Commons (PDC) studies holding CPTAC data generated on the
same TCGA tumors (the PDC "CPTAC-TCGA" project). It is used by
appendCPTAC() to select studies.
data(cptacProjects)data(cptacProjects)
A data.frame with one row per TCGA project and PDC study
(8 rows) and 8 columns:
tcga_project: TCGA project ID.
pdc_study_id: PDC study ID.
pdc_name: PDC study name.
experiment: Name given to the experiment added to the
MultiAssayExperiment.
analytical_fraction: Proteome, Phosphoproteome or Glycoproteome.
data_type: quantDataMatrix data type that is downloaded; NA if
the PDC has no matrix for the study.
pdc_disease_type: PDC disease label used to split studies that span
several TCGA projects; NA if not needed.
verified: TRUE if every qualified TCGA patient in the study was
found in the GDC project when the data were built.
Cancer types profiled by CPTAC-3 (e.g. LUAD, ccRCC) and the "Prospective" CPTAC-2 collections are not included: those cohorts use new patients rather than TCGA samples, so there is nothing to match against a TCGA MultiAssayExperiment.
One study can cover more than one TCGA project (PDC000111 holds colon and
rectum tumors); pdc_disease_type separates them. The JHU and PNNL
ovarian proteomes share 33 patients and are separate experiments.
Some TCGA-derived studies (the colon proteome, PDC000111, and the ovarian
glycoproteome, PDC000112) have biospecimen records in the PDC but no
quantification matrix available through its API. They are listed with
data_type = NA and are skipped by appendCPTAC().
Built from the PDC GraphQL API (https://pdc.cancer.gov/graphql)
and the GDC API (https://api.gdc.cancer.gov) by
data-raw/cptacProjects.R in the package sources. Experiment names and
data types are curated in that script.
data("cptacProjects", package = "CPTACdata") cptacProjectsdata("cptacProjects", package = "CPTACdata") cptacProjects
Downloads the studies of one CPTAC cohort listed in cptacCohorts, such as
the CPTAC-3 clear cell renal cell carcinoma discovery cohort, and combines
them in a MultiAssayExperiment, with one experiment per study and the
PDC clinical data of the cohort's patients as colData.
getCPTAC( cohort, experiments = NULL, replicates = c("all", "first"), dry_run = FALSE )getCPTAC( cohort, experiments = NULL, replicates = c("all", "first"), dry_run = FALSE )
cohort |
The cohort to download, a value of the |
experiments |
The experiments to include, values of the |
replicates |
How to handle technical replicates, which the PDC marks
with a |
dry_run |
If |
Specimens are kept if they are "Qualified", not pooled, and come from a
patient: reference channels such as the internal reference pool, QC
samples and the NCI-7 cell lines (PDC disease type "Other") are dropped.
Columns are named by the PDC matrix label, which for these cohorts is the
aliquot_submitter_id; technical replicates keep their .1, .2
suffix. The quantification is the PDC Common Data Analysis Pipeline value
given by the data_type column of cptacCohorts.
Biospecimen and clinical tables are cached for the R session, so a
dry_run followed by a real run downloads them only once.
If dry_run = FALSE, a MultiAssayExperiment with:
One experiment per study, named as in the experiment column of
cptacCohorts. Each is a SummarizedExperiment with one assay, named
after the data_type of the study, holding the PDC quantification
matrix (missing values are NA). Its colData has
case_submitter_id, sample_submitter_id, aliquot_submitter_id,
sample_type and pdc_column (the column label in the PDC matrix),
and its metadata has the same provenance fields as the experiments
added by appendCPTAC().
colData with one row per patient (case_submitter_id), holding the
PDC disease type, demographics (e.g. gender, vital_status,
days_to_birth) and diagnosis (e.g. primary_diagnosis,
tumor_grade, ajcc_pathologic_stage, age_at_diagnosis). Values
are kept as the PDC reports them, as character. When a patient has
several diagnosis records, their distinct values are joined with
"; ".
A sampleMap linking every column to its patient.
If dry_run = TRUE, a data.frame with one row per selected study and
these columns:
experiment: experiment name.
pdc_study_id: PDC study ID.
quant_available: TRUE if the PDC has a quantification matrix for
the study.
patients: number of distinct patients in the study that pass the
specimen filters.
aliquots: number of their aliquots.
## Cohort and experiment names come from cptacCohorts, which ships with ## the package and needs no network access data("cptacCohorts", package = "CPTACdata") unique(cptacCohorts[["cohort"]]) ## Experiments of one cohort; those with data_type NA have no matrix ccrccStudies <- cptacCohorts[ cptacCohorts[["cohort"]] == "CPTAC CCRCC Discovery Study", c("experiment", "pdc_study_id", "data_type") ] ccrccStudies ## Downloading queries the PDC API, so it runs only after you have ## accepted the PDC Data Use Agreement with ## options(CPTACdata.acceptDUA = TRUE). if (isTRUE(getOption("CPTACdata.acceptDUA"))) { getCPTAC("CPTAC CCRCC Discovery Study", dry_run = TRUE) ccrcc <- getCPTAC( "CPTAC CCRCC Discovery Study", experiments = c("Proteome", "Phosphoproteome") ) ccrcc }## Cohort and experiment names come from cptacCohorts, which ships with ## the package and needs no network access data("cptacCohorts", package = "CPTACdata") unique(cptacCohorts[["cohort"]]) ## Experiments of one cohort; those with data_type NA have no matrix ccrccStudies <- cptacCohorts[ cptacCohorts[["cohort"]] == "CPTAC CCRCC Discovery Study", c("experiment", "pdc_study_id", "data_type") ] ccrccStudies ## Downloading queries the PDC API, so it runs only after you have ## accepted the PDC Data Use Agreement with ## options(CPTACdata.acceptDUA = TRUE). if (isTRUE(getOption("CPTACdata.acceptDUA"))) { getCPTAC("CPTAC CCRCC Discovery Study", dry_run = TRUE) ccrcc <- getCPTAC( "CPTAC CCRCC Discovery Study", experiments = c("Proteome", "Phosphoproteome") ) ccrcc }