Update documentation and internal functions; change package title and improve README descriptions

Author: harshanal

NAMESPACE

@@ -1,11 +1,16 @@
 # Generated by roxygen2: do not edit by hand
 
+export(adorn_dates)
 export(age_sex_pyramid)
+export(base_plotly)
 export(col_chart)
 export(epi_curve)
 export(epi_map)
 export(line_chart)
 export(llm_interpret)
+export(palette_gen)
+export(param_rename)
+export(plotly_legend_pos)
 export(point_chart)
 import(ISOweek)
 import(RColorBrewer)

R/age_sex_pyramid.R

@@ -1,6 +1,6 @@
 #' Generate an Age-Sex Pyramid
 #'
-#' This function creates an age-sex pyramid visualization, either as a static ggplot or an interactive plotly chart.
+#' This function creates an age-sex pyramid visualisation, either as a static ggplot or an interactive plotly chart.
 #' The function can take either a line list (ungrouped data) or already grouped data as input.
 #' When using a line list, the function processes the data, groups it by age and sex, and then generates the pyramid.
 #' If grouped data is provided, it directly creates the pyramid.
@@ -163,14 +163,14 @@ age_sex_pyramid <- function(
       if (is.null(var_map$age_group) || is.null(var_map$sex) || is.null(var_map$value)) {
         stop("For grouped data, var_map must include 'age_group', 'sex', and 'value'")
       }
-      
+
       # Create a new data frame with standardized column names
       .grp_df <- data.frame(
         age_group = params$df[[var_map$age_group]],
         sex = params$df[[var_map$sex]],
         value = params$df[[var_map$value]]
       )
-      
+
       # Add confidence limits if they exist and are requested
       if (params$conf_limits) {
         if (is.null(var_map$lowercl) || is.null(var_map$uppercl)) {
@@ -188,7 +188,7 @@ age_sex_pyramid <- function(
         .grp_df$lowercl <- .grp_df$value
         .grp_df$uppercl <- .grp_df$value
       }
-      
+
       # Ensure age_group is ordered correctly
       # Extract numeric part from age group labels for sorting
       age_order <- order(as.integer(sub("^(\\d+).*", "\\1", sub("[<+]", "", .grp_df$age_group))))
@@ -227,10 +227,10 @@ age_sex_pyramid <- function(
     return(result)
   }else{
     # plotly implementation of dynamic age-sex-pyramid
-    
+
     # Process data similarly to static version
     var_map <- params$var_map
-    
+
     if (params$grouped == FALSE) {
       .grp_df <- process_line_list_for_age_sex_pyramid(
         df = params$df,
@@ -243,14 +243,14 @@ age_sex_pyramid <- function(
       if (is.null(var_map$age_group) || is.null(var_map$sex) || is.null(var_map$value)) {
         stop("For grouped data, var_map must include 'age_group', 'sex', and 'value'")
       }
-      
+
       # Create a new data frame with standardized column names
       .grp_df <- data.frame(
         age_group = params$df[[var_map$age_group]],
         sex = params$df[[var_map$sex]],
         value = params$df[[var_map$value]]
       )
-      
+
       # Add confidence limits if they exist and are requested
       if (params$conf_limits) {
         if (is.null(var_map$lowercl) || is.null(var_map$uppercl)) {
@@ -268,43 +268,43 @@ age_sex_pyramid <- function(
         .grp_df$lowercl <- .grp_df$value
         .grp_df$uppercl <- .grp_df$value
       }
-      
+
       # Ensure age_group is ordered correctly
       # Extract numeric part from age group labels for sorting
       age_order <- order(as.integer(sub("^(\\d+).*", "\\1", sub("[<+]", "", .grp_df$age_group))))
       .grp_df$age_group <- factor(.grp_df$age_group, levels = unique(.grp_df$age_group[age_order]))
     }
-    
-    # Create the plotly visualization
+
+    # Create the plotly visualisation
     male_data <- .grp_df[.grp_df$sex == "Male", ]
     female_data <- .grp_df[.grp_df$sex == "Female", ]
-    
-    # Convert values for males to negative for visualization
+
+    # Convert values for males to negative for visualisation
     male_data$value <- -male_data$value
     if (params$conf_limits) {
       male_data$lowercl <- -male_data$lowercl
       male_data$uppercl <- -male_data$uppercl
     }
-    
+
     # Calculate maximum range for symmetric axis
     if (params$conf_limits) {
-      all_x <- c(male_data$value, female_data$value, male_data$lowercl, male_data$uppercl, 
+      all_x <- c(male_data$value, female_data$value, male_data$lowercl, male_data$uppercl,
                  female_data$lowercl, female_data$uppercl)
     } else {
       all_x <- c(male_data$value, female_data$value)
     }
     min_x <- min(all_x)
     max_x <- max(all_x)
     max_range <- max(abs(min_x), max_x)
-    
+
     # Generate symmetric tick values and positive labels
     positive_ticks <- pretty(c(0, max_range), n = ceiling(params$x_breaks / 2))
     tickvals <- sort(unique(c(-positive_ticks, positive_ticks)))
     ticktext <- as.character(abs(tickvals))
-    
+
     # Create the plot
     p <- plot_ly(showlegend = TRUE)
-    
+
     # Add male bars
     p <- add_trace(p,
                    x = male_data$value,
@@ -315,7 +315,7 @@ age_sex_pyramid <- function(
                    orientation = 'h',
                    hoverinfo = "text",
                    hovertext = paste0("Male: ", round(abs(male_data$value), 2), "<br>Age: ", male_data$age_group))
-    
+
     # Add female bars
     p <- add_trace(p,
                    x = female_data$value,
@@ -326,7 +326,7 @@ age_sex_pyramid <- function(
                    orientation = 'h',
                    hoverinfo = "text",
                    hovertext = paste0("Female: ", round(female_data$value, 2), "<br>Age: ", female_data$age_group))
-    
+
     # Add confidence limits if requested
     if (params$conf_limits) {
       p <- add_trace(p,
@@ -370,7 +370,7 @@ age_sex_pyramid <- function(
                      hoverinfo = "text",
                      hovertext = paste0("Female Upper CI: ", round(female_data$uppercl, 2), "<br>Age: ", female_data$age_group))
     }
-    
+
     # Update layout with corrected titles and custom ticks
     p <- layout(p,
                 title = params$legend_title,
@@ -400,7 +400,7 @@ age_sex_pyramid <- function(
                 showlegend = TRUE,
                 legend = get_plotly_legend_position(params$legend_position)
     )
-    
+
     return(p)
   }
 }

R/agesex_pyramid_grouped.R

@@ -18,6 +18,7 @@
 #'                    If TRUE, the data frame should include the lowercl and uppercl columns.
 #'
 #' @return Returns an age-sex pyramid as a ggplot object
+#' @keywords internal
 #'
 #' @import ggplot2
 #' @import dplyr

R/base_gg.R

@@ -1,15 +1,15 @@
-
-#' Creates base ggplot object for use across other functions.
-#' Parameters are not passed explicitly to the function, so
-#' function call needs to be proceeded by environment(base_gg) <- environment()
+#' Base ggplot object for line_chart, point_chart, and epi_curve
 #'
-#' @return ggplot object
+#' @description Internal function to create base ggplot object. Note that the
+#' function call needs to be proceeded by environment(base_gg) <- environment()
+#' to ensure that the function can find variables in the calling environment.
 #'
 #' @examples
 #' \dontrun{
 #' environment(base_gg) <- environment()
 #' base <- base_gg()
 #' }
+#' @keywords internal
 base_gg <- function() {
 
 

R/base_plotly.R

@@ -1,9 +1,10 @@
-
 #' Creates base plotly object for use across other functions.
 #' Parameters are not passed explicitly to the function, so
 #' function call needs to be proceeded by environment(base_plotly) <- environment()
 #'
 #' @return plotly object
+#' @keywords internal
+#' @export
 #'
 #' @examples
 #' \dontrun{

R/data.R

@@ -25,6 +25,7 @@
 #'   \item{SHAPE_Area}{}
 #'   \item{geometry}{}
 #' }
+#' @keywords internal
 "PHEC_boundaries_2016"
 
 #' Local Authority Districts (May 2023) Boundaries for London BGC
@@ -58,6 +59,7 @@
 #'   \item{SHAPE_Area}{}
 #'   \item{geometry}{}
 #' }
+#' @keywords internal
 "London_LA_boundaries_2023"
 
 #' Countries (December 2023) Boundaries UK BUC
@@ -88,4 +90,5 @@
 #'   \item{SHAPE_Area}{}
 #'   \item{geometry}{}
 #' }
+#' @keywords internal
 "UK_boundaries_2023"

R/llm_intepret.R

@@ -1,11 +1,11 @@
 #' Interpret Epidemiological Data or Visualisations using LLMs
-#' 
+#'
 #' @description
 #' `r lifecycle::badge("experimental")`
-#' 
+#'
 #' This function interprets a given data frame or ggplot visualisation by sending it to a language model API via the elmer package. It supports multiple LLM providers, allowing users to specify the desired provider and model through environment variables.
 #'
-#' @param input An input object, either a data frame or a ggplot object, representing the data or visualization to be interpreted.
+#' @param input An input object, either a data frame or a ggplot object, representing the data or visualisation to be interpreted.
 #' @param word_limit Integer. The desired word length for the response. Defaults to 100.
 #' @param prompt_extension Character. Optional additional instructions to extend the standard prompt. Defaults to NULL.
 #' @return A character string containing the narrative or interpretation of the input object as generated by the LLM.
@@ -36,35 +36,35 @@ llm_interpret <- function(input,
                           word_limit = 100,
                           prompt_extension = NULL) {
   lifecycle::signal_stage("experimental", "llm_interpret()")
-  
+
   # Validate input parameters
   if (!is.numeric(word_limit) || word_limit <= 0) {
     stop("word_limit must be a positive number")
   }
-  
+
   if (!is.null(prompt_extension) && !is.character(prompt_extension)) {
     stop("prompt_extension must be NULL or a character string")
   }
-  
+
   # Check for required environment variables with informative messages
   tryCatch({
     provider <- Sys.getenv("LLM_PROVIDER")
     if (provider == "") {
       stop("LLM_PROVIDER environment variable is not set. ",
            "Please set it to one of: 'openai', 'gemini', or 'claude'")
     }
-    
+
     api_key <- Sys.getenv("LLM_API_KEY")
     if (api_key == "") {
       stop("LLM_API_KEY environment variable is not set. ",
-           sprintf("For %s, please set the appropriate API key.", 
+           sprintf("For %s, please set the appropriate API key.",
                    toupper(provider)))
     }
-    
+
     model <- Sys.getenv("LLM_MODEL")
     if (model == "") {
       stop("LLM_MODEL environment variable is not set. ",
-           sprintf("For %s, please set an appropriate model identifier.", 
+           sprintf("For %s, please set an appropriate model identifier.",
                    toupper(provider)))
     }
   }, error = function(e) {
@@ -83,7 +83,7 @@ llm_interpret <- function(input,
   }, error = function(e) {
     stop("Failed to initialize chat client: ", conditionMessage(e))
   })
-  
+
   # Set the system prompt with error handling
   tryCatch({
     chat$set_system_prompt(
@@ -114,7 +114,7 @@ llm_interpret <- function(input,
     if (nrow(input) == 0) {
       stop("Input data frame is empty")
     }
-    
+
     # Convert data frame to JSON with error handling
     json_data <- tryCatch({
       jsonlite::toJSON(input, pretty = TRUE, auto_unbox = TRUE)
@@ -132,7 +132,7 @@ llm_interpret <- function(input,
   }
   else if (inherits(input, "ggplot")) {
     temp_file <- NULL
-    
+
     # Use withCallingHandlers for cleanup even if error occurs
     withCallingHandlers({
       # Save the ggplot object as a temporary image

R/process_line_list_for_asp.R

@@ -19,6 +19,8 @@
 #' @return A data frame that is aggregated by age group and sex, with columns for age group, sex, value (count),
 #' lower confidence limit, and upper confidence limit.
 #'
+#' @keywords internal
+#'
 #' @examples
 #' \dontrun{
 #'   df <- epiviz::lab_data