Package 'SerolyzeR'

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

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
)

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
)

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"))

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")

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.

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.

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"))

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)

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

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

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
)

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)

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))

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

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")

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)

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 = 6,
  sort_plates = TRUE,
  log_scale = c("all"),
  separate_legend = FALSE,
  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)

Description

More details can be found here: Model

Usage

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

Arguments

Value

(data.frame())

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)

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)

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
)

Description

Read the BIOPLEX format data

Usage

read_bioplex_format(path, verbose = TRUE)

Arguments

Description

Read the Intelliflex format data

Usage

read_intelliflex_format(path, verbose = TRUE)

Arguments

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.

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.

• BIOPLEX: Used by Bio-Rad 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().

   • BIOPLEX files are read using read_bioplex_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)

Description

Read the xPONENT format data

Usage

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

Arguments

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⁠, starts with NEG (or Neg) or ends with 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"))