From 7885ccf6332eda449a3104f1feb56e60563360d5 Mon Sep 17 00:00:00 2001
From: Ethan Bass <ethanbass@gmail.com>
Date: Sun, 24 Dec 2023 18:31:27 -0500
Subject: [PATCH] docs: update docs, added explanatory comments to internal
 fncs

---
 R/call_openchrom.R               | 13 +++++-----
 R/call_rainbow.R                 |  9 +++++++
 R/read_chemstation_ch.R          | 10 +++++---
 R/read_chemstation_report.R      |  1 +
 R/read_mdf.R                     |  1 +
 R/read_shimadzu_ascii.R          | 18 ++++++++++++-
 R/read_shimadzu_lcd.R            | 43 +++++++++++++++++++-------------
 R/read_thermoraw.R               |  1 +
 R/reshape_chroms.R               |  3 +--
 man/call_openchrom.Rd            | 12 ++++-----
 man/read_shimadzu_lcd.Rd         |  6 +++++
 man/write_openchrom_batchfile.Rd |  4 ++-
 12 files changed, 85 insertions(+), 36 deletions(-)

diff --git a/R/call_openchrom.R b/R/call_openchrom.R
index 21da731..029c3d2 100644
--- a/R/call_openchrom.R
+++ b/R/call_openchrom.R
@@ -34,12 +34,12 @@
 #' @param return_paths Logical. If TRUE, the function will return a character
 #' vector of paths to the newly created files.
 #' @param verbose Logical. Whether to print output from OpenChrom to the console.
-#' @return If \code{return_paths} is \code{FALSE}, the function will return a list of
-#' chromatograms (if an appropriate parser is available in chromConverter). The
-#' chromatograms will be returned in \code{matrix} or \code{data.frame} format
-#' according to the value of {data_class}. If \code{return_paths} is \code{TRUE},
-#' the function will return a character vector of paths to the newly created
-#' files.
+#' @return If \code{return_paths} is \code{FALSE}, the function will return a
+#' list of chromatograms (if an appropriate parser is available to import the
+#' files into R). The chromatograms will be returned in \code{matrix} or
+#' \code{data.frame} format according to the value of {format_out}. If
+#' \code{return_paths} is \code{TRUE}, the function will return a character
+#' vector of paths to the newly created files.
 #' @section Side effects: Chromatograms will be exported in the format specified
 #' by \code{export_format} in the folder specified by \code{path_out}.
 #' @author Ethan Bass
@@ -98,6 +98,7 @@ call_openchrom <- function(files, path_out = NULL, format_in,
 }
 
 #' Writes OpenChrom XML batch file
+#' This function is called internally by \code{call_openchrom}.
 #' @import xml2
 #' @import magrittr
 #' @param files Paths to files for conversion
diff --git a/R/call_rainbow.R b/R/call_rainbow.R
index 796a5ef..5ef075b 100644
--- a/R/call_rainbow.R
+++ b/R/call_rainbow.R
@@ -85,6 +85,9 @@ call_rainbow <- function(file,
   xx
 }
 
