R/help.R

In metrumresearchgroup/yspec: Data Specification for Pharmacometrics

ys_export_impl <- function(path,overwrite=FALSE) {
  path <- normalPath(path, mustWork=FALSE)
  if(!overwrite) {
    if(dir.exists(path)) {
      stop(
        "The output directory already exists; remove it or use ", 
        "overwrite=TRUE", call.=FALSE
      )
    }
  }
  if(!dir.exists(path)) dir.create(path)
  cp <- function(...) {
    file.copy(system.file(..., package = "yspec"), path, overwrite=overwrite)  
  }
  a <- cp("internal",  "analysis1.yml")
  b <- cp("internal",  "ysdb_internal.yml")
  c <- cp("internal",  "ys_get_assets.md")
  d <- cp("internal",  "analysis1.csv")
  e <- cp("internal",  "ys_example.Rmd")
  f <- cp("reference", "specification.md")
  if(!all(a,b,c,d,e)) {
    warning("Some assets were not exported.", call.=FALSE)  
  }
  return(invisible(path))
}


ys_view_impl <- function(dir,file) {
  file <- system.file(dir,file, package = "yspec")
  tmp <- file.path(tempdir(),paste0("view_",basename(file)))
  file.copy(file,tmp)
  if(requireNamespace("rstudioapi")) {
    if(rstudioapi::isAvailable()) {
      rstudioapi::navigateToFile(tmp)
    } else {
      cat(readLines(tmp),sep="\n")
    }
  } else {
    file.show(file)  
  }
}

# nocov start
ys_help_setup <- function(libname, pkgname) {
  spec <- function(...) {
    ys_load(file(), ...)
  }
  file <- function() system.file("internal", "analysis1.yml", package = "yspec")
  data <- function() {
    read.csv(
      file = csv(),
      na.strings = '.', as.is=TRUE, stringsAsFactors=FALSE
    )
  }
  csv  <- function() system.file("internal", "analysis1.csv", package = "yspec")
  proj <- function() {
    ys_project(
      load_spec_ex("DEM104101F_PK.yml"), 
      load_spec_ex("DEM104101F_PKPD.yml"),
      load_spec_ex("DEM104101F_AE.yml")
    )
  }
  yaml <- function() {
    ys_view_impl("internal", "analysis1.yml")  
  }
  ref <- function()  {
    ys_view_impl("reference", "reference.md") 
  }
  db <- function() {
    ys_view_impl("internal", "ysdb_internal.yml")    
  }
  example <- function() {
    ys_view_impl("internal", "ys_example.Rmd") 
  }
  export <- function(path,...) {
    ys_export_impl(path,...)  
  }
  return(structure(environment(),class="yhelp"))
}
# nocov end

##' @param ... not used 
##' @rdname ys_help
##' @export
print.yhelp <- function(...) {
  fmt <- function(x,n=22,flag="-") {
    formatC(x,width=n,flag=flag)
  }
  rhs <- green $ italic
  cat("\n")
  cat(blue(fmt("CODE:")),blue("# DESCRIPTION:"),"\n")
  cat((fmt("ys_help$spec()")),rhs("# analysis1 yspec object"),"\n")
  cat((fmt("ys_help$file()")),rhs("# analysis1.yml file path"),"\n")
  cat((fmt("ys_help$data()")),rhs("# analysis1 example data set"),"\n")  
  cat((fmt("ys_help$csv()")),rhs("# analysis1.csv file path"),"\n")
  cat((fmt("ys_help$proj()")),rhs("# example project object"),"\n")
  cat((fmt("ys_help$yaml()")),rhs("# view analysis1 yaml file"),"\n")
  cat((fmt("ys_help$ref()")),rhs("# view syntax reference for yaml file"),"\n")
  cat((fmt("ys_help$db()")),green("# view internal lookup databases"),"\n")
  cat((fmt("ys_help$example()")),rhs("# view Rmd file with yspec workflow"),"\n")
  cat((fmt("ys_help$export('out')")),rhs("# export example package assets"),"\n")
  cat("\n")
  return(invisible(NULL))
}

##' yspec help object
##' 
##' `ys_help` is an environment containing functions that can be called to 
##' provide information and examples for how yspec works.  `specification()`, 
##' `internal_db()` and `analysis1()` will open up markdown or yaml files
##' using [rstudioapi::navigateToFile] if that package is installed and 
##' [file.show] in case it is not.
##' 
##' @details
##' - `spec()` generates the analysis1 yspec object
##' - `file()` the file name and path of an example yspec file
##' - `data()` is a function that generates a data set that can be checked 
##'   against `spec()`
##' - `csv()` is the file name (and path) to the data set generated by `data()`
##' - `proj()` generates a project object that can be rendered into a document
##' - `yaml()` shows the analysis1 yaml file
##' - `ref()` shows the syntax reference for yaml file
##' - `db()` shows the internal column lookup data base
##' - `example()` shows and Rmd file showing yspec workflow
##' - `export(path)` export internal assets that can be used for exploration
##'   in the local filesystem; you must supply the location (`path`) to 
##'   where the content is to be exported; there is also an `overwrite` argument
##'   that will allow overwriting an existing folder (use with care!)
##'
##' @examples
##' spec <- ys_help$spec()
##' 
##' file <- ys_help$file()
##' 
##' data <- ys_help$data()  
##' 
##' csv  <- ys_help$csv()
##' 
##' \dontrun{
##' proj <- ys_help$proj()
##' 
##' ref <- ys_help$ref()
##' 
##' db <- ys_help$db()
##' 
##' ex <- ys_help$example()
##' 
##' path <- ys_help$export("expath")
##' 
##' }
##' 
##' @md
##' @export
ys_help <- ys_help_setup()