Merge pull request #150 from aim-rsf/ropensci-examples

Indicate internal functions

R/collect_inputs.R

@@ -1,13 +1,14 @@
 #' 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.
 #' @param json_file As defined in map_metadata
 #' @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
 

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) {

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

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

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

R/user_interactions.R

@@ -1,13 +1,14 @@
-#' 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.
 #'
 #' @param data_element Name of the variable
 #' @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,16 +177,17 @@ 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
 #'
 #' @param prompt_text Text to display to the user, to prompt their response.
 #' @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) {