Volcalc functions

[Aariq]

This is a thread to discuss what the eventual user interface of volcalc should look like. How many functions should be available to the user? What should their names be? What arguments should they have? What should the defaults be for those arguments (if any)?

[Aariq]

In terms of functions, here's what I'm imagining. calc_vol() is still the main function users interact with, but it no longer downloads anything or accesses the KEGG API at all. Instead, it takes as input a path to a .mol file or a SMILES or InChI string (more on how to do that well in a separate discussion). Chemical structures are then translated to mol objects or the .mol file is read in. The mol object is passed to get_fx_groups(), which no longer takes KEGG identifiers and no longer queries KEGG for molecular weight and formula (#25). The output of get_fx_groups() is passed to a new function, simpol(), which does all the calculations and outputs a tibble (currently this code is in calc_vol() and it could stay there, but right now I like the idea of having it split off mostly for the sake of more space and organization for documentation). One of the columns in the returned tibble should be the input—either file paths or the SMILES identifiers. calc_vol()'s job is to vectorize all this, so the input can be multiple file paths or multiple SMILES identifiers, and to tidy the resulting tibble depending on what the user wants returned back.

All of the KEGG related functionality gets put in kegg_get() which takes either compound_id or pathway_id and returns a tibble with pathway_id (if used), compound_id, and a column of file paths to the corresponding .mol files that can be used as input to calc_vol(). The resulting output can be joined to the output from calc_vol() also.

I think this means that calc_pathway_vol() can be removed. We can use a vignette to demonstrate querying an entire KEGG pathway with kegg_get() and calc_vol() and demonstrate joining the two resulting tibbles together.

[KristinaRiemer]

Really basic initial diagram of function layout:

[Aariq]

This is something we can try to include in the README eventually

[Aariq]

Sketch of functions and their arguments (I'm sure I'm missing some things, but this is the rough idea)

#' @param input a vector of either 1) file paths to .mol files, SMILES strings, InChI strings
#' @param from indicates which type `input` is
#' @param return_fx_groups should the functional groups be in the output?
#' @param return_calc_steps should the intermediate calculations be in the output?
#' @returns tibble with one row for each element of `input`
calc_vol <- function(input,
                     from = c("mol_path", "smiles", "inchi"),
                     return_fx_groups = FALSE,
                     return_calc_steps = FALSE) {
  
#1 if from == mol_path read in mol_path to SDFset object
  # else translate from `from` to SDFset
  
#2 call get_fx_groups()

#3 call calc_simpol()
  
#4 wrangle output according to optional args
    
}

#' @param SDFset object created by ChemmineR::read.SDFset()
#' @returns tibble of functional group counts
get_fx_groups <- function(SDFset) {
  
}

#' @param fx_groups tibble output by get_fx_groups()
#' @returns `fx_groups` appended with columns for volatility calculations
calc_simpol <- function(fx_groups) {
  
}

#' @param compound_ids character vector of compound IDs
#' @param pathway_ids character vector of KEGG pathway IDs
#' @param path where to put the output
#' @details You can only supply either `compound_ids` OR `pathway_ids`, not both
#' 
#' @returns a tibble with 2 or 3 columns: `compound_ids`, `pathway_ids`, and
#'   `mol_path` containing file paths to downloaded .mol files
#' 
get_mol_kegg <- function(compound_ids, pathway_ids, path){
  
}