Type:	Package
Title:	Reading, Quality Control and Preprocessing of MBA (Multiplex Bead Assay) Data
Description:	Speeds up the process of loading raw data from MBA (Multiplex Bead Assay) examinations, performs quality control checks, and automatically normalises the data, preparing it for more advanced, downstream tasks. The main objective of the package is to create a simple environment for a user, who does not necessarily have experience with R language. The package is developed within the project 'PvSTATEM', which is an international project aiming for malaria elimination.
BugReports:	https://github.com/mini-pw/SerolyzeR/issues
Version:	1.3.0
License:	BSD_3_clause + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	dplyr, ggplot2, nplr, R6, readxl, stringi, stringr, grid, png, tools, ggrepel, lubridate, R.utils, svglite, fs, scales, rlang
Suggests:	knitr, qpdf, rmarkdown, testthat (≥ 3.0.0)
Config/testfhat/edition:	3
VignetteBuilder:	knitr
URL:	https://github.com/mini-pw/SerolyzeR, https://mini-pw.github.io/SerolyzeR/
NeedsCompilation:	no
Packaged:	2025-07-18 08:20:34 UTC; tymot
Author:	Tymoteusz Kwiecinski [aut, cre], Jakub Grzywaczewski [aut], Mateusz Nizwantowski [aut], Przemyslaw Biecek [ths], Nuno Sepulveda [ths]
Maintainer:	Tymoteusz Kwiecinski <tymoteuszkwiecinski@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-18 09:00:02 UTC

Logistic regression model for the standard curve

Description

The Model class is a wrapper around the nplr model. It allows to predict the RAU (Relative Antibody Unit) values directly from the MFI values of a given sample.

The nplr model is fitted using the formula:

y = B + \frac{T - B}{(1 + 10^{b \cdot (x_{mid} - x)})^s},

where:

• y is the predicted value, MFI in our case,

• x is the independent variable, dilution in our case,

• B is the bottom plateau - the right horizontal asymptote,

• T is the top plateau - the left horizontal asymptote,

• b is the slope of the curve at the inflection point,

• x_{mid} is the x-coordinate at the inflection point,

• s is the asymmetric coefficient.

This equation is referred to as the Richards' equation. More information about the model can be found in the nplr package documentation.

After the model is fitted to the data, the RAU values can be predicted using the predict.Model() method. The RAU value is simply a predicted dilution value (using the standard curve) for a given MFI multiplied by 1,000 000 to have a more readable value. For more information about the differences between dilution, RAU and MFI values, please see Normalisation section in the Basic SerolyzeR functionalities vignette.

Public fields

Active bindings

Methods

Public methods

• Model$new()

• Model$predict()

• Model$get_plot_data()

• Model$print()

• Model$clone()

Method new()

Create a new instance of Model R6 class

Usage

Model$new(
  analyte,
  dilutions,
  mfi,
  npars = 5,
  verbose = TRUE,
  log_dilution = TRUE,
  log_mfi = TRUE,
  scale_mfi = TRUE,
  mfi_min = NULL,
  mfi_max = NULL,
  ...
)

Arguments

Method predict()

Predict RAU values from the MFI values

Usage

Model$predict(mfi, over_max_extrapolation = 0, eps = 1e-06, ...)

Arguments

Returns

(data.frame())
Dataframe with the predicted RAU values for given MFI values The columns are named as follows:

• RAU - the Relative Antibody Units (RAU) value

• MFI - the predicted MFI value

Method get_plot_data()

Data that can be used to plot the standard curve.

Usage

Model$get_plot_data()

Returns

(data.frame())
Prediction dataframe for scaled MFI (or logMFI) values in the range [0, 1]. Columns are named as in the predict method

Method print()

Function prints the basic information about the model such as the number of parameters or samples used

Usage

Model$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

Model$clone(deep = FALSE)

Arguments

Examples

plate_file <- system.file("extdata", "CovidOISExPONTENT.csv", package = "SerolyzeR")
layout_file <- system.file("extdata", "CovidOISExPONTENT_layout.csv", package = "SerolyzeR")
plate <- read_luminex_data(plate_file, layout_filepath = layout_file)
model <- create_standard_curve_model_analyte(plate, "S2", log_mfi = TRUE)
print(model)

Plate Object

Description

The Plate object represents a Luminex assay plate and stores data related to its samples, analytes, metadata, and batch information. This object is typically created by functions such as read_luminex_data(), process_file(), or process_dir().

It provides methods for accessing and manipulating data, including retrieving specific analyte measurements, filtering by sample type, and performing blank adjustments.

Public fields

Methods

Public methods

• Plate$new()

• Plate$print()

• Plate$summary()

• Plate$get_data()

• Plate$get_dilution()

• Plate$get_dilution_values()

• Plate$blank_adjustment()

• Plate$clone()

Method new()

Method to initialize the Plate object

Usage

Plate$new(
  plate_name,
  sample_names,
  analyte_names,
  batch_name = "",
  plate_datetime = NULL,
  sample_locations = NULL,
  sample_types = NULL,
  dilutions = NULL,
  dilution_values = NULL,
  default_data_type = NULL,
  data = NULL,
  batch_info = NULL,
  layout = NULL
)

Arguments

Method print()

Function prints the basic information about the plate such as the number of samples and analytes

Usage

Plate$print(...)

Arguments

Method summary()

Function outputs basic information about the plate, such as examination date, batch name, and sample types.

Usage

Plate$summary(..., include_names = FALSE)

Arguments

Method get_data()

Function returns data for a specific analyte and sample.

Usage

Plate$get_data(
  analyte,
  sample_type_filter = "ALL",
  data_type = self$default_data_type
)

Arguments

Returns

Dataframe containing information about a given sample type and analyte Get the string representation of dilutions

Method get_dilution()

Function returns the dilution represented as strings for a specific sample type.

Usage

Plate$get_dilution(sample_type)

Arguments

Returns

A list containing names of the samples as keys and string representing dilutions as values. Get the numeric representation of dilutions

Method get_dilution_values()

Function returns the dilution values for a specific sample type.

Usage

Plate$get_dilution_values(sample_type)

Arguments

Returns

A list containing names of the samples as keys and numeric values representing dilutions as values.

