Merge pull request #50 from aim-rsf/doc_data

add documentation for package data

R/data-domain_list.R

@@ -0,0 +1,16 @@
+#' List of domains
+#'
+#' A simplified list of domains, to demo the function domain_mapping.R \cr \cr
+#' This data was created with these two steps:
+#' \enumerate{
+#'  \item \code{domain_list <- read.csv('browseMetadata/data-raw/domain_list_demo.csv')}
+#'  \item \code{usethis::use_data(domain_list)}
+#' }
+#' @docType data
+#
+#' @usage data(domain_list)
+#'
+#' @format A data frame with 5 rows and 1 column
+#' 
+#' @source The csv was manually created
+"domain_list"

R/data-json_metadata.R

@@ -0,0 +1,20 @@
+#' Json metadata file
+#'
+#' Example metadata for a health dataset, to demo the function domain_mapping.R \cr \cr
+#' This data was created with these five steps:
+#' \enumerate{
+#'   \item Go to https://modelcatalogue.cs.ox.ac.uk/hdruk_live/#/catalogue/dataModel/17e86f3f-ec29-4c8e-9efc-8793a74b107d 
+#'   \item Download json metadata file by selecting the 'Export as JSON' option on the download button
+#'   \item \code{install.packages("rjson")}
+#'   \item \code{json_metadata <- rjson::fromJSON(file = '/browseMetadata/data-raw/maternity_indicators_dataset_(mids)_20240105T132210.json')}
+#'   \item \code{usethis::use_data(json_metadata)}
+#' }
+#'
+#' @docType data
+#
+#' @usage data(json_metadata)
+#'
+#' @format Nested lists
+#'
+#' @source https://modelcatalogue.cs.ox.ac.uk/hdruk_live/#/catalogue/dataModel/17e86f3f-ec29-4c8e-9efc-8793a74b107d
+"json_metadata"

R/domain_mapping.R

@@ -1,13 +1,13 @@
 #' domain_mapping
 #'
-#'This function will read in the metadata file for a chosen dataset, loop through all the variables, and ask the user to catergorise/label each variable as belonging to one or more domains.
-#'The domains will appear in the Plots tab and dataset information will be printed to the R console, for the user's reference in making these categorisations. 
+#'This function will read in the metadata file for a chosen dataset, loop through all the variables, and ask the user to catergorise/label each variable as belonging to one or more domains.\cr \cr
+#'The domains will appear in the Plots tab and dataset information will be printed to the R console, for the user's reference in making these categorisations. \cr \cr
 #'A log file will be saved with the catergorisations made. 
 #'To speed up this process, some auto-categorisations will be made by the function for commonly occurring variables;
-#'these auto-categorisations should be verified by the user by checking the csv log file. 
+#'these auto-categorisations should be verified by the user by checking the csv log file. \cr \cr
 #'Example inputs are provided within the package data, for the user to run this function in a demo mode.
-#'@param json_file The metadata file. This should be downloaded from the metadata catalogue as a json file.
-#'@param domain_file The domain list file. This should be a csv file created by the user, with each domain listed on a separate line within quotation marks.
+#'@param json_file The metadata file. This should be downloaded from the metadata catalogue as a json file. See 'data-raw/maternity_indicators_dataset_(mids)_20240105T132210.json' for an example download.
+#'@param domain_file The domain list file. This should be a csv file created by the user, with each domain listed on a separate line. See 'data-raw/domain_list_demo.csv' for a template.
 #'@return The function will return a log file with the mapping between dataset variables and domains, alongside details about the dataset.
 #'@examples
 #'# Run in demo mode by providing no inputs: domain_mapping()
@@ -28,8 +28,8 @@ domain_mapping <- function(json_file= NULL,domain_file= NULL) {
     # Load data: Check if demo data should be used
   if (is.null(json_file) && is.null(domain_file)) {
     # If both json_file and domain_file are NULL, use demo data
-    meta_json <- get('json_metdata')
-    domains <- get('domains_list')
+    meta_json <- get('json_metadata')
+    domains <- get('domain_list')
     DomainListDesc <- 'DemoList'
     cat('\n')
     cli_alert_info('Running domain_mapping in demo mode using package data files')

data-raw/domain_list_demo.csv

@@ -0,0 +1,6 @@
+Domain_Name
+"Socioeconomic factors"
+"Location"
+"Education"
+"Health"
+"Parental Information"