Document a Dataset — document_dataset • noclocksr

This function generates a roxygen2 skeleton for documenting a dataset.

Usage

document_dataset(
  data_obj,
  name = "DATASET_NAME",
  description = "DATASET_DESCRIPTION",
  source = "DATASET_SOURCE",
  col_types = purrr::map_chr(data_obj, typeof),
  col_descs = rep("COLUMN_DESCRIPTION", length(names(data_obj))),
  file = fs::path("R", "data.R"),
  append = TRUE,
  overwrite = !append,
  ...
)

Arguments

data_obj: (Required) The dataset to document. Should be a data.frame or tibble.
name: (Optional) The name of the dataset. Default is DATASET_NAME if not provided.
description: (Optional) A description of the dataset. Default is DATASET_DESCRIPTION if not provided.
source: (Optional) The source of the dataset. Default is DATASET_SOURCE if not provided.
col_types: (Optional) A character vector of column types. Default is the types of the columns in the dataset.
col_descs: (Optional) A character vector of column descriptions. Default is COLUMN_DESCRIPTION for each column.
file: (Optional) The file to write the documentation to. Default is R/pkg_data.R.
append: (Optional) Append to the file if it exists. Default is TRUE. If FALSE, the file will be overwritten, unless overwrite is TRUE, then the function does not write to a file.
overwrite: (Optional) Overwrite the file if it exists. Default is FALSE.
...: Additional arguments

Value

Invisibly returns a character string with the roxygen2 documentation skeleton for the dataset.

Examples

# Create a sample dataset
data(mtcars)

# Temporary file for testing
temp_file <- fs::path_temp("test_mtcars.R")

# Call the function
document_dataset(
  mtcars,
  name = "mtcars",
  description = "Motor Trend Car Road Tests",
  source = "Henderson and Velleman (1981)",
  col_descs = c(
    "Miles per Gallon",
    "Number of Cylinders",
    "Displacement",
    "Horsepower",
    "Rear Axle Ratio",
    "Weight (per 1000 lbs)",
    "1/4 mile time",
    "V/S",
    "Transmission (0 = automatic, 1 = manual)",
    "Number of forward gears",
    "Number of carburetors"
  ),
  file = temp_file,
  overwrite = TRUE
)

# View the contents of the file
readLines(temp_file)
#>  [1] "#' mtcars"                                                                 
#>  [2] "#'"                                                                        
#>  [3] "#' @description"                                                           
#>  [4] "#' Motor Trend Car Road Tests"                                             
#>  [5] "#'"                                                                        
#>  [6] "#' @source"                                                                
#>  [7] "#' Henderson and Velleman (1981)"                                          
#>  [8] "#'"                                                                        
#>  [9] "#' @format A data frame with 32 rows and 11 columns:"                      
#> [10] "#' \\describe{"                                                            
#> [11] "#'   \\item{\\code{mpg}}{double. Miles per Gallon.}"                       
#> [12] "#'   \\item{\\code{cyl}}{double. Number of Cylinders.}"                    
#> [13] "#'   \\item{\\code{disp}}{double. Displacement.}"                          
#> [14] "#'   \\item{\\code{hp}}{double. Horsepower.}"                              
#> [15] "#'   \\item{\\code{drat}}{double. Rear Axle Ratio.}"                       
#> [16] "#'   \\item{\\code{wt}}{double. Weight (per 1000 lbs).}"                   
#> [17] "#'   \\item{\\code{qsec}}{double. 1/4 mile time.}"                         
#> [18] "#'   \\item{\\code{vs}}{double. V/S.}"                                     
#> [19] "#'   \\item{\\code{am}}{double. Transmission (0 = automatic, 1 = manual).}"
#> [20] "#'   \\item{\\code{gear}}{double. Number of forward gears.}"               
#> [21] "#'   \\item{\\code{carb}}{double. Number of carburetors.}"                 
#> [22] "#'}"                                                                       
#> [23] "\"mtcars\""                                                                
#> [24] ""