tidied function descriptions

ec363 · Nov 3, 2024 · a0d10ce · a0d10ce
1 parent e3f26de
commit a0d10ce
Show file tree

Hide file tree

Showing 24 changed files with 366 additions and 322 deletions.
diff --git a/R/calc_fpconc.R b/R/calc_fpconc.R
@@ -1,10 +1,10 @@
 #' Calculate FP concentration in molar units
 #'
-#' Takes as input timecourse plate reader data processed with `process_plate`
-#' and uses normalised/calibrated values to calculate FP concentration. Adds
-#' column(s) for FP concentration as either: (a) `normalisedFP/cellvolume`
-#' (RFU/L), (b) `calibratedFP/cellvolume` (moles/L, or M). Plots results and
-#' returns a dataframe.
+#' Takes as input plate reader data processed with `process_plate()` and uses
+#' normalised/calibrated values to calculate FP concentration. Adds column(s)
+#' for FP concentration as either: (a) `normalisedFP/cellvolume` (RFU/L), (b)
+#' `calibratedFP/cellvolume` (moles/L, or M). Plots results and returns a
+#' dataframe.
 #'
 #' @param data_csv path to a CSV file containing processed plate reader data
 #' @param timecourse logical. Is the data timecourse/kinetic data and does it

diff --git a/R/calc_fppercell.R b/R/calc_fppercell.R
@@ -1,9 +1,9 @@
 #' Calculate FP per cell values
 #'
-#' Takes as input timecourse plate reader data processed with `process_plate`
-#' and uses normalised/calibrated values to calculate per-cell values. Adds
-#' column(s) for FP/cell as either: (a) `normalisedFP/normalisedOD` (RFU/OD),
-#' (b) `calibratedFP/calibratedOD` (molecules/cell). Plots results and returns a
+#' Takes as input plate reader data processed with `process_plate()` and uses
+#' normalised/calibrated values to calculate per-cell values. Adds column(s) for
+#' FP/cell as either: (a) `normalisedFP/normalisedOD` (RFU/OD), (b)
+#' `calibratedFP/calibratedOD` (molecules/cell). Plots results and returns a
 #' dataframe. Note that technically, units of molecules are 'molecules of
 #' equivalent FP' and cells are 'particles of equivalent microspheres'.
 #'

diff --git a/R/generate_cfs.R b/R/generate_cfs.R
@@ -1,24 +1,24 @@
 #' Generate conversion factors for FP calibrations
 #'
-#' Generate conversion factors for FP calibrations. Originally based on
-#' `flopr::generate_cfs` but with many changes. ... The original function was
-#' intended for fluorescein and microspheres, this one can be used for any
-#' fluorescent calibrant, including proteins. Takes as input a parsed CSV of
-#' fluorescence data of a dilution series of FPs at one or more gains, that
-#' contains both data and metadata columns (including: `instrument`, `plate`,
-#' `seal`, `channel_name`, `channel_ex`, `channel_em`, `media`, `calibrant`,
-#' `protein`, `replicate`, `volume`, `molecular_weight_gmol`,
-#' `concentration_ngul`, `dilution`, `rev_dilution`, `well`, the columns for the
-#' fluorescence data, `row`, `column`). ... A number of arguments allow the
-#' tweaking of the original data set. Following this, the data is reshaped,
-#' normalised, trimmed of saturated points, summarised and used to fit a model
-#' for the conversion factors from arbitrary to absolute units. Optional extras:
-#' the `sensitivity_plots` argument extends this analysis to identify the limits
-#' of detection and relative sensitivity and dynamic range of each gain. Plots
-#' are saved to record the processed data at every step, allowing for visual
-#' sanity checks and troubleshooting. A CSV file with the fitted conversion
-#' factors is saved (along with the processed data if requested with
-#' `more_csvs`).
+#' Generate conversion factors for fluorescent protein (FP) calibrations.
+#' Originally based on `flopr::generate_cfs()` but with numerous changes. The
+#' original function was intended for fluorescein and microsphere calibrations,
+#' whereas this one can be used for any fluorescent calibrant, including
+#' proteins. Takes as input a parsed CSV of fluorescence data of a dilution
+#' series of FPs at one or more gains, that contains both data and metadata
+#' columns (including: `instrument`, `plate`, `seal`, `channel_name`,
+#' `channel_ex`, `channel_em`, `media`, `calibrant`, `protein`, `replicate`,
+#' `volume`, `molecular_weight_gmol`, `concentration_ngul`, `dilution`,
+#' `rev_dilution`, `well`, the columns for the fluorescence data, `row`,
+#' `column`). A number of arguments allow the tweaking of the original data set.
+#' Following this, the data is reshaped, normalised, trimmed of saturated
+#' points, summarised and used to fit a model for the conversion factors from
+#' arbitrary to absolute units. Optional extras: the `sensitivity_plots`
+#' argument extends this analysis to identify the limits of detection and
+#' relative sensitivity and dynamic range of each gain. Plots are saved to
+#' record the processed data at every step, allowing for visual sanity checks
+#' and troubleshooting. A CSV file with the fitted conversion factors is saved
+#' (along with the processed data if requested with `more_csvs`).
 #'
 #' @param calibration_csv character string. Path of the calibration data CSV
 #'   file.
