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,
Bridge = NULL,
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,
security = TRUE,
excludeSamples = NULL,
excludeTargets = NULL,
advancedQC = FALSE,
forceDefaultQC = FALSE,
...
)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, Bridge, Calibrator, ExecutionDetails, plateID, attributes.
string(s) that represents the names of internal control targets.
Default is 'mCherry'.Only used for xml file formats.
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.
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.
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.
If TRUE (default), uses TAP detectability criteria in sample QC which includes more matrix types than non-TAP criteria.
string(s) present in the sample names
that represent the bridge sample wells.
Set to NULL (default) to use the
type variable from the Barcode B file or
if there are no bridge samples (default).
Only used for xml file formats.
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.
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.
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.
Logical TRUE / FALSE. Default is FALSE.
When TRUE, a maximum of one NC outlier is 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.
Logical TRUE / FALSE. Default is FALSE.
This parameter is passed to the applyAQ function. When TRUE, a maximum of
one IPC / CAL outlier will be removed per-target if the NPQ mad-based
z-score exceeds AQ_IPC_outlier_threshold.
z-score cutoff for identifying IPC / CAL outliers. This parameter is passed to the applyAQ function. Default is 3.
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.
Logical. Default is TRUE. Should security checks be performed before generating AQ data.
A vector of sample names that will be excluded from all outputs.
A vector of target names that will be excluded from all outputs.
Whether to use advancedQC metrics
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.
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.