diff --git a/R/collect_inputs.R b/R/collect_inputs.R index cc38b57..c5729d7 100644 --- a/R/collect_inputs.R +++ b/R/collect_inputs.R @@ -1,6 +1,6 @@ #' load_data #' -#' This function is called within the map_metadata function. \cr \cr +#' Internal Function: This function is called within the map_metadata function. \cr \cr #' It collects the inputs needed for the map_metadata function (defaults or user inputs) #' If some inputs are NULL, it loads the default inputs. If defaults not available, it prints error for the user. #' If inputs are not NULL, it loads the user-specified inputs. @@ -8,6 +8,7 @@ #' @param domain_file As defined in map_metadata #' @param look_up_file As defined in map_metadata #' @return A list of 5: all inputs needed for the map_metadata function to run. +#' @keywords internal #' @importFrom cli cli_alert_info cli_alert_danger #' @importFrom jsonlite fromJSON #' @importFrom utils read.csv @@ -50,13 +51,14 @@ load_data <- function(json_file, domain_file, look_up_file) { #' copy_previous #' -#' This function is called within the map_metadata function. \cr \cr +#' Internal Function: This function is called within the map_metadata function. \cr \cr #' It searches for previous OUTPUT files in the output_dir, that match the dataset name. \cr \cr #' If files exist, it removes duplicates and autos, and stores the rest of the data elements in a dataframe. \cr \cr #' #' @param dataset_name Name of the dataset #' @param output_dir Output directory to be searched #' @return It returns a list of 2: df_prev_exist (a boolean) and df_prev (NULL or populated with data elements to copy) +#' @keywords internal #' @importFrom dplyr %>% distinct #' @importFrom cli cli_alert_info diff --git a/R/compare.R b/R/compare.R index 7a65755..979c2fa 100644 --- a/R/compare.R +++ b/R/compare.R @@ -1,6 +1,6 @@ #' valid_comparison #' -#' This function is called within the map_metadata_compare function. \cr \cr +#' Internal Function: This function is called within the map_metadata_compare function. \cr \cr #' It reads two inputs to see if they are equal. \cr \cr #' If the test is 'warning' status and inputs are not equal it gives warning but continues. \cr \cr #' If the test is 'danger' status and inputs are not equal it stops and exits, with error message. \cr \cr @@ -10,6 +10,7 @@ #' @param severity Level of severity. Only 'danger' or 'warning' #' @param severity_text The text to print if inputs are not equal. #' @return Returns nothing if inputs are equal. If inputs are not equal, returns variable text depending on level of severity. +#' @keywords internal #' @importFrom cli cli_alert_warning valid_comparison <- function(input_1, input_2, severity, severity_text) { @@ -32,7 +33,7 @@ valid_comparison <- function(input_1, input_2, severity, severity_text) { #' concensus_on_mismatch #' -#' This function is called within the map_metadata_compare function. \cr \cr +#' Internal Function: This function is called within the map_metadata_compare function. \cr \cr #' For a specific data element, it compares the domain code categorisation between two sessions. #' If the categorisation differs, it prompts the user for a new consensus decision by presenting the json metadata. \cr \cr #' @@ -41,6 +42,7 @@ valid_comparison <- function(input_1, input_2, severity, severity_text) { #' @param datavar Data Element n #' @param domain_code_max The maximum allowable domain code integer #' @return It returns a list of 2: the domain code and the note from the consensus decision +#' @keywords internal #' @importFrom cli cli_alert_info concensus_on_mismatch <- function(ses_join, table_df, datavar, domain_code_max) { diff --git a/R/data-package_data.R b/R/data-package_data.R index d6b0456..38f3a22 100644 --- a/R/data-package_data.R +++ b/R/data-package_data.R @@ -1,6 +1,6 @@ -#' Output dataframe +#' Internal: Output dataframe #' -#' Empty output dataframe for map_metadata.R to fill. Created by: \cr \cr +#' Internal Dataset: Empty output dataframe for map_metadata.R to fill. Created by: \cr \cr #' \enumerate{ #' \item \code{output_df <- data.frame(timestamp = character(0), #' table = character(0), @@ -15,14 +15,16 @@ # #' @usage data(output_df) #' +#' @keywords internal +#' #' @format A data frame with 0 rows and 6 columns #' #' @source The dataframe was manually created as package data, using the above code. "output_df" -#' Output log dataframe +#' Internal: Output log dataframe #' -#' Empty log output dataframe for map_metadata.R to fill. Created by: \cr \cr +#' Internal Dataset: Empty log output dataframe for map_metadata.R to fill. Created by: \cr \cr #' \enumerate{ #' \item \code{log_output_df <- data.frame(timestamp = character(1), #' browseMetadata = character(1), @@ -40,14 +42,16 @@ # #' @usage data(log_output_df) #' +#' @keywords internal +#' #' @format A data frame with 1 empty row and 9 columns #' #' @source The dataframe was manually created as package data, using the above code. "log_output_df" -#' List of domains +#' Internal: List of Domains #' -#' A simplified list of domains, to demo the function map_metadata.R \cr \cr +#' Internal Dataset: A simplified list of domains, to demo the function map_metadata.R \cr \cr #' This data was created with these two steps: #' \enumerate{ #' \item \code{domain_list <- read.csv('browseMetadata/inst/inputs/domain_list_demo.csv',header=FALSE)} @@ -57,12 +61,14 @@ # #' @usage data(domain_list) #' +#' @keywords internal +#' #' @format A data frame with 5 rows and 1 column #' #' @source The csv was manually created "domain_list" -#' Json metadata file +#' Internal: JSON Metadata File #' #' Example metadata for a health dataset, to demo the function map_metadata.R \cr \cr #' This data was created with these five steps: @@ -78,12 +84,14 @@ # #' @usage data(json_metadata) #' +#' @keywords internal +#' #' @format Nested lists #' #' @source https://modelcatalogue.cs.ox.ac.uk/hdruk_live/#/catalogue/dataModel/16920b16-e24c-49f9-b4df-3dc85779822b/dataClasses "json_metadata" -#' Auto-categorisations +#' Internal: Auto-categorisations #' #' A list of pre-defined pairings between data element and domain code. \cr \cr #' For each data element that map_metadata processes: \cr \cr @@ -97,6 +105,8 @@ # #' @usage data(look_up) #' +#' @keywords internal +#' #' @format A data frame with a variable number of rows and 3 columns #' #' @source The csv was manually created diff --git a/R/data_manipulation.R b/R/data_manipulation.R index d78bf92..fae8fa0 100644 --- a/R/data_manipulation.R +++ b/R/data_manipulation.R @@ -1,12 +1,13 @@ #' json_table_to_df #' -#' This function is called within the browse_metadata and map_metadata functions. \cr \cr +#' Internal Function: This function is called within the browse_metadata and map_metadata functions. \cr \cr #' It reads in the nested lists from the json and extracts information needed into a dataframe. \cr \cr #' It does this for one specific table in a dataset. \cr \cr #' #' @param dataset This is the dataModel field of the json #' @param n The table number (as a json can have multiple tables within a dataset) #' @return A dataframe for that specific table, including data label, description and type. +#' @keywords internal json_table_to_df <- function(dataset, n) { json_table <- dataset$childDataClasses$childDataElements[n] @@ -25,7 +26,7 @@ json_table_to_df <- function(dataset, n) { #' count_empty_desc #' -#' This function is called within the browse_metadata function. \cr \cr +#' Internal Function: This function is called within the browse_metadata function. \cr \cr #' It reads in a data frame that summarises one table of the dataset. \cr \cr #' It counts missing variable descriptions, based on specified criteria. #' @@ -34,6 +35,7 @@ json_table_to_df <- function(dataset, n) { #' @return A simpler dataframe with Y/N empty counts for variables in the table. #' @importFrom dplyr %>% group_by n summarize #' @importFrom tidyr complete +#' @keywords internal count_empty_desc <- function(table_df, table_colname) { table_df["empty"] <- NA diff --git a/R/plotting.R b/R/plotting.R index 10a6735..f5183ef 100644 --- a/R/plotting.R +++ b/R/plotting.R @@ -1,10 +1,11 @@ -#' ref_plot +#' Internal: ref_plot #' #' This function is called within the map_metadata function. \cr \cr #' It plots a reference table to guide the user in their categorisation of domains. \cr \cr #' This reference table is based on the user inputted domains and the default domains provided by this package. \cr \cr #' @param domains The output of load_data #' @return A reference table that appears in the Plots tab. A list of 2 containing the derivatives for this plot, used later in map_metadata' +#' @keywords internal #' @importFrom gridExtra tableGrob grid.arrange #' @importFrom graphics plot.new @@ -19,7 +20,7 @@ ref_plot <- function(domains) { return(list(code = code, domain_table = domain_table)) } -#' end_plot +#' Internal: end_plot #' #' This function is called within the map_metadata function. \cr \cr #' A summary plot is created that includes the domain code reference table and counts of domain code categorisations \cr \cr @@ -28,6 +29,7 @@ ref_plot <- function(domains) { #' @param table_name The table name #' @param ref_table The domain code reference table (which domain maps to which integer) #' @return It returns a ggplot +#' @keywords internal #' @importFrom dplyr %>% group_by count arrange #' @importFrom stats reorder #' @importFrom gridExtra grid.arrange diff --git a/R/user_interactions.R b/R/user_interactions.R index 030e9a3..4d508b9 100644 --- a/R/user_interactions.R +++ b/R/user_interactions.R @@ -1,6 +1,6 @@ -#' user_categorisation +#' Internal: user_categorisation #' -#' This function is called within the map_metadata function. \cr \cr +#' Internal Function: This function is called within the map_metadata function. \cr \cr #' It displays data properties to the user and requests a categorisation into a domain. \cr \cr #' An optional note can be included with the categorisation. #' @@ -8,6 +8,7 @@ #' @param data_desc Description of the variable #' @param data_type Data type of the variable #' @param domain_code_max Max code in the domain list (0-3 auto included, then N included via domain_file) +#' @keywords internal #' @return It returns a list containing the decision and decision note #' @importFrom cli cli_alert_warning @@ -65,9 +66,9 @@ user_categorisation <- function(data_element, data_desc, data_type, domain_code_ return(list(decision = decision, decision_note = decision_note)) } -#' user_categorisation_loop +#' Internal: user_categorisation_loop #' -#' This function is called within the map_metadata function. \cr \cr +#' Internal Function: This function is called within the map_metadata function. \cr \cr #' Given a specific table and a number of data elements to search, it checks for 3 different sources of domain categorisation: \cr \cr #' 1 - If data elements match those in the look-up table, auto categorise them \cr \cr #' 2 - If data elements match to previous table output, copy them \cr \cr @@ -81,6 +82,7 @@ user_categorisation <- function(data_element, data_desc, data_type, domain_code_ #' @param df_plots Output from the ref_plot function, to indicate maximum domain code allowed #' @param output_df Empty output dataframe, to fill #' @return An output dataframe containing information about the table, data elements and categorisations +#' @keywords internal #' @importFrom dplyr %>% add_row #' @importFrom cli cli_alert_info @@ -142,16 +144,16 @@ user_categorisation_loop <- function(start_v, end_v, table_df, df_prev_exist, df output_df } -#' user_prompt +#' Internal: user_prompt #' -#' This function is called within the map_metadata function. \cr \cr +#' Internal Function: This function is called within the map_metadata function. \cr \cr #' It prompts a response from the user. \cr \cr #' #' @param prompt_text Text to display to the user, to prompt their response. #' @param any_keys Boolean to determine if any key responses are allowable. #' If FALSE, only these are allowed: Y, y, N and n. #' @return It returns variable text, depending on any_keys. - +#' @keywords internal user_prompt <- function(prompt_text, any_keys) { # prompt text is not # any_keys, when TRUE it allows any input, when FALSE it only allows y/n/Y/N @@ -175,9 +177,9 @@ user_prompt <- function(prompt_text, any_keys) { response } -#' user_prompt_list +#' Internal: user_prompt_list #' -#' This function is called within the map_metadata function. \cr \cr +#' Internal Function: This function is called within the map_metadata function. \cr \cr #' It prompts a response from the user, in the form of a list. \cr \cr #' It checks if the user has given the an input within the allowed range - if not, it re-sends prompt. \cr \cr #' @@ -185,6 +187,7 @@ user_prompt <- function(prompt_text, any_keys) { #' @param list_allowed A list of allowable integer responses. #' @param empty_allowed A boolean specifying if no response is allowed. #' @return It returns a list of integers to process, that match the prompt options. +#' @keywords internal #' @importFrom cli cli_alert_info cli_alert_danger user_prompt_list <- function(prompt_text, list_allowed, empty_allowed) {