From 465f78e144bcc3ba98a97899acc4b5d70c1f254b Mon Sep 17 00:00:00 2001
From: Batool Almarzouq <batool@liverpool.ac.uk>
Date: Wed, 27 Nov 2024 13:32:43 +0300
Subject: [PATCH] indicate internal functions

---
 R/collect_inputs.R    |  6 ++++--
 R/compare.R           |  6 ++++--
 R/data-package_data.R | 26 ++++++++++++++++++--------
 R/data_manipulation.R |  6 ++++--
 R/plotting.R          |  6 ++++--
 R/user_interactions.R | 21 ++++++++++++---------
 6 files changed, 46 insertions(+), 25 deletions(-)

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