JOSS Review: Functionality documentation

[njtierney]

RE:

Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?

The documentation is currently not satisfactory to a research standard. In particular I think three things need to be addressed:

• [ ] Function arguments must be specified when giving examples
• [ ] A package website should be generated with pkgdown - See "get started" for details on how to do this
• [ ] Function argument types should be specified.

Function arguments must be specified when giving examples

Currently the arguments are specified in the files: design_ord.R(), op_fwer_cont(), op_fwer_ord(), and op_power_surv() do not have named arguments, e.g.,

#' @examples
#' op_power_surv(20, 0.05, 0.1, 4, c(1 / 2, 1), 1, 0.74, 12, 40, 20, 1, 0, 12)

A package website should be generated with pkgdown

A package website is now quite simple to create, following instructions from "get started" the steps are:

# Run once to configure package to use pkgdown
usethis::use_pkgdown()
# Run to build the website
pkgdown::build_site()
# renders the website when code is pushed to github
usethis::use_pkgdown_github_pages()

This creates a great landing place for the package - it is nicer to read than the standard CRAN PDF manual.

Function argument types should be specified

Function arguments are currently written as:

#' @param delta0 Standardized effect size in ineffective arm.
#' @param delta1 Standardized effect size in effective arm.
#' @param alpha Type I error.
#' @param beta Type II error.
#' @param K Number of treatment arms.
#' @param frac Vector of fractions for information time at each look.

The type of information should be specified, e.g., is it numeric? What sort of range of values? Is it a vector, or a scalar (just 1 value?)

[Tpatni123]

Function arguments must be specified when giving examples

I will add this.

A package website should be generated with pkgdown

Thank you for providing this information but I think that the vignette is sufficient considering the requirements of the journal.

Function argument types should be specified

I have mentioned that when the argument is a vector(e.g. I have mentioned that the frac argument is a vector in the roxygen skeleton but I will check others just to be sure) and regarding the type of variable and other things, people using such specialized package must be cognizant of arguments like alpha and beta which are very common terms in such settings. So, respectfully, I think the current format is fine.

[njtierney]

Thank you for providing this information but I think that the vignette is sufficient considering the requirements of the journal.

It is your decision at the end of the day - however I do believe that the paper.md converted to a vignette should be provided in the package.

I have mentioned that when the argument is a vector(e.g. I have mentioned that the frac argument is a vector in the roxygen skeleton but I will check others just to be sure) and regarding the type of variable and other things, people using such specialized package must be cognizant of arguments like alpha and beta which are very common terms in such settings. So, respectfully, I think the current format is fine.

The JOSS Journal guidelines state:

Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?

While I can appreciate that there might be assumptions we could make about the audience, I think it is worth spending the time to document the types of arguments you expect the users to use. Whilst it might appear obvious to you what the arguments should be, I do not consider the current description to meet satisfactory levels of scientific software. I suggest providing a couple of words with each argument to state the type of data you require as I suggested above.

[Tpatni719]

I have included the type of argument for the functions and indicated when it is a vector. Its not plausible to provide range for certain arguments because e.g. the effect size can be of any value and is based on the discretion of the investigator. Sometimes, they push the parameters beyond the nominal levels just to see how the operating characteristics of trial changes.

[njtierney]

Thanks for this!