documenting a list of data frames with roxygen2

Question

I am trying to document some data I append in my package.

I have a list with 3 elements (data.frames) and each of this data frames has some columns. I wonder how to document this hierarchical structure (list -> data.frame -> column) within roxygen2. The examples show always only one layer, data.frame and then column names. Here is a minimal example with two data frames in a list.

list(
  names=data.frame(id=1:10, a=letters[1:10]),
  values=data.frame(id=rep(1:10, each=10), values=runif(100))
)

In my list, all three data.frames are connected with an id column, so they are kind of related, but I don't want to put them into one data frame, because of saving memory.

Any suggestions are welcome.

EDIT

I tried to add segments to my documentation, but this does not seem to work

#' List with group information for the test data set
#'
#' This dataset is a list with 2 data.tables (proteins, timepoint). 
#' It has a common id column in all data.tables.
#'
#' \strong{proteins}
#' @format A data frame with 5458 rows and 3 columns
#' \describe{
#'   \item{id}{unique group id}
#'   \item{names}{individual names}
#'   \item{other names}{other names}
#' }
#'
#' \strong{timepoint}
#' @format A data frame with 80248 rows and 5 columns
#' \describe{
#'   \item{id}{unique group id}
#'   \item{timepoint}{individual timepoint}
#'   \item{imputed_mean}{mean value including imputed values}
#'   \item{measured_mean}{mean value without imputing (contains NAs)}
#'   \item{value_count}{number of measured values within the replicates}
#' }
'pg_test'

The output looks like it can only handle 1 @format parameter.

Any other suggestion?

Answer 1

Actually, I just figured out a solution, as long nobody else has a better suggestion...

#' List with group information for the test data set
#'
#' This dataset is a list with 2 data.tables (proteins, timepoint). 
#' It has a common id column in all data.tables.
#'
#' @format 
#' \enumerate{
#' \item \strong{proteins} A data frame with 5458 rows and 3 columns
#' \describe{
#'   \item{id}{unique group id}
#'   \item{names}{individual names}
#'   \item{other names}{other names}
#' }
#'
#' \item \strong{timepoint} A data frame with 80248 rows and 5 columns
#' \describe{
#'   \item{id}{unique group id}
#'   \item{timepoint}{individual timepoint}
#'   \item{imputed_mean}{mean value including imputed values}
#'   \item{measured_mean}{mean value without imputing (contains NAs)}
#'   \item{value_count}{number of measured values within the replicates}
#' }
#' }
'pg_test'

Could also be solved with

#' \describe{
#'   \item{One}{First item}
....

instead of \enumerate I guess. But this solution works for now.