+#' Extract data with rainbow
+#' This function is called internally by \code{call_rainbow}.
+#' @author Ethan Bass
 #' @noRd
 extract_rb_data <- function(xx, format_out = "matrix",
                             data_format = c("wide", "long"),
@@ -111,6 +114,8 @@ extract_rb_data <- function(xx, format_out = "matrix",
   data
 }
 
+#' Extract 'rainbow' element names.
+#' This function is called internally by \code{call_rainbow}.
 #' @noRd
 extract_rb_names <- function(xx){
   sapply(xx, function(xxx){
@@ -118,6 +123,8 @@ extract_rb_names <- function(xx){
   })
 }
 
+#' Assign 'rainbow' read
+#' This function is called internally by \code{call_rainbow}.
 #' @noRd
 assign_rb_read <- function(){
   pos <- 1
@@ -126,6 +133,8 @@ assign_rb_read <- function(){
   assign("rb_parse_agilent", reticulate::import("rainbow.agilent"), envir = envir)
 }
 
+#' Check 'rainbow' configuration
+#' This function is called internally by \code{call_rainbow}.
 #' @noRd
 check_rb_configuration <- function(){
   assign_rb_read()
diff --git a/R/read_chemstation_ch.R b/R/read_chemstation_ch.R
index 32a8123..1a8ccce 100644
--- a/R/read_chemstation_ch.R
+++ b/R/read_chemstation_ch.R
@@ -163,16 +163,18 @@ get_chemstation_dir_name <- function(path){
   grep("\\.D|\\.d$", sp, ignore.case = TRUE, value = TRUE)
 }
 
+#' Get number of characters for Agilent segment
 #' @noRd
 get_nchar <- function(f){
   as.numeric(readBin(f, what = "raw", n = 1))
 }
 
 #' Decode double delta array
-#' @noRd
 #' @note This function was adapted from the
 #' \href{https://github.com/chemplexity/chromatography}{Chromatography Toolbox}
 #' ((c) James Dillon 2014).
+#' @noRd
+
 decode_double_delta <- function(file, offset) {
 
   seek(file, 0, 'end')
@@ -208,10 +210,11 @@ decode_double_delta <- function(file, offset) {
 }
 
 #' Decode double array
-#' @noRd
 #' @note This function was adapted from the
 #' \href{https://github.com/chemplexity/chromatography}{Chromatography Toolbox}
 #' ((c) James Dillon 2014).
+#' @noRd
+
 decode_double_array_4byte <- function(file, offset) {
   seek(file, 0, 'end')
   fsize <- seek(file, NA, "current")
@@ -238,10 +241,11 @@ decode_double_array_8byte <- function(file, offset) {
 }
 
 #' Decode delta array
-#' @noRd
 #' @note This function was adapted from the
 #' \href{https://github.com/chemplexity/chromatography}{Chromatography Toolbox}
 #' ((c) James Dillon 2014).
+#' @noRd
+
 decode_delta <- function(file, offset) {
     seek(file, 0, 'end')
     fsize <- seek(file, NA, "current")
diff --git a/R/read_chemstation_report.R b/R/read_chemstation_report.R
index ca04e29..92e9904 100644
--- a/R/read_chemstation_report.R
+++ b/R/read_chemstation_report.R
@@ -136,6 +136,7 @@ convert_chemstation_peaklist <- function(table, data_format =
 }
 
 #' Remove blank lines
+#' This function is called internally by \code{read_chemstation_reports}.
 #' @noRd
 remove_blank_lines <- function(x){
   x[which(x != "")]
diff --git a/R/read_mdf.R b/R/read_mdf.R
index 37e0468..a729833 100644
--- a/R/read_mdf.R
+++ b/R/read_mdf.R
@@ -65,6 +65,7 @@ read_mdf <- function(file, format_out = c("matrix","data.frame"),
 }
 
 #' Extract MDF metadata
+#' This function is called internally by \code{read_mdf}.
 #' @author Ethan Bass
 #' @noRd
 extract_mdf_metadata <- function(x){
diff --git a/R/read_shimadzu_ascii.R b/R/read_shimadzu_ascii.R
index 7430c16..13cfae8 100644
--- a/R/read_shimadzu_ascii.R
+++ b/R/read_shimadzu_ascii.R
@@ -143,6 +143,9 @@ read_shimadzu <- function(file, what = "chromatogram",
   xx
 }
 
+#' Convert list of mass spectra to data.frame
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 ms_list_to_dataframe <- function(x){
   if (!is.null(names(x))){
@@ -156,7 +159,10 @@ ms_list_to_dataframe <- function(x){
   }
   as.data.frame(do.call(rbind, ms))
 }
-#' Read Shimadzu Metadata
+
+#' Read 'Shimadzu' Metadata
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 read_shimadzu_metadata <- function(x, met = NULL, sep){
 
@@ -181,6 +187,8 @@ read_shimadzu_metadata <- function(x, met = NULL, sep){
 }
 
 #' Read Shimadzu Chromatogram
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 read_shimadzu_chromatogram <- function(file, x, chrom.idx, sep, data_format,
                                        read_metadata, format_out){
@@ -221,6 +229,8 @@ read_shimadzu_chromatogram <- function(file, x, chrom.idx, sep, data_format,
 }
 
 #' Read Shimadzu DAD Array
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 read_shimadzu_dad <- function(file, x, chrom.idx, sep, data_format,
                               read_metadata, format_out){
@@ -258,6 +268,8 @@ read_shimadzu_dad <- function(file, x, chrom.idx, sep, data_format,
 }
 
 #' Read Shimadzu Peak Table
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 read_shimadzu_peaktable <- function(file, x, idx, sep, format_in, format_out){
   nrows <- as.numeric(strsplit(x = x[idx + 1], split = sep)[[1]][2])
@@ -283,6 +295,8 @@ read_shimadzu_peaktable <- function(file, x, idx, sep, format_in, format_out){
 }
 
 #' Read Shimadzu MS Spectrum
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 read_shimadzu_spectrum <- function(file, x, idx, sep){
   nrows <- as.numeric(strsplit(x = x[idx + 1], split = sep)[[1]][2])
@@ -295,6 +309,8 @@ read_shimadzu_spectrum <- function(file, x, idx, sep){
 }
 
 #' Extract Header from Shimadzu ASCII Files
+#' This function is called internally by \code{read_shimadzu}.
+#' @author Ethan Bass
 #' @noRd
 extract_shimadzu_header <- function(x, chrom.idx, sep){
   index <- chrom.idx + 1
diff --git a/R/read_shimadzu_lcd.R b/R/read_shimadzu_lcd.R
index b7b4fb2..de4a4da 100644
--- a/R/read_shimadzu_lcd.R
+++ b/R/read_shimadzu_lcd.R
@@ -34,6 +34,10 @@
 #' @param data_format Either \code{wide} (default) or \code{long}.
 #' @param read_metadata Logical. Whether to attach metadata.
 #' @author Ethan Bass
+#' @return A 3D chromatogram from the PDA stream in \code{matrix} or
+#' \code{data.frame} format, according to the value of \code{format_out}.
+#' The chromatograms will be returned in \code{wide} or \code{long} format
+#' according to the value of \code{data_format}.
 #' @note This parser is experimental and may still
 #' need some work. It is not yet able to interpret much metadata from the files.
 #' @export
@@ -75,6 +79,7 @@ read_shimadzu_lcd <- function(path, format_out = c("matrix", "data.frame"),
 }
 
 #' Read Shimadzu "Method" stream
+#' This function is called internally by \code{read_shimadzu_lcd}.
 #' @author Ethan Bass
 #' @noRd
 read_sz_method <- function(path){
@@ -110,6 +115,7 @@ read_sz_method <- function(path){
 }
 
 #' Infer times from 'Shimadzu' Method stream
+#' This function is called internally by \code{read_shimadzu_lcd}.
 #' @author Ethan Bass
 #' @noRd
 get_sz_times <- function(sz_method, nval){
@@ -151,6 +157,7 @@ read_shimadzu_raw <- function(path, n_lambdas = NULL){
 }
 
 #' Export OLE stream
+#' This function is called internally by \code{read_shimadzu_lcd}.
 #' Use olefile to export te specified stream.
 #' @param file Path to ole file.
 #' @author Ethan Bass
@@ -183,7 +190,25 @@ export_stream <- function(path_in, stream, path_out, remove_null_bytes = FALSE,
   }
 }
 
+#' Extract wavelengths from Shimadzu LCD
+#' This function is called internally by \code{read_shimadzu_lcd}.
+#' @author Ethan Bass
+#' @noRd
+read_shimadzu_wavelengths <- function(path){
+  path_wavtab <- export_stream(path, stream =  c("PDA 3D Raw Data", "Wavelength Table"))
+  f <- file(path_wavtab, "rb")
+  on.exit(close(f))
+  n_lambda <- readBin(f, what="integer", size = 4)
+  count <- 1
+  # lambdas <- numeric(n_lambda)
+  lambdas <- sapply(seq_len(n_lambda), function(i){
+    readBin(f, what="integer", size = 4)/100
+  })
+  lambdas
+}
+
 #' Read 'Shimadzu' LCD data block
+#' This function is called internally by \code{read_shimadzu_lcd}.
 #' @author Ethan Bass
 #' @noRd
 decode_shimadzu_block <- function(file) {
@@ -236,6 +261,7 @@ decode_shimadzu_block <- function(file) {
 }
 
 #' Return twos complement from binary string
+#' This function is called internally by \code{read_shimadzu_lcd}.
 #' @noRd
 twos_complement <- function(bin, exp){
   if (missing(exp)){
@@ -277,20 +303,3 @@ integer_to_binary <- function(x, n) {
   # Return
   x
 }
-
-#' Extract wavelengths from Shimadzu LCD
-#' @author Ethan Bass
-#' @noRd
-read_shimadzu_wavelengths <- function(path){
-  path_wavtab <- export_stream(path, stream =  c("PDA 3D Raw Data", "Wavelength Table"))
-  f <- file(path_wavtab, "rb")
-  on.exit(close(f))
-  n_lambda <- readBin(f, what="integer", size = 4)
-  count <- 1
-  # lambdas <- numeric(n_lambda)
-  lambdas <- sapply(seq_len(n_lambda), function(i){
-    readBin(f, what="integer", size = 4)/100
-  })
-  lambdas
-}
-
diff --git a/R/read_thermoraw.R b/R/read_thermoraw.R
index 7e26167..4112dc9 100644
--- a/R/read_thermoraw.R
+++ b/R/read_thermoraw.R
@@ -96,6 +96,7 @@ read_thermoraw <- function(path_in, path_out = NULL,
 #' @return No return value.
 #' @author Ethan Bass
 #' @noRd
+
 configure_thermo_parser <- function(reconfigure = FALSE, check = FALSE){
   if (.Platform$OS.type == "windows"){
     path_parser <- readLines(system.file("shell/path_parser.txt", package = 'chromConverter'))
diff --git a/R/reshape_chroms.R b/R/reshape_chroms.R
index bd1615b..29f58a9 100644
--- a/R/reshape_chroms.R
+++ b/R/reshape_chroms.R
@@ -1,4 +1,3 @@
-
 #' Reshapes list of chromatograms from wide to long format
 #' @name reshape_chroms
 #' @param x A list of chromatographic matrices in wide format.
@@ -92,7 +91,7 @@ reshape_chrom_long <- function(x, lambdas, format_out = NULL, names_to = "lambda
   data
 }
 
-
+#' Reshapes a single chromatogram from long to wide format
 #' @noRd
 reshape_chrom_wide <- function(x, lambdas, lambda_var = "lambda", time_var="rt",
                                value_var = "int", drop){
diff --git a/man/call_openchrom.Rd b/man/call_openchrom.Rd
index 2e4b3dd..091a3b4 100644
--- a/man/call_openchrom.Rd
+++ b/man/call_openchrom.Rd
@@ -32,12 +32,12 @@ vector of paths to the newly created files.}
 \item{verbose}{Logical. Whether to print output from OpenChrom to the console.}
 }
 \value{
-If \code{return_paths} is \code{FALSE}, the function will return a list of
-chromatograms (if an appropriate parser is available in chromConverter). The
-chromatograms will be returned in \code{matrix} or \code{data.frame} format
-according to the value of {data_class}. If \code{return_paths} is \code{TRUE},
-the function will return a character vector of paths to the newly created
-files.
+If \code{return_paths} is \code{FALSE}, the function will return a
+list of chromatograms (if an appropriate parser is available to import the
+files into R). The chromatograms will be returned in \code{matrix} or
+\code{data.frame} format according to the value of {format_out}. If
+\code{return_paths} is \code{TRUE}, the function will return a character
+vector of paths to the newly created files.
 }
 \description{
 Writes \code{xml} batch-files and calls OpenChrom file parsers using a
diff --git a/man/read_shimadzu_lcd.Rd b/man/read_shimadzu_lcd.Rd
index b929954..b480987 100644
--- a/man/read_shimadzu_lcd.Rd
+++ b/man/read_shimadzu_lcd.Rd
@@ -20,6 +20,12 @@ read_shimadzu_lcd(
 
 \item{read_metadata}{Logical. Whether to attach metadata.}
 }
+\value{
+A 3D chromatogram from the PDA stream in \code{matrix} or
+\code{data.frame} format, according to the value of \code{format_out}.
+The chromatograms will be returned in \code{wide} or \code{long} format
+according to the value of \code{data_format}.
+}
 \description{
 Read 3D PDA data stream from 'Shimadzu' LCD files.
 }
diff --git a/man/write_openchrom_batchfile.Rd b/man/write_openchrom_batchfile.Rd
index 75a5ab9..597fea6 100644
--- a/man/write_openchrom_batchfile.Rd
+++ b/man/write_openchrom_batchfile.Rd
@@ -2,7 +2,8 @@
 % Please edit documentation in R/call_openchrom.R
 \name{write_openchrom_batchfile}
 \alias{write_openchrom_batchfile}
-\title{Writes OpenChrom XML batch file}
+\title{Writes OpenChrom XML batch file
+This function is called internally by \code{call_openchrom}.}
 \usage{
 write_openchrom_batchfile(
   files,
@@ -26,6 +27,7 @@ Returns path to newly created xml batch file.
 }
 \description{
 Writes OpenChrom XML batch file
+This function is called internally by \code{call_openchrom}.
 }
 \author{
 Ethan Bass