Improve function documentation

GaryBAYLOR commented 2 years ago

The documentation for the functions (Rd files) needs to be improved. The issues I can identify include

\title{}: Be consistent in title capitalization by either capitalizing the first word or all words in the title. As an example, the current title for the function bound_propensity is Bound Generalized Propensity Score, while the title for the function calc_additive_ate is Evaluate mixture rules found during the rpart decision tree process
\description{}: Do not simply repeat the title but provide a short description of what the function(s) do(es) (one paragraph, a few lines only)
\value{}: Finish TODOs
\examples{}: Add one or more examples to demo how to use each function. It is also used for the purpose of function testing purpose. Please refer to https://cran.r-project.org/doc/manuals/R-exts.html#Rd-format for more details

lightning-auriga commented 2 years ago

I concur about the above. I'll add that checking the R CMD CHECK output is helpful to spot some obvious ones, like missing parameter documentation. The github action unfortunately only errors on actual errors, whereas the warnings and notes can be very helpful.

blind-contours commented 2 years ago

Current R CMD CHECK passes with no notes, warnings or errors. All documentation has been updated. There are some areas I would like to give better detail on but all functions exported to the user have detailed documentation.

GaryBAYLOR commented 2 years ago

A large number of functions exported to users miss the documentation for returned value section, see https://github.com/blind-contours/CVtreeMLE/issues/18

GaryBAYLOR commented 2 years ago

Running R CMD CHECK does return errors on my end. Please refer to https://github.com/blind-contours/CVtreeMLE/issues/19 and https://github.com/blind-contours/CVtreeMLE/issues/20 for more details.

(base) mymacs-iMac:CVtreeMLE-main-2 mymac$ ?build
bash: ?build: command not found
(base) mymacs-iMac:CVtreeMLE-main-2 mymac$ R CMD CHECK /Users/mymac/Downloads/CVtreeMLE_0.0.0.9000.tar.gz
* using log directory ‘/Users/mymac/Downloads/CVtreeMLE-main-2/CVtreeMLE.Rcheck’
* using R version 4.2.1 (2022-06-23)
* using platform: x86_64-apple-darwin17.0 (64-bit)
* using session charset: UTF-8
* checking for file ‘CVtreeMLE/DESCRIPTION’ ... OK
* this is package ‘CVtreeMLE’ version ‘0.0.0.9000’
* package encoding: UTF-8
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... WARNING
Found the following files with non-portable file names:
  man/figures/README-plot sim_mixture_results-1.png
  vignettes/man/figures/vignette-plot sim_mixture_results-1.png
These are not fully portable file names.
See section ‘Package structure’ in the ‘Writing R Extensions’ manual.
* checking for sufficient/correct file permissions ... OK
* checking whether package ‘CVtreeMLE’ can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking DESCRIPTION meta-information ... WARNING
Invalid license file pointers: LICENSE
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking dependencies in R code ... NOTE
Namespaces in Imports field not imported from:
  ‘pre’ ‘sl3’
  All declared Imports should be used.
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... NOTE
CVtreeMLE : <anonymous>: no visible binding for global variable
  ‘h_aw_trunc_lvl’
create_sls: no visible binding for global variable ‘Lrnr_mean’
create_sls: no visible binding for global variable ‘Lrnr_ranger’
create_sls: no visible global function definition for ‘make_learner’
create_sls: no visible binding for global variable ‘Lrnr_glm’
create_sls: no visible binding for global variable ‘Lrnr_glmnet’
create_sls: no visible binding for global variable ‘Lrnr_xgboost’
create_sls: no visible binding for global variable ‘Stack’
create_sls: no visible binding for global variable ‘Lrnr_glmtree’
est_comb_exposure: no visible global function definition for
  ‘make_sl3_Task’
est_comb_exposure: no visible binding for global variable
  ‘Lrnr_cv_selector’
est_comb_exposure: no visible binding for global variable
  ‘loss_squared_error’
est_comb_exposure: no visible binding for global variable ‘Lrnr_sl’
est_marg_nuisance_params: no visible global function definition for
  ‘make_sl3_Task’
est_marg_nuisance_params: no visible binding for global variable
  ‘Lrnr_cv_selector’
est_marg_nuisance_params: no visible binding for global variable
  ‘loss_loglik_binomial’
est_marg_nuisance_params: no visible binding for global variable
  ‘Lrnr_sl’
est_marg_nuisance_params: no visible binding for global variable
  ‘loss_squared_error’
est_mix_nuisance_params: no visible global function definition for
  ‘make_sl3_Task’
est_mix_nuisance_params: no visible binding for global variable
  ‘Lrnr_cv_selector’
est_mix_nuisance_params: no visible binding for global variable
  ‘loss_loglik_binomial’
est_mix_nuisance_params: no visible binding for global variable
  ‘Lrnr_sl’
est_mix_nuisance_params: no visible binding for global variable
  ‘loss_squared_error’
fit_marg_rule_backfitting: no visible global function definition for
  ‘make_sl3_Task’
fit_marg_rule_backfitting: no visible binding for global variable
  ‘Lrnr_cv_selector’
fit_marg_rule_backfitting: no visible binding for global variable
  ‘loss_squared_error’
fit_marg_rule_backfitting: no visible binding for global variable
  ‘Lrnr_sl’
fit_marg_rule_backfitting: no visible binding for global variable
  ‘sl3_Task’
fit_mix_rule_backfitting: no visible global function definition for
  ‘make_sl3_Task’
fit_mix_rule_backfitting: no visible binding for global variable
  ‘Lrnr_cv_selector’
fit_mix_rule_backfitting: no visible binding for global variable
  ‘loss_squared_error’