Adjust the MFI values by subtracting the background

Method blank_adjustment()

Function adjusts the values of samples (all samples excluding the blanks) by clamping the values to the aggregated value of the BLANK samples for each analyte separately.

The purpose of this operation is to unify the data by clamping values below the background noise. how this method works was inspired by the paper "Quality control of multiplex antibody detection in samples from large-scale surveys: the example of malaria in Haiti." which covers the quality control in the MBA.

In short, this operation firstly calculates the aggregate of MFI in the BLANK samples (available methods are: min, max, mean, median) and then replaces all values below this threshold with the threshold value.

Method does not modifies the data of type Count.

This operation is recommended to be performed before any further analysis, but is optional. Skipping it before further analysis is allowed, but will result in a warning.

@references van den Hoogen, L.L., Présumé, J., Romilus, I. et al. Quality control of multiplex antibody detection in samples from large-scale surveys: the example of malaria in Haiti. Sci Rep 10, 1135 (2020). https://doi.org/10.1038/s41598-020-57876-0

Usage

Plate$blank_adjustment(threshold = "max", in_place = TRUE)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Plate$clone(deep = FALSE)

Arguments

PlateBuilder

Description

This class helps creating the Plate object. It is used to store the data and validate the final fields.

Active bindings

Methods

Public methods

• PlateBuilder$new()

• PlateBuilder$set_sample_locations()

• PlateBuilder$set_dilutions()

• PlateBuilder$set_sample_types()

• PlateBuilder$set_sample_names()

• PlateBuilder$set_plate_datetime()

• PlateBuilder$set_data()

• PlateBuilder$set_default_data_type()

• PlateBuilder$set_batch_info()

• PlateBuilder$set_plate_name()

• PlateBuilder$set_layout()

• PlateBuilder$build()

• PlateBuilder$clone()

Method new()

Initialize the PlateBuilder object

Usage

PlateBuilder$new(sample_names, analyte_names, batch_name = "", verbose = TRUE)

Arguments

Method set_sample_locations()

Set the sample types used during the examination

Usage

PlateBuilder$set_sample_locations(sample_locations)

Arguments

Method set_dilutions()

Extract and set the dilutions from layout, sample names or use a provided vector of values. The provided vector should be the same length as the number of samples and should contain dilution factors saved as strings

Usage

PlateBuilder$set_dilutions(use_layout_dilutions = TRUE, values = NULL)

Arguments

Method set_sample_types()

Usage

PlateBuilder$set_sample_types(use_layout_types = TRUE, values = NULL)

Arguments

Method set_sample_names()

Set the sample names used during the examination. If the layout is provided, extract the sample names from the layout file. Otherwise, uses the original sample names from the Luminex file

In case there are multiple samples with the same name, it prints a warning and renames the samples, by adding a number.

Usage

PlateBuilder$set_sample_names(use_layout_sample_names = TRUE)

Arguments

Method set_plate_datetime()

Set the plate datetime for the plate

Usage

PlateBuilder$set_plate_datetime(plate_datetime)

Arguments

Method set_data()

Set the data used during the examination

Usage

PlateBuilder$set_data(data)

Arguments

Method set_default_data_type()

Set the data type used for calculations

Usage

PlateBuilder$set_default_data_type(data_type = "Median")

Arguments

Method set_batch_info()

Set the batch info for the plate

Usage

PlateBuilder$set_batch_info(batch_info)

Arguments

Method set_plate_name()

Set the plate name for the plate. The plate name is extracted from the filepath

Usage

PlateBuilder$set_plate_name(file_path)

Arguments

Method set_layout()

Set the layout matrix for the plate. This function performs basic validation

• verifies if the plate is a matrix of shape 8x12 with 96 wells

Usage

PlateBuilder$set_layout(layout_matrix)

Arguments

Method build()

Create a Plate object from the PlateBuilder object

Usage

PlateBuilder$build(validate = TRUE, reorder = TRUE)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

PlateBuilder$clone(deep = FALSE)

Arguments

Check if two paths are equal

Description

Function checks if two paths are equal after converting them to absolute paths.

Usage

check_path_equal(path1, path2)

Arguments

Value

(logical(1)) TRUE if the paths are equal, FALSE otherwise.

Clamp a value to a range

Description

Clamp a value to a range

Usage

clamp(x, lower = -Inf, upper = Inf)

Arguments

Value

A numeric value clamped to the range [lower, upper].

Convert dilutions to numeric values

Description

Convert dilutions saved as strings in format ⁠1/\d+⁠ into numeric values

Usage

convert_dilutions_to_numeric(dilutions)

Arguments

Value

a vector of numeric values representing the dilutions

Create a standard curve model for a certain analyte

Description

Create a standard curve model for a certain analyte

Usage

create_standard_curve_model_analyte(
  plate,
  analyte_name,
  data_type = "Median",
  source_mfi_range_from_all_analytes = FALSE,
  detect_high_dose_hook = TRUE,
  ...
)

Arguments

Value

(Model()) Standard Curve model

Remove holes from a vector

Description

Function selects the values from the vector at the given locations and creates a vector "without holes". Works only for 96-plate.

Usage

create_vector_without_holes(vector, locations)

Arguments

Value

A vector with values at the given locations

Try to detect the format of a file

Description

Try to detect the format of a file

Usage

detect_mba_format(filepath, format = NULL)

Convert dilution to RAU

Description

Convert dilution to RAU

Usage

dilution_to_rau(predicted_dilution)

Arguments

Value

The RAU value corresponding to the predicted dilution .

Extract dilution factor from the sample name

Description

function extracts dilution factor from the sample name - useful for detecting dilution from sample names

Usage

extract_dilution_from_names(sample_name)

Arguments

Value

a vector of dilutions represented as strings extracted from the sample names

Extract dilutions from the layout representation

Description

Extract dilution factor represented as string from vector of characters. The matches has to be exact and the dilution factor has to be in the form of ⁠1/\d+⁠

Usage

extract_dilutions_from_layout(dilutions)

Arguments

Extract sample names from layout

Description

Function extracts sample names from the layout file based on the provided locations. Function assumes that the plate is 96-well and extracts the sample names according to the provided location strings.