@@ -32,9 +32,9 @@
 #'   measures (column names) specified here.
 #' @param exclude character string. If specified, excludes any measures (column
 #'   names) specified here.
-#' @param gain_fix logical. Optionally add "0" before 2-digit gain names i.e. 'GFP
-#'   40' -> 'GFP 040', or `blueblue 40` -> `blueblue 040`- which fixes ordering
-#'   of plots. Defaults to FALSE.
+#' @param gain_fix logical. Optionally add "0" before 2-digit gain names i.e.
+#'   'GFP 40' -> 'GFP 040', or `blueblue 40` -> `blueblue 040`- which fixes
+#'   ordering of plots. Defaults to FALSE.
 #' @param rename_from character string. Rename measures (column names)
 #'   containing character string `rename_from` to character string specified in
 #'   `rename_to`. Both `rename_from` and `rename_to` need to be completed to
@@ -51,9 +51,9 @@
 #'   channel name and the gain value in the measures columns, e.g. for "GFP 40"
 #'   it is " ", for "GFP40" it is "" and for "GFP_40" it is "_". Required for
 #'   plotting the gain vs conversion factors. Defaults to "".
-#' @param complete_blank logical. Optionally adds "0" to the `concentration_ngul`
-#'   column for wells identified as blank (`protein` = "none"). Useful if data
-#'   layout is missing these values. Defaults to FALSE.
+#' @param complete_blank logical. Optionally adds "0" to the
+#'   `concentration_ngul` column for wells identified as blank (`protein` =
+#'   "none"). Useful if data layout is missing these values. Defaults to FALSE.
 #' @param outfolder character string. Path to folder where output files should
 #'   be saved. Defaults to current working directory.
 #'

diff --git a/R/get_conc_bca.R b/R/get_conc_bca.R
@@ -1,6 +1,6 @@
 #' Get FP concentrations using bicinchoninic acid (BCA) assay method
 #'
-#' Get protein's concentration from a *dilution series* measured with the
+#' Get protein's concentration from a dilution series measured with the
 #' bicinchoninic acid (BCA) assay. Takes two input data sets, the BCA assay data
 #' and the A562 baseline data. The A562 baseline data is necessary for proteins
 #' that might naturally absorb in this range. Script normalises BCA assay data

diff --git a/R/get_mw.R b/R/get_mw.R
@@ -1,6 +1,10 @@
 #' Get molecular weight of a protein
 #'
-#' Get molecular weight of protein in Daltons from its sequence alone.
+#' Get the molecular weight of a protein in Daltons from its sequence alone.
+#' Uses calculation (<https://web.expasy.org/compute_pi/pi_tool-doc.html>) and
+#' amino acid mass data (`aa_mass_data`,
+#' <https://web.expasy.org/findmod/findmod_masses.html#AA>) from the Swiss
+#' Bioinformatics Resource Portal, Expasy.
 #'
 #' @param protein character string of protein sequence using the 1-letter code.
 #'

diff --git a/R/get_pathlength.R b/R/get_pathlength.R
@@ -1,18 +1,18 @@
 #' Get path length in a typical 96-well plate
 #'
-#' Calculates the path length of an input test_volume by comparing it to a
+#' Calculates the path length of an input `test_volume` by comparing it to a
 #' linear model using internal data of pathlengths vs volume. ... To work out
-#' the pathlength in a microplate assay, there are two options. Option1. Measure
-#' the pathlength each time you do an assay by taking A975-A900 for each well as
-#' the `kfactor(well)`, and calculating `pathlength` = `kfactor(well)` /
+#' the pathlength in a microplate assay, there are two options. Option 1:
+#' Measure the pathlength each time you do an assay by taking A975-A900 for each
+#' well as the `kfactor(well)`, and calculating `pathlength` = `kfactor(well)` /
 #' `kfactor(1cm pathlength)`. The 1cm k-factors can be derived using
-#' `get_kfactor` function. Option2 (here). Use a standardised dataset of
-#' pathlength vs volume by measuring the A975-A900 of defined volumes of buffer,
-#' and calculating the pathlengths of each. This is saved as the
-#' pathlength_water_data dataset, and is used in this function to create a
-#' linear model of pathlength vs volume. Experimental data suggests that aqueous
-#' buffers give very similar pathlength values for a given volume, so here we
-#' use data from water to approximate all aqueous buffers.
+#' `get_kfactor()` function. Option 2 (used here): Create a standardised dataset
+#' of pathlength vs volume by measuring the A975-A900 of defined volumes of
+#' buffer, and calculating the pathlengths of each (the `pathlength_water_data`
+#' dataset) and use this to create a linear model of pathlength vs volume.
+#' Experimental data suggests that aqueous buffers give very similar pathlength
+#' values for a given volume, so here we use data from water to approximate all
+#' aqueous buffers.
 #'
 #' @param test_volume numeric value of volume whose pathlength is required, in
 #'   microlitres (ul)

diff --git a/R/process_plate.R b/R/process_plate.R
@@ -1,26 +1,30 @@
-#' Process timecourse plate reader data (normalise, correct and calibrate)
+#' Process experimental data (normalise, correct and calibrate)
 #'
-#' Normalise and calibrate plate reader measurements to obtain molecular units
-#' from the raw data. Originally based on `flopr::process_plate` but with many
-#' changes. Takes as input timecourse plate reader data containing optical
-#' density measurements and fluorescence measurements as CSV file. First, the
-#' function normalises optical density readings and fluorescence readings to an
-#' autofluorescence model based on the specified negative wells (see 2020
-#' Fedorec et al ACS SynBio for details). The identity of the blank wells need
-#' to be specified in `blank_wells`, the reading to be used for optical density
-#' in `od_name`, and the fluorescence channels in `flu_channels`. The
-#' autofluorescence model can be set with `af_model` on the `neg_well` wells,
-#' alternatively, fluorescence can be normalised to blank wells by setting
-#' `af_model` to `NULL`. Second, if `do_quench_correction` is TRUE, it
-#' compensates for cellular quenching of fluorescence measurements according to
-#' the cell density. This requires the specification of `od_type` as "OD600" or
-#' "OD700". Third, if `do_calibrate` is TRUE, normalised values are calibrated,
-#' where conversion factors are provided as `od_coeffs_csv` for OD and
-#' `fluor_coeffs_csv` for fluorescence, and each calibration is specified by the
-#' `flu_slugs` to represent the FP used, `flu_gains` to provide the gain used,
-#' and `flu_labels` to specify how the relevant plots should be labelled, (e.g.
-#' `flu_slugs = c("mcherry", "mtagbfp2")`, `flu_gains = c(60,80)`, `flu_labels =
-#' c("RFP, BFP")`).
+#' Processes experimental (fluorescence and absorbance) data from microplate
+#' readers. Expects 'parsed' data that is tidy and attached to appropriate
+#' metadata. Numerous arguments offer options to customise how and whether
+#' normalisation, correction and/or calibration is carried out. Data can be
+#' timecourse (kinetic) data or single timepoint (endpoint) data, and can
+#' contain fluorescence data only or include absorbance (OD) data to enumerate
+#' cell density. Originally based on `flopr::process_plate()` but with numerous
+#' changes. First, the function normalises optical density readings (if present)
+#' to media/buffer wells, and fluorescence readings, either to media/buffer
+#' wells or to cellular autofluorescence. Fluorescence channels must be
+#' specified in `flu_channels`, the blank wells in `blank_wells`, and the
+#' reading to be used for optical density in `od_name`. The cellular
+#' autofluorescence model can be set with `af_model` on the negative
+#' (`neg_well`) wells, or set to `NULL`. Second, if `do_quench_correction` is
+#' TRUE, the 'quenching' or attenuation of fluorescence measurements by cells is
+#' corrected for according to the cell density measured. This requires the
+#' specification of `od_type` as "OD600" or "OD700". Third, if `do_calibrate` is
+#' TRUE, normalised values for both fluorescence and optical density are
+#' converted into meaningful units. Here, the paths to conversion factor CSV
+#' files must be provided as `od_coeffs_csv` for OD and `fluor_coeffs_csv` for
+#' fluorescence. For fluorescence measurements, each calibration must be
+#' specified by `flu_slugs` to represent the FP used, `flu_gains` to provide the
+#' gain, and `flu_labels` to specify how the relevant plots should be labelled,
+#' (e.g. `flu_slugs = c("mcherry", "mtagbfp2")`, `flu_gains = c(60,80)`,
+#' `flu_labels = c("RFP, BFP")`).
 #'
 #' @param data_csv path to a CSV file containing parsed plate reader data
 #' @param blank_well the well coordinates of one or more media blanks. Defaults

diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml
@@ -3,7 +3,7 @@ pkgdown: 2.0.9
 pkgdown_sha: ~
 articles:
   fpcountr: fpcountr.html
-last_built: 2024-11-03T19:03Z
+last_built: 2024-11-03T20:35Z
 urls:
   reference: https://ec363.github.io/fpcountr/reference
   article: https://ec363.github.io/fpcountr/articles