build_panel_sheet: Build Panel Sheet

In bjoleary/dxr: Diagnostic Product Evaluation in R

Build Panel Sheet

Description

A function to build an excel file with fill-in-the-blank cells for common information needed about a sample panel or ground-truth.

Usage

build_panel_sheet(
  panel_name,
  panel_description = NA_character_,
  n_samples,
  sample_groups = c("Positive", "Negative"),
  sample_matrices,
  analytes,
  targets,
  qualitative_outcomes = c("Positive", "Negative"),
  qualitative_comparators,
  semiquantitative_outcomes = NA_character_,
  semiquantitative_comparators = NA_character_,
  quantitative_units = NA_character_,
  quantitative_comparators = NA_character_
)

Arguments

panel_name	The name of the panel being used for the evaluation. Must be a character string (not a multi-level vector) and must not be NA.
panel_description	An optional sentence or paragraph describing the panel. Defaults to NA. If provided, it must be a string rather than a multi-level vector.
n_samples	The number of samples in the panel. Must be numeric and greater than 0. If not provided as an integer, it will be converted into one.
sample_groups	The descriptive terms used to describe groups of samples, provided as a character vector. Defaults to c("Positive", "Negative") for evaluations of qualitative tests, but additional levels can be added for, for example, potentially cross-reactive negative subgroups. This must be a character vector with at least one level.
sample_matrices	The matrix or matrices in which the samples are provided. For example, for a serology assay panel, this could be "Serum" for serum-only, "EDTA Plasma" for plasma only, or c("Serum", "EDTA Plasma") for evaluations involving multiple sample types. This must be provided with at least one level (not NA).
analytes	The analyte or analytes for which the panel has been characterized and truth has been established. For example, for a serology assay panel, this could be "Pan-Ig" or c("IgM", "IgG", "Pan-Ig"). This must be provided with at least one level (not NA).
targets	The target or targets for which the panel has been characterized and truth has been established. For example, for a SARS-CoV-2 assay, this could be "Spike" or "RBD". Multiple targets can also be used, such as c("Spike", "Nucleocapsid"). This must be provided with at least one level (not NA).
qualitative_outcomes	The valid qualitative outcomes associated with the panel. Typically, this should be c("Positive", "Negative"). Note that while the assay being evaluated may also provide an "Equivocal" result level, this level should not typically be included in the panel sheet, where ground truth is expected to have been determined for each sample present. This must be provided with at least one level (not NA).
qualitative_comparators	The qualitative comparator methods used to determine qualitative ground truth for the panel. For example, if an FDA-authorized PCR assay is used to determine ground truth–positive or negative–for an evaluation of an antigen assay, this can be provided as "FDA-authorized PCR assay" (or, ideally, the specific assay used, sample matrix, etc.). If different methods were used to characterize different samples, provide each method as an element of a character vector. For example, c("FDA-authorized PCR Assay 1", "FDA-authorized PCR Assay 2", "Both FDA-authorized PCR Assay 1 and 2").
semiquantitative_outcomes	The valid semi-quantitative outcomes associated with the panel. Defaults to NA, indicating that no semi-quantitative ground truth has been established for the sample panel. If titers or other information are available, the relevant levels must be provided as a character vector. For example: c("0", "100", "400", "1600", "6400") (where 0 corresponds to a sample with a negative qualitative truth).
semiquantitative_comparators	The semi-quantitative comparator methods used to determine qualitative ground truth for the panel. Works similarly to qualitative_comparators above. Defaults to NA. If semiqquantitative_outcomes are provide (not all NA), then this must be provided as well. If semiqquantitative_outcomes are not provide (all(is.na(semiqquantitative_outcomes))), then this must be NA as well.
quantitative_units	If quantitative outcomes have been established for the panel, this is a character string describing the units of those quantitative outcomes. Defaults to NA, indicating that no quantitative ground truth has been established for the sample panel. If the outcomes are unit-less, "Unit-less" can be used.
quantitative_comparators	The quantitative comparator methods used to determine qualitative ground truth for the panel. Works similarly to qualitative_comparators above. Defaults to NA. If quantitative_units is provide (not NA), then this must be provided as well. If quantitative_units is not provide (is.na(quantitative_units)), then this must be NA as well.

Value

Returns a list includint the panel_metadata and panel_table.

Examples

build_panel_sheet(
  panel_name = "Example Panel",
  panel_description = NA_character_,
  n_samples = 110L,
  sample_groups = c("Positive", "Negative"),
  sample_matrices = c("Serum", "Plasma"),
  analytes = c("IgM", "IgG", "Pan-Ig"),
  targets = c("Spike", "Nucleocapsid"),
  qualitative_outcomes = c("Positive", "Negative"),
  qualitative_comparators =
    c(
      "CDC Spike Antigen Assay and NCI Implementation of MS RBD Assay",
      "Collected Pre-2020"
    ),
  semiquantitative_outcomes = c("0", "100", "400", "1600", "6400"),
  semiquantitative_comparators = "CDC Spike Antigen Assay",
  quantitative_units = NA_character_,
  quantitative_comparators = NA_character_
)

bjoleary/dxr documentation built on Dec. 5, 2023, 8:33 p.m.