PhIPData-class: The PhIPData class
In athchen/PhIPData: Container for PhIP-Seq Experiments

Description Usage Arguments Details Value Constructor See Also Examples

The PhIPData class is a matrix-like container designed to organize results from phage-immunoprecipitation (PhIP-Seq) experiments. Rows in PhIPData objects represent peptides and columns represent samples. Each object contains at least three assays:

counts: a matrix of raw read counts,
logfc: a matrix of log2 estimated fold-change in comparison to beads-only samples,
prob: a matrix of probabilities associated with whether a sample has an enriched antibody response for a peptide.

The PhIPData class extends the RangedSummarizedExperiment class, so methods documented in RangedSummarizedExperiment and SummarizedExperiment also work on PhIPData objects.

PhIPData(
  counts = matrix(nrow = 0, ncol = 0),
  logfc = matrix(nrow = 0, ncol = 0),
  prob = matrix(nrow = 0, ncol = 0),
  peptideInfo = S4Vectors::DataFrame(),
  sampleInfo = S4Vectors::DataFrame(),
  metadata = list(),
  .defaultNames = "info"
)

`counts`	a `matrix`, `data.frame`, or `DataFrame`of integer read counts.
`logfc`	a `matrix`, `data.frame`, or `DataFrame` of log2 estimated fold changes.
`prob`	a `matrix`, `data.frame`, or `DataFrame` of probability values (p-values or posterior probabilities) for enrichment estimates.
`peptideInfo`	a `data.frame` or `DataFrame` of peptide information.
`sampleInfo`	a `data.frame` or `DataFrame` of additional sample information.
`metadata`	a `list` object containing experiment-specific metadata.
`.defaultNames`	vector of names to use when sample and peptide identifiers disagree across the metadata and the `counts`, `logfc`, and `prob` matrices. If `.defaultNames` is of length 1, the same source is used for both peptide and sample identifiers. If `.defaultNames` is longer than 2, the first and second elements correspond to the names for peptides and samples, respectively. Valid options are: "info": names should be taken from the `SampleInfo` or `peptideInfo` objects. "counts": names should be taken from the row/column names of the `counts` object. "logfc": names should be taken from the row/column names of the `logfc` object. "prob": names should be taken from the row/column names of the `prob` object.

Rows of PhIPData objects correspond to peptides of interest and are organized in GRanges or GRangesList objects. Though originally designed for genomic ranges, the sequence name and genomic range information in GRanges objects can be replaced with peptide names and amino acid positions, respectively. If no peptide names are given, peptides are given the names of pep_rownum. Peptide positions are specified by columns pos_start and pos_end in the peptideInfo argument of the constuctor. Missing position information is set to 0. Additional peptide annotation can also be stored in GRanges objects and can be used to subset PhIPData objects as shown below.

Columns of PhIPData objects represent samples. Sample metadata are stored in a DataFrame and can be accessed as shown below. If no sample names are specified, samples are given default names of sample_colnum.

Unlike RangedSummarizedExperiment/SummarizedExperiment objects, PhIPData objects must contain counts, logfc, prob. If any of the three assays are missing when the constructor is called, an empty matrix of the same names and dimensions is initialized for that assay. Sample and peptide names are harmonized across assays and annotation during construction and replacement.

Though 'counts' typically contain integer values for the number of reads aligned to each peptide, 'PhIPData' only requires that stored values are non-negative numeric values. Pseudocounts or non-integer count values can also be stored in the 'counts' assay.

A PhIPData object.

PhIPData objects are constructed using the homonymous function and arguments as described above. Any PhIPData object can be created so long as peptide and sample identifiers (or lack thereof) are specified via any of the parameters.

PhIPData-methods for accessors and modifiers for PhIPData components. SummarizedExperiment

## Construct a new PhIPData object
counts_dat <- matrix(sample(1:1e6, 25, replace = TRUE), nrow = 5)
logfc_dat <- matrix(rnorm(25, 0, 10), nrow = 5)
prob_dat <- matrix(rbeta(25, 1, 1), nrow = 5)

peptide_meta <- data.frame(
    pos_start = 1:5,
    pos_end = 6:10,
    species = c(rep("HIV", 3), rep("EBV", 2))
)
sample_meta <- data.frame(
    gender = sample(c("M", "F"), 5, TRUE),
    group = sample(c("ctrl", "trt", "beads"), 5, TRUE)
)
exp_meta <- list(
    date_run = as.Date("2021/01/20"),
    reads_per_sample = colSums(counts_dat)
)

rownames(counts_dat) <- rownames(logfc_dat) <-
    rownames(prob_dat) <- rownames(peptide_meta) <-
    paste0("pep_", 1:5)
colnames(counts_dat) <- colnames(logfc_dat) <-
    colnames(prob_dat) <- rownames(sample_meta) <-
    paste0("sample_", 1:5)

phip_obj <- PhIPData(
    counts_dat, logfc_dat, prob_dat,
    peptide_meta, sample_meta, exp_meta
)
phip_obj