Read NULISAseq XML, perform normalization, and QC

Reads NULISAseq XML file or processes a pre-built raw data structure. This function can accept either a file path to an XML file, or a pre-built list structure (e.g., reconstructed from a NAS data object for reprocessing with sample exclusions).

loadNULISAseq(
  file,
  IC = NULL,
  IPC = NULL,
  SC = NULL,
  NC = NULL,
  TAP = TRUE,
  sample_group_covar = "SAMPLE_MATRIX",
  plateID = NULL,
  scaleFactor = 10^4,
  transformReverse_scaleFactor = 10^4,
  replace_cal_blank_zeros = FALSE,
  replace_zeros_with_NA = TRUE,
  AQ_NC_outlier_removal = FALSE,
  AQ_IPC_outlier_removal = FALSE,
  AQ_IPC_outlier_threshold = 3,
  AQ_IPC_mad_floor = 0.3,
  AQ_IPC_max_outliers = 1,
  AQ_NC_max_outliers = 1,
  NC_max_outliers = 1,
  security = TRUE,
  excludeSamples = NULL,
  excludeTargets = NULL,
  advancedQC = FALSE,
  forceDefaultQC = FALSE,
  ...
)

Arguments

file: Either a character string (file path) or a list (pre-built raw structure). If a file path, reads the XML file using readNULISAseq. If a list, must contain required fields: Data, samples, targets, IC, IPC, NC, SampleNames. Optional fields: SC, Calibrator, ExecutionDetails, plateID, attributes.
IC: string(s) that represents the names of internal control targets. Default is 'mCherry'.Only used for xml file formats.
IPC: string(s) present in the sample names that represent the inter-plate control wells. For example, 'IPC'. Set to NULL (default) to use the type variable from the Barcode B file or if there are no IPCs. Only used for xml file formats.
SC: string(s) present in the sample names that represent the sample control wells. For example, 'SC'. Set to NULL (default) to use the type variable from the Barcode B file or if there are no IPCs. Only used for xml file formats.
NC: string(s) present in the sample names that represent the negative control wells. For example, 'NC'. Set to NULL (default) to use the type variable from the Barcode B file or if there are no NCs. Only used for xml file formats.
TAP: If TRUE (default), uses TAP detectability criteria in sample QC which includes more matrix types than non-TAP criteria.
sample_group_covar: Optional column name in the Barcode B file and samples data matrix output by readNULISAseq that represents subgroups for which detectability will be calculated separately, in addition to overall detectability. Default is 'SAMPLE_MATRIX', Function will check first to be sure that the variable is present in the column names of the samples matrix. Can be set to NULL to not use this feature.
replace_cal_blank_zeros: Logical TRUE / FALSE. Default is FALSE. This parameter is passed to the applyAQ function. If FALSE, the "a" parameter for targets with a zero blank calibrator (NC) mean is set using the blank calibrator mean value (which would equal zero in these cases). IF TRUE, the "a" parameter for targets with a zero blank calibrator mean is set using the nonzero master curve "a" parameter estimate instead.
replace_zeros_with_NA: Logical TRUE / FALSE. This parameter is passed to the applyAQ function. When TRUE (default), any zero values in the AQ data output will be replaced with NA. When FALSE, these values remain as zero.
AQ_NC_outlier_removal: Logical TRUE / FALSE. Default is FALSE. When TRUE, up to AQ_NC_max_outliers NC outliers are removed per-target for AQ. Note: this and the other AQ_*_outlier_* options below only take effect when AQ is computed via NULISAseqAQ::applyAQ. When NULISAseqAQ is not installed and the function falls back to AQ values embedded in the XML, these options are ignored. If the XML file being read has a <Parameters> block (see MaxAqCalOutliersToRemove, MaxAqNcOutliersToRemove, MaxNcOutliersToRemove), those values are used as the default for AQ_IPC_outlier_removal/AQ_IPC_max_outliers, AQ_NC_outlier_removal/AQ_NC_max_outliers, and NC_max_outliers respectively, unless the corresponding *_outlier_removal/NC_max_outliers argument is explicitly passed by the caller.
AQ_IPC_outlier_removal: Logical TRUE / FALSE. Default is FALSE. This parameter is passed to the applyAQ function. When TRUE, up to AQ_IPC_max_outliers IPC / CAL outliers will be removed per-target if the NPQ mad-based z-score exceeds AQ_IPC_outlier_threshold.
AQ_IPC_outlier_threshold: z-score cutoff for identifying IPC / CAL outliers. This parameter is passed to the applyAQ function. Default is 3.
AQ_IPC_mad_floor: If the mad value is below AQ_IPC_mad_floor it will be replaced by this value, preventing low-variance targets from having unnecessary outlier removal. This parameter is passed to the applyAQ function. Default is 0.3.
AQ_IPC_max_outliers: Maximum number of IPC / CAL outliers to remove per-target when AQ_IPC_outlier_removal is TRUE. Default is 1.
AQ_NC_max_outliers: Maximum number of NC outliers to remove per-target for AQ when AQ_NC_outlier_removal is TRUE. Default is 1.
NC_max_outliers: Maximum number of NC outliers to remove per-target before LOD/detectability calculations. Default is 1. 0 disables removal.
security: Logical. Default is TRUE. Should security checks be performed before generating AQ data.
excludeSamples: A vector of sample names that will be excluded from all outputs.
excludeTargets: A vector of target names that will be excluded from all outputs.
advancedQC: Whether to use advancedQC metrics
forceDefaultQC: If TRUE, ignore any QC thresholds/criteria defined in the panel XML (`<QCThresholds>`) and use the hardcoded defaults only. Default FALSE: XML-defined thresholds override the defaults per-flag, and any flag absent from the XML falls back to its hardcoded default.
...: Additional arguments passed to readNULISAseq when file is a path, including canonicalTargets and targetMap.

Value

List of lists, data frames, and matrices. Output will differ slightly depending on the input file type. Includes sample_group_covar storing the column name used for sample grouping in detectability, so downstream functions can map group levels to SAMPLE_MATRIX for "High Abundance" labeling.