Update release status with error fixes in docs (#178)

* update the release version

* grammar, spelling and comas fixed

* fixed requested changes

* regenerated docs

---------

Co-authored-by: Fersoil <Fersoil>

DESCRIPTION

@@ -3,7 +3,7 @@ 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 of the same name - 'PvSTATEM', which is an international project aiming for malaria elimination.
 BugReports: https://github.com/mini-pw/PvSTATEM/issues
-Version: 0.0.4
+Version: 0.0.5
 License: BSD_3_clause + file LICENSE
 Encoding: UTF-8
 Authors@R: c(

NEWS.md

@@ -1,3 +1,12 @@
+PvSTATEM 0.0.5
+---------------------------------------------------------------
+* added function `generate_plate_report` generating the html report
+* added nMFI normalisation type
+* added an option to include raw MFI in the output of `process_plate` function
+* renamed output of the model to RAU (Relative Antibody Unit), which should be more interpretable for human
+* simple censoring of the extrapolation
+
+
 PvSTATEM 0.0.4
 ---------------------------------------------------------------
 * met the CRAN policy

R/classes-model.R

@@ -20,9 +20,9 @@
 #'
 #' After the model is fitted to the data, the RAU values can be predicted using the `predict` method.
 #' The RAU value is simply a predicted dilution value (using the standard curve) for a given MFI
-#' multiplied by 1 000 000 in order to have a more readable value.
+#' 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 the
-#' "Normalization" section in the "Basic PvSTATEM functionalities" vignette.
+#' "Normalisation" section in the "Basic PvSTATEM functionalities" vignette.
 #'
 #'
 #' @examples

R/generate_report.R

@@ -1,7 +1,8 @@
 #' Generate a report for a plate.
 #'
-#' This function generates a report for a plate. The report is generated using
-#' the `plate_report_template.Rmd` template.
+#' @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 `plate_report_template.Rmd` template.
 #'
 #' @param plate A plate object.
 #' @param use_model (`logical(1)`) A logical value indicating whether the model should be used in the report.

R/get-nmfi.R

@@ -3,28 +3,28 @@
 #' @description
 #' The function calculates the normalised MFI (nMFI) values for each of the analytes in the plate.
 #'
-#' The nMFI values are calculated as the ratio of the MFI values of test samples to the MFI values of the standard curve samples with the target dilution.
+#' The nMFI values are calculated as the ratio of the test samples' MFI values to the standard curve samples with the target dilution.
 #'
 #'
 #'
 #' **When nMFI could be used?**
-#' In general it is preferred to use Relative Antibody Unit (RAU) values for any kind of analysis.
-#' However, in some cases it is impossible to fit a model to the standard curve samples.
+#' In general, it is preferred to use Relative Antibody Unit (RAU) values for any analysis.
+#' However, it is sometimes impossible to fit a model to the standard curve samples.
 #' This may happen if the MFI values of test samples are much higher than the MFI of standard curve samples.
-#' Then, the prediction would require large data extrapolation, that could lead to unreliable results.
+#' Then, the prediction would require significant data extrapolation, which could lead to unreliable results.
 #'
-#' In such cases, the nMFI values could be used as a proxy for RAU values, if we want, for instance, to account for plate-to-plate variation.
+#' In such cases, the nMFI values could be used as a proxy for RAU values if we want, for instance, to account for plate-to-plate variation.
 #'
 #' @param plate (`Plate()`) a plate object for which to calculate the nMFI values
 #' @param reference_dilution (`numeric(1) or character(1)`) the dilution value of the standard curve sample
-#' to use as a reference for normalisation. Default is `1/400`.
+#' to use as a reference for normalisation. The default is `1/400`.
 #' It should refer to a dilution of a standard curve sample in the given plate object.
 #' This parameter could be either a numeric value or a string.
 #' In case it is a character string, it should have format `1/d+`, where `d+` is any positive integer.
-#' @param data_type (`character(1)`) type of data to use for the computation. Median is the default
-#' @param verbose (`logical(1)`) print additional information. Default is `TRUE`
+#' @param data_type (`character(1)`) type of data for the computation. Median is the default
+#' @param verbose (`logical(1)`) print additional information. The default is `TRUE`
 #'
-#' @return nmfi (`data.frame`) a data frame with normalised MFI values for each of the analytes in the plate and all test samples.
+#' @return nmfi (`data.frame`) a data frame with normalised MFI values for each analyte in the plate and all test samples.
 #'
 #' @examples
 #'

R/plots-plate.R

@@ -1,18 +1,19 @@
-#' Plot a 96-well plate with colored wells
+#' Plot a 96-well plate with coloured wells
 #'
-#' It is a generic function to plot a 96-well plate with colored wells
+#' 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 colors in the wells using ggplot2.
-#' This function is not intended to be used directly by the user.
-#' Rather, it is used by other functions, specified in this file.
+#' 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.
 #'
-#' @param colors A vector with 96 colors that will be used to color the wells, order is from left to right and top to bottom
+#' @param colours A vector with 96 colours will be used to colour the wells; the order is from left to right and top to bottom
 #' @param plot_numbers Logical value indicating if the well numbers should be plotted, default is `FALSE`
-#' @param numbers An optional vector with 96 numbers, plotted on the wells. Order is from left to right and top to bottom, must have the same length as colors. It could be used, for instance, to plot the bead count of each well. Must be provided in case the `plot_numbers` parameters is set to `TRUE`
+#' @param numbers An optional vector with 96 numbers plotted on the wells. Order is from left to right and top to bottom and must have the same length as colours. 
+#' It could be used, for instance, to plot the bead count of each well. Must be provided in case the `plot_numbers` parameter is set to `TRUE`
 #' @param plot_title The title of the plot (default is "Plate")
 #' @param plot_legend Logical value indicating if the legend should be plotted, default is `FALSE`
-#' @param legend_mapping A named vector with the colors mapping used to create the legend
+#' @param legend_mapping A named vector with the colour mapping used to create the legend
 #'
 #' @return A ggplot object
 #'
@@ -111,10 +112,10 @@ plot_plate <- function(colors, plot_numbers = FALSE, numbers = NULL, plot_title
 
 #' Plot counts in a 96-well plate
 #'
-#' This is a function used to plot counts in a 96-well plate using a color to represent the count ranges.
-#' There is possibility to plot exact counts in each well. \cr \cr
-#' If plot window is resized, it's best to re-run the function to adjust the scaling.
-#' Sometimes when legend is plotted, whole layout may be shifted, then it's best to stretch the window, and everything will be adjusted automatically.
+#' 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. \cr \cr
+#' 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.
 #'
 #' @param plate The plate object with the counts data
 #' @param analyte_name The name of the analyte
@@ -202,9 +203,9 @@ plot_counts <- function(plate, analyte_name, plot_counts = TRUE, plot_legend = F
 #' Plot layout of a 96-well plate
 #'
 #' @description
-#' This is a function used to plot the layout of a 96-well plate using a color to represent the sample types. \cr \cr
-#' If plot window is resized, it's best to re-run the function to adjust the scaling.
-#' Sometimes when legend is plotted, whole layout may be shifted, then it's best to stretch the window, and everything will be adjusted automatically.
+#' This function plots the layout of a 96-well plate using a colour to represent the sample types. \cr \cr
+#' 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.
 #'
 #'
 #' @param plate The plate object with the layout information

R/process-plate.R

@@ -12,7 +12,7 @@ is_valid_normalisation_type <- function(normalisation_type) {
 #' **RAU** is the default normalisation type.
 #'
 #'
-#' The behavior of the function, in case of RAU normalisation type, can be summarized as follows:
+#' The behaviour of the function, in the case of RAU normalisation type, can be summarised as follows:
 #' 1. Adjust blanks if not already done.
 #' 2. Fit a model to each analyte using standard curve samples.
 #' 3. Compute RAU values for each analyte using the corresponding model.
@@ -35,22 +35,21 @@ is_valid_normalisation_type <- function(normalisation_type) {
 #'
 #' @param plate (`Plate()`) a plate object
 #' @param output_path (`character(1)`) path to save the computed RAU values.
-#' If not provided the file will be saved in the working directory with the name `{normalisation_type}_{plate_name}.csv`.
+#' If not provided, the file will be saved in the working directory with the name `{normalisation_type}_{plate_name}.csv`.
 #' Where the `{plate_name}` is the name of the plate.
 #' @param normalisation_type (`character(1)`) type of normalisation to use. Available options are:
 #' \cr \code{c(`r toString(VALID_NORMALISATION_TYPES)`)}.
-#' In case
 #' @param data_type (`character(1)`) type of data to use for the computation. Median is the default
-#' @param include_raw_mfi (`logical(1)`) include raw MFI values in the output. Default is `TRUE`.
+#' @param include_raw_mfi (`logical(1)`) include raw MFI values in the output. The default is `TRUE`.
 #' In case this option is `TRUE`, the output dataframe contains two columns for each analyte: one for the normalised values and one for the raw MFI values.
 #' The normalised columns are named as `AnalyteName` and `AnalyteName_raw`, respectively.
-#' @param adjust_blanks (`logical(1)`) adjust blanks before computing RAU values. Default is `FALSE`
-#' @param verbose (`logical(1)`) print additional information. Default is `TRUE`
+#' @param adjust_blanks (`logical(1)`) adjust blanks before computing RAU values. The default is `FALSE`
+#' @param verbose (`logical(1)`) print additional information. The default is `TRUE`
 #' @param reference_dilution (`numeric(1)`) target dilution to use as reference for the nMFI normalisation. Ignored in case of RAU normalisation.
 #' Default is `1/400`.
 #' It should refer to a dilution of a standard curve sample in the given plate object.
 #' This parameter could be either a numeric value or a string.
-#' In case it is a character string, it should have format `1/d+`, where `d+` is any positive integer.
+#' In case it is a character string, it should have the format `1/d+`, where `d+` is any positive integer.
 #' @param ... Additional arguments to be passed to the fit model function (`create_standard_curve_model_analyte`)
 #'
 #' @examples

README.md

@@ -7,7 +7,7 @@
 
 
 ## Overview
-This package is a simple tool that handles various formats of raw data produced in Multiplex Bead Assay (MBA). In short, it reads the unstructured, raw data from, e.g., the Luminex device and outputs normalised and well-structured data, which can be used later in more advanced downstream analysis.
+This package is a simple tool that handles various raw data formats produced in Multiplex Bead Assay (MBA). In short, it reads the unstructured, raw data from, e.g., the Luminex device and outputs normalised and well-structured data, which can be used later in more advanced downstream analysis.
 
 The package includes three main steps for preprocessing the data:
 
@@ -20,8 +20,7 @@ The package includes three main steps for preprocessing the data:
 
 ### 🟡 *Semi-release* version
 
-The package is still in a *semi-release* version and new functionalities are being added. We plan to finish this stage of development by the end of 2024, by adding summary reports, quality control tools comparing multiple plates, and different normalisation methods.
-
+The package is still in a *semi-release* version, and new functionalities are being added. We plan to finish this stage of development by the end of 2024 by adding summary reports, quality control tools comparing multiple plates, and different normalisation methods.
 
 ## Installation
 
@@ -30,30 +29,29 @@ The easiest way to install the package is using the CRAN repository:
 install.packages("PvSTATEM")
 require(PvSTATEM) # load the installed package
 ```
-
 Now, you are ready to use the package to read your files! 
 
+Please note that since uploading the package to the CRAN repository requires the volunteers' time to manually run checks on the packages, the **package version currently released on CRAN might not be the latest**. 
 
-
-Optionally, it is possible to build and install the package by hand. It can be done using a simple command `install_github` available in `devtools` library:
+The package is under heavy development, with new features being released weekly. Therefore, if you'd like to test the latest package functionalities, we recommend installing it in the development version. It can be done using a simple command `install_github` available in the `devtools` library:
 
 ``` r
 require(devtools)
 install_github("mini-pw/PvSTATEM")
 require(PvSTATEM) # load the installed package
 ```
 
-The first command loads the `devtools` library (you might need to install it first - using command `install_packages("devtools")`), and the second one sources the git repository with the code of our package and automatically installs it. 
+The first command loads the `devtools` library (you might need to install it first - using the command `install_packages("devtools")`), and the second one sources the git repository with the code of our package and automatically installs it. 
 
 ## Examples and instructions
 
 The example use of the package and its functionalities can be found in [the vignettes](https://mini-pw.github.io/PvSTATEM/articles/example_script.html).
-For more detailed documentation of the package, check [the package website](https://mini-pw.github.io/PvSTATEM).
+For more detailed documentation, check [the package website](https://mini-pw.github.io/PvSTATEM).
 
 
 ## Contributing and issues
 
-As a project in the development phase, we are open to any suggestions, bug reports, and contributions. If you have any ideas or issues, please report them in the [Issues](https://github.com/mini-pw/PvSTATEM/issues) section. Our team of developers will try to address them as soon as possible.
+As a project in the development phase, we are open to any suggestions, bug reports, and contributions. If you have any ideas or issues, please report them in the [Issues](https://github.com/mini-pw/PvSTATEM/issues) section. Our team of developers will address them as soon as possible.