NEWS.md
j with colors[j + 1], matching the HTML table. Plates without SC wells previously drew IPC and NC with colors[3] and colors[5] (issue #784).axis_limits now sets the value (NPQ) axis when horizontal = TRUE. It previously set the target axis (issue #785).insertCovariatesXML(sanitize_names = TRUE) lower-camel form (so "Visit Week" finds visitWeek). The name is no longer pasted into an XPath expression, so names such as "Visit (week)" no longer leak xml2 warnings. It stops with a specific message instead of silently returning a zip of unsplit XML copies with meaningless names when the XML has no covariates, the covariate is not found, or the name matches more than one covariate (issue #535).lmNULISAseq()/lmerNULISAseq() already return (return_model_fits = TRUE), so no refit is needed and any number of terms can be tested in one call. lm fits get an exact F test via car::Anova(); linear mixed fits get an F test with Satterthwaite denominator df via lmerTest, reported in a new DenDF column; glm fits get a likelihood-ratio chi-square, the same test glmNULISAseq_predict() reports as Chisq_stat; glmerMod fits get a Wald chi-square, since an LR test there would need the reduced-model refit this function exists to avoid. stat_type names which statistic each row holds. FDR and Bonferroni adjustment are computed within each term across targets. Unlike the existing reduced_modelFormula refit mechanism, it does not silently degenerate when the tested term is nested inside a higher-order term that remains in the model. Requested term names are matched by component set, so "group:sex:time" resolves even though terms() canonicalizes the label to "sex:group:time". Aliased (rank-deficient) coefficients from empty interaction cells are tolerated: the term is tested on its estimable coefficients with Df reduced to match, and a term with no estimable coefficient left is skipped for that target with a warning. When terms is NULL, terms are selected structurally from the design matrix, unioned across all fits, so an aliased coefficient or a factor level missing from one target cannot decide what is tested for the rest. Input is validated at the entry point: modelFits must be a uniquely named list of fits, and a missing or NULL value reports that lmNULISAseq()/lmerNULISAseq() need to be re-run with return_model_fits = TRUE (their default is FALSE) rather than failing later with a message about model terms. An unnamed or partially named list is now rejected instead of silently returning results for the named fits only.<QCThresholds> (and processing parameters via <Parameters>), overriding the hardcoded defaults in QC.R on a per-flag basis (issue #670). Flags absent from the XML fall back to their hardcoded defaults. New helper mergeQCCriteria() overlays XML thresholds onto the QC*Criteria() defaults (overriding only value-like fields; flag set, ordering, and thresholdNames stay code-defined). Supports per-matrix sample Detectability keys (Detectability_PLASMA → Detectability.plasma), appliesWhen="TAP" gating, and operator="none" informational-only rows (displayed, never flag). A new forceDefaultQC argument to loadNULISAseq() forces the hardcoded defaults and ignores the XML.AQ_NC_outlier_removal and AQ_IPC_outlier_removal (both default FALSE), plus AQ_IPC_outlier_threshold (default 3) and AQ_IPC_mad_floor (default 0.3). When enabled, a maximum of one NC and/or one IPC/CAL outlier is removed per-target during absolute quantification. Default behavior is unchanged. These options only take effect when AQ is computed via NULISAseqAQ::applyAQ; they are ignored in the XML-embedded fallback path.extract_assay_names() also now treats any unreported or blank <Assay> value as the literal name “NULISAseq” rather than “unknown, compatible with anything.”AlamarTargetID attribute on every BarcodeA/Barcode element that lacks one, from a caller-supplied targetName -> alamarTargetID table (data.frame or CSV). The call succeeds for every input or fails for all: each file is resolved first, and if any target name is missing from the table, listed under several ids, or carries an id that contradicts the table, the function stops with a message listing every offending target and writes nothing. On success a file with insertions is re-serialized by xml2; other outputs receive a byte-for-byte copy; existing ids are never changed.readNULISAseq() (and loadNULISAseq() / importNULISAseq(), which pass through) gains canonicalTargets = TRUE and targetMap = NULL. With canonicalTargets = TRUE (the default), every parsed targetName is rewritten to the current spelling the new alamar_target_map() table lists for its AlamarTargetID, before any matrix is keyed by name, so differently-spelled exports of the same target merge as one row across plates. A row with no id is backfilled from the table (current or alias spelling); an id-less spelling the table lists under more than one id takes the id whose species (optional table column) matches the plate’s species, derived from ExecutionDetails$Assay (guessed from the plate’s resolved ids when the assay name is the generic NULISAseq); when no single id remains, the row keeps its parsed spelling with AlamarTargetID = NA and a warning names the file and every candidate id. The as-parsed spelling is kept in targets$targetName_raw. targetMap layers caller-supplied targetName -> alamarTargetID aliases on top of the shipped table for one read (ids must already be rows of the table). IC and excludeTargets (and the QC-report YAML that feeds them) accept either the canonical spelling or the spelling parsed from the same file, and the default IC (mCherry, when IC = NULL on an XML without target types) follows a rename of that target too. IC target names are now matched exactly rather than as a regular expression, so a name such as LTA|LTB no longer marks LTA and LTB as controls too, and the default mCherry no longer marks a target whose name merely contains mCherry. A multi-element IC on an XML without target types now marks every listed target as a control; ifelse() truncated it to the first, so sample QC and detectability change for such calls. An IC or excludeTargets value that is one target’s canonical name and another target’s parsed spelling warns and uses the canonical match. A merge of plates whose targets carry different alamarTargetID values under one name warns, because the rows pool into one. writeNULISAseq() gains canonicalTargets and targetMap pass-through arguments; its target_info_file may name targets by the parsed spelling, and rows that match no target warn instead of vanishing from the workbook. The long tables (Data_NPQ_long, Data_AQ_long) and writeNULISAseq() carry the canonical Target and the resolved AlamarTargetID (populated for id-less XMLs where the table knows the spelling); targetName_raw stays in targets and is not exported. Set canonicalTargets = FALSE to keep names exactly as parsed. The long tables and writeNULISAseq() gain an opt-in include_target_provenance argument that adds a Target_raw column holding the parsed spelling next to the canonical Target; default off.insertTargetIDs argument (default FALSE) writes AlamarTargetID onto each BarcodeA/Barcode node that has no id. The ids come from data$targets, as readNULISAseq() resolved them. An existing id is never changed. If an existing id disagrees with data, the call stops and returns no XML. Hidden targets and targets in excludeTargets are not rows of loadNULISAseq() output, so they get no id. A target with no resolved id (an ambiguous or unknown name) also gets no id. A target whose id came from the plate’s species guess (its parsed spelling sits under several ids in the table) gets no id either, unless targetMap names that id. canonicalTargets/targetMap pass through when data is NULL. When data is supplied, an explicit canonicalTargets or targetMap gives a warning, because the function ignores it. A written id is permanent: a re-read of the output takes it without the alias table.target_mean_pca and the sample-level PCA intentionally keep reading the full, zero-inclusive matrix, since a joint multi-target PCA cannot drop scattered cells without imputing values or dropping whole targets/samples.Data_NPQ_long and Data_AQ_long now carry plate (run) level QC from qcPlate as Plate_QC_Status plus Plate_QC_<metric> and Plate_QC_<metric>_Status columns, repeated on every row of a plate (issue #641). Controlled by the existing include_qc argument. Target QC columns are still absent for RQ runs whose XML has no <TargetQC> and that were not processed with advancedQC; this change does not alter that.Target_Detectability) are now threshold=0 and operator="none": they display but never produce a pass/warning verdict. This is a permanent, non-overridable setting - mergeQCCriteria() explicitly excludes Detectability from panel-XML overrides, since many existing panel XML files carry a <QCThresholds> entry for it that mirrors the old hardcoded default and would otherwise silently re-enable flagging."001" and a literal "NA" category, becomes a factor with its values intact. Real NA values stay NA. The result no longer depends on plate order.x must be present in the data. Problem with plateID.” The renaming step skips data frames that have no plateID column, such as detectability.AbsData (the report’s Absolute-Quant-vs-Relative-Quant mode) was assigned inside the per-file for loop in the load-data chunk, so it leaked out as whatever the last plate’s AbsAssay happened to be. A batch mixing an AQ run with an RQ run of the same panel silently changed report mode (target QC criteria, AQSC/CAL vs SC/IPC labels) depending on plate order (issue #3936). AbsData is now computed once after all runs are loaded and requires every run to agree; a new AQ parameter to render_QC_report() lets a caller that already knows the merge stripped AQ fields (e.g. NAS) force RQ explicitly.ReadCount nodes for a target or sample barcode that was dropped from data$targets/data$samples (e.g. a hidden target, modifiers="hide"). .annotate_readcounts() looked up barcodes with [[ on a plain named vector, which errors on an unmatched name instead of returning NA; it now uses single-bracket indexing so unmatched barcodes are skipped like any other unresolved lookup.QCThresholds, PlateQC, SampleQC and TargetQC sections. The function writes a section only when it is absent. It does not recompute an existing section. Previously, one call on a 1.3.0 file added a second copy of each section. A re-read of such an AQ file could multiply the targetAQ_param rows, and a second call could crash. A repeat call now adds nothing. An input that already has more than one copy of a section stops the call. The message names the sections. Every ExecutionDetails/XMLversion node now gets the value 1.3.0. A call adds a node only when none exists, so a repeat call adds none. Previously, each call added one more node, and an older value stayed first. Every call still recomputes the ReadCount attributes that data has a value for, also on a 1.3.0 input.NULL immediately when defaults is NULL (e.g. QCTargetCriteria(advancedQC=FALSE) on a plain RQ run), instead of proceeding to warn that every panel-XML <TargetQC> threshold key has “no matching computation.” Previously, any plain RQ run with panel-XML target thresholds warned on every QCFlagTarget() recompute (issue #702).NULISAseqAQ and XML-embedded fallback modes: the fallback path includes the blank_outlier_table and IPC_outlier_table elements (as NULL) that applyAQ() returns.NULISAseqAQ::applyAQ only when the installed version accepts them (filtered against formals()), preventing an “unused arguments” error and aborted AQ processing when an older NULISAseqAQ is installed.sig_targets list instead of grepl(target, ...) (which matched substrings like CCL1→CCL14 and regex metacharacters like LTA|LTB). Site B: per-plate pairwise fraction now matches plate names with a bounded pattern instead of grep(plate, ...) (which matched Plate_1→Plate_10), while still matching emmeans’ parenthesized factor levels.NULL) before calling emmeans::emmeans() (issue #655), which previously aborted the entire report with “Can’t handle an object of class NULL”.IC_normed$normData alongside Data/samples/SampleNames (issue #655), keeping columns aligned so the IC-normalized control CV% is computed on the correct wells.IPC/NC/SC/Bridge/Calibrator (issue #697). Previously, if the excluded well was itself an IPC/NC/SC/Bridge control (e.g. an IPC well with zero internal-control reads), its name lingered in those lists after its column was dropped from Data, causing interPlateNorm() to fail with “subscript out of bounds” and aborting QC report generation entirely.drop=FALSE, and the function now errors clearly (“No IPC wells remain…” / “No samples remain for intensity normalization…”) when a plate’s IPC list or resolved intensity-normalization sample set (which covers NC and Bridge-based normalization) is empty, rather than silently treating a missing control as “no normalization needed.” It also now validates that IPC well names/indices actually exist in the data, raising a specific “not found in the data” error instead of the generic “subscript out of bounds.” Previously, a plate left with exactly one control well after exclusion crashed with the opaque dim(X) must have a positive length, and a plate left with zero wells of a given type silently skipped that normalization step (e.g. IPC factors defaulted to 1) instead of failing - producing a report that looked normalized but wasn’t. This also closes the same hole for loadNULISAseq(excludeSamples=...), which routes through the same function. Also fixed IPC_method='mean', which previously errored on any input due to an argument passed positionally into the wrong parameter.lod() now emits a warning and returns NA for LOD and an all-NA aboveLOD matrix (with blank_outlier_table = NULL) instead of calling stop(). Callers that caught the error, for example with tryCatch(), must now check for NA in the result. Downstream QC and detectability treat an NA aboveLOD as unknown, not as not-detected. It also uses drop=FALSE when subsetting blanks, which fixes the dim(X) must have a positive length crash when exactly one blank well remains after sample exclusion.grepl("", ...) matched every sample name and mislabeled all samples on that plate as “Bridge”. Also gave the sample-QC dotchart’s label index (inds) an explicit default so it can no longer be left undefined when neither the SC nor Bridge relabeling block runs for a plate.aboveLOD and detectability matrices for csv_long (Counts Report) input, which previously lacked these fields.ParseableMatch count, which previously inflated the reported match rate.filter_run_data() now uses drop=FALSE when subsetting samples/targets to preserve data.frame structure.row_split is now gated on cluster_rows; previously, passing cluster_rows=FALSE with the default row_split could produce an error (#669).sampleName is plate-suffixed; previously, the match was not anchored to the _ delimiter, causing mismatches (#644).render(), instead of producing an opaque error (#691).render_table coercion instead of being silently converted to integers.sanitize_names argument (default FALSE). When TRUE, covariate column names are passed through clean_covariate_names(case = "lower_camel") before being written as XML attributes, matching NAS’s covariate-upload sanitation so attribute names stay stable across NAS export → NULISAseqR import → NAS re-import (follow-up to Alamar-Biosciences/NULISA-Analysis-Software#3199). Default FALSE preserves the historical write-verbatim contract for direct callers. Errors with a clear message if sanitation would collide two original columns onto the same attribute name (e.g. sampleName + "Sample Name" both targeting sampleName)PlateID) by appending _covar suffix; emits a message when renaming occurs to inform users of the changedo.call(rbind) with dplyr::bind_rows() when aggregating samples across plates, fixing crashes when importing plates with different XML schemas (e.g. mismatched metadata columns)do.call(rbind) with dplyr::bind_rows() for RunSummary aggregation; drops NA-named slots from each plate’s RunSummary list to eliminate spurious NA. columns when plates have no balancers in the XMLis.na() instead of is.null() for XML attribute checks, fixing silent failures when attributes return NA rather than NULL
covariates$sampleName is plate-suffixed (e.g. LowQC_Plasma_begin_<plate>.xml), which previously produced NA for the injected covariate on every QC sample on re-import (issue Alamar-Biosciences/NULISA-Analysis-Software#3199). Match now anchors on either exact equality or the _<plate>.xml suffix used by NAS, avoiding both the prior silent-skip and the substring over-match it could regress into. Empty or whitespace-only barcode text is now skipped explicitlynoDetectability modifiernoDetectability modifier have individual detectability computed but are excluded from summary statistics (mean, sd, median, min, max, # detectable targets)exclude_targets parameter; consolidated and centralized detectability formatting logic to avoid duplication; “High Abundance” label now shown only for PLASMA/SERUM matrix types; detectability set to NA for non-plasma/serum sample types; returns numeric columns by default (format=FALSE) to preserve downstream computationinclude_IC_counts = TRUE
tolower) in quantifiability() and the QC report skeleton to ensure consistent ordering across platformsnoDetectability targets kept in batch effect assessment; guarded against edge caseslmNULISAseq.R); removed LazyData field; added withr to Suggestsapply() dimension drop in detectability output table; fixed rowSums NA handling and guarded against empty target sets in aggregationnoDetectability targets from detectability calculationsnoDetectability targets now correctly included in Failed_Targets for CV criterion onlynumericCovariates for list inputstibble:: prefix for column_to_rownames()
noDetectability target handlingxml_files parameter moved to first position for more intuitive usageoutput_filename (“NULISAseq_QC_Report.html”) and output_dir (current working directory)dataDir (current working directory)Rmd_input_file path construction using system.file()
data_matrix before blanks)targetNoOutlierDetection only includes targets present in data_matrix
intersect() to find common samples between Data_AQ_aM and SampleNames
LOD_pgmL (limit of detection in pg/mL units) from XML data for AQ assayslod() function call to use data_matrix= explicitlytest-importNULISAseq.R - Tests for importNULISAseq() function with and without NULISAseqAQ package, including fallback mode validation and AQ data consistency checkstest-reverse-curve.R - Tests for reverse curve target handling, including correlation validation, data transformation verification, and NPQ value consistency between loadNULISAseq() and importNULISAseq()
test-writeNULISAseq.R - Tests for Excel output generation with both RQ-only and AQ data, including validation of sheet structure, column names, and specific data valuesinst/rmarkdown/templates/nulisaseq/skeleton/ to tests/testthat/fixtures/ for better organization.gitignore file from skeleton template directoryAUTO_PLATE IDs with duplicate detection before processingexcludeSamples, excludeTargets, and control parameters (IC, IPC, SC, NC, Bridge, Calibrator) using prioritized keys (user-provided plate names, internal IDs, or fallback names)AUTO_PLATE ID from NULISAseq XML file headersVersion 1.4.0 represents a major expansion of the NULISAseqR package, introducing new analytical capabilities, enhanced visualization tools, and improved data processing functions.
loadNULISAseq() which accommodates absolute quantification (AQ) NULISAseq assay panelsFour new functions enable using single-target NPQ as a predictor in covariate-adjusted linear and logistic regression models:
withinDR matrix to AQ output for dynamic range filteringimportNULISAseq functionupper_log2FC_threshold and lower_log2FC_threshold parameters for labeling targets based on effect sizewriteNULISAseq (empty cells vs “NA” string)drop=FALSE)Full Changelog: https://github.com/Alamar-Biosciences/NULISAseqR/compare/main…1.4