[JOSS REVIEW] Example usage

[yjunechoe]

The Example usage checklist asks:

Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).

I notice that you have since added example data such that your example lines like this can now run. This is a good improvement.

However, I don't think it's appropriate for every function to get a corresponding example data of an input. They do tell the users what the input should look like, but users need additional context about how you got those inputs in the first place, especially if the input to one function is the output of another function from the package. In other words, I would like to see changes to the fact that examples are one-liners, to make examples more user friendly.

Take canwegetalltheallelesfromonecross() for example:

#' @examples
#' canwegetalltheallelesfromonecross(x=examplefertilizeoutput,desiredvector=exampledesiredvec)

It seems to me that examplefertilizeoutput is a specific kind of a data frame object that is produced by another function from the package fertilize(), which is in turn derived from spermandeggs(), then in turn compilegametes(), and so on. So really, what the user would want to see from examples is something more like:

#' @examples
#' x <- compilegametes(...)
#' y <- spermandeggs(x, ...)
#' z <- fertilize(y, ...) 
#' canwegetalltheallelesfromonecross(z, exampledesiredvec)

So that they can trace the history of the inputs to canwegetalltheallelesfromonecross() and understand where canwegetalltheallelesfromonecross() fits in to the rest of the workflow. Note that it is perfectly fine and in fact encouraged to have other functions be used in a function's examples, especially the function comes in at a later part of a larger workflow.

Additionally, if exampledesiredvec is something the user should manually specify themselves, it'd be more beneficial to demonstrate that process in the example. So instead of defining exampledesiredvec internal to the package and exporting it, please do this inside the example so that it's visible to the user:

exampledesiredvec <- c("homopos", "homopos", "homopos", "homopos")

So combined, the re-write of examples for canwegetalltheallelesfromonecross() would look something like:

#' @examples
#' # We start with a basic set up where ...
#' x <- compilegametes(...)
#' y <- spermandeggs(x, ...)
#' z <- fertilize(y, ...) 
#'
#' # To determine XYZ, we define a vector of ...
#' exampledesiredvec <- c("homopos", "homopos", "homopos", "homopos")
#'
#' # Pass the output of `fertilize()` and the desired vector to get back information about ...
#' canwegetalltheallelesfromonecross(z, exampledesiredvec)

Note the generous use of spacing and comments. Examples should be readable from a glance, and should showcase the function alongside the environment where you expect it to be used.

[sportiellomike]

I am working on these issues and will tag you when resolved. As you mentioned, this will take some time. I appreciate your patience.

[sportiellomike]

Fixed all of this.