add doc

R/concensus_on_mismatch.R

@@ -1,3 +1,16 @@
+#' concensus_on_mismatch
+#'
+#' This function is called within the browseMetadata_compare_outputs 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
+#'
+#' @param ses_join The joined dataframes from the two sessions
+#' @param Table_df Metadata from the json file, for one table in the dataset
+#' @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
+#' @importFrom CHECK LATER
+
 concensus_on_mismatch <- function(ses_join,Table_df,datavar,domain_code_max){
 
   if (ses_join$Domain_code_ses1[datavar] != ses_join$Domain_code_ses2[datavar]){
@@ -8,7 +21,7 @@ concensus_on_mismatch <- function(ses_join,Table_df,datavar,domain_code_max){
       "\nDOMAIN CODE (note) for session 2 --> ",ses_join$Domain_code_ses2[datavar],'(',ses_join$Note_ses2[datavar],')'
       ))
     cat("\n\n")
-    cli_alert_info("Provide concensus decision for this DataElement:")
+    cli::cli_alert_info("Provide concensus decision for this DataElement:")
     decision_output <- user_categorisation(Table_df$Label[datavar],Table_df$Description[datavar],Table_df$Type[datavar],domain_code_max)
     Domain_code_join <- decision_output$decision
     Note_join <- decision_output$decision_note

R/copy_previous.R

@@ -1,4 +1,13 @@
-#' DOCUMENT!
+#' copy_previous
+#'
+#' This function is called within the browseMetadata 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
+#' @param output_dir
+#' @return It returns a list of 2: df_prev_exist (a boolean) and df_prev (NULL or populated with data elements to copy)
+#' @importFrom CHECK LATER
 
 copy_previous <- function(Dataset_Name,output_dir) {
 

R/end_plot.R

@@ -1,4 +1,13 @@
-#' DOCUMENT!
+#' end_plot
+#'
+#' This function is called within the browseMetadata function. \cr \cr
+#' A summary plot is created that includes the domain code reference table and counts of domain code categorisations \cr \cr
+#'
+#' @param df The Output dataframe with all the domain categorisations
+#' @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
+#' @importFrom CHECK LATER
 
 end_plot <- function(df,Table_name, ref_table){
 

R/join_outputs.R

@@ -1,4 +1,13 @@
-# used in browseMetadata_compare_outputs
+#' join_outputs
+#'
+#' This function is called within the browseMetadata_compare_outputs function. \cr \cr
+#' Joins output dataframes from two sessions, on the column DataElement.
+#'
+#' @param session_1 Dataframe from session 1
+#' @param session_2 Dataframe from session 2
+#' @return Dataframe with information from session 1 and 2, joined on column DataElement.
+#' @importFrom CHECK LATER
+#'
 
 join_outputs <- function(session_1, session_2){
 

R/json_table_to_df.R

@@ -1,3 +1,14 @@
+#' join_outputs
+#'
+#' This function is called within the browseMetadata function. \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 Dataset number (as a json can have multiple datasets)
+#' @return A dataframe for that specific table, including data label, description and type.
+#' @importFrom CHECK LATER
+#'
 
 json_table_to_df <- function(Dataset,n){
 

R/load_data.R

@@ -1,5 +1,16 @@
-#' DOCUMENT!
-
+#' load_data
+#'
+#' This function is called within the browseMetadata function. \cr \cr
+#' It collects the inputs needed for the browseMetadata 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 browseMetadata
+#' @param domain_file As defined in browseMetadata
+#' @param look_up_file As defined in browseMetadata
+#' @return A list of 5: all inputs needed for the browseMetadata function to run.
+#' @importFrom CHECK LATER
+#'
+#'
 load_data <- function(json_file, domain_file,look_up_file){
 
   # Collect meta_json and domains

R/ref_plot.R

@@ -1,4 +1,13 @@
-#' DOCUMENT!
+#' ref_plot
+#'
+#' This function is called within the browseMetadata 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 browseMetadata.
+#' @importFrom CHECK LATER
+#'
+#'
 
 ref_plot <- function(domains){
 

R/user_categorisation.R

@@ -1,6 +1,6 @@
 #' user_categorisation
 #'
-#' This function is used within the browseMetadata function. \cr \cr
+#' This function is called within the browseMetadata 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.
 #'

R/user_categorisation_loop.R

@@ -1,3 +1,21 @@
+#' user_categorisation_loop
+#'
+#' This function is called within the browseMetadata 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
+#' 3 - If no match for 1 or 2, data elements are categorised by the user \cr \cr
+#' @param start_v Index of data element to start
+#' @param end_v Index of data element to end
+#' @param Table_df Dataframe with the table information, extracted from json metadata
+#' @param df_prev_exist Boolean to indicate with previous dataframes exist (to copy from)
+#' @param df_prev Previous dataframes to copy from (or NULL)
+#' @param lookup The lookup table to enable auto categorisations
+#' @param df_plots Output from the ref_plot function, to indicate maximum domain code allowed
+#' @param Output Empty Output dataframe, to fill
+#' @return An Output dataframe containing information about the table, data elements and categorisations
+#' @importFrom CHECK LATER
+
 user_categorisation_loop <- function(start_v,end_v,Table_df,df_prev_exist,df_prev,lookup,df_plots,Output) {
 
   for (data_v in start_v:end_v) {

R/user_prompt.R

@@ -1,4 +1,19 @@
-#' DOCUMENT!
+#' user_prompt
+#'
+#' This function is called within the browseMetadata function. \cr \cr
+#' It prompts a response from the user. \cr \cr
+#'
+#' @param pre_prompt_text Optional text to display to the user, prior to prompt.
+#' This should be a data frame:
+#' data.frame(Heading = logical(0), Text = character(0))
+#' Each row of the dataframe specifies Heading TRUE/FALSE and text to display.
+#' @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.
+#' @param post_yes_text Optional text to post after receiving a 'Y' or 'y'
+#' response from user. Same dataframe format as pre_prompt_text.
+#' @return It returns variable text, depending on any_keys.
+#' @importFrom CHECK LATER
 
 user_prompt <- function(pre_prompt_text = NULL, prompt_text, any_keys, post_yes_text = NULL) {
 

R/user_prompt_list.R

@@ -1,4 +1,14 @@
-#' DOCUMENT!
+#' user_prompt_list
+#'
+#' This function is called within the browseMetadata 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.
+#' @importFrom CHECK LATER
 
 user_prompt_list <- function(prompt_text,list_allowed,empty_allowed) {
 

R/valid_comparison.R

@@ -1,9 +1,16 @@
-#use in browseMetadata_compare_outputs
-#need to document this properly but the general idea is -
-#reads in 2 inputs to see if they are equal
-#if the test is 'warning' and inputs are not equal it just gives a warning to the user and continues
-#if the test is 'danger' and the inputs are not equal it stops and exists out of the main function
+#' valid_comparison
 
+#' This function is called within the browseMetadata_compare_outputs 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
+#' @param input1 Input 1
+#' @param input2 Input 2
+#' @param severity Level of severity. Only 'danger' or 'warning'
+#' @param severity_text The text to print if inputs are not equal.
+#' @return It returns variable text, depending on any_keys.
+#' @importFrom CHECK LATER
+#'
 valid_comparison <- function(input1, input2, severity, severity_text) {
 
   if (!severity %in% c('danger', 'warning')) {