fit_mix_rule_backfitting: no visible binding for global variable
  ‘Lrnr_sl’
fit_mix_rule_backfitting: no visible global function definition for
  ‘pre’
fit_mix_rule_backfitting: no visible global function definition for
  ‘maxdepth_sampler’
fit_mix_rule_backfitting: no visible binding for global variable
  ‘sl3_Task’
Undefined global functions or variables:
  Lrnr_cv_selector Lrnr_glm Lrnr_glmnet Lrnr_glmtree Lrnr_mean
  Lrnr_ranger Lrnr_sl Lrnr_xgboost Stack h_aw_trunc_lvl
  loss_loglik_binomial loss_squared_error make_learner make_sl3_Task
  maxdepth_sampler pre sl3_Task
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... WARNING
Documented arguments not in \usage in documentation object 'CVtreeMLE':
  ‘h_aw_trunc_lvl’

Functions with \usage entries need to have the appropriate \alias
entries, and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.
See chapter ‘Writing R documentation files’ in the ‘Writing R
Extensions’ manual.
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking contents of ‘data’ directory ... OK
* checking data for non-ASCII characters ... OK
* checking LazyData ... OK
* checking data for ASCII and uncompressed saves ... OK
* checking files in ‘vignettes’ ... WARNING
Files in the 'vignettes' directory but no files in 'inst/doc':
  ‘NIEHS_interactions.png’, ‘intro_CVtreeMLE.Rmd’,
    ‘man/figures/vignette-plot sim_mixture_results-1.png’
* checking examples ... ERROR
Running examples in ‘CVtreeMLE-Ex.R’ failed
The error most likely occurred in:

> ### Name: CVtreeMLE
> ### Title: Fit ensemble decision trees to a vector of exposures and use
> ###   targeted maximum likelihood estimation to determine the average
> ###   treatment effect in each leaf of best fitting tree
> ### Aliases: CVtreeMLE
> 
> ### ** Examples
> 
> n <- 800
> p <- 4
> x <- matrix(rnorm(n * p), n, p)
> colnames(x) <- c("A1", "A2", "W1", "W2")
> y_prob <- plogis(3 * sin(x[, 1]) + sin(x[, 2]), sin(x[, 4]))
> Y <- rbinom(n = n, size = 1, prob = y_prob)
> data <- as.data.frame(cbind(x,Y))
> 
> CVtreeMLE_fit <- CVtreeMLE(data = data,
+                           w = c("W1", "W2"),
+                           a = c("A1", "A2"),
+                           y = "Y",
+                           family = "binomial",
+                           parallel = FALSE,
+                           n_folds = 2)
Error in create_sls() : object 'Lrnr_mean' not found
Calls: CVtreeMLE -> create_sls
Execution halted
* checking for unstated dependencies in ‘tests’ ... OK
* checking tests ...
  Running ‘testthat.R’
 ERROR
Running the tests in ‘tests/testthat.R’ failed.
Last 13 lines of output:
  Backtrace:
      ▆
   1. └─CVtreeMLE::fit_mix_rule_backfitting(...) at test_mixture_thresholds_eight_beta.R:19:0
  ── Error (test_mixture_thresholds_one_beta.R:16:1): (code run outside of `test_that()`) ──
  Error in `pre(formula, data = at, family = "gaussian", use.grad = FALSE, 
      tree.unbiased = TRUE, removecomplements = TRUE, removeduplicates = TRUE, 
      maxdepth = maxdepth_sampler(), sampfrac = min(1, (11 * sqrt(dim(at)[1]) + 
          1)/dim(at)[1]), nfolds = 10, par.final = FALSE, par.init = FALSE)`: could not find function "pre"
  Backtrace:
      ▆
   1. └─CVtreeMLE::fit_mix_rule_backfitting(...) at test_mixture_thresholds_one_beta.R:16:0

  [ FAIL 5 | WARN 1 | SKIP 0 | PASS 2 ]
  Error: Test failures
  Execution halted
* checking for unstated dependencies in vignettes ... OK
* checking package vignettes in ‘inst/doc’ ... WARNING
Directory 'inst/doc' does not exist.
Package vignette without corresponding single PDF/HTML:
   ‘intro_CVtreeMLE.Rmd’

* checking running R code from vignettes ...
  ‘intro_CVtreeMLE.Rmd’ using ‘UTF-8’... OK
 NONE
* checking re-building of vignette outputs ... ERROR
Error(s) in re-building vignettes:
  ...
--- re-building ‘intro_CVtreeMLE.Rmd’ using rmarkdown
Quitting from lines 114-127 (intro_CVtreeMLE.Rmd) 
Error: processing vignette 'intro_CVtreeMLE.Rmd' failed with diagnostics:
could not find function "make_sl3_Task"
--- failed re-building ‘intro_CVtreeMLE.Rmd’

SUMMARY: processing the following file failed:
  ‘intro_CVtreeMLE.Rmd’

Error: Vignette re-building failed.
Execution halted

* checking PDF version of manual ... OK
* DONE

Status: 3 ERRORs, 5 WARNINGs, 2 NOTEs
See
  ‘/Users/mymac/Downloads/CVtreeMLE-main-2/CVtreeMLE.Rcheck/00check.log’
for details.

blind-contours commented 2 years ago

I made a mistake in the last updates where I moved sl3, pre, and partykit out of the namespace to avoid bloat, which then requires the users to library in the packages and as such, in the package, to specify the package functions using ::. I'v updated all this and now the package should pass check with only 3 small warnings which I'm working on.

blind-contours / CVtreeMLE

Improve function documentation #4