Usage

extract_sample_names_from_layout(layout_names, locations)

Arguments

Extract the experiment date from xPONENT raw output

Description

This method extracts the real experiment date - BatchStartTime, which corresponds to the time when the experiment was conducted.

The Date in the top of the xPONENT file refers to the moment when the CSV xPONENT file was exported from the system

In case the file was parsed with an exact_parse parameter, it looks for a parameter in a BatchMetadata list. Otherwise it tries to read it from the raw header.

In case this method fails, it fails back to read the Date from the file

Usage

extract_xponent_experiment_date(xponent_output, verbose = TRUE)

Arguments

Value

A character string representing the datetime of the experiment

Filter Samples by Sample Type

Description

This function returns a logical vector indicating which samples in the plate match the specified sample_type_filter. It is typically used for subsetting sample-related data such as MFI values, layout, or names.

If sample_type_filter is set to "ALL", all sample types are considered valid.

Usage

filter_sample_types(sample_types, sample_type_filter)

Arguments

Value

A logical vector the same length as sample_types, indicating which samples match.

Find a layout file given plate filepath

Description

Find a layout file given plate filepath

Usage

find_layout_file(plate_filepath, layout_filepath = NULL)

Format dilutions

Description

The function counts the number of times each dilution factor appears and sorts them in descending order based on the corresponding dilution values. The output is a string that lists the dilution factors and their counts in the format ⁠count x dilution_factor⁠. If the dilutions vector looks like c("1/2", "1/2", "1/2", "1/3", "1/3", "1/4"), the output will be "3x1/2, 2x1/3, 1x1/4".

Usage

format_dilutions(dilutions, dilution_values, sample_types)

Arguments

Value

A formatted string that lists the dilution factors and their counts. Returns NULL if dilutions is NULL.

Format X-axis label

Description

Returns a generic x-axis label for the plot based on the prefix and scale.

Usage

format_xlab(prefix, prefix_short, scale_y)

Arguments

Value

A formatted x-axis label.

Format Y-axis label

Description

Returns a generic y-axis label for the plot based on the data type and scale.

Usage

format_ylab(data_type, scale_y)

Arguments

Value

A formatted y-axis label.

Generate a Levey-Jennings Report for Multiple Plates.

Description

This function generates a Levey-Jennings report for a list of plates. The report includes layout plot, levey jennings plot, for each analyte and selected dilutions.

Usage

generate_levey_jennings_report(
  list_of_plates,
  report_title,
  dilutions = c("1/100", "1/400"),
  filename = NULL,
  output_dir = "reports",
  additional_notes = NULL,
  ...
)

Arguments

Details

The report also includes stacked standard curves plot in both monochromatic and color versions for each analyte. The report is generated using the R Markdown template file levey_jennings_report_template.Rmd, located in the inst/templates directory of the package. You can access it using: system.file("templates/levey_jennings_report_template.Rmd", package = "SerolyzeR").

Value

A Levey-Jennings report in HTML format.

Examples

output_dir <- tempdir(check = TRUE)

dir_with_luminex_files <- system.file("extdata", "multiplate_lite",
  package = "SerolyzeR", mustWork = TRUE
)
list_of_plates <- process_dir(dir_with_luminex_files,
  return_plates = TRUE, format = "xPONENT", output_dir = output_dir
)
note <- "This is a Levey-Jennings report.\n**Author**: Jane Doe \n**Tester**: John Doe"

generate_levey_jennings_report(
  list_of_plates = list_of_plates,
  report_title = "QC Report",
  dilutions = c("1/100", "1/200"),
  output_dir = tempdir(),
  additional_notes = note
)

Generate a report for a plate.

Description

This function generates a report for a plate. The report contains all the necessary information about the plate, from the general plate parameters, such as examination date, to the breakdown of the analytes' plots. The report is generated using the R Markdown template file plate_report_template.Rmd, located in the inst/templates directory of the package. You can access it using: system.file("templates/plate_report_template.Rmd", package = "SerolyzeR").

Usage

generate_plate_report(
  plate,
  use_model = TRUE,
  filename = NULL,
  output_dir = "reports",
  counts_lower_threshold = 50,
  counts_higher_threshold = 70,
  additional_notes = NULL,
  ...
)

Arguments

Value

A report.

Examples

plate_file <- system.file("extdata", "CovidOISExPONTENT_CO_reduced.csv", package = "SerolyzeR")
# a plate file with reduced number of analytes to speed up the computation
layout_file <- system.file("extdata", "CovidOISExPONTENT_CO_layout.xlsx", package = "SerolyzeR")
note <- "This is a test report.\n**Author**: Jane Doe \n**Tester**: John Doe"

plate <- read_luminex_data(plate_file, layout_file, verbose = FALSE)
example_dir <- tempdir(check = TRUE) # a temporary directory
generate_plate_report(plate,
  output_dir = example_dir,
  counts_lower_threshold = 40,
  counts_higher_threshold = 50,
  additional_notes = note
)

Determine the Join Value

Description

Returns a non-NA/non-NULL value based on the inputs. If either value is NA or NULL, it returns the non-NA/non-NULL value. If both values are equal, it returns that value.

Usage

get_join_value(x, y)

Arguments

Value

A non-NA/non-NULL value or the common value if x equals y. Returns NULL if the values differ and neither is NA or NULL.

Generate the matrix of plate locations

Description

The function generates a matrix of plate locations. The locations are represented in a nrow x ncol matrix. Usually number of rows equals to 8 and number of columns to 12, and the total matrix size is 96.

The fields are represented as E3, where the letter corresponds to the row and the number to the column.

Usage

get_location_matrix(nrow = 8, ncol = 12, as_vector = FALSE)

Arguments

Value

a matrix with locations

Calculate Normalised MFI (nMFI) Values for a Plate

Description

Calculates normalised MFI (nMFI) values for each analyte in a Luminex plate. The nMFI values are computed as the ratio of each test sample's MFI to the MFI of a standard curve sample at a specified reference dilution.

Usage

get_nmfi(
  plate,
  reference_dilution = 1/400,
  data_type = "Median",
  sample_type_filter = "ALL",
  verbose = TRUE
)

Arguments

Details

