Merge pull request #12 from mpc-bioinformatics/documentation

Add testing scripts

Author: ItsMeKathy

LICENSE

@@ -1,6 +1,3 @@
 YEAR: 2024
-
 COPYRIGHT HOLDER:  Medizinisches Proteom-Center
-
 ORGANIZATION: Ruhr University Bochum
-

R/generate_graphs_from_quantdata.R

@@ -5,7 +5,7 @@
 #' @param id_cols                  \strong{integer vector} \cr
 #'                                 The columns with ids, e.g. peptide sequences (everything except the peptide ratios)
 #' @param fasta_edgelist           \strong{data.frame} \cr
-#'                                 An edgelist created from the corresponding FASTA file, eg. created with [generate_edgelist()].
+#'                                 An edgelist created from the corresponding FASTA file, eg. created with [bppg::generate_edgelist()].
 #' @param outpath                  \strong{character} \cr
 #'                                 The output path for the results.
 #' @param seq_column               \strong{character} \cr
@@ -20,7 +20,7 @@
 #' @return A list of list of subgraphs
 #' @export
 #'
-#' @seealso [generate_edgelist()]
+#' @seealso [bppg::generate_edgelist()]
 #'
 #' @examples
 #'
@@ -91,24 +91,42 @@ generate_quant_graphs <- function(peptide_ratios,
 
 #' Generate graphs from quantitative peptide-level data
 #'
-#' @param D data set with peptide sequence as first column and peptide intensities in subsequent columns
-#' (e.g. output from bppg::read_MQ_peptidetable)
-#' @param fasta fasta file used for identification of peptides in D
-#' @param outpath bla
-#' @param missed_cleavages bla
-#' @param min_aa bla
-#' @param max_aa bla
-#' @param ... currently not in use
-#' @param id_columns column numbers of D that contain ID information (the rest should contain only peptide intensities, properly normalized)
-#' @param seq_column column name of the peptide sequence
-#' @param collapse_protein_nodes if TRUE protein nodes will be collapsed
-#' @param collapse_peptide_nodes if TRUE, peptide nodes will be collapsed
-#' @param suffix suffix for output files
+#' @param D                        \strong{data.frame} \cr
+#'                                 A data set with peptide sequence as first column
+#'                                 and peptide intensities in subsequent columns
+#'                                 ,e.g. created with [bppg::read_MQ_peptidetable()].
+#' @param fasta                    \strong{list of vector of characters} \cr
+#'                                 A fasta file used for identification of peptides in D,
+#'                                 already read into R by [seqinr::read.fasta()].
+#' @param outpath                  \strong{character} \cr
+#'                                 The output path for the results.
+#' @param missed_cleavages         \strong{integer} \cr
+#'                                 The number of allowed missed cleavages in a peptide.
+#' @param min_aa                   \strong{integer} \cr
+#'                                 The minimum number of amino acids in a peptide.
+#' @param max_aa                   \strong{integer} \cr
+#'                                 The maximum number of amino acids in a peptide.
+#' @param id_columns               \strong{integer vector} \cr
+#'                                 The columns of D that contain ID information (the rest should contain only peptide intensities, properly normalized).
+#' @param seq_column               \strong{character} \cr
+#'                                 The column name of the column with the peptide sequences.
+#' @param collapse_protein_nodes   \strong{logical} \cr
+#'                                 If \code{TRUE}, the protein nodes will be collapsed.
+#' @param collapse_peptide_nodes   \strong{logical} \cr
+#'                                 If \code{TRUE}, the peptide nodes will be collapsed.
+#' @param suffix                   \strong{character} \cr
+#'                                 The suffix for output files.
+#' @param ...                      currently not in use
 #'
-#' @return list of list of graphs
+#' @return A list of list of graphs
 #' @export
 #'
-#' @examples # TODO
+#' @seealso [bppg::read_MQ_peptidetable()], [seqinr::read.fasta()],
+#'          [bppg::generate_quant_graphs()], [bppg::generate_graphs_from_FASTA()]
+#'
+#' @examples
+#'
+
 generate_graphs_from_quant_data <- function(D,
                                             fasta,
                                             outpath = NULL,

R/helpers-Digest.R

@@ -5,22 +5,29 @@
 
 #' Digestion of a single protein sequence.
 #'
-#' @param sequence Protein sequence as character.
-#' @param enzyme "trypsin" (does not cut before proline) or "trypsin.strict" ().
-#' @param missed Maximal number of missed cleavages.
-#' @param warn Print out warnings, e.g. if a protein has no cleavage site.
-#' @param remove_initial_M also return peptides where intital Methionine is removed?
+#' @param sequence           \strong{character} \cr
+#'                           The protein sequence.
+#' @param enzyme             \strong{character} \cr
+#'                           The enzyme used in digestion e.g. "trypsin" (does not cut before proline) or "trypsin.strict" ().
+#' @param missed             \strong{character} \cr
+#'                           The maximal number of missed cleavages.
+#' @param warn               \strong{logical} \cr
+#'                           If \code{TRUE}, warnings will be printed e.g. if a protein has no cleavage site.
+#' @param remove_initial_M   \strong{logical} \cr
+#'                           If \code{TRUE}, the initial methionine will be removed from the peptides.
 #'
-#' @return vector of peptides
+#' @return A vector of peptides.
 #' @export
 #'
+#' @seealso [digest_fasta()]
+#'
 #' @examples
 #' library(seqinr)
 #' file <- system.file("extdata", "2020_01_31_proteome_S_cerevisae.fasta", package = "bppg")
 #' fasta <- seqinr::read.fasta(file = file, seqtype = "AA", as.string = TRUE)
 #'
 #' digested_proteins <- Digest2(fasta[[1]])
-
+#'
 
 Digest2 <- function (sequence, enzyme = "trypsin", missed = 0, warn = TRUE, remove_initial_M = FALSE) {
   seq_vector <- strsplit(sequence, split = "")[[1]]
@@ -131,25 +138,35 @@ Digest2 <- function (sequence, enzyme = "trypsin", missed = 0, warn = TRUE, remo
 
 
 
-#' In silico tryptic digestion of whole FASTA file
+#' In silico tryptic digestion of whole FASTA file.
 #'
-#' @param fasta List of protein sequences (e.g., imported FASTA file by seqinr::read.fasta).
-#' @param missed_cleavages Maximal number of missed cleavages.
-#' @param min_aa Minimal number of amino acids (set to 0 for no filtering).
-#' @param max_aa Maximal number of amino acids (set to Inf for no filtering).
-#' @param ... Additional arguments for Digest2().
+#' @param fasta              \strong{list of vector of characters} \cr
+#'                           A fasta file, already read into R by [seqinr::read.fasta()].
+#' @param missed_cleavages   \strong{integer} \cr
+#'                           The maximal number of missed cleavages.
+#' @param min_aa             \strong{integer} \cr
+#'                           The minimal number of amino acids (set to 0 for no filtering).
+#' @param max_aa             \strong{integer} \cr
+#'                           The maximal number of amino acids (set to Inf for no filtering).
+#' @param ...                Additional arguments for [Digest2()].
 #'
-#' @return List of vectors of peptide sequences, filtered for minimal and maximal number of
-#' amino acids.
+#' @return List of vectors of peptide sequences, filtered for minimal and maximal number of amino acids.
 #' @export
 #'
+#' @seealso [Digest2()]
+#'
 #' @examples
 #' library(seqinr)
 #' file <- system.file("extdata", "uniprot_test.fasta", package = "bppg")
 #' fasta <- seqinr::read.fasta(file = file, seqtype = "AA", as.string = TRUE)
 #' res <- digest_fasta(fasta)
 #'
-digest_fasta <- function(fasta, missed_cleavages = 2, min_aa = 6, max_aa = 50, ...)  {
+
+digest_fasta <- function(fasta,
+                         missed_cleavages = 2,
+                         min_aa = 6,
+                         max_aa = 50,
+                         ...)  {
 
   digested_proteins <- pbapply::pblapply(fasta, function(x) {
     sequ <- x

R/helpers-add_graph_attributes.R

@@ -1,12 +1,15 @@
-#' Adds vertex attributes with uniqueness of peptides and number of unique peptides
-#' for proteins
+#' Adds vertex attributes with uniqueness of peptides and number of unique peptides for proteins.
 #'
-#' @param G graph
+#' @param G \strong{igraph graph object} \cr
+#'          A peptide-protein graph.
 #'
-#' @return graph with 2 additional vertex attributes, uniqueness and nr_unique_peptides
+#' @return A graph with 2 additional vertex attributes, uniqueness and nr_unique_peptides
 #' @export
 #'
-#' @examples # TODO
+#' @seealso [generate_graphs_from_FASTA()], [generate_quant_graphs()], [add_average_pep_ratio()]
+#'
+#' @examples
+
 add_uniqueness_attributes <- function(G) {
 
   ### FALSE = peptide, TRUE = protein
@@ -37,16 +40,20 @@ add_uniqueness_attributes <- function(G) {
 
 
 
-#' Adds average peptide ratios as a attribute to the graphs, if a list of peptide ratios is already present
+#' Adds average peptide ratios as a attribute to the graphs, if a list of peptide ratios is already present.
 #'
-#' @param G graph
-#' @param type not used at the moment. Default is 'geom_mean'
+#' @param G      \strong{igraph graph object} \cr
+#'               A peptide-protein graph.
+#' @param type   \strong{character} \cr
+#'               !NOT USED AT THE MOMENT!
 #'
-#' @return graphs with added attributes
+#' @return A graph with added peptide ratio attributes.
 #' @export
 #'
+#' @seealso [generate_graphs_from_FASTA()], [generate_quant_graphs()], [add_uniqueness_attributes()]
+#'
 #' @examples
-#' # TODO
+
 add_average_pep_ratio <- function(G, type = "geom_mean") {
 
   pep_ratio <- igraph::V(G)$pep_ratio

R/helpers-assign_protein_accessions.R

@@ -1,13 +1,17 @@
 #' Assign protein accessions to a list of peptides, depending on a FASTA file.
 #'
-#' @param sequence vector of peptide sequences
-#' @param fasta_vec names vector of protein sequences from fasta file(s)
+#' @param sequence    \strong{character vector} \cr
+#'                    The peptide sequences.
+#' @param fasta_vec   \strong{character vector} \cr
+#'                    The names vector of protein sequences from fasta file(s).
 #'
-#' @return list of assigned proteins
+#' @return A list of assigned proteins.
 #' @export
 #'
+#' @seealso [generate_graphs_from_FASTA()], [generate_quant_graphs()]
+#'
 #' @examples
-#' ### TODO
+
 assign_protein_accessions <- function(sequence, fasta_vec) {
 
   protein_accessions <- names(fasta_vec)

R/helpers-collapse_nodes_edgelist.R

@@ -1,12 +1,18 @@
 #' Collapsing of peptide and protein nodes of an edgelist.
 #'
-#' @param edgelist edgelist
-#' @param collapse_protein_nodes bla
-#' @param collapse_peptide_nodes bla
+#' @param edgelist                 \strong{data.frame} \cr
+#'                                 An edgelist eg. created with [generate_edgelist()].
+#' @param collapse_protein_nodes   \strong{logical} \cr
+#'                                 If \code{TRUE}, the protein nodes will be collapsed.
+#' @param collapse_peptide_nodes   \strong{logical} \cr
+#'                                 If \code{TRUE}, the peptide nodes will be collapsed.
 #'
-#' @return Edgelist with collapsed protein and peptide nodes
+#' @return An edgelist with collapsed protein and/or peptide nodes.
 #' @export
 #'
+#' @seealso For edgelists with peptide ratios: [collapse_edgelist_quant()] \cr
+#'          [generate_graphs_from_FASTA()], [generate_quant_graphs()], [generate_edgelist()]
+#'
 #' @examples
 #' library(seqinr)
 #' file <- system.file("extdata", "uniprot_test.fasta", package = "bppg")
@@ -50,7 +56,6 @@ collapse_edgelist <- function(edgelist,
 
 
   edgelist2 <- edgelist
-  #keep <- logical(nrow(edgelist2))
 
   pepNodes2 <- pepNodes
   pepNodes2$peptide <- limma::strsplit2(pepNodes2$peptide, ";")[,1]  # first peptide from list

R/helpers-collapse_nodes_edgelist_quant_pepratio.R

@@ -1,12 +1,18 @@
 #' Collapsing of peptide and protein nodes of an edgelist.
 #'
-#' @param edgelist edgelist
-#' @param collapse_protein_nodes bla
-#' @param collapse_peptide_nodes bla
+#' @param edgelist                 \strong{data.frame} \cr
+#'                                 An edgelist  with peptide ratios eg. created with [generate_edgelist()].
+#' @param collapse_protein_nodes   \strong{logical} \cr
+#'                                 If \code{TRUE}, the protein nodes will be collapsed.
+#' @param collapse_peptide_nodes   \strong{logical} \cr
+#'                                 If \code{TRUE}, the peptide nodes will be collapsed.
 #'
-#' @return Edgelist with collapsed protein and peptide nodes
+#' @return An edgelist with collapsed protein and/or peptide nodes.
 #' @export
 #'
+#' @seealso For edgelists without peptide ratios: [collapse_edgelist()] \cr
+#'          [generate_graphs_from_FASTA()], [generate_quant_graphs()], [generate_edgelist()]
+#'
 #' @examples
 #' library(seqinr)
 #' file <- system.file("extdata", "uniprot_test.fasta", package = "bppg")
@@ -18,8 +24,8 @@
 
 
 collapse_edgelist_quant <- function(edgelist,
-                              collapse_protein_nodes = TRUE,
-                              collapse_peptide_nodes = TRUE) {
+                                    collapse_protein_nodes = TRUE,
+                                    collapse_peptide_nodes = TRUE) {
 
   if (!collapse_protein_nodes & !collapse_peptide_nodes) {
     return(edgelist)
@@ -55,7 +61,6 @@ collapse_edgelist_quant <- function(edgelist,
   pepNodes2$peptide <- limma::strsplit2(pepNodes2$peptide, ";")[,1]  # first peptide from list
   edgelist2 <- edgelist[edgelist$peptide %in% pepNodes2$peptide,]
 
-
   protNodes2 <- protNodes
   protNodes2$protein <- limma::strsplit2(protNodes2$protein, ";")[,1]  # first peptide from list
   edgelist3 <- edgelist2[edgelist2$protein %in% protNodes2$protein,]

R/helpers-convertToBipartiteGraph.R

@@ -1,13 +1,15 @@
 #' Conversion of submatrices to subgraphs.
 #'
-#' @param x element of a submatrix list
+#' @param x   \strong{matrix} \cr
+#'            An element of a submatrix list.
 #'
-#' @return graph as igraph object
+#' @return A graph as igraph object.
 #' @export
 #'
 #' @examples
 #' M <- matrix(c(1,0,1,1), nrow = 2, byrow = TRUE)
 #' bppg::convertToBipartiteGraph(M)
+
 convertToBipartiteGraph <- function(x) {
   if ("list" %in% class(x)) { # class list if it contains peptide ratios
     S <- x$X

R/helpers-generate_edgelist.R

@@ -1,11 +1,15 @@
-#' Generate edgelist from list of in silico digested proteins
+#' Generate edgelist from list of in silico digested proteins.
 #'
-#' @param digested_proteins Output from digest_fasta() (List of vectors of peptide sequences)
-#' @param prot_origin origin of the protein (e.g. organism, spike-in/background etc)
+#' @param digested_proteins   \strong{list of vector of characters} \cr
+#'                            The output from [digest_fasta()] (List of vectors of peptide sequences)
+#' @param prot_origin         \strong{vector of characters} \cr
+#'                            origin of the protein (e.g. organism, spike-in/background etc)
 #'
-#' @return edgelist
+#' @return An edgelist.
 #' @export
 #'
+#' @seealso [digest_fasta()]
+#'
 #' @examples
 #' library(seqinr)
 #' file <- system.file("extdata", "uniprot_test.fasta", package = "bppg")
@@ -14,6 +18,7 @@
 #' edgelist <- generate_edgelist(digested_proteins)
 #'
 #'
+
 generate_edgelist <- function(digested_proteins, prot_origin = NULL) {
   #calculate necessary number of edges by counting the peptides belonging to each protein
   mat_length <- sum(lengths(digested_proteins))

R/helpers-generate_graphs_via_edgelist.R

@@ -1,10 +1,13 @@
-#' Generate bipartite peptide-protein graphs from a list of digested proteins via an edgelist
+#' Generate bipartite peptide-protein graphs from a list of digested proteins via an edgelist.
 #'
-#' @param edgelist Output from generate_edgelist (edgelist)
+#' @param edgelist   \strong{data.frame} \cr
+#'                   An edgelist, output from [generate_edgelist()].
 #'
-#' @return List of subgraphs as igraph objects.
+#' @return A list of subgraphs as igraph objects.
 #' @export
 #'
+#' @seealso [generate_edgelist()]
+#'
 #' @examples
 #' ### TODO: example takes longer than 5s
 #' library(seqinr)