Normalised MFI (nMFI) is a simple, model-free metric used to compare test sample responses relative to a fixed concentration from the standard curve. It is particularly useful when model fitting (e.g., for RAU calculation) is unreliable or not possible, such as when test sample intensities fall outside the standard curve range.

The function locates standard samples with the specified dilution and divides each test sample’s MFI by the corresponding standard MFI value for each analyte.

Value

nmfi (data.frame) a data frame with normalised MFI values for each analyte in the plate and all test samples.

When Should nMFI Be Used?

While RAU values are generally preferred for antibody quantification, they require successful model fitting of the standard curve. This may not be feasible when:

• The test samples produce MFI values outside the range of the standard curve.

• The standard curve is poorly shaped or missing critical points.

In such cases, nMFI serves as a useful alternative, allowing for plate-to-plate comparison without the need for extrapolation.

References

L. Y. Chan, E. K. Yim, and A. B. Choo, Normalized median fluorescence: An alternative flow cytometry analysis method for tracking human embryonic stem cell states during differentiation, http://dx.doi.org/10.1089/ten.tec.2012.0150

Examples

# read the plate
plate_file <- system.file("extdata", "CovidOISExPONTENT.csv", package = "SerolyzeR")
layout_file <- system.file("extdata", "CovidOISExPONTENT_layout.csv", package = "SerolyzeR")

plate <- read_luminex_data(plate_file, layout_file)

# artificially bump up the MFI values of the test samples (the Median data type is default one)
plate$data[["Median"]][plate$sample_types == "TEST", ] <-
  plate$data[["Median"]][plate$sample_types == "TEST", ] * 10

# calculate the nMFI values
nmfi <- get_nmfi(plate, reference_dilution = 1 / 400)

# we don't do any extrapolation and the values should be comparable across plates
head(nmfi)
# different params
nmfi <- get_nmfi(plate, reference_dilution = "1/50")
nmfi <- get_nmfi(plate, reference_dilution = "1/50", sample_type_filter = c("TEST", "BLANK"))

Get output directory for a given input file

Description

Get output directory for a given input file

Usage

get_output_dir(
  input_file,
  input_dir,
  output_dir = NULL,
  flatten_output_dir = FALSE
)

Handle differences in datetimes

Description

Handle differences in the datetime format between xPONENT and INTELLIFLEX and output POSIXct datetime object containing the correct datetime with the default timezone.

Usage

handle_datetime(datetime_str, file_format = "xPONENT")

Arguments

Value

POSIXct datetime object

Detect and handle the high dose hook effect

Description

Typically, the MFI values associated with standard curve samples should decrease as we dilute the samples. However, sometimes in high dilutions, the MFI presents a non monotonic behavior. In that case, MFI values associated with dilutions above (or equal to) high_dose_threshold should be removed from the analysis.

For the nplr model the recommended number of standard curve samples is at least 4. If the high dose hook effect is detected but the number of samples below the high_dose_threshold is lower than 4, additional warning is printed and the samples are not removed.

Warning: High dose hook effect affects which dilution and MFI values are used to fit the logistic model and by extension affects the maximum value to which the predicted RAU MFI values are extrapolated / truncated.

The function returns a logical vector that can be used to subset the MFI values.

Usage

handle_high_dose_hook(mfi, dilutions, high_dose_threshold = 1/200)

Arguments

Value

sample selector (logical())

References

Namburi, R. P. et. al. (2014) High-dose hook effect. DOI: 10.4103/2277-8632.128412

Examples

plate_filepath <- system.file(
  "extdata", "CovidOISExPONTENT.csv",
  package = "SerolyzeR", mustWork = TRUE
) # get the filepath of the csv dataset
layout_filepath <- system.file(
  "extdata", "CovidOISExPONTENT_layout.xlsx",
  package = "SerolyzeR", mustWork = TRUE
)
plate <- read_luminex_data(plate_filepath, layout_filepath) # read the data

# here we plot the data with observed high dose hook effect
plot_standard_curve_analyte(plate, "RBD_omicron")

# here we create the model with the high dose hook effect handled
model <- create_standard_curve_model_analyte(plate, "RBD_omicron")

Check if the vector is monotically decreasing

Description

Check if the vector is monotically decreasing

Usage

is.decreasing(x)

Arguments

Value

(logical(1)) TRUE if the vector is monotonically decreasing, FALSE otherwise

Check if a value is a scalar

Description

This will return FALSE for NULL and vectors of length bigger than 2.

Usage

is.scalar(x)

Arguments

Value

TRUE if the object is a scalar, FALSE otherwise.

Check if a string is a number

Description

Check if a string is a number

Usage

is.str.number(x)

Arguments

Value

TRUE if the string is a number, FALSE otherwise.

Identify if a file is a MBA data file

Description

Identify if a file is a MBA data file

Usage

is_mba_data_file(filepath, check_format = TRUE)

Arguments

Value

TRUE if the file is a MBA data file, FALSE otherwise.

Check if a mba format is supported

Description

Check if a given format is supported.

Usage

is_mba_format(format, allow_nullable = FALSE)

Arguments

Value

(logical(1)) TRUE if the format is in the supported list, else FALSE

Check if a value is an outlier

Description

Check if a value is an outlier

Usage

is_outlier(x)

Arguments

Value

A logical vector indicating whether each value is an outlier.

Check validity of given data type

Description

Check if the data type is valid. The data type is valid if it is one of the elements of the VALID_DATA_TYPES vector. The valid data types are:
c(Median, Net MFI, Count, Avg Net MFI, Mean, Peak).

Usage

is_valid_data_type(data_type)

Arguments

Value

TRUE if the data type is valid, FALSE otherwise.

Check validity of given sample type

Description

Check if the sample type is valid. The sample type is valid if it is one of the elements of the VALID_SAMPLE_TYPES vector. The valid sample types are:

c(ALL, BLANK, TEST, NEGATIVE CONTROL, STANDARD CURVE, POSITIVE CONTROL).

Usage

is_valid_sample_type(sample_type)

Arguments

Value

TRUE if the sample type is valid, FALSE otherwise.

Merge dataframes

Description

Merges a list of dataframes by handling column collisions through specified strategies: "intersection" or "union".

Usage

merge_dataframes(
  dataframes,
  column_collision_strategy = "intersection",
  fill_value = NA
)

Arguments

Value

Merged dataframe

Merge Normalised Data from Multiple Plates

Description

This function merges normalised data from a list of Plate objects into a single data.frame. It supports different normalisation types and handles column mismatches based on the specified strategy.

Usage

merge_plate_outputs(
  plates,
  normalisation_type,
  column_collision_strategy = "intersection",
  verbose = TRUE,
  ...
)

Arguments

Value

A merged data.frame containing normalised data across all plates.

Examples

# creating temporary directory for the example
output_dir <- tempdir(check = TRUE)

dir_with_luminex_files <- system.file("extdata", "multiplate_reallife_reduced",
  package = "SerolyzeR", mustWork = TRUE
)
list_of_plates <- process_dir(dir_with_luminex_files,
  return_plates = TRUE, format = "xPONENT", output_dir = output_dir
)

df <- merge_plate_outputs(list_of_plates, "RAU", sample_type_filter = c("TEST", "STANDARD CURVE"))

Plot counts in a 96-well plate

Description

This function plots counts in a 96-well plate using a colour to represent the count ranges. There is a possibility of plotting exact counts in each well.

If the plot window is resized, it's best to re-run the function to adjust the scaling. Sometimes, when a legend is plotted, the whole layout may be shifted. It's best to stretch the window, and everything will be adjusted automatically.

Usage

plot_counts(
  plate,
  analyte_name,
  plot_counts = TRUE,
  plot_legend = FALSE,
  lower_threshold = 50,
  higher_threshold = 70
)

Arguments

Value

A ggplot object

Examples

plate_filepath <- system.file("extdata", "CovidOISExPONTENT_CO.csv",
  package = "SerolyzeR", mustWork = TRUE
)
layout_filepath <- system.file("extdata", "CovidOISExPONTENT_CO_layout.xlsx",
  package = "SerolyzeR", mustWork = TRUE
)
plate <- read_luminex_data(plate_filepath, layout_filepath)
plot_counts(
  plate = plate, analyte_name = "OC43_NP_NA",
  plot_counts = TRUE, plot_legend = FALSE
)

Plot layout of a 96-well plate

Description

This function plots the layout of a 96-well plate using a colour to represent the sample types.

If the plot window is resized, it's best to re-run the function to adjust the scaling. Sometimes, the whole layout may be shifted when a legend is plotted. It's best to stretch the window, and everything will be adjusted automatically.

Usage

plot_layout(plate, plot_legend = TRUE)

Arguments

Value

A ggplot object

Examples

plate_filepath <- system.file("extdata", "CovidOISExPONTENT_CO.csv",
  package = "SerolyzeR", mustWork = TRUE
)
layout_filepath <- system.file("extdata", "CovidOISExPONTENT_CO_layout.xlsx",
  package = "SerolyzeR", mustWork = TRUE
)
plate <- read_luminex_data(plate_filepath, layout_filepath)
plot_layout(plate = plate, plot_legend = TRUE)

Plot Levey-Jennings chart

Description

The function plots a Levey-Jennings chart for the given analyte in the list of plates. The Levey-Jennings chart is a graphical representation of the data that enables the detection of outliers and trends. It is a quality control tool that is widely used in the laboratories across the world.

The method takes several parameters that can customise its output. Except for the required parameters (list_of_plates and analyte_name), the most significant optional ones are dilution and sd_lines.

The additional parameters can be used for improving the plots interpretability, by customizing the layout, y-scale, etc.

For better readibilty, the plot is zoomed out in the y-axis, by a factor of 1.5.

Usage

plot_levey_jennings(
  list_of_plates,
  analyte_name,
  dilution = "1/400",
  sd_lines = c(1, 2, 3),
  mfi_log_scale = TRUE,
  sort_plates = TRUE,
  plate_labels = "number",
  label_angle = 0,
  legend_position = "bottom",
  data_type = "Median"
)

Arguments

Value

A ggplot object with the Levey-Jennings chart

Examples

# creating temporary directory for the example
output_dir <- tempdir(check = TRUE)

dir_with_luminex_files <- system.file("extdata", "multiplate_reallife_reduced",
  package = "SerolyzeR", mustWork = TRUE
)
list_of_plates <- process_dir(dir_with_luminex_files,
  return_plates = TRUE, format = "xPONENT", output_dir = output_dir
)
list_of_plates <- rep(list_of_plates, 10) # since we have only 3 plates i will repeat them 10 times

plot_levey_jennings(list_of_plates, "ME", dilution = "1/400", sd_lines = c(0.5, 1, 1.96, 2.58))

Plot MFI value distribution for a given analyte

Description

Plot MFI value distribution for a given analyte

Usage

plot_mfi_for_analyte(
  plate,
  analyte_name,
  data_type = "Median",
  plot_type = "violin",
  scale_y = "log10",
  plot_outliers = FALSE,
  ...
)

Arguments

Value

A ggplot object

Plot a 96-well plate with coloured wells

Description

It is a generic function to plot a 96-well plate with coloured wells used by other functions in this package, mainly to plot layout and counts. The function uses a background image of a 96-well plate and plots the colours in the wells using ggplot2. This function is not intended for the user to use directly. Rather, it is used by other functions specified in this file.

Usage

plot_plate(
  colours,
  plot_numbers = FALSE,
  numbers = NULL,
  plot_title = "Plate",
  plot_legend = FALSE,
  legend_mapping = NULL
)

Arguments

Value

A ggplot object

Standard curves

Description

Plot standard curve samples of a plate of a given analyte.

Usage

plot_standard_curve_analyte(
  plate,
  analyte_name,
  data_type = "Median",
  decreasing_rau_order = TRUE,
  log_scale = c("all"),
  plot_line = TRUE,
  plot_blank_mean = TRUE,
  plot_rau_bounds = TRUE,
  plot_legend = TRUE,
  legend_position = "bottom",
  verbose = TRUE,
  ...
)

Arguments

Value

ggplot object with the plot

Examples

path <- system.file("extdata", "CovidOISExPONTENT.csv",
  package = "SerolyzeR", mustWork = TRUE
)
layout_path <- system.file("extdata", "CovidOISExPONTENT_layout.xlsx",
  package = "SerolyzeR", mustWork = TRUE
)
plate <- read_luminex_data(path, layout_filepath = layout_path, verbose = FALSE)
plot_standard_curve_analyte(plate, "Spike_6P", plot_legend = FALSE, data_type = "Median")

Plot standard curve of a certain analyte with fitted model

Description

Function plots the values of standard curve samples and the fitted model.

Usage

plot_standard_curve_analyte_with_model(
  plate,
  model,
  data_type = "Median",
  decreasing_rau_order = TRUE,
  log_scale = c("all"),
  plot_asymptote = TRUE,
  plot_test_predictions = TRUE,
  plot_blank_mean = TRUE,
  plot_rau_bounds = TRUE,
  plot_legend = TRUE,
  legend_position = "bottom",
  verbose = TRUE,
  ...
)

Arguments

Value

a ggplot object with the plot

Examples

path <- system.file("extdata", "CovidOISExPONTENT.csv",
  package = "SerolyzeR", mustWork = TRUE
)
layout_path <- system.file("extdata", "CovidOISExPONTENT_layout.xlsx",
  package = "SerolyzeR", mustWork = TRUE
)
plate <- read_luminex_data(path, layout_filepath = layout_path, verbose = FALSE)
model <- create_standard_curve_model_analyte(plate, analyte_name = "Spike_B16172")
plot_standard_curve_analyte_with_model(plate, model, decreasing_rau_order = FALSE)

Standard curve stacked plot for levey-jennings report

Description

As a quality control measure to detect plates with inconsistent results or drift in calibration over time, this function plots standard curves for a specified analyte across multiple plates on a single plot. It enables visual comparison of standard curves, making it easier to spot outliers or shifts in calibration. The function can be run standalone or used as part of a broader Levey-Jennings report.

Each curve represents one plate, and users can choose how colours are applied — either in a monochromatic blue gradient (indicating time-based drift) or with distinct hues for clearer differentiation.

Usage

plot_standard_curve_stacked(
  list_of_plates,
  analyte_name,
  data_type = "Median",
  decreasing_dilution_order = TRUE,
  monochromatic = TRUE,
  legend_type = NULL,
  plot_legend = TRUE,
  legend_position = "bottom",
  max_legend_items_per_row = 3,
  legend_text_size = 8,
  sort_plates = TRUE,
  log_scale = c("all"),
  verbose = TRUE
)

Arguments

Details

The function overlays all standard curves from the provided plates for the given analyte. When monochromatic = TRUE, the curves are drawn in a blue gradient — oldest plates in light blue (almost white) and most recent ones in dark blue. This visual encoding helps track drift in calibration over time.

When monochromatic = FALSE, colours are selected from a hue palette to ensure distinct appearance, especially useful when comparing many plates simultaneously.

The legend_type determines how curves are identified in the legend. By default, it adapts based on the monochromatic setting.

If the legend becomes crowded (e.g., with long plate names), use max_legend_items_per_row and legend_text_size to improve layout and readability.

Value

ggplot object with the plot

Examples

# creating temporary directory for the example
output_dir <- tempdir(check = TRUE)

dir_with_luminex_files <- system.file("extdata", "multiplate_reallife_reduced",
  package = "SerolyzeR", mustWork = TRUE
)
list_of_plates <- process_dir(dir_with_luminex_files,
  return_plates = TRUE, format = "xPONENT", output_dir = output_dir
)
plot_standard_curve_stacked(list_of_plates, "ME", data_type = "Median", monochromatic = FALSE)

Standard curve thumbnail for report

Description

Function generates a thumbnail of the standard curve for a given analyte. The thumbnail is used in the plate report. It doesn't have any additional parameters, because it is used only internally.

Usage

plot_standard_curve_thumbnail(plate, analyte_name, data_type = "Median")

Arguments

Value

ggplot object with the plot

Predict the RAU values from the MFI values

Description

More details can be found here: Model

Usage

## S3 method for class 'Model'
predict(object, mfi, ...)

Arguments

Value

(data.frame())

Process a Directory of Luminex Data Files

Description

This function processes all Luminex plate files within a specified directory. Each plate file is processed using process_file(), and the resulting normalised data is saved. Optionally, quality control reports can be generated, and results from multiple plates can be merged into a single file.

Workflow

1. Identify all Luminex plate files in the input_dir, applying recursive search if recurse = TRUE.

2. Detect the format of each file based on the format parameter or the filename.

3. Locate the corresponding layout file using the filename or use the common layout passed with the layout_filepath parameter.

4. Determine the appropriate output directory using get_output_dir().

5. Process each plate file using process_file().

6. If merge_outputs = TRUE, merge normalised data from multiple plates into a single CSV file.

Naming Conventions for Input Files

• If format is specified:

  • Each plate file should be named as ⁠{plate_name}.csv⁠.

  • The corresponding layout file should be named as ⁠{plate_name}_layout.csv⁠ or ⁠{plate_name}_layout.xlsx⁠.

  • Alternatively, if layout_filepath is provided, it serves as a unified layout file for all plates.

• If format equals NULL (automatic detection):

  • Each plate file should be named as ⁠{plate_name}_{format}.csv⁠, where {format} is either xPONENT or INTELLIFLEX.

  • The corresponding layout file should be named using the same convention as above, i.i. ⁠{plate_name}_{format}_layout.csv⁠ or ⁠{plate_name}_{format}_layout.xlsx⁠.

Output File Structure

• The output_dir parameter specifies where the processed files are saved.

• If output_dir is NULL, output files are saved in the same directory as the input files.

• By default, the output directory structure follows the input directory, unless flatten_output_dir = TRUE, which saves all outputs directly into output_dir.

• Output filenames follow the convention used in process_file().

  • For a plate named {plate_name}, the normalised output files are named as:

    • ⁠{plate_name}_RAU.csv⁠ for RAU normalisation.

    • ⁠{plate_name}_nMFI.csv⁠ for nMFI normalisation.

    • ⁠{plate_name}_MFI.csv⁠ for MFI normalisation.

  • If generate_reports = TRUE, a quality control report for every plate is saved as ⁠{plate_name}_report.pdf⁠.

  • If merge_outputs = TRUE, merged normalised files are named as:

    • ⁠merged_RAU_{timestamp}.csv⁠

    • ⁠merged_nMFI_{timestamp}.csv⁠

    • ⁠merged_MFI_{timestamp}.csv⁠

  • If generate_multiplate_reports = TRUE, a multiplate quality control report is saved as ⁠multiplate_report_{timestamp}.pdf⁠.

Usage

process_dir(
  input_dir,
  output_dir = NULL,
  recurse = FALSE,
  flatten_output_dir = FALSE,
  layout_filepath = NULL,
  format = "xPONENT",
  normalisation_types = c("MFI", "RAU", "nMFI"),
  generate_reports = FALSE,
  generate_multiplate_reports = FALSE,
  merge_outputs = TRUE,
  column_collision_strategy = "intersection",
  return_plates = FALSE,
  dry_run = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

If return_plates = TRUE, returns a sorted list of Plate objects. Otherwise, returns NULL.

Examples

# Process all plate files in a directory
input_dir <- system.file("extdata", "multiplate_lite", package = "SerolyzeR", mustWork = TRUE)
output_dir <- tempdir(check = TRUE)
plates <- process_dir(input_dir, return_plates = TRUE, output_dir = output_dir)

Process a File to Generate Normalised Data and Reports

Description

This function reads a Luminex plate file by calling read_luminex_data() and then processes it by calling process_plate(). It optionally generates also a quality control report using generate_plate_report(). It reads the specified plate file, processes the plate object using all specified normalisation types (including raw MFI values), and saves the results. If generate_report = TRUE, a quality control report is also generated.

Usage

process_file(
  plate_filepath,
  layout_filepath,
  output_dir = "normalised_data",
  format = "xPONENT",
  generate_report = FALSE,
  process_plate = TRUE,
  normalisation_types = c("MFI", "RAU", "nMFI"),
  blank_adjustment = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

A Plate object containing the processed data.

Workflow

1. Read the plate file and layout file.

2. Process the plate data using the specified normalisation types (MFI, RAU, nMFI).

3. Save the processed data to CSV files in the specified output_dir. The files are named as ⁠{plate_name}_{normalisation_type}.csv⁠.

4. Optionally, generate a quality control report. The report is saved as an HTML file in the output_dir, under the name ⁠{plate_name}_report.html⁠.

Examples

# Example 1: Process a plate file with default settings (all normalisation types)
plate_file <- system.file("extdata", "CovidOISExPONTENT_CO_reduced.csv", package = "SerolyzeR")
layout_file <- system.file("extdata", "CovidOISExPONTENT_CO_layout.xlsx", package = "SerolyzeR")
example_dir <- tempdir(check = TRUE)
process_file(plate_file, layout_file, output_dir = example_dir)

# Example 2: Process the plate for only RAU normalisation
process_file(plate_file, layout_file, output_dir = example_dir, normalisation_types = c("RAU"))

# Example 3: Process the plate and generate a quality control report
process_file(plate_file, layout_file, output_dir = example_dir, generate_report = TRUE)

Process Plate Data and Save Normalised Output

Description

Processes a Luminex plate and computes normalised values using the specified normalisation_type. Depending on the chosen method, the function performs blank adjustment, fits models, and extracts values for test samples. Optionally, the results can be saved as a CSV file.

Usage

process_plate(
  plate,
  filename = NULL,
  output_dir = "normalised_data",
  write_output = TRUE,
  normalisation_type = "RAU",
  data_type = "Median",
  sample_type_filter = "ALL",
  blank_adjustment = FALSE,
  verbose = TRUE,
  reference_dilution = 1/400,
  ...
)

Arguments

Details

Supported normalisation types:

• RAU (Relative Antibody Units): Requires model fitting. Produces estimates using a standard curve. See create_standard_curve_model_analyte for details.

• nMFI (Normalised Median Fluorescence Intensity): Requires a reference dilution. See get_nmfi.

• MFI (Blank-adjusted Median Fluorescence Intensity): Returns raw MFI values (adjusted for blanks, if requested).

Value

A data frame of computed values, with test samples as rows and analytes as columns.

RAU Workflow

1. Optionally perform blank adjustment.

2. Fit a model for each analyte using standard curve data.

3. Predict RAU values for test samples.

4. Aggregate and optionally save results.

nMFI Workflow

1. Optionally perform blank adjustment.

2. Compute normalised MFI using the reference_dilution.

3. Aggregate and optionally save results.

MFI Workflow

1. Optionally perform blank adjustment.

2. Return adjusted MFI values.

See Also

create_standard_curve_model_analyte, get_nmfi

Examples

plate_file <- system.file("extdata", "CovidOISExPONTENT_CO_reduced.csv", package = "SerolyzeR")
layout_file <- system.file("extdata", "CovidOISExPONTENT_CO_layout.xlsx", package = "SerolyzeR")
plate <- read_luminex_data(plate_file, layout_file, verbose = FALSE)

example_dir <- tempdir(check = TRUE)

# Process using default settings (RAU normalisation)
process_plate(plate, output_dir = example_dir)

# Use a custom filename and skip blank adjustment
process_plate(plate,
  filename = "no_blank.csv",
  output_dir = example_dir,
  blank_adjustment = FALSE
)

# Use nMFI normalisation with reference dilution
process_plate(plate,
  normalisation_type = "nMFI",
  reference_dilution = "1/400",
  output_dir = example_dir
)

Read the Intelliflex format data

Description

Read the Intelliflex format data

Usage

read_intelliflex_format(path, verbose = TRUE)

Arguments

Read layout data from a file

Description

Read layout data from a file

Usage

read_layout_data(layout_file_path, ...)

Arguments

Value

A matrix with the layout data. The row names are supposed to be letters A,B,C, etc. The column names are supposed to be numbers 1,2,3, etc.

Read Luminex Data

Description

Reads a Luminex plate file and returns a Plate object containing the extracted data. Optionally, a layout file can be provided to specify the arrangement of samples on the plate.

Usage

read_luminex_data(
  plate_filepath,
  layout_filepath = NULL,
  format = "xPONENT",
  plate_file_separator = ",",
  plate_file_encoding = "UTF-8",
  use_layout_sample_names = TRUE,
  use_layout_types = TRUE,
  use_layout_dilutions = TRUE,
  default_data_type = "Median",
  sample_types = NULL,
  dilutions = NULL,
  verbose = TRUE,
  ...
)

Arguments

Details

The function supports two Luminex data formats:

• xPONENT: Used by older Luminex machines.

• INTELLIFLEX: Used by newer Luminex devices.

Value

A Plate object containing the parsed Luminex data.

Workflow

1. Validate input parameters, ensuring the specified format is supported.

2. Read the plate file using the appropriate parser:

   • xPONENT files are read using read_xponent_format().

   • INTELLIFLEX files are read using read_intelliflex_format().

3. Post-process the extracted data:

   • Validate required data columns (Median, Count).

   • Extract sample locations and analyte names.

   • Parse the date and time of the experiment.

File Structure

• Plate File (plate_filepath): A CSV file containing Luminex fluorescence intensity data.

• Layout File (layout_filepath) (optional): An Excel or CSV file containing the plate layout.

  • The layout file should contain a table with 8 rows and 12 columns, where each cell corresponds to a well location.

  • The values in the table represent the sample names for each well.

Sample types detection

The read_luminex_data() method automatically detects the sample types based on the sample names, unless provided the sample_types parameter. The sample types are detected used the translate_sample_names_to_sample_types() method. In the documentation of this method, which can be accessed with command ?translate_sample_names_to_sample_types, you can find the detailed description of the sample types detection.

Duplicates in sample names

In some cases, we want to analyse the sample with the same name twice on one plate. The package allows for such situations, but we assume that the user knows what they are doing.

When importing sample names (either from the layout file or the plate file), the function will check for duplicates. If any are found, it will issue a warning like:

Duplicate sample names detected: A, B. Renaming to make them unique.

Then it will add simple numeric suffixes (e.g. “.1”, “.2”) to the repeated sample names so that every name is unique while keeping the original text easy to recognize.

Examples

# Read a Luminex plate file with an associated layout file
plate_file <- system.file("extdata", "CovidOISExPONTENT.csv", package = "SerolyzeR")
layout_file <- system.file("extdata", "CovidOISExPONTENT_layout.csv", package = "SerolyzeR")
plate <- read_luminex_data(plate_file, layout_file)

# Read a Luminex plate file without a layout file
plate_file <- system.file("extdata", "CovidOISExPONTENT_CO.csv", package = "SerolyzeR")
plate <- read_luminex_data(plate_file, verbose = FALSE)

Read the xPONENT format data

Description

Read the xPONENT format data

Usage

read_xponent_format(
  path,
  exact_parse = FALSE,
  encoding = "utf-8",
  separator = ",",
  verbose = TRUE
)

Arguments

Remove Empty Lists from a List

Description

This internal function filters out elements from a list that are empty lists.

Usage

remove_empty_lists(lst)

Arguments

Value

A list with empty lists removed.

Select Columns from a DataFrame

Description

Selects specified columns from a dataframe. If a column does not exist in the dataframe, it will be added with a specified replacement value.

Usage

select_columns(df, columns, replace_value = NA)

Arguments

Value

A dataframe containing the specified columns, with missing columns filled with the replacement value.

Sort a flat list by value

Description

Sort a flat list by value

Usage

sort_list_by(list_obj, decreasing = FALSE, value_f = function(elem) elem)

Arguments

Translate sample names to sample types

Description

Function translates sample names to sample types based on the sample name from Luminex file and the sample name from the layout file, which may not be provided. The function uses regular expressions to match the sample names to the sample types.

Usage

translate_sample_names_to_sample_types(
  sample_names,
  sample_names_from_layout = NULL
)

Arguments

Details

Function assigns SampleType to each of the samples from one of c(ALL, BLANK, TEST, NEGATIVE CONTROL, STANDARD CURVE, POSITIVE CONTROL).

It parses the names as follows:

If sample_names or sample_names_from_layout equals to BLANK, BACKGROUND or B, then SampleType equals to BLANK

If sample_names or sample_names_from_layout equals to ⁠STANDARD CURVE⁠, SC, S, contains substring ⁠1/\d+⁠ and has prefix ⁠ ⁠, S_, S , S or CP3, then SampleType equals to ⁠STANDARD CURVE⁠. For instance, sample with a name S_1/2 or ⁠S 1/2⁠ will be classified as ⁠STANDARD CURVE⁠.

If sample_names or sample_names_from_layout equals to ⁠NEGATIVE CONTROL⁠, N, or contains substring NEG, then SampleType equals to ⁠NEGATIVE CONTROL⁠

If sample_names or sample_names_from_layout starts with P followed by whitespace, POS followed by whitespace, some sample name followed by substring ⁠1/\d+⁠ SampleType equals to ⁠POSITIVE CONTROL⁠

Otherwise, the returned SampleType is TEST

It also removes any additional suffixes created by make.unique() method, such as, .1, .4.

Value

A vector of valid sample_type strings of length equal to the length of sample_names

Examples

translate_sample_names_to_sample_types(c("B", "BLANK", "NEG", "TEST1"))
translate_sample_names_to_sample_types(c("S", "CP3"))

Validate filepath and output_dir

Description

This function validates the filepath and output_dir arguments.

Usage

validate_filepath_and_output_dir(
  filename,
  output_dir,
  plate_name,
  suffix,
  extension,
  verbose = TRUE
)

Arguments

Value

An absolute output path.

Verbose Cat

Description

This function prints the input to the console if the verbose argument is TRUE.

Usage

verbose_cat(..., verbose = TRUE)

Arguments

Verify Character Join

Description

Checks if two character values are equal. If either value is NULL, returns TRUE.

Usage

verify_character_join(x, y)

Arguments

Value

TRUE if the values are equal or if either value is NULL. Returns FALSE otherwise.

Verify Numeric Join

Description

Checks if two numeric values are equal. If either value is NA, returns TRUE.

Usage

verify_numeric_join(x, y)

Arguments

Value

TRUE if the values are equal or if either value is NA. Returns FALSE otherwise.