diff --git a/NAMESPACE b/NAMESPACE index 3a90b19..e8931cd 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -14,6 +14,7 @@ export(is_plural) export(is_singular) export(list_templates) export(narrate_descriptive) +export(narrate_forecast) export(narrate_trend) export(narratorServer) export(narratorUI) diff --git a/R/edit_templates.R b/R/edit_templates.R index 37aeed1..96a47b7 100644 --- a/R/edit_templates.R +++ b/R/edit_templates.R @@ -7,27 +7,35 @@ edit_templates <- function() { templates <- list_templates() %>% dplyr::select(name, type, template) - # templates %>% - # dplyr::mutate(words = stringr::str_extract_all( - # template, - # "(?<=\\{)[^\\}]+") - # ) - - df <- narrator::sales %>% + df_descriptive <- narrator::sales %>% dplyr::group_by(Region, Product) %>% dplyr::summarise(Sales = sum(Sales)) + df_trend <- narrator::sales %>% + dplyr::mutate(Month = lubridate::floor_date(Date, unit = "months")) %>% + dplyr::group_by(Region, Product, Month) %>% + dplyr::summarise(Sales = sum(Sales)) + not.null <- function(x) { if (is.null(x)) return(FALSE) if (!is.null(x)) return(TRUE) } - narrative_output <- df %>% + narrative_descriptive <- df_descriptive %>% narrate_descriptive( return_data = TRUE, coverage = 0.4 ) + narrative_trend <- df_trend %>% + narrate_trend( + return_data = TRUE, + coverage = 0.4 + ) + + narrative_output <- c(narrative_descriptive, narrative_trend) + + # ui ---------------------------------------------------------------------- ui <- miniUI::miniPage( shiny::tags$style( type = 'text/css', @@ -47,22 +55,28 @@ edit_templates <- function() { label = "Export", class = "btn-warning"), + h3("Templates"), DT::DTOutput("template_table"), + h3("Updated Narrative"), DT::DTOutput("new_table") ) ) server <- function(input, output, session) { - data <- shiny::reactiveValues(data = templates) + rv <- shiny::reactiveValues( + data = templates, + template_type = NULL + ) shiny::observeEvent(input$edit,{ shiny::showModal( if (length(input$template_table_rows_selected) >=1 ) { - template_name <- toString(data$data[input$template_table_rows_selected, 1]) - template <- toString(data$data[input$template_table_rows_selected, 3]) + template_name <- toString(rv$data[input$template_table_rows_selected, 1]) + rv$template_type <- toString(rv$data[input$template_table_rows_selected, 2]) + template <- toString(rv$data[input$template_table_rows_selected, 3]) ind <- narrative_output %>% purrr::map(template_name) %>% @@ -85,14 +99,11 @@ edit_templates <- function() { dplyr::mutate(value = as.character(value)) %>% DT::datatable( rownames = FALSE, - #extensions = "Scroller", height = 800, options = list( pageLength = 10, dom = "t", - deferRender = TRUE#, - #scrollY = 200, - #scroller = TRUE + deferRender = TRUE ), class = 'cell-border stripe' ) @@ -117,12 +128,12 @@ edit_templates <- function() { i <- input$template_table_rows_selected template_new <- input$single_template - data$data[i, 3] <- template_new + rv$data[i, 3] <- template_new shiny::removeModal() }) shiny::observeEvent(input$export,{ - output <- data$data %>% + output <- rv$data %>% dplyr::mutate(result = glue::glue("{type}_{name} = {template} ")) %>% @@ -146,11 +157,12 @@ edit_templates <- function() { output$template_table <- DT::renderDataTable({ DT::datatable( - data$data, + rv$data, rownames = FALSE, extensions = "Scroller", selection = list(mode = "single"), options = list( + pageLength = 10, dom = "t", deferRender = TRUE, scrollY = 200, @@ -161,17 +173,36 @@ edit_templates <- function() { }) output$new_table <- DT::renderDataTable({ - templates_new <- data$data + req(rv$template_type) + + templates_descriptive <- rv$data %>% + dplyr::filter(type == "descriptive") + + templates_trend <- rv$data %>% + dplyr::filter(type == "trend") + + templates_new <<- templates_new + template_type <<- rv$template_type - do.call(narrator::narrate_descriptive, - c(list(df = df), split(templates_new$template, templates_new$name)) + output_descriptive <- do.call(narrator::narrate_descriptive, + c(list(df = df_descriptive), split(templates_descriptive$template, templates_descriptive$name)) ) %>% tibble::enframe(name = "Name", value = "Narrative") %>% - tidyr::unnest(cols = Narrative) %>% + tidyr::unnest(cols = Narrative) + + output_trend <- do.call(narrator::narrate_trend, + c(list(df = df_trend), split(templates_trend$template, templates_trend$name)) + ) %>% + tibble::enframe(name = "Name", value = "Narrative") %>% + tidyr::unnest(cols = Narrative) + + output_descriptive %>% + dplyr::bind_rows(output_trend) %>% DT::datatable( rownames = FALSE, extensions = "Scroller", options = list( + pageLength = 10, dom = "t", deferRender = TRUE, scrollY = 200, diff --git a/R/narrate_forecast.R b/R/narrate_forecast.R new file mode 100644 index 0000000..61e96fd --- /dev/null +++ b/R/narrate_forecast.R @@ -0,0 +1,285 @@ +#' Create Narrative for Time Series Forecast Data Frames +#' +#' @inheritParams narrate_trend +#' @param forecast Name of the forecast column in the data frame +#' @param actuals Name of the actuals column in the data frame +#' +#' @return A [list()] of narratives by default and [character()] if `simplify = TRUE` +#' @export +#' +#' @examples +#' library(prophet) +#' library(dplyr) +#' library(tidyr) +#' +#' fit_prophet <- function(data) { +#' model <- prophet(data) +#' future <- make_future_dataframe(model, periods = 12, freq = "month") +#' forecast <- predict(model, future) +#' return(forecast) +#' } +#' grouped_data <- sales %>% +#' dplyr::mutate(ds = lubridate::floor_date(Date, unit = "month")) %>% +#' dplyr::group_by(Region, ds) %>% +#' dplyr::summarise(y = sum(Sales, na.rm = TRUE)) %>% +#' tidyr::nest() +#' +#' grouped_data$forecast <- lapply(grouped_data$data, fit_prophet) +#' +#' actuals <- grouped_data %>% +#' dplyr::select(-forecast) %>% +#' unnest(data) +#' +#' df <- grouped_data %>% +#' dplyr::select(-data) %>% +#' unnest(forecast) %>% +#' dplyr::select(ds, yhat) %>% +#' dplyr::left_join(actuals) %>% +#' dplyr::rename(Actuals = y, +#' Forecast = yhat) +#' +#' narrate_forecast(df) +narrate_forecast <- function( + df, + measure = NULL, + dimensions = NULL, + date = NULL, + frequency = NULL, + summarization = "sum", + type = "yoy", + coverage = 0.5, + coverage_limit = 5, + narration_depth = 2, + use_chatgpt = FALSE, + openai_api_key = Sys.getenv("OPENAI_API_KEY"), + forecast = "Forecast", + actuals = "Actuals", + template_cy = "Forecasted volume for {current_year} is {format_num(cy_forecast)}", + template_ftm = "Overall forecast for the next 12 months is {format_num(ftm_forecast)}", + template_ftm_change = "Projected {trend} in the next 12 months is equal to {format_num(ftm_change)} ({ftm_change_p}%).", + use_renviron = FALSE, + return_data = FALSE, + simplify = FALSE, + format_numbers = TRUE, + collapse_sep = ", ", + collapse_last = " and ", + ...) { + + # Assertion --------------------------------------------------------------- + if (!is.data.frame(df) && !dplyr::is.tbl(df)) stop("'df' must be a data frame, tibble, or dplyr::tbl connection") + + df <- df %>% + dplyr::ungroup() + + if (!actuals %in% names(df)) stop(glue::glue("{actuals} must be a column in the data frame")) + if (!forecast %in% names(df)) stop(glue::glue("{forecast} must be a column in the data frame")) + + if (coverage_limit < 1) stop("'coverage_limit' must be higher or equal to 1") + if (coverage_limit%%1!=0) stop("'coverage_limit' must be an interger, no decimals allowed") + + if (coverage <= 0 || coverage > 1) stop("'coverage' must be more than 0 and less or equal to 1") + + # Calculating dimensions from a data.frame + if (is.null(dimensions)) { + dimensions <- df %>% + dplyr::select(where(is.character), where(is.factor)) %>% + names() + } else { + if (!all(dimensions %in% names(df))) { + stop("all dimensions must be columns the data frame (df)") + } + } + + # Checking dimensions data types + dimension_dtypes <- df %>% + dplyr::select(dplyr::all_of(dimensions)) %>% + head() %>% + dplyr::collect() %>% + lapply(class) + + if (!all(dimension_dtypes %in% c("character", "factor"))) { + stop(glue::glue("Data types for {toString(dimensions)} must be either 'character' or 'numeric', but is {toString(dimension_dtypes)}")) + } + + if (!class(df[[actuals]]) %in% c("numeric", "integer", "character", "factor")) { + stop(glue::glue("{actuals} must be a numeric column, but is {class(df[[actuals]])}")) + } + + if (!class(df[[forecast]]) %in% c("numeric", "integer", "character", "factor")) { + stop(glue::glue("{forecast} must be a numeric column, but is {class(df[[forecast]])}")) + } + + if (is.null(date)) { + date <- df %>% + dplyr::select_if(lubridate::is.timepoint) %>% + names() + + if (length(date) > 0) { + date <- date[1] + } else { + stop("Date column is required in 'Date', 'dttm', 'POSIXlt' or 'POSIXct' formats") + } + } + + if (!date %in% names(df)) stop("{date} is not a column in the data frame") + + if (!any(class(df[[date]]) %in% c("Date", "POSIXct", "POSIXlt"))) { + stop(glue::glue("{date} must be a numeric column, but is {class(df[[date]])[1]}")) + } + + if (is.null(frequency)) { + frequency <- narrator::get_frequency(df[date]) + } else { + df <- df %>% + dplyr::mutate(!!date := switch( + frequency, + "quarter" = lubridate::floor_date(base::get(date), unit = "quarter"), + "month" = lubridate::floor_date(base::get(date), unit = "month"), + "week" = lubridate::floor_date(base::get(date), unit = "week", week_start = 1), + "day" = base::get(date) + ) + ) + } + + # Renviron ---------------------------------------------------------------- + # Getting Environment Variables if available + # Candidate for a helper function + if (!is.null(getOption("narrator.use_renviron"))) { + use_renviron <- getOption("narrator.use_renviron") + } else if (Sys.getenv("use_renviron") != "") { + use_renviron <- Sys.getenv("use_renviron") + } + + if (use_renviron == TRUE) { + if (Sys.getenv("forecast_template_cy") != "") { + template_cy <- Sys.getenv("forecast_template_cy") + } + + if (Sys.getenv("forecast_template_ftm") != "") { + template_ftm <- Sys.getenv("forecast_template_ftm") + } + + if (Sys.getenv("forecast_template_ftm_change") != "") { + template_ftm <- Sys.getenv("forecast_template_ftm_change") + } + } + + # Total ------------------------------------------------------------------- + # Transforming dttm or similar formats to date and avoiding time zone issues + df <- df %>% + dplyr::mutate(!!date := as.Date(base::get(date))) + + # Current Year + max_actuals_date <- df %>% + dplyr::filter(!is.na(Actuals)) %>% + dplyr::select(dplyr::all_of(date)) %>% + as.matrix() %>% + as.Date() %>% + max() + + next_date <- switch( + frequency, + "week" = max_actuals_date + lubridate::weeks(1), + "month" = max_actuals_date + months(1), + "quarter" = max_actuals_date + months(3) + ) + + max_forecast_date <- df %>% + dplyr::select(dplyr::all_of(date)) %>% + as.matrix() %>% + as.Date() %>% + max() + + current_year <- lubridate::year(max_actuals_date) + + # If current year is complete and nothing was forecast we add different narrative + if (lubridate::year(next_date) == current_year + 1) { + template_cy <- "Actuals for {current_year} are equal to {format_num(cy_forecast)}" + } + + cy_forecast <- df %>% + dplyr::filter(lubridate::year(base::get(date)) == current_year) %>% + dplyr::mutate(Forecast = ifelse(is.na(Actuals), Forecast, Actuals)) %>% + dplyr::summarise(Forecast = sum(Forecast, na.rm = TRUE)) %>% + as.numeric() %>% + round() + + narrative_cy <- glue::glue(template_cy, ...) + + narrative <- list(narrative_cy) %>% + rlang::set_names("Current Year Actuals") + + variables <- list( + template_cy = narrative_cy, + current_year = current_year, + max_actuals_date = max_actuals_date, + max_forecast_date = max_forecast_date, + frequency = frequency, + cy_forecast = cy_forecast) + + # Next 12 months + # In case we have at least one year of forecast values narrate FTM + # We count it as at least 52 weeks + if (as.numeric(max_forecast_date - max_actuals_date)/7 >= 52 & !is.null(template_ftm)) { + ftm_forecast <- df %>% + dplyr::filter(base::get(date) > max_actuals_date, + base::get(date) <= max_actuals_date + months(12)) %>% + dplyr::summarise(Forecast = sum(Forecast, na.rm = TRUE)) %>% + as.numeric() %>% + round() + + narrative_ftm <- glue::glue(template_ftm, ...) + + narrative <- list(narrative_ftm) %>% + rlang::set_names(glue::glue("Overall {forecast} in the next 12 months")) %>% + append(narrative, after = 0) + + variables <- append(variables, list(narrative_ftm = narrative_ftm), 1) + variables <- append(variables, list(template_ftm = template_ftm), 1) + variables <- append(variables, list(ftm_forecast = ftm_forecast)) + + if (!is.null(template_ftm_change)) { + ltm_actuals <- df %>% + dplyr::filter(!is.na(Actuals), + base::get(date) > max_actuals_date - months(12)) %>% + dplyr::summarise(Forecast = sum(Forecast, na.rm = TRUE)) %>% + as.numeric() %>% + round() + + trend <- ifelse(ftm_forecast > ltm_actuals, "increase", "decrease") + ftm_change <- ftm_forecast - ltm_actuals + ftm_change_p <- round(ftm_change/ltm_actuals*100, 1) + + narrative_ftm_change <- glue::glue(template_ftm_change, ...) + + narrative <- list(narrative_ftm_change) %>% + rlang::set_names(glue::glue("Overall {trend} the next 12 months")) %>% + append(narrative, after = 0) + + variables <- append(variables, list(narrative_ftm_change = narrative_ftm_change), 1) + variables <- append(variables, list(template_ftm_change = template_ftm_change), 1) + variables <- append(variables, + list(trend = trend, + ltm_actuals = ltm_actuals) + ) + } + } + + # ChatGPT ----------------------------------------------------------------- + if (use_chatgpt) { + narrative <- enhance_narrative(narrative, openai_api_key = openai_api_key) + } + + # Output ------------------------------------------------------------------ + if (return_data == TRUE) { + return(variables) + } + + if (simplify == TRUE) { + narrative <- as.character(narrative) + variables$narrative <- as.character(variables$narrative) + } + + return(narrative) +} + diff --git a/README.md b/README.md index 430c045..82c3342 100644 --- a/README.md +++ b/README.md @@ -135,30 +135,27 @@ narrative_enhanced <- enhance_narrative(narrative_one) cat(narrative_enhanced) ``` -The company has achieved a remarkable Total Sales figure of 38790478.4 -across all Regions. Upon further analysis, it is evident that the -Outlying Regions, such as NA and EMEA, have contributed significantly to -this commendable feat. NA has recorded an impressive figure of -18079736.4, which accounts for 46.6% of the overall sales, whereas EMEA -has recorded 13555412.7, which is 34.9% of the total sales. - -Upon examination of the NA market, it is observed that Food & Beverage -has emerged as the leading product category, accounting for a -substantial figure of 7392821, which is 40.9% of the sales. Furthermore, -Electronics follows suit, with an impressive contribution of 3789132.7, -which is 21% of the total sales. - -Similarly, the EMEA market depicts Food & Beverage as the dominant -player in terms of sales figures, accounting for a whopping 5265113.2, -which constitutes 38.8% of the total sales. Electronics comes in a close -second, contributing 3182803.4, which is 23.5% of the sales. - -Additionally, Food & Beverage emerges as the major contributor to -Outlying Products by Sales, with a massive figure of 15543469.7, which -accounts for a significant 40.1% of the overall sales. Electronics -follows suit, contributing 8608962.8, which is 22.2% of the total sales. -These numbers highlight the significance of these products in the -overall success of the company’s sales figures. +The company’s Total Sales across all Regions have reached a remarkable +figure of 38790478.4. Outlying Regions by Sales are NA, which has +generated sales figures of 18079736.4, accounting for 46.6% of the total +sales. Following closely is EMEA, responsible for sales figures of +13555412.7, representing 34.9% of the total sales. + +Analysing the sales figures for the NA market, we can identify two +significant products that have achieved excellent results. Food & +Beverage led the way with an outstanding 7392821 in sales, comprising +40.9% of the market share. Electronics followed closely with sales +figures of 3789132.7, accounting for an estimated 21% market share. + +In the EMEA market, we also see impressive figures of sales for the Food +& Beverage sector with 5265113.2 accounting for 38.8% market share, and +Electronics achieving sales of 3182803.4, accounting for an estimated +23.5% of the market. + +Combined, Food & Beverage and Electronics products have driven the +Outlying Products by Sales with notable figures of 15543469.7 and +8608962.8, which represent 40.1% and 22.2% of the market share, +respectively. ### Translation @@ -170,28 +167,26 @@ translation <- translate_narrative(narrative_enhanced, language = "Czech") cat(translation) ``` -Společnost dosáhla pozoruhodného celkového tržby ve výši 38790478,4 -všech regionů. Z další analýzy je jasné, že odlehlé regiony, jako jsou -NA a EMEA, významně přispěly k tomuto pochvalnému úspěchu. NA -zaznamenala skvělou částku 18079736,4, což představuje 46,6 % celkových -prodejů, zatímco EMEA zapsala 13555412,7, což znamená 34,9 % celkových +Celkové Spojené Prodeje Společnosti napříč všemi regiony dosáhly +pozoruhodné sumy 38790478.4. Regiony nad rámec očekávání jsou Severní +Amerika (NA), která vygenerovala prodej ve výši 18079736.4, což +představuje 46,6% celkového prodeje. Těsně na druhém místě je EMEA, +zodpovědná za prodej ve výši 13555412.7, což odpovídá 34,9% celkových prodejů. -Při zkoumání NA trhu je pozorováno, že potraviny a nápoje se staly -vedoucí kategorií produktů, představující podstatnou částku 7392821, což -je 40,9 % prodejů. Elektronika následuje, s impozantním přínosem -3789132,7, což je 21 % celkových prodejů. +Analýzou prodejů na trhu Severní Ameriky můžeme identifikovat dva +významné produkty, které dosáhly vynikajících výsledků. Vedením šla +kategorie Jídla a Nápojů se skvělými prodeji za 7392821, což tvoří 40.9% +tržního podílu. Elektronika následovala blízko za prodejovými čísly ve +výši 3789132.7, což odpovídá přibližně 21% tržního podílu. -Podobně se na trhu EMEA ukazuje, že potraviny a nápoje jsou dominantním -hráčem z hlediska prodejních čísel, představující ohromující 5265113,2, -což představuje 38,8 % celkových prodejů. Elektronika následuje těsně za -ní, přispívající 3182803,4, což je 23,5 % prodejů. +Na trhu EMEA vidíme také impozantní prodejová čísla od kategorie Jídla a +Nápojů (5265113.2), což tudíž tvoří 38.8% tržního podílu, a Elektronika +s prodejem ve výši 3182803.4, což představuje 23.5% tržního podílu. -Dodatečně se potraviny a nápoje stávají hlavním přispěvatelem k prodejům -odlehlých produktů, s obrovskou částkou 15543469,7, což představuje -významných 40,1 % celkových prodejů. Elektronika následuje s přínosem -8608962,8, což je 22,2 % celkových prodejů. Tyto čísla zdůrazňují význam -těchto produktů v celkovém úspěchu prodejů společnosti. +Celkově kategorie Jídla a Nápojů a Elektronika pohánějí Outlying +Produkty s významnými čísly ve výši 15543469.7 a 8608962.8, což odpovídá +40.1% a 22.2% tržního podílu. ### Summarization @@ -203,12 +198,12 @@ summarization <- summarize_narrative(narrative_enhanced) cat(summarization) ``` -The company achieved total sales of \$38,790,478.4 with contributions -from NA and EMEA regions. Food & Beverage dominated both markets with -highest sales figures, totaling \$15,543,469.7 and \$5,265,113.2, -respectively. Electronics followed with \$8,608,962.8 and \$3,182,803.4 -in sales. These products are significant for the company’s overall sales -success. +Total Sales of 38790478.4 have been achieved by the company across all +regions. NA and EMEA are the top regions with sales figures of +18079736.4 and 13555412.7, respectively. Food & Beverage and Electronics +are the leading products, with impressive sales figures in both regions +driving the market share. They account for 40.1% and 22.2% of the market +share respectively, combining to contribute to the overall success. # Python diff --git a/_pkgdown.yml b/_pkgdown.yml index 62fe0b4..47b58af 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -62,6 +62,7 @@ articles: contents: - descriptive - trend + - forecast - title: Customization desc: Making edits and formatting of the narrative outputs diff --git a/docs/404.html b/docs/404.html index 5e22ae9..ddca6df 100644 --- a/docs/404.html +++ b/docs/404.html @@ -44,6 +44,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html index 55debe6..dc33cbd 100644 --- a/docs/LICENSE-text.html +++ b/docs/LICENSE-text.html @@ -26,6 +26,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
diff --git a/docs/LICENSE.html b/docs/LICENSE.html index b537cba..925aa3e 100644 --- a/docs/LICENSE.html +++ b/docs/LICENSE.html @@ -26,6 +26,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
diff --git a/docs/articles/index.html b/docs/articles/index.html index 00dc39d..4ab40bc 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -26,6 +26,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
@@ -62,6 +63,8 @@

Narratives

Trend Narratives
+
Forecast Narratives
+

Customization

diff --git a/docs/authors.html b/docs/authors.html index a48ac84..4316e93 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -26,6 +26,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
diff --git a/docs/index.html b/docs/index.html index dc39297..c6d7011 100644 --- a/docs/index.html +++ b/docs/index.html @@ -50,6 +50,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
@@ -172,10 +173,10 @@

ChatGPT
 narrative_enhanced <- enhance_narrative(narrative_one)
 cat(narrative_enhanced)

-

The company has achieved a remarkable Total Sales figure of 38790478.4 across all Regions. Upon further analysis, it is evident that the Outlying Regions, such as NA and EMEA, have contributed significantly to this commendable feat. NA has recorded an impressive figure of 18079736.4, which accounts for 46.6% of the overall sales, whereas EMEA has recorded 13555412.7, which is 34.9% of the total sales.

-

Upon examination of the NA market, it is observed that Food & Beverage has emerged as the leading product category, accounting for a substantial figure of 7392821, which is 40.9% of the sales. Furthermore, Electronics follows suit, with an impressive contribution of 3789132.7, which is 21% of the total sales.

-

Similarly, the EMEA market depicts Food & Beverage as the dominant player in terms of sales figures, accounting for a whopping 5265113.2, which constitutes 38.8% of the total sales. Electronics comes in a close second, contributing 3182803.4, which is 23.5% of the sales.

-

Additionally, Food & Beverage emerges as the major contributor to Outlying Products by Sales, with a massive figure of 15543469.7, which accounts for a significant 40.1% of the overall sales. Electronics follows suit, contributing 8608962.8, which is 22.2% of the total sales. These numbers highlight the significance of these products in the overall success of the company’s sales figures.

+

The company’s Total Sales across all Regions have reached a remarkable figure of 38790478.4. Outlying Regions by Sales are NA, which has generated sales figures of 18079736.4, accounting for 46.6% of the total sales. Following closely is EMEA, responsible for sales figures of 13555412.7, representing 34.9% of the total sales.

+

Analysing the sales figures for the NA market, we can identify two significant products that have achieved excellent results. Food & Beverage led the way with an outstanding 7392821 in sales, comprising 40.9% of the market share. Electronics followed closely with sales figures of 3789132.7, accounting for an estimated 21% market share.

+

In the EMEA market, we also see impressive figures of sales for the Food & Beverage sector with 5265113.2 accounting for 38.8% market share, and Electronics achieving sales of 3182803.4, accounting for an estimated 23.5% of the market.

+

Combined, Food & Beverage and Electronics products have driven the Outlying Products by Sales with notable figures of 15543469.7 and 8608962.8, which represent 40.1% and 22.2% of the market share, respectively.

Translation

@@ -183,10 +184,10 @@

Translation
 translation <- translate_narrative(narrative_enhanced, language = "Czech")
 cat(translation)

-

Společnost dosáhla pozoruhodného celkového tržby ve výši 38790478,4 všech regionů. Z další analýzy je jasné, že odlehlé regiony, jako jsou NA a EMEA, významně přispěly k tomuto pochvalnému úspěchu. NA zaznamenala skvělou částku 18079736,4, což představuje 46,6 % celkových prodejů, zatímco EMEA zapsala 13555412,7, což znamená 34,9 % celkových prodejů.

-

Při zkoumání NA trhu je pozorováno, že potraviny a nápoje se staly vedoucí kategorií produktů, představující podstatnou částku 7392821, což je 40,9 % prodejů. Elektronika následuje, s impozantním přínosem 3789132,7, což je 21 % celkových prodejů.

-

Podobně se na trhu EMEA ukazuje, že potraviny a nápoje jsou dominantním hráčem z hlediska prodejních čísel, představující ohromující 5265113,2, což představuje 38,8 % celkových prodejů. Elektronika následuje těsně za ní, přispívající 3182803,4, což je 23,5 % prodejů.

-

Dodatečně se potraviny a nápoje stávají hlavním přispěvatelem k prodejům odlehlých produktů, s obrovskou částkou 15543469,7, což představuje významných 40,1 % celkových prodejů. Elektronika následuje s přínosem 8608962,8, což je 22,2 % celkových prodejů. Tyto čísla zdůrazňují význam těchto produktů v celkovém úspěchu prodejů společnosti.

+

Celkové Spojené Prodeje Společnosti napříč všemi regiony dosáhly pozoruhodné sumy 38790478.4. Regiony nad rámec očekávání jsou Severní Amerika (NA), která vygenerovala prodej ve výši 18079736.4, což představuje 46,6% celkového prodeje. Těsně na druhém místě je EMEA, zodpovědná za prodej ve výši 13555412.7, což odpovídá 34,9% celkových prodejů.

+

Analýzou prodejů na trhu Severní Ameriky můžeme identifikovat dva významné produkty, které dosáhly vynikajících výsledků. Vedením šla kategorie Jídla a Nápojů se skvělými prodeji za 7392821, což tvoří 40.9% tržního podílu. Elektronika následovala blízko za prodejovými čísly ve výši 3789132.7, což odpovídá přibližně 21% tržního podílu.

+

Na trhu EMEA vidíme také impozantní prodejová čísla od kategorie Jídla a Nápojů (5265113.2), což tudíž tvoří 38.8% tržního podílu, a Elektronika s prodejem ve výši 3182803.4, což představuje 23.5% tržního podílu.

+

Celkově kategorie Jídla a Nápojů a Elektronika pohánějí Outlying Produkty s významnými čísly ve výši 15543469.7 a 8608962.8, což odpovídá 40.1% a 22.2% tržního podílu.

Summarization @@ -195,7 +196,7 @@

Summarization
 summarization <- summarize_narrative(narrative_enhanced)
 cat(summarization)

-

The company achieved total sales of $38,790,478.4 with contributions from NA and EMEA regions. Food & Beverage dominated both markets with highest sales figures, totaling $15,543,469.7 and $5,265,113.2, respectively. Electronics followed with $8,608,962.8 and $3,182,803.4 in sales. These products are significant for the company’s overall sales success.

+

Total Sales of 38790478.4 have been achieved by the company across all regions. NA and EMEA are the top regions with sales figures of 18079736.4 and 13555412.7, respectively. Food & Beverage and Electronics are the leading products, with impressive sales figures in both regions driving the market share. They account for 40.1% and 22.2% of the market share respectively, combining to contribute to the overall success.

diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index d8257cf..ce5552a 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -4,10 +4,11 @@ pkgdown_sha: ~ articles: descriptive: descriptive.html echarts: echarts.html + forecast: forecast.html formatting: formatting.html templates: templates.html trend: trend.html -last_built: 2023-04-23T10:16Z +last_built: 2023-05-07T18:34Z urls: reference: https://denisabd.github.io/narrator/reference article: https://denisabd.github.io/narrator/articles diff --git a/docs/reference/index.html b/docs/reference/index.html index 02457a5..6ce9a6f 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -26,6 +26,7 @@
Descriptive Narratives Trend Narratives + Forecast Narratives Formatting Output Editing Templates
@@ -72,6 +73,11 @@

Narrativesnarrate_forecast() + +
Create Narrative for Time Series Forecast Data Frames
+
+ narrate_trend()
Create Narrative for Metric Development in Time
diff --git a/docs/search.json b/docs/search.json index ec80475..d9fe992 100644 --- a/docs/search.json +++ b/docs/search.json @@ -1 +1 @@ -[{"path":"https://denisabd.github.io/narrator/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 Denis Abdullin Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"r","dir":"Articles","previous_headings":"","what":"R","title":"Descriptive Narratives","text":"","code":"library(narrator) library(dplyr) library(knitr)"},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"simple-table","dir":"Articles","previous_headings":"R","what":"Simple Table","title":"Descriptive Narratives","text":"Starting simplest table one dimension one measure. overall sales volume well outlying Territories analyzed.","code":"df_one <- sales %>% group_by(Region) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_one) narrate_descriptive(df_one) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"summarization","dir":"Articles","previous_headings":"R","what":"Summarization","title":"Descriptive Narratives","text":"multiple summarization/aggregation options data frame, controlled summarization argument can sum, count average","code":"sales %>% narrate_descriptive( measure = \"Sales\", dimensions = \"Region\", summarization = \"count\" ) #> $`Total Sales` #> Total Sales across all Regions is 9026. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (3821, 39.4 %), EMEA (2883, 29.8 %). sales %>% narrate_descriptive( measure = \"Sales\", dimensions = \"Region\", summarization = \"average\" ) #> $`Average Sales` #> Average Sales across all Regions is 3879. #> #> $`Region by Sales` #> Outlying Regions by Sales are LATAM (2303.3, -40.6 % vs average Sales), ASPAC (2398.6, -38.2 % vs average Sales)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"multiple-dimensions","dir":"Articles","previous_headings":"R","what":"Multiple Dimensions","title":"Descriptive Narratives","text":"","code":"df_two <- sales %>% filter(Region %in% c(\"NA\", \"EMEA\")) %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_two) narrate_descriptive(df_two) #> $`Total Sales` #> Total Sales across all Regions is 31635149.1. #> #> $`Region by Sales` #> Outlying Region by Sales is NA (18079736.4, 57.2 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (12657934.2, 40 %), Electronics (6971936.1, 22 %)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"depth","dir":"Articles","previous_headings":"R","what":"Depth","title":"Descriptive Narratives","text":"Narration depth can controlled narration_depth argument. get summary narratives set narration_depth = 1","code":"narrate_descriptive( df_two, narration_depth = 1 ) #> $`Total Sales` #> Total Sales across all Regions is 31635149.1. #> #> $`Region by Sales` #> Outlying Region by Sales is NA (18079736.4, 57.2 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (12657934.2, 40 %), Electronics (6971936.1, 22 %)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"coverage","dir":"Articles","previous_headings":"R","what":"Coverage","title":"Descriptive Narratives","text":"Key argument narratives coverage. used narrate important things avoid simple looping dimension levels. default coverage set 0.5 means narration stop soon cumulative sum reaches 50 % mark. increased coverage, additional narrative returned.","code":"df_three <- sales %>% group_by(Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) df_three %>% mutate( Share = round(Sales/sum(Sales)*100, 1), Cumulative = cumsum(Share)) %>% kable() narrate_descriptive(df_three) #> $`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). narrate_descriptive(df_three, coverage = 0.7) #> $`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %)."},{"path":"https://denisabd.github.io/narrator/articles/echarts.html","id":"simple-plots","dir":"Articles","previous_headings":"","what":"Simple Plots","title":"Narrate Echarts Plots","text":"Let’s create bar plot sales data: can extract underlying data plot object using echarts4r::e_get_data() function convert tibble suitable narrative extraction. can add narrative plot echarts4r::e_text_g() can done scatter plot pie chart, scatter narrate_descriptive() take first numeric measure.","code":"barplot <- sales %>% dplyr::group_by(Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% echarts4r::e_chart(Region) %>% echarts4r::e_bar(Sales) %>% echarts4r::e_tooltip() barplot bar_narrative <- barplot %>% echarts4r::e_get_data() %>% purrr::map_df(bind_rows) %>% narrate_descriptive() bar_narrative #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). bar_narrative <- bar_narrative %>% unlist(use.names = FALSE) %>% paste(\"\\n\", collapse = \"\") barplot %>% echarts4r::e_text_g( style = list( text = bar_narrative, fontSize = 16 ), left = \"2%\", top = \"3%\", rotation = 0 ) scatterplot <- sales %>% dplyr::group_by(Region, Product) %>% dplyr::summarise(Sales = sum(Sales), Quantity = sum(Quantity), Price = mean(Price), .groups = \"keep\") %>% echarts4r::e_chart(Sales) %>% echarts4r::e_scatter(Quantity, Price) %>% echarts4r::e_tooltip() scatterplot scatterplot %>% echarts4r::e_get_data() %>% purrr::map_df(bind_rows) %>% narrate_descriptive() #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %), Electronics (3182803.4, 23.5 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). piechart <- sales %>% dplyr::group_by(Product) %>% dplyr::summarise(Sales = sum(Sales)) %>% echarts4r::e_chart(Product) %>% echarts4r::e_pie(Sales, radius = c(\"50%\", \"70%\")) %>% echarts4r::e_tooltip() piechart piechart %>% echarts4r::e_get_data() %>% purrr::map_df(bind_rows) %>% narrate_descriptive() #> $`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"descriptive-narrative","dir":"Articles","previous_headings":"","what":"Descriptive Narrative","title":"Introducing narrator","text":"Basic narrative type descriptive stats, looking outliers biggest contributors total volumes data set. narratives quite useful can help look deeper data set hierarchy.","code":""},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"simple-table","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Simple Table","title":"Introducing narrator","text":"Starting simplest table one dimension one measure. overall sales volume well outlying Territories analyzed.","code":"df_one <- sales %>% group_by(Region) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_one) narrate_descriptive(df_one) #> $`Total Sales` #> Total Sales across all Regions: 2.1 M. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (1 M, 47.4 %), EMEA (655.4 K, 30.7 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"multiple-dimensions","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Multiple Dimensions","title":"Introducing narrator","text":"","code":"df_two <- sales %>% filter(Region %in% c(\"NA\", \"EMEA\")) %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_two) narrate_descriptive(df_two) #> $`Total Sales` #> Total Sales across all Regions: 1.7 M. #> #> $`Region by Sales` #> Outlying Region by Sales is NA (1 M, 60.7 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Product E (241.6 K, 23.9 %), Product B (201.9 K, 20 %), Product F (154.1 K, 15.2 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (440.2 K, 26.4 %), Product B (297.8 K, 17.9 %), Product F (247 K, 14.8 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"coverage","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Coverage","title":"Introducing narrator","text":"Key argument narratives coverage. used narrate important things avoid simple looping dimension levels. default coverage set 0.5 means narration stop soon cumulative sum reaches 50 % mark. increased coverage, additional narrative returned.","code":"df_three <- sales %>% group_by(Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) df_three %>% mutate(Share = round(Sales/sum(Sales)*100, 1), Cumulative = cumsum(Share)) %>% kable() narrate_descriptive(df_three) #> $`Total Sales` #> Total Sales across all Products: 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). narrate_descriptive(df_three, coverage = 0.7) #> $`Total Sales` #> Total Sales across all Products: 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"changing-templates","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Changing Templates","title":"Introducing narrator","text":"Template-based systems based calculations individual variables, combining together inside template. can return list calculated variables full narrative realization: Let’s change template narrative function rework wording well changing ‘’ ‘’ since Sales plural: can set templates using usethis::edit_r_environ() setting environment variable using data science platform capabilities. method little handy setting .Renviron variable names using certain convention adding use_renviron = TRUE narrate function. example created variable uses unique part function name, underscore, template name - descriptive + - + template_total can get templates currently available package list_templates() function:","code":"narrate_descriptive(df_three, coverage = 0.7, return_data = TRUE) #> $template_total #> Total Sales across all Products: 2.1 M. #> #> $narrative #> $narrative$`Total Sales` #> Total Sales across all Products: 2.1 M. #> #> $narrative$`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %). #> #> #> $template_outlier_final #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %). #> #> $measure #> [1] \"Sales\" #> #> [[5]] #> [1] \"Product\" #> #> $total #> [1] \"2.1 M\" #> #> $outlier_insight #> [1] \"Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %)\" narrate_descriptive( df_three, template_total = \"Overall {measure} for all {pluralize(dimension1)} are equal to {total}. \") #> $`Total Sales` #> Overall Sales for all Products are equal to 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). Sys.getenv(\"descriptive_template_total\") #> [1] \"Total {measure} = {total}.\" narrate_descriptive( df_three,template_total = Sys.getenv(\"descriptive_template_total\") ) #> $`Total Sales` #> Total Sales = 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). narrate_descriptive(df_three, use_renviron = TRUE) #> $`Total Sales` #> Total Sales = 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). list_templates() %>% kable()"},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"correcting-text","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Correcting Text","title":"Introducing narrator","text":"can correct sentence using, currently experimental correct_text() function. requires udpipe installation load model choosing working directory.","code":"correct_text(\"Total Profit across all Regions are 85 M\", download_udpipe = FALSE) #> [1] \"Total Profit across all Regions is 85 M\""},{"path":"https://denisabd.github.io/narrator/articles/python.html","id":"installation","dir":"Articles","previous_headings":"","what":"Installation","title":"Python","text":"use Python version package install pynarrator pip:","code":"pip3 install pynarrator import os from pynarrator import narrate_descriptive, read_data import pprint sales = read_data() narrative = narrate_descriptive( df = sales, measure = 'Sales', dimensions = ['Region', 'Product'], return_data = False, coverage = 0.5 ) pprint.pprint(narrative) #> {'Product by Sales': 'Outlying Products by Sales are Food & Beverage ' #> '(15543469.7, 40.0%), Electronics (8608962.8, 22.0%).', #> 'Region by Sales': 'Outlying Regions by Sales are NA (18079736.4, 47.0%), ' #> 'EMEA (13555412.7, 35.0%).', #> 'Total Sales': 'Total Sales across all Regions is 38790478.42.'} df_two = (sales .query('Region in [\"NA\", \"EMEA\"]') .groupby(['Region', 'Product']) .agg(Sales=('Sales', 'sum')) .reset_index() .sort_values('Sales', ascending=False) ) pprint.pprint(df_two) #> Region Product Sales #> 9 NA Food & Beverage 7392820.96 #> 3 EMEA Food & Beverage 5265113.22 #> 8 NA Electronics 3789132.66 #> 2 EMEA Electronics 3182803.42 #> 10 NA Home 2165764.54 #> 11 NA Tools 2054959.14 #> 4 EMEA Home 1633026.36 #> 6 NA Baby 1521544.70 #> 5 EMEA Tools 1499974.62 #> 7 NA Clothing 1155514.38 #> 0 EMEA Baby 1146743.82 #> 1 EMEA Clothing 827751.30 narrative = narrate_descriptive(df_two) pprint.pprint(narrative) #> {'Product by Sales': 'Outlying Products by Sales are Food & Beverage ' #> '(12657934.2, 40.0%), Electronics (6971936.1, 22.0%).', #> 'Region by Sales': 'Outlying Region by Sales is NA (18079736.4, ' #> '56.99999999999999%).', #> 'Total Sales': 'Total Sales across all Regions is 31635149.12.'} narrative = narrate_descriptive(df_two, simplify = True) pprint.pprint(narrative) #> ['Total Sales across all Regions is 31635149.12.', #> 'Outlying Region by Sales is NA (18079736.4, 56.99999999999999%).', #> 'Outlying Products by Sales are Food & Beverage (12657934.2, 40.0%), ' #> 'Electronics (6971936.1, 22.0%).']"},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"changing-templates","dir":"Articles","previous_headings":"","what":"Changing Templates","title":"Editing Templates","text":"Template-based systems based calculations individual variables, combining together inside template. can return list calculated variables full narrative realization: Let’s change template narrative function rework wording well changing ‘’ ‘’ since Sales plural:","code":"df <- sales %>% group_by(Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) narrate_descriptive(df, coverage = 0.7, return_data = TRUE) #> $narrative #> $narrative$`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $narrative$`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %). #> #> #> $`Total Sales` #> $`Total Sales`$narrative_total #> Total Sales across all Products is 38790478.4. #> #> $`Total Sales`$template_total #> [1] \"Total {measure} across all {pluralize(dimension_one)} is {total}.\" #> #> $`Total Sales`$measure #> [1] \"Sales\" #> #> $`Total Sales`$dimension_one #> [1] \"Product\" #> #> $`Total Sales`$total #> [1] 38790478 #> #> $`Total Sales`$total_raw #> [1] 38790478 #> #> #> $`Product by Sales` #> $`Product by Sales`$narrative_outlier_final #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %). #> #> $`Product by Sales`$template_outlier_multiple #> [1] \"Outlying {pluralize(dimension)} by {measure} are {outlier_insight}.\" #> #> $`Product by Sales`$dimension #> [1] \"Product\" #> #> $`Product by Sales`$measure #> [1] \"Sales\" #> #> $`Product by Sales`$outlier_insight #> [1] \"Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %)\" #> #> $`Product by Sales`$n_outliers #> [1] 3 #> #> $`Product by Sales`$outlier_levels #> [1] \"Food & Beverage\" \"Electronics\" \"Home\" #> #> $`Product by Sales`$outlier_values #> [1] 15543470 8608963 4599371 #> #> $`Product by Sales`$outlier_values_p #> [1] \"40.1 %\" \"22.2 %\" \"11.9 %\" narrate_descriptive( df, template_total = \"Overall {measure} for all {pluralize(dimension_one)} are equal to {total}. \") #> $`Total Sales` #> Overall Sales for all Products are equal to 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with {measure} of {outlier_values}, making it {outlier_values_p} of total.\", template_outlier_multiple = \"{outlier_levels} are the biggest {dimension} by {measure} with {outlier_values} or {outlier_values_p} share of total {measure} respectively.\", measure = \"Sales\", dimensions = c(\"Region\", \"Product\"), coverage = 0.4) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Among Regions NA is an outlier, with Sales of 18079736.4, making it 46.6 % of total. #> #> $`NA by Product` #> In NA, significant Product by Sales is Food & Beverage (7392821, 40.9 %). #> #> $`Product by Sales` #> Among Products Food & Beverage is an outlier, with Sales of 15543469.7, making it 40.1 % of total."},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"r-environment","dir":"Articles","previous_headings":"Changing Templates","what":"R Environment","title":"Editing Templates","text":"can set templates using usethis::edit_r_environ() setting environment variable using data science platform capabilities. method little handy setting .Renviron variable names using certain convention adding use_renviron = TRUE narrate function. example created variable uses unique part function name, underscore, template name - descriptive + - + template_total","code":"Sys.getenv(\"descriptive_template_total\") narrate_descriptive( df, template_total = Sys.getenv(\"descriptive_template_total\") ) narrate_descriptive( df, use_renviron = TRUE ) #> $`Total Sales` #> Sales is equal to 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %)."},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"list-templates","dir":"Articles","previous_headings":"Changing Templates","what":"List Templates","title":"Editing Templates","text":"can get templates currently available package list_templates() function:","code":"list_templates() %>% kable()"},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"editing-gadget","dir":"Articles","previous_headings":"Changing Templates","what":"Editing Gadget","title":"Editing Templates","text":"Exploring templates might easy task, narrator allows prepare templates interactively using edit_templates() function.","code":"edit_templates()"},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"average-vs-others","dir":"Articles","previous_headings":"Changing Templates","what":"Average vs Others","title":"Editing Templates","text":"summarization set average way output calculation significantly different. Generally better way using outputs using different templates different summarization types. Giving users control template creation avoiding strict ruling look introduce additional complexity. example, use template_outlier default summarization = \"sum\" get great descriptive narrative: trying summarization = \"average\" get trouble, case compare values every level overall average Sales. Default templates handle using logic {outlier_insight} calculation. can using something like :","code":"sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with {measure} of {outlier_values}, making it {outlier_values_p} of total.\", measure = \"Sales\", dimensions = \"Region\", coverage = 0.3) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Among Regions NA is an outlier, with Sales of 18079736.4, making it 46.6 % of total. sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with {measure} of {outlier_values}, making it {outlier_values_p} of total.\", measure = \"Sales\", dimensions = \"Region\", summarization = \"average\", coverage = 0.3) #> $`Average Sales` #> Average Sales across all Regions is 3879. #> #> $`Region by Sales` #> Among Regions LATAM is an outlier, with Sales of 2303.3, making it -40.6 % of total. sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with average {measure} of {outlier_values}, {outlier_values_p} lower than average {measure} across all records.\", measure = \"Sales\", dimensions = \"Region\", summarization = \"average\", coverage = 0.3) #> $`Average Sales` #> Average Sales across all Regions is 3879. #> #> $`Region by Sales` #> Among Regions LATAM is an outlier, with average Sales of 2303.3, -40.6 % lower than average Sales across all records."},{"path":"https://denisabd.github.io/narrator/articles/trend.html","id":"year-over-year","dir":"Articles","previous_headings":"","what":"Year-over-Year","title":"Trend Narratives","text":"Default narrative returned analyzing year--date (YTD) vs prior year--date (PYTD) volumes, based data set date range. current year considered max date supplied data.","code":"df <- sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"month\")) %>% dplyr::group_by(Region, Product, Date) %>% dplyr::summarise(Sales = sum(Sales, na.rm = TRUE)) df %>% head() %>% kable() narrate_trend(df) #> $`2021 YTD vs 2020 YTD` #> From 2020 YTD to 2021 YTD, Sales had an increase of 1.13 M (9.1 %, 12.42 M to 13.55 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are NA (533.1 K, 9.1 %, 5.9 M to 6.4 M), EMEA (416.9 K, 9.91 %, 4.2 M to 4.6 M). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Food & Beverage (243.3 K, 9.92 %, 2.5 M to 2.7 M), Tools (186.8 K, 31.87 %, 585.9 K to 772.7 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Electronics (312.1 K, 35.88 %, 869.7 K to 1.2 M), Food & Beverage (238.2 K, 14.54 %, 1.6 M to 1.9 M). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Food & Beverage (535.4 K, 10.63 %, 5 M to 5.6 M), Electronics (525.9 K, 19.79 %, 2.7 M to 3.2 M)."},{"path":"https://denisabd.github.io/narrator/articles/trend.html","id":"previous-period","dir":"Articles","previous_headings":"","what":"Previous Period","title":"Trend Narratives","text":"Different time frame can selected using type argument narrate_trend() function. numeric string values accepted, 1 stands ‘yoy’, 2 ‘previous period’, 3 ‘period last year’. previous period selected, compare volumes December 2021 November 2021:","code":"narrate_trend(df, type = \"previous period\") #> $`Dec 2021 vs Nov 2021` #> From Nov 2021 to Dec 2021, Sales had an increase of 176.32 K (10.3 %, 1.71 M to 1.89 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are EMEA (154.2 K, 26.54 %, 580.8 K to 735 K), NA (-111 K, -13.14 %, 844.4 K to 733.4 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Food & Beverage (97.1 K, 45.41 %, 213.8 K to 310.9 K), Tools (60.1 K, 76.53 %, 78.6 K to 138.7 K). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Tools (-87.2 K, -55.54 %, 157 K to 69.8 K), Home (-51.4 K, -44.95 %, 114.3 K to 62.9 K). #> #> $`Sales change by Product` #> Product with biggest changes of Sales is Food & Beverage (197.2 K, 31.28 %, 630.6 K to 827.8 K)."},{"path":"https://denisabd.github.io/narrator/articles/trend.html","id":"same-period-last-year","dir":"Articles","previous_headings":"","what":"Same Period Last Year","title":"Trend Narratives","text":"Alternatively, can use numeric option, comfortable . function get December 2020 data comparison:","code":"narrate_trend(df, type = 3) #> $`Dec 2021 vs Dec 2020` #> From Dec 2020 to Dec 2021, Sales had an increase of 92.89 K (5.2 %, 1.79 M to 1.89 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are EMEA (184.3 K, 33.48 %, 550.6 K to 735 K), NA (-144.3 K, -16.44 %, 877.8 K to 733.4 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Food & Beverage (104.2 K, 50.43 %, 206.7 K to 310.9 K), Tools (78.5 K, 130.46 %, 60.2 K to 138.7 K). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Clothing (-71.6 K, -76.95 %, 93.1 K to 21.5 K), Home (-44.3 K, -41.31 %, 107.2 K to 62.9 K). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Food & Beverage (118.3 K, 16.67 %, 709.5 K to 827.8 K), Electronics (108.3 K, 36.23 %, 298.8 K to 407.1 K), Baby (-79.3 K, -33.91 %, 233.9 K to 154.6 K)."},{"path":"https://denisabd.github.io/narrator/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Denis Abdullin. Author, maintainer.","code":""},{"path":"https://denisabd.github.io/narrator/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Abdullin D (2023). narrator: Create Natural Language Text Narratives Data. R package version 0.1.0, https://denisabd.github.io/narrator/.","code":"@Manual{, title = {narrator: Create Natural Language Text Narratives from the Data}, author = {Denis Abdullin}, year = {2023}, note = {R package version 0.1.0}, url = {https://denisabd.github.io/narrator/}, }"},{"path":"https://denisabd.github.io/narrator/index.html","id":"narrator-","dir":"","previous_headings":"","what":"Create Natural Language Text Narratives from the Data","title":"Create Natural Language Text Narratives from the Data","text":"Template-based NLG framework creating text narratives data enhance using ChatGPT. Demo shiny application showing core package capabilities deployed shinyapps.io. Package available R Python, core features even syntax similar. Corresponding classes data types used languages: data.frame vs pandas data frame list vs dictionary character vector vs list","code":""},{"path":"https://denisabd.github.io/narrator/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Create Natural Language Text Narratives from the Data","text":"R can install development version narrator GitHub : Python install pynarrator pip:","code":"# install.packages(\"devtools\") devtools::install_github(\"denisabd/narrator\") pip3 install pynarrator"},{"path":[]},{"path":"https://denisabd.github.io/narrator/index.html","id":"basic-use-cases","dir":"","previous_headings":"","what":"Basic Use Cases","title":"Create Natural Language Text Narratives from the Data","text":"Simple tables one categorical columns (dimensions) one measure can transformed text using narrate_descriptive() function. can analyze changes time using narrate_trend() function:","code":"library(narrator) library(dplyr) narrative_one <- sales %>% narrate_descriptive( measure = \"Sales\", dimensions = c(\"Region\", \"Product\") ) narrative_one #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %), Electronics (3182803.4, 23.5 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). narrative_two <- sales %>% narrate_trend( measure = \"Sales\", date = \"Date\", dimensions = c(\"Region\", \"Product\") ) narrative_two #> $`2021 YTD vs 2020 YTD` #> From 2020 YTD to 2021 YTD, Sales had an increase of 1.13 M (9.1 %, 12.42 M to 13.55 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are NA (533.1 K, 9.1 %, 5.9 M to 6.4 M), EMEA (416.9 K, 9.91 %, 4.2 M to 4.6 M). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Food & Beverage (243.3 K, 9.92 %, 2.5 M to 2.7 M), Tools (190.5 K, 32.72 %, 582.2 K to 772.7 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Electronics (313.1 K, 36.05 %, 868.6 K to 1.2 M), Food & Beverage (244.8 K, 15.01 %, 1.6 M to 1.9 M). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Food & Beverage (535.4 K, 10.63 %, 5 M to 5.6 M), Electronics (525.9 K, 19.79 %, 2.7 M to 3.2 M)."},{"path":"https://denisabd.github.io/narrator/index.html","id":"chatgpt","dir":"","previous_headings":"","what":"ChatGPT","title":"Create Natural Language Text Narratives from the Data","text":"narrator can use ChatGPT API improve narratives. can either set use_chatgpt = TRUE function creates narrative use enhance_narrative() improve existing narrative output. can supply list character, function collapse text sentence send request Chat GPT. Set token .Renviron file OPENAI_API_KEY supply function openai_api_key argument. functionality requires setup ChatGPT API key make accessible R. Obtain ChatGPT API key. can create API key accessing OpenAI API page Best Practices API Key Safety Change .Renviron file usethis::edit_r_environ() adding `OPENAI_API_KEY=xx-xxxxxx` company achieved remarkable Total Sales figure 38790478.4 across Regions. Upon analysis, evident Outlying Regions, NA EMEA, contributed significantly commendable feat. NA recorded impressive figure 18079736.4, accounts 46.6% overall sales, whereas EMEA recorded 13555412.7, 34.9% total sales. Upon examination NA market, observed Food & Beverage emerged leading product category, accounting substantial figure 7392821, 40.9% sales. Furthermore, Electronics follows suit, impressive contribution 3789132.7, 21% total sales. Similarly, EMEA market depicts Food & Beverage dominant player terms sales figures, accounting whopping 5265113.2, constitutes 38.8% total sales. Electronics comes close second, contributing 3182803.4, 23.5% sales. Additionally, Food & Beverage emerges major contributor Outlying Products Sales, massive figure 15543469.7, accounts significant 40.1% overall sales. Electronics follows suit, contributing 8608962.8, 22.2% total sales. numbers highlight significance products overall success company’s sales figures.","code":"narrative_enhanced <- enhance_narrative(narrative_one) cat(narrative_enhanced)"},{"path":"https://denisabd.github.io/narrator/index.html","id":"translation","dir":"","previous_headings":"ChatGPT","what":"Translation","title":"Create Natural Language Text Narratives from the Data","text":"Translate text using translate_narrative() function, specify language argument English: Společnost dosáhla pozoruhodného celkového tržby ve výši 38790478,4 všech regionů. Z další analýzy je jasné, že odlehlé regiony, jako jsou NA EMEA, významně přispěly k tomuto pochvalnému úspěchu. NA zaznamenala skvělou částku 18079736,4, což představuje 46,6 % celkových prodejů, zatímco EMEA zapsala 13555412,7, což znamená 34,9 % celkových prodejů. Při zkoumání NA trhu je pozorováno, že potraviny nápoje se staly vedoucí kategorií produktů, představující podstatnou částku 7392821, což je 40,9 % prodejů. Elektronika následuje, s impozantním přínosem 3789132,7, což je 21 % celkových prodejů. Podobně se na trhu EMEA ukazuje, že potraviny nápoje jsou dominantním hráčem z hlediska prodejních čísel, představující ohromující 5265113,2, což představuje 38,8 % celkových prodejů. Elektronika následuje těsně za ní, přispívající 3182803,4, což je 23,5 % prodejů. Dodatečně se potraviny nápoje stávají hlavním přispěvatelem k prodejům odlehlých produktů, s obrovskou částkou 15543469,7, což představuje významných 40,1 % celkových prodejů. Elektronika následuje s přínosem 8608962,8, což je 22,2 % celkových prodejů. Tyto čísla zdůrazňují význam těchto produktů v celkovém úspěchu prodejů společnosti.","code":"translation <- translate_narrative(narrative_enhanced, language = \"Czech\") cat(translation)"},{"path":"https://denisabd.github.io/narrator/index.html","id":"summarization","dir":"","previous_headings":"ChatGPT","what":"Summarization","title":"Create Natural Language Text Narratives from the Data","text":"output verbose can summarize summarize_narrative() function: company achieved total sales $38,790,478.4 contributions NA EMEA regions. Food & Beverage dominated markets highest sales figures, totaling $15,543,469.7 $5,265,113.2, respectively. Electronics followed $8,608,962.8 $3,182,803.4 sales. products significant company’s overall sales success.","code":"summarization <- summarize_narrative(narrative_enhanced) cat(summarization)"},{"path":"https://denisabd.github.io/narrator/index.html","id":"python","dir":"","previous_headings":"","what":"Python","title":"Create Natural Language Text Narratives from the Data","text":"basic Python examples, details visit pynarrator github pynarrator website default narrate_descriptive() returns dictionary narratives names. simplify = True output list: return_data=True get list variables calculated inside function: functions, Chat GPT related calls similar R","code":"import os from pynarrator import narrate_descriptive, read_data, enhance_narrative, translate_narrative, summarize_narrative sales = read_data() narrate_descriptive( df = sales, measure = 'Sales', dimensions = ['Region', 'Product'], return_data = False, coverage = 0.5 ) narrate_descriptive( df = sales, measure = 'Sales', dimensions = 'Region', return_data = False, simplify = True, coverage = 0.5 ) narrative_two = narrate_descriptive( df = sales, measure = 'Sales', dimensions = 'Region', return_data = False, simplify = True, coverage = 0.5 ) pprint.pprint(narrative_two) narrate_descriptive( df = sales, measure = 'Sales', dimensions = ['Region', 'Product'], return_data = True, simplify = True, coverage = 0.5 ) narrative_enhanced = enhance_narrative(narrative_one) translation = translate_narrative(narrative_enhanced, language = \"Czech\") summarization = summarize_narrative(narrative_enhanced)"},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":null,"dir":"Reference","previous_headings":"","what":"Add HTML Tags to Text — add_tag","title":"Add HTML Tags to Text — add_tag","text":"Add HTML Tags Text","code":""},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add HTML Tags to Text — add_tag","text":"","code":"add_tag(text, tag = \"h3\")"},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add HTML Tags to Text — add_tag","text":"text Text string tag HTML tag like p, b, h1 ","code":""},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add HTML Tags to Text — add_tag","text":"glue character HTML tags","code":""},{"path":[]},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add HTML Tags to Text — add_tag","text":"","code":"add_tag(\"Title Text\", tag = \"h2\") #>

Title Text <\/h2> add_tag(\"bold text\", tag = \"b\") #> bold text <\/b>"},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":null,"dir":"Reference","previous_headings":"","what":"Clean HTML Tags from the Text — clean_tags","title":"Clean HTML Tags from the Text — clean_tags","text":"Clean HTML Tags Text","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Clean HTML Tags from the Text — clean_tags","text":"","code":"clean_tags(html_string)"},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Clean HTML Tags from the Text — clean_tags","text":"html_string Text html tags","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Clean HTML Tags from the Text — clean_tags","text":"character() vector text strings without tags","code":""},{"path":[]},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Clean HTML Tags from the Text — clean_tags","text":"","code":"clean_tags(\"Total increase is equal to 14.5 % <\/b>\") #> [1] \"Total increase is equal to 14.5 %\" clean_tags(\"

Sales by Region<\/h3>\") #> [1] \"Sales by Region\""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Clean Text String — clean_text","title":"Clean Text String — clean_text","text":"Function cleans text string improving narration, removing excessive white spaces","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Clean Text String — clean_text","text":"","code":"clean_text( text, upper = c(\"YTD\", \"PYTD\"), lower = c(\"vs\", \"br>\", \"h1>\", \"h2>\", \"h3>\", \"h4>\", \"h5>\", \"h6>\", \"b>\") )"},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Clean Text String — clean_text","text":"text Text string cleaning. Can contain multiple sentences. upper Vector words need changed uppercase text lower Vector words need changed lowercase text","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Clean Text String — clean_text","text":"Text string","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Clean Text String — clean_text","text":"","code":"text <- \"Similarly in 2020 the sum of spend increased by 15.4% ( 4.3 % higher than average).\" clean_text(text) #> [1] \"Similarly in 2020 the sum of spend increased by 15.4 % (4.3 % higher than average).\" clean_text(\" Total is 12,300 Orders ( 23.5 % for East ) \") #> [1] \"Total is 12,300 Orders (23.5 % for East)\""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Correct the Sentence Using UDPIPE — correct_text","title":"Correct the Sentence Using UDPIPE — correct_text","text":"Correct Sentence Using UDPIPE","code":""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Correct the Sentence Using UDPIPE — correct_text","text":"","code":"correct_text(text, language = \"english\", download_udpipe = TRUE, measure = \"\")"},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Correct the Sentence Using UDPIPE — correct_text","text":"text Text string correction language Language udpipe model, defaults 'english' download_udpipe Download udpipe working directory measure Measure template","code":""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Correct the Sentence Using UDPIPE — correct_text","text":"Text string","code":""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Correct the Sentence Using UDPIPE — correct_text","text":"","code":"correct_text(\"In 2020 total Sales across all Regions (EMEA, NA, ASPAC) is equal to 23.5 M\") #> Loading required namespace: udpipe #> [1] \"In 2020 total Sales across all Regions ( EMEA , NA , ASPAC ) are equal to 23.5 MS\" correct_text(\"Total Profit across all Regions are 85 M\") #> [1] \"Total Profit across all Regions is 85 M\""},{"path":"https://denisabd.github.io/narrator/reference/edit_templates.html","id":null,"dir":"Reference","previous_headings":"","what":"Interactively Edit Package Templates — edit_templates","title":"Interactively Edit Package Templates — edit_templates","text":"Interactively Edit Package Templates","code":""},{"path":"https://denisabd.github.io/narrator/reference/edit_templates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Interactively Edit Package Templates — edit_templates","text":"","code":"edit_templates()"},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":null,"dir":"Reference","previous_headings":"","what":"Enhance the narrative output with ChatGPT — enhance_narrative","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"Enhance narrative output ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"","code":"enhance_narrative( narrative, prompt = \"Improve the narrative by adding better business language for the following:\", openai_api_key = Sys.getenv(\"OPENAI_API_KEY\") )"},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"narrative List narratives returned narrate_* function, character vector string enhanced ChatGPT prompt Prompt send OpenAI API openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\")","code":""},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"character() narratives enhanced ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"","code":"if (FALSE) { narrative <- sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% narrate_descriptive() enhance_narrative(narrative) }"},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":null,"dir":"Reference","previous_headings":"","what":"Format Numeric Values — format_num","title":"Format Numeric Values — format_num","text":"Format Numeric Values","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Format Numeric Values — format_num","text":"","code":"format_num( num, format = \"auto\", decimals = 1, threshold = 10000, format_list = c(\"\", \"K\", \"M\", \"B\", \"T\") )"},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Format Numeric Values — format_num","text":"num Number numeric vector format Format numeric output - \"auto\", \"K\", \"M\", \"B\" \"T\" decimals Number decimal numbers rounding threshold Threshold converting specific format, threshold thousand delimiters added format_list List formats use automated","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Format Numeric Values — format_num","text":"character() vector","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Format Numeric Values — format_num","text":"","code":"format_num(27334254) #> [1] \"27.3 M\" format_num(c(27334254, 12332, 23425435534)) #> [1] \"27.3 M\" \"12.3 K\" \"23.4 B\""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":null,"dir":"Reference","previous_headings":"","what":"Format numeric value — format_number","title":"Format numeric value — format_number","text":"Format numeric value","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Format numeric value — format_number","text":"","code":"format_number( num, format = \"auto\", decimals = 1, threshold = 10000, format_list = c(\"\", \"K\", \"M\", \"B\", \"T\") )"},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Format numeric value — format_number","text":"num Number numeric vector format Format numeric output - \"auto\", \"K\", \"M\", \"B\" \"T\" decimals Number decimal numbers rounding threshold Threshold converting specific format, threshold thousand delimiters added format_list List formats use automated","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Format numeric value — format_number","text":"vector numerics","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Format numeric value — format_number","text":"","code":"format_number(27334254) #> [1] \"27.3 M\" format_number(c(27334254, 12332, 23425435534)) #> [1] \"27.3 M\" \"12.3 K\" \"23.4 B\""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":null,"dir":"Reference","previous_headings":"","what":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"Add HTML Tags Colors Percentage Values Text","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"","code":"format_pct(text, positive = \"green\", negative = \"red\")"},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"text Text string character vector/list text strings positive Color highlight percentage increase negative Color highlight percentage decline","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"list() text strings","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"","code":"text <- \"Spend increased by 13.2 % in EMEA but decreased by -13.2 % in LATAM\" format_pct(text) #> [[1]] #> [1] \"Spend increased by 13.2 %<\/span> <\/b> in EMEA but decreased by -13.2 %<\/span> <\/b> in LATAM\" #>"},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Add HTML Tags to Add Color and Boldness — format_text","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"Function adds html code around selected string adding options colorized /bold display HTML documents.","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"","code":"format_text(text, color = \"auto\", bold = TRUE)"},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"text Text string want format color Color name, \"auto\" color determined based number parsed - red negative, green positive bold Make text bold ","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"text HTML tags","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"","code":"text <- format_text(\"1.2%\", color = \"auto\", bold = TRUE) text #> [1] \" 1.2%<\/span> <\/b>\""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":null,"dir":"Reference","previous_headings":"","what":"Get Date Frequency of the Data — get_frequency","title":"Get Date Frequency of the Data — get_frequency","text":"Function group data estimate frequency time stamps, returning 'year', 'quarter', 'month', 'week' 'day'. can use raw aggregated data frames","code":""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get Date Frequency of the Data — get_frequency","text":"","code":"get_frequency(df, date_field = NULL)"},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get Date Frequency of the Data — get_frequency","text":"df data.frame() tibble() Data frame tibble, can aggregated raw date_field Date field analyzed, default first date-like column used","code":""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get Date Frequency of the Data — get_frequency","text":"frequency - \"quarter\", \"month\", \"week\" \"day\"","code":""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get Date Frequency of the Data — get_frequency","text":"","code":"sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"month\")) %>% get_frequency() #> [1] \"month\" sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"week\")) %>% get_frequency() #> [1] \"week\" sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"quarter\")) %>% dplyr::group_by(Region, Date) %>% dplyr::summarise(Sales = sum(Sales, na.rm = TRUE)) %>% get_frequency() #> [1] \"quarter\" get_frequency(sales) #> [1] \"day\""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":null,"dir":"Reference","previous_headings":"","what":"Test Plural State of an English Word — is_plural","title":"Test Plural State of an English Word — is_plural","text":"Test Plural State English Word","code":""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Test Plural State of an English Word — is_plural","text":"","code":"is_plural(x) is_singular(x)"},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Test Plural State of an English Word — is_plural","text":"x vector words test","code":""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Test Plural State of an English Word — is_plural","text":"logical vector","code":""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Test Plural State of an English Word — is_plural","text":"","code":"is_singular(c(\"boats\", \"house\", \"cats\", \"river\")) #> [1] FALSE TRUE FALSE TRUE is_plural(c(\"boats\", \"house\", \"cats\", \"river\")) #> [1] TRUE FALSE TRUE FALSE"},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":null,"dir":"Reference","previous_headings":"","what":"Return a Table of all Templates Currently Available in the Package — list_templates","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"Return Table Templates Currently Available Package","code":""},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"","code":"list_templates()"},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"tibble templates functions packages","code":""},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"","code":"list_templates() #> # A tibble: 12 × 4 #> fun type name template #> #> 1 narrate_descriptive descriptive template_total Total {measure}… #> 2 narrate_descriptive descriptive template_average Average {measur… #> 3 narrate_descriptive descriptive template_outlier Outlying {dimen… #> 4 narrate_descriptive descriptive template_outlier_multiple Outlying {plura… #> 5 narrate_descriptive descriptive template_outlier_l2 In {level_l1}, … #> 6 narrate_descriptive descriptive template_outlier_l2_multiple In {level_l1}, … #> 7 narrate_trend trend template_total From {timeframe… #> 8 narrate_trend trend template_average Average {measur… #> 9 narrate_trend trend template_outlier {dimension} wit… #> 10 narrate_trend trend template_outlier_multiple {pluralize(dime… #> 11 narrate_trend trend template_outlier_l2 In {level_l1}, … #> 12 narrate_trend trend template_outlier_l2_multiple In {level_l1}, …"},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Descriptive Narrative — narrate_desc","title":"Create Descriptive Narrative — narrate_desc","text":"Create Descriptive Narrative","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Descriptive Narrative — narrate_desc","text":"","code":"narrate_desc( df, measure = NULL, dimensions = NULL, coverage = 0.5, coverage_limit = 5, narrative_total = \"{measure} across all {pluralize(dimension1)} is {total}. \", narrative_outlier = \"Outlying {dimension} by {measure} is {outlier_insight}. \", narrative_outlier_multiple = \"Outlying {pluralize(dimension)} by {measure} are {outlier_insight}. \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Descriptive Narrative — narrate_desc","text":"...","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Descriptive Narrative — narrate_desc","text":"","code":"sales %>% narrate_desc(measure = \"Sales\", dimensions = c(\"Territory\", \"State\")) #> Sales across all Territories is 10032628.85. Outlying Territory by Sales is EMEA (5 M, 49.6%). Outlying State by Sales is ."},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Descriptive Text Narratives from Data — narrate_descriptive","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"narrate_descriptive() creates text narratives data frame containing one numeric one character factor text columns using glue syntax. Function can work raw aggregated data frame. automatically use first numeric column measure character factor columns dimensions","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"","code":"narrate_descriptive( df, measure = NULL, dimensions = NULL, summarization = \"sum\", coverage = 0.5, coverage_limit = 5, narration_depth = 2, use_chatgpt = FALSE, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\"), template_total = \"Total {measure} across all {pluralize(dimension_one)} is {total}.\", template_average = \"Average {measure} across all {pluralize(dimension_one)} is {total}.\", template_outlier = \"Outlying {dimension} by {measure} is {outlier_insight}.\", template_outlier_multiple = \"Outlying {pluralize(dimension)} by {measure} are {outlier_insight}.\", template_outlier_l2 = \"In {level_l1}, significant {level_l2} by {measure} is {outlier_insight}.\", template_outlier_l2_multiple = \"In {level_l1}, significant {pluralize(level_l2)} by {measure} are {outlier_insight}.\", use_renviron = FALSE, return_data = FALSE, simplify = FALSE, format_numbers = FALSE, collapse_sep = \", \", collapse_last = \" and \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"df data.frame() tibble() Data frame tibble, can aggregated raw measure Numeric measure function create calculations , NULL take first numeric field available dimensions Vector dimensions analysis, default character factor variable used summarization Approach data summarization/aggregation - 'sum', 'count' 'average' coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation narration_depth Parameter control depth analysis 1 summary 2 detailed use_chatgpt TRUE - use ChatGPT enhance narrative openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\") template_total glue template total volumes narrative template_average glue template average volumes narrative template_outlier glue template single outlier narrative template_outlier_multiple glue template multiple outliers narrative template_outlier_l2 glue template deeper hierarchical single outlier narrative template_outlier_l2_multiple glue template deeper hierarchical multiple outliers narrative use_renviron TRUE use .Renviron variables template. can also set options(narrator.use_renviron = TRUE) make global session, create environment variable \"use_renviron\" changing .Renviron file usethis::edit_r_environ() return_data TRUE - return list variables used function's templates simplify TRUE - return character vector, FALSE - named list format_numbers TRUE - format big numbers K/M/B using format_num() function collapse_sep Separator glue_collapse cases multiple values single variable collapse_last Separator glue_collapse last item, cases multiple values single variable ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"list() narratives default character() simplify = TRUE","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"","code":"sales %>% narrate_descriptive(measure = \"Sales\", dimensions = c(\"Region\", \"Product\")) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %), Electronics (3182803.4, 23.5 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). #> sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Quantity = sum(Quantity)) %>% narrate_descriptive() #> $`Total Quantity` #> Total Quantity across all Products is 65653. #> #> $`Product by Quantity` #> Outlying Products by Quantity are Home (26697, 40.7 %), Tools (25457, 38.8 %). #> #> $`Home by Region` #> In Home, significant Regions by Quantity are NA (12204, 45.7 %), EMEA (8693, 32.6 %). #> #> $`Tools by Region` #> In Tools, significant Regions by Quantity are NA (11253, 44.2 %), EMEA (8216, 32.3 %). #> #> $`Region by Quantity` #> Outlying Regions by Quantity are NA (29819, 45.4 %), EMEA (21249, 32.4 %). #> sales %>% narrate_descriptive(measure = \"Order ID\", dimensions = \"Region\", summarization = \"count\") #> $`Total Order ID` #> Total Order ID across all Regions is 10000. #> #> $`Region by Order ID` #> Outlying Regions by Order ID are NA (3975, 39.8 %), EMEA (2986, 29.9 %). #>"},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Narrative for Metric Development in Time — narrate_trend","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"Create Narrative Metric Development Time","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"","code":"narrate_trend( df, measure = NULL, dimensions = NULL, date = NULL, frequency = NULL, summarization = \"sum\", type = \"yoy\", coverage = 0.5, coverage_limit = 5, narration_depth = 2, use_chatgpt = FALSE, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\"), template_total = \"From {timeframe_prev} to {timeframe_curr}, {measure} had an {trend} of {change} ({change_p}, {total_prev} to {total_curr}).\", template_average = \"Average {measure} had an {trend} of {change} ({change_p}, {total_prev} to {total_curr}).\", template_outlier = \"{dimension} with biggest changes of {measure} is {outlier_insight}.\", template_outlier_multiple = \"{pluralize(dimension)} with biggest changes of {measure} are {outlier_insight}.\", template_outlier_l2 = \"In {level_l1}, significant {level_l2} by {measure} change is {outlier_insight}.\", template_outlier_l2_multiple = \"In {level_l1}, significant {pluralize(level_l2)} by {measure} change are {outlier_insight}.\", use_renviron = FALSE, return_data = FALSE, simplify = FALSE, format_numbers = TRUE, collapse_sep = \", \", collapse_last = \" and \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"df data.frame() tibble() Data frame tibble, can aggregated raw measure Numeric measure function create calculations , NULL take first numeric field available dimensions Vector dimensions analysis, default character factor variable used date Name date column used time based analysis frequency Level time based aggregation comparing across years summarization Approach data summarization/aggregation - 'sum', 'count' 'average' type Type trend analysis create: 1 'yoy', 2 'previous period', 3 'period last year' coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation narration_depth Parameter control depth analysis 1 summary 2 detailed use_chatgpt TRUE - use ChatGPT enhance narrative openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\") template_total glue template total volumes narrative template_average glue template average volumes narrative template_outlier glue template single outlier narrative template_outlier_multiple glue template multiple outliers narrative template_outlier_l2 glue template deeper hierarchical single outlier narrative template_outlier_l2_multiple glue template deeper hierarchical multiple outliers narrative use_renviron TRUE use .Renviron variables template. can also set options(narrator.use_renviron = TRUE) make global session, create environment variable \"use_renviron\" changing .Renviron file usethis::edit_r_environ() return_data TRUE - return list variables used function's templates simplify TRUE - return character vector, FALSE - named list format_numbers TRUE - format big numbers K/M/B using format_num() function collapse_sep Separator glue_collapse cases multiple values single variable collapse_last Separator glue_collapse last item, cases multiple values single variable ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"list() narratives default character() simplify = TRUE","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"","code":"sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"week\")) %>% dplyr::group_by(Region, Product, Date) %>% dplyr::summarise(Sales = sum(Sales, na.rm = TRUE)) %>% narrate_trend() #> $`2021 YTD vs 2020 YTD` #> From 2020 YTD to 2021 YTD, Sales had an increase of 1.08 M (8.7 %, 12.42 M to 13.5 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are NA (520.6 K, 8.89 %, 5.9 M to 6.4 M), EMEA (386.6 K, 9.17 %, 4.2 M to 4.6 M). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Food & Beverage (239.3 K, 9.76 %, 2.5 M to 2.7 M), Tools (189.6 K, 32.51 %, 583.2 K to 772.7 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Electronics (310.4 K, 35.72 %, 868.9 K to 1.2 M), Food & Beverage (223.4 K, 13.61 %, 1.6 M to 1.9 M). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Electronics (529.1 K, 19.95 %, 2.7 M to 3.2 M), Food & Beverage (507.9 K, 10.07 %, 5 M to 5.6 M). #>"},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":null,"dir":"Reference","previous_headings":"","what":"Server Logic for Narrator — narratorServer","title":"Server Logic for Narrator — narratorServer","text":"Server logic shiny module work together narratorUI","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Server Logic for Narrator — narratorServer","text":"","code":"narratorServer(id, df, summarization = \"sum\", ...)"},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Server Logic for Narrator — narratorServer","text":"id Namespace specification df Reactive data frame summarization Summarization/aggregation data - 'sum', 'count' 'average' ... Additional arguments narrate_* functions","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Server Logic for Narrator — narratorServer","text":"Narrative output","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Server Logic for Narrator — narratorServer","text":"","code":"library(shiny) library(narrator) library(dplyr) #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union df <- sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) ui <- fluidPage( narratorUI(id = \"main\") ) server <- function(input, output, session) { narratorServer( id = \"main\", df = reactive(df), format = TRUE, summarization = \"sum\") } if (interactive()) shinyApp(ui, server)"},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":null,"dir":"Reference","previous_headings":"","what":"Shiny Module for Narrator — narratorUI","title":"Shiny Module for Narrator — narratorUI","text":"UI shiny module work together narratorServer","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Shiny Module for Narrator — narratorUI","text":"","code":"narratorUI( id, narration_depth = 2, coverage = 0.5, coverage_limit = 5, format = TRUE, ... )"},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Shiny Module for Narrator — narratorUI","text":"id Namespace specification narration_depth Parameter control depth analysis 1 summary 2 detailed coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation format TRUE - format text HTML tags ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Shiny Module for Narrator — narratorUI","text":"UI","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Shiny Module for Narrator — narratorUI","text":"","code":"library(shiny) library(narrator) library(dplyr) df <- sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) ui <- fluidPage( narratorUI(id = \"main\") ) server <- function(input, output, session) { narratorServer( id = \"main\", df = reactive(df), format = TRUE, summarization = \"sum\") } if (interactive()) shinyApp(ui, server)"},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":null,"dir":"Reference","previous_headings":"","what":"UI Module for Narrator — narrator_shiny","title":"UI Module for Narrator — narrator_shiny","text":"UI shiny module work together narratorServer Server logic shiny module work together narratorUI","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"UI Module for Narrator — narrator_shiny","text":"","code":"narratorUI( id, narration_depth = 2, coverage = 0.5, coverage_limit = 5, format = TRUE, ... ) narratorServer(id, df, summarization = \"sum\", format = TRUE, ...)"},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"UI Module for Narrator — narrator_shiny","text":"id Namespace specification format TRUE - format text HTML tags ... Additional arguments narrate_* functions df Reactive data frame","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"UI Module for Narrator — narrator_shiny","text":"UI Narrative output","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"UI Module for Narrator — narrator_shiny","text":"","code":"library(shiny) library(narrator) library(dplyr) #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union df <- sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) #> `summarise()` has grouped output by 'Region'. You can override using the #> `.groups` argument. ui <- fluidPage( narratorUI(id = \"main\") ) server <- function(input, output, session) { narratorServer( id = \"main\", df = reactive(df), format = TRUE, summarization = \"sum\") } if (interactive()) shinyApp(ui, server)"},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":null,"dir":"Reference","previous_headings":"","what":"Pipe Operator — %>%","title":"Pipe Operator — %>%","text":"See magrittr::%>% details.","code":""},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Pipe Operator — %>%","text":"","code":"lhs %>% rhs"},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Pipe Operator — %>%","text":"lhs value magrittr placeholder. rhs function call using magrittr semantics.","code":""},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Pipe Operator — %>%","text":"result calling rhs(lhs).","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":null,"dir":"Reference","previous_headings":"","what":"Pluralize a Word in English — pluralize","title":"Pluralize a Word in English — pluralize","text":"Pluralize Word English","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Pluralize a Word in English — pluralize","text":"","code":"pluralize(x, n = 2, prepend = FALSE)"},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Pluralize a Word in English — pluralize","text":"x character vector words make plural n number plural (plurals change amount also impacts prepend functionality) prepend prepend value n output? Default: FALSE","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Pluralize a Word in English — pluralize","text":"character vector modified pluralized words","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Pluralize a Word in English — pluralize","text":"","code":"pluralize('test') #> [1] \"tests\" pluralize('test', 5) #> [1] \"tests\" pluralize('test', 5, TRUE) #> [1] \"5 tests\" pluralize('regex') #> [1] \"regexes\""},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":null,"dir":"Reference","previous_headings":"","what":"Synthetic Sales Data — sales","title":"Synthetic Sales Data — sales","text":"Synthetic Sales Data","code":""},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Synthetic Sales Data — sales","text":"","code":"sales"},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Synthetic Sales Data — sales","text":"tibble 10000 rows 9 variables: Order ID Unique ID order Date Date Order creation Region Region/Region shipment Product Product Name Store Store size - Big, Medium Small Promotion Promotion present Price Raw unit price quantity Quantity Number units sold Sales Final Sales, including promotional discounts","code":""},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Synthetic Sales Data — sales","text":"","code":"sales #> # A tibble: 10,000 × 9 #> `Order ID` Date Region Product Store Promo…¹ Price Quant…² Sales #> #> 1 QR10276 2019-01-30 EMEA Tools Big 1 89.6 28 2007. #> 2 QR15245 2020-07-26 ASPAC Tools Big 0 268. 7 1880. #> 3 QR13938 2020-03-05 EMEA Home Big 0 223. 18 4019. #> 4 QR15934 2020-10-08 LATAM Clothing Big 0 210. 27 5681. #> 5 QR10963 2019-04-15 EMEA Tools Big 0 193. 22 4248. #> 6 QR13639 2020-01-30 EMEA Food & Bever… Small 0 215. 8 1717. #> 7 QR13110 2019-12-04 LATAM Electronics Medi… 0 250. 22 5498. #> 8 QR19849 2021-12-13 EMEA Tools Big 0 223 59 13157 #> 9 QR13078 2019-12-01 EMEA Electronics Big 0 231 32 7392 #> 10 QR15064 2020-07-08 EMEA Tools Medi… 0 185. 21 3889. #> # … with 9,990 more rows, and abbreviated variable names ¹​Promotion, ²​Quantity"},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":null,"dir":"Reference","previous_headings":"","what":"Singularize a Word in English — singularize","title":"Singularize a Word in English — singularize","text":"Singularize Word English","code":""},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Singularize a Word in English — singularize","text":"","code":"singularize(x)"},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Singularize a Word in English — singularize","text":"x vector words make singular","code":""},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Singularize a Word in English — singularize","text":"modified character vector singularized words","code":""},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Singularize a Word in English — singularize","text":"","code":"singularize('test') #> [1] \"test\" singularize(c(\"boats\", \"houses\", \"cats\", \"rivers\")) #> [1] \"boat\" \"house\" \"cat\" \"river\" pluralize(singularize(c(\"boats\", \"houses\", \"cats\", \"rivers\"))) #> [1] \"boats\" \"houses\" \"cats\" \"rivers\" singularize(c(\"buses\", \"wishes\", \"pitches\", \"boxexs\")) #> [1] \"bus\" \"wish\" \"pitch\" \"boxex\" pluralize(singularize(c(\"buses\", \"wishes\", \"pitches\", \"boxexs\"))) #> [1] \"buses\" \"wishes\" \"pitches\" \"boxexes\" singularize(c(\"pennies\", \"spies\", \"babies\", \"cities\", \"daisies\")) #> [1] \"penny\" \"spy\" \"baby\" \"city\" \"daisie\" pluralize(singularize(c(\"pennies\", \"spies\", \"babies\", \"cities\", \"daisies\"))) #> [1] \"pennies\" \"spies\" \"babies\" \"cities\" \"daisies\" singularize(c(\"sheep\", \"fish\", \"deer\", \"species\", \"aircraft\")) #> [1] \"sheep\" \"fish\" \"deer\" \"specie\" \"aircraft\" pluralize(singularize(c(\"sheep\", \"fish\", \"deer\", \"species\", \"aircraft\"))) #> [1] \"sheep\" \"fish\" \"deer\" \"species\" \"aircraft\""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":null,"dir":"Reference","previous_headings":"","what":"Summarize the narrative output with ChatGPT — summarize_narrative","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"Summarize narrative output ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"","code":"summarize_narrative( narrative, prompt = \"Summarize the following narrative to make it shorter:\", openai_api_key = Sys.getenv(\"OPENAI_API_KEY\") )"},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"narrative List narratives returned narrate_* function, character vector string enhanced ChatGPT prompt Prompt send OpenAI API openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\")","code":""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"character() narratives enhanced ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"","code":"if (FALSE) { narrative <- sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% narrate_descriptive() narrative <- enhance_narrative(narrative) summarize_narrative(narrative) }"},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":null,"dir":"Reference","previous_headings":"","what":"Translate the narrative output with ChatGPT — translate_narrative","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"Translate narrative output ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"","code":"translate_narrative( narrative, prompt = \"Using professional language translate the following text to\", language, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\") )"},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"narrative List narratives returned narrate_* function, character vector string enhanced ChatGPT prompt Prompt send OpenAI API language Write language translate narrative , please use English , ex. \"Spanish\" \"Español\" openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\")","code":""},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"character() narratives enhanced ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"","code":"if (FALSE) { narrative <- sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% narrate_descriptive() narrative <- enhance_narrative(narrative) translate_narrative(narrative, \"Spanish\") }"},{"path":"https://denisabd.github.io/narrator/news/index.html","id":"narrator-010","dir":"Changelog","previous_headings":"","what":"narrator 0.1.0","title":"narrator 0.1.0","text":"CRAN Release Core functions narrative creation: narrate_descriptive(), narrate_trend() Output formatting functions rendering HTML Rmarkdown shiny OpenAI API, ChatGPT accessible improving, translating summarizing narratives","code":""}] +[{"path":"https://denisabd.github.io/narrator/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 Denis Abdullin Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"r","dir":"Articles","previous_headings":"","what":"R","title":"Descriptive Narratives","text":"","code":"library(narrator) library(dplyr) library(knitr)"},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"simple-table","dir":"Articles","previous_headings":"R","what":"Simple Table","title":"Descriptive Narratives","text":"Starting simplest table one dimension one measure. overall sales volume well outlying Territories analyzed.","code":"df_one <- sales %>% group_by(Region) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_one) narrate_descriptive(df_one) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"summarization","dir":"Articles","previous_headings":"R","what":"Summarization","title":"Descriptive Narratives","text":"multiple summarization/aggregation options data frame, controlled summarization argument can sum, count average","code":"sales %>% narrate_descriptive( measure = \"Sales\", dimensions = \"Region\", summarization = \"count\" ) #> $`Total Sales` #> Total Sales across all Regions is 9026. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (3821, 39.4 %), EMEA (2883, 29.8 %). sales %>% narrate_descriptive( measure = \"Sales\", dimensions = \"Region\", summarization = \"average\" ) #> $`Average Sales` #> Average Sales across all Regions is 3879. #> #> $`Region by Sales` #> Outlying Regions by Sales are LATAM (2303.3, -40.6 % vs average Sales), ASPAC (2398.6, -38.2 % vs average Sales)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"multiple-dimensions","dir":"Articles","previous_headings":"R","what":"Multiple Dimensions","title":"Descriptive Narratives","text":"","code":"df_two <- sales %>% filter(Region %in% c(\"NA\", \"EMEA\")) %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_two) narrate_descriptive(df_two) #> $`Total Sales` #> Total Sales across all Regions is 31635149.1. #> #> $`Region by Sales` #> Outlying Region by Sales is NA (18079736.4, 57.2 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (12657934.2, 40 %), Electronics (6971936.1, 22 %)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"depth","dir":"Articles","previous_headings":"R","what":"Depth","title":"Descriptive Narratives","text":"Narration depth can controlled narration_depth argument. get summary narratives set narration_depth = 1","code":"narrate_descriptive( df_two, narration_depth = 1 ) #> $`Total Sales` #> Total Sales across all Regions is 31635149.1. #> #> $`Region by Sales` #> Outlying Region by Sales is NA (18079736.4, 57.2 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (12657934.2, 40 %), Electronics (6971936.1, 22 %)."},{"path":"https://denisabd.github.io/narrator/articles/descriptive.html","id":"coverage","dir":"Articles","previous_headings":"R","what":"Coverage","title":"Descriptive Narratives","text":"Key argument narratives coverage. used narrate important things avoid simple looping dimension levels. default coverage set 0.5 means narration stop soon cumulative sum reaches 50 % mark. increased coverage, additional narrative returned.","code":"df_three <- sales %>% group_by(Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) df_three %>% mutate( Share = round(Sales/sum(Sales)*100, 1), Cumulative = cumsum(Share)) %>% kable() narrate_descriptive(df_three) #> $`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). narrate_descriptive(df_three, coverage = 0.7) #> $`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %)."},{"path":"https://denisabd.github.io/narrator/articles/echarts.html","id":"simple-plots","dir":"Articles","previous_headings":"","what":"Simple Plots","title":"Narrate Echarts Plots","text":"Let’s create bar plot sales data: can extract underlying data plot object using echarts4r::e_get_data() function convert tibble suitable narrative extraction. can add narrative plot echarts4r::e_text_g() can done scatter plot pie chart, scatter narrate_descriptive() take first numeric measure.","code":"barplot <- sales %>% dplyr::group_by(Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% echarts4r::e_chart(Region) %>% echarts4r::e_bar(Sales) %>% echarts4r::e_tooltip() barplot bar_narrative <- barplot %>% echarts4r::e_get_data() %>% purrr::map_df(bind_rows) %>% narrate_descriptive() bar_narrative #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). bar_narrative <- bar_narrative %>% unlist(use.names = FALSE) %>% paste(\"\\n\", collapse = \"\") barplot %>% echarts4r::e_text_g( style = list( text = bar_narrative, fontSize = 16 ), left = \"2%\", top = \"3%\", rotation = 0 ) scatterplot <- sales %>% dplyr::group_by(Region, Product) %>% dplyr::summarise(Sales = sum(Sales), Quantity = sum(Quantity), Price = mean(Price), .groups = \"keep\") %>% echarts4r::e_chart(Sales) %>% echarts4r::e_scatter(Quantity, Price) %>% echarts4r::e_tooltip() scatterplot scatterplot %>% echarts4r::e_get_data() %>% purrr::map_df(bind_rows) %>% narrate_descriptive() #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %), Electronics (3182803.4, 23.5 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). piechart <- sales %>% dplyr::group_by(Product) %>% dplyr::summarise(Sales = sum(Sales)) %>% echarts4r::e_chart(Product) %>% echarts4r::e_pie(Sales, radius = c(\"50%\", \"70%\")) %>% echarts4r::e_tooltip() piechart piechart %>% echarts4r::e_get_data() %>% purrr::map_df(bind_rows) %>% narrate_descriptive() #> $`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %)."},{"path":"https://denisabd.github.io/narrator/articles/forecast.html","id":"overall-forecast","dir":"Articles","previous_headings":"","what":"Overall Forecast","title":"Forecast Narratives","text":"data.frame time series forecast actuals time, use narrate_forecast() create narrative around overall forecast, anticipated changes next time period current year volumes. Let’s use prophet example. Notice require data frame , using ts objects, please make relevant conversions first. Actuals recent year, overall forecast next year (available forecast data frame) projected YoY change next vs last twelve months:","code":"fit_prophet <- function(data) { model <- prophet::prophet(data) future <- prophet::make_future_dataframe(model, periods = 12, freq = \"month\") forecast <- predict(model, future) return(forecast) } grouped_data <- sales %>% dplyr::mutate(ds = lubridate::floor_date(Date, unit = \"month\")) %>% dplyr::group_by(Region, ds) %>% dplyr::summarise(y = sum(Sales, na.rm = TRUE)) %>% tidyr::nest() grouped_data$forecast <- lapply(grouped_data$data, fit_prophet) actuals <- grouped_data %>% dplyr::select(-forecast) %>% tidyr::unnest(data) df <- grouped_data %>% dplyr::select(-data) %>% tidyr::unnest(forecast) %>% dplyr::select(ds, yhat) %>% dplyr::left_join(actuals) %>% dplyr::rename(Actuals = y, Forecast = yhat) df %>% head() %>% kable() narrate_forecast(df, forecast = \"Forecast\", actuals = \"Actuals\") #> $`Current Year Actuals` #> Actuals for 2021 are equal to 13.5 M #> #> $`Overall Forecast in the next 12 months` #> Overall forecast for the next 12 months is 13.8 M #> #> $`Overall increase the next 12 months` #> Projected increase in the next 12 months is equal to 447.7 K (3.3%)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"descriptive-narrative","dir":"Articles","previous_headings":"","what":"Descriptive Narrative","title":"Introducing narrator","text":"Basic narrative type descriptive stats, looking outliers biggest contributors total volumes data set. narratives quite useful can help look deeper data set hierarchy.","code":""},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"simple-table","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Simple Table","title":"Introducing narrator","text":"Starting simplest table one dimension one measure. overall sales volume well outlying Territories analyzed.","code":"df_one <- sales %>% group_by(Region) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_one) narrate_descriptive(df_one) #> $`Total Sales` #> Total Sales across all Regions: 2.1 M. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (1 M, 47.4 %), EMEA (655.4 K, 30.7 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"multiple-dimensions","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Multiple Dimensions","title":"Introducing narrator","text":"","code":"df_two <- sales %>% filter(Region %in% c(\"NA\", \"EMEA\")) %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) kable(df_two) narrate_descriptive(df_two) #> $`Total Sales` #> Total Sales across all Regions: 1.7 M. #> #> $`Region by Sales` #> Outlying Region by Sales is NA (1 M, 60.7 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Product E (241.6 K, 23.9 %), Product B (201.9 K, 20 %), Product F (154.1 K, 15.2 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (440.2 K, 26.4 %), Product B (297.8 K, 17.9 %), Product F (247 K, 14.8 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"coverage","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Coverage","title":"Introducing narrator","text":"Key argument narratives coverage. used narrate important things avoid simple looping dimension levels. default coverage set 0.5 means narration stop soon cumulative sum reaches 50 % mark. increased coverage, additional narrative returned.","code":"df_three <- sales %>% group_by(Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) df_three %>% mutate(Share = round(Sales/sum(Sales)*100, 1), Cumulative = cumsum(Share)) %>% kable() narrate_descriptive(df_three) #> $`Total Sales` #> Total Sales across all Products: 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). narrate_descriptive(df_three, coverage = 0.7) #> $`Total Sales` #> Total Sales across all Products: 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %)."},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"changing-templates","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Changing Templates","title":"Introducing narrator","text":"Template-based systems based calculations individual variables, combining together inside template. can return list calculated variables full narrative realization: Let’s change template narrative function rework wording well changing ‘’ ‘’ since Sales plural: can set templates using usethis::edit_r_environ() setting environment variable using data science platform capabilities. method little handy setting .Renviron variable names using certain convention adding use_renviron = TRUE narrate function. example created variable uses unique part function name, underscore, template name - descriptive + - + template_total can get templates currently available package list_templates() function:","code":"narrate_descriptive(df_three, coverage = 0.7, return_data = TRUE) #> $template_total #> Total Sales across all Products: 2.1 M. #> #> $narrative #> $narrative$`Total Sales` #> Total Sales across all Products: 2.1 M. #> #> $narrative$`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %). #> #> #> $template_outlier_final #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %). #> #> $measure #> [1] \"Sales\" #> #> [[5]] #> [1] \"Product\" #> #> $total #> [1] \"2.1 M\" #> #> $outlier_insight #> [1] \"Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %), Product H (262.7 K, 12.3 %)\" narrate_descriptive( df_three, template_total = \"Overall {measure} for all {pluralize(dimension1)} are equal to {total}. \") #> $`Total Sales` #> Overall Sales for all Products are equal to 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). Sys.getenv(\"descriptive_template_total\") #> [1] \"Total {measure} = {total}.\" narrate_descriptive( df_three,template_total = Sys.getenv(\"descriptive_template_total\") ) #> $`Total Sales` #> Total Sales = 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). narrate_descriptive(df_three, use_renviron = TRUE) #> $`Total Sales` #> Total Sales = 2.1 M. #> #> $`Product by Sales` #> Outlying Products by Sales are Product E (546.9 K, 25.6 %), Product B (396.7 K, 18.6 %), Product F (326.2 K, 15.3 %). list_templates() %>% kable()"},{"path":"https://denisabd.github.io/narrator/articles/intro.html","id":"correcting-text","dir":"Articles","previous_headings":"Descriptive Narrative","what":"Correcting Text","title":"Introducing narrator","text":"can correct sentence using, currently experimental correct_text() function. requires udpipe installation load model choosing working directory.","code":"correct_text(\"Total Profit across all Regions are 85 M\", download_udpipe = FALSE) #> [1] \"Total Profit across all Regions is 85 M\""},{"path":"https://denisabd.github.io/narrator/articles/python.html","id":"installation","dir":"Articles","previous_headings":"","what":"Installation","title":"Python","text":"use Python version package install pynarrator pip:","code":"pip3 install pynarrator import os from pynarrator import narrate_descriptive, read_data import pprint sales = read_data() narrative = narrate_descriptive( df = sales, measure = 'Sales', dimensions = ['Region', 'Product'], return_data = False, coverage = 0.5 ) pprint.pprint(narrative) #> {'Product by Sales': 'Outlying Products by Sales are Food & Beverage ' #> '(15543469.7, 40.0%), Electronics (8608962.8, 22.0%).', #> 'Region by Sales': 'Outlying Regions by Sales are NA (18079736.4, 47.0%), ' #> 'EMEA (13555412.7, 35.0%).', #> 'Total Sales': 'Total Sales across all Regions is 38790478.42.'} df_two = (sales .query('Region in [\"NA\", \"EMEA\"]') .groupby(['Region', 'Product']) .agg(Sales=('Sales', 'sum')) .reset_index() .sort_values('Sales', ascending=False) ) pprint.pprint(df_two) #> Region Product Sales #> 9 NA Food & Beverage 7392820.96 #> 3 EMEA Food & Beverage 5265113.22 #> 8 NA Electronics 3789132.66 #> 2 EMEA Electronics 3182803.42 #> 10 NA Home 2165764.54 #> 11 NA Tools 2054959.14 #> 4 EMEA Home 1633026.36 #> 6 NA Baby 1521544.70 #> 5 EMEA Tools 1499974.62 #> 7 NA Clothing 1155514.38 #> 0 EMEA Baby 1146743.82 #> 1 EMEA Clothing 827751.30 narrative = narrate_descriptive(df_two) pprint.pprint(narrative) #> {'Product by Sales': 'Outlying Products by Sales are Food & Beverage ' #> '(12657934.2, 40.0%), Electronics (6971936.1, 22.0%).', #> 'Region by Sales': 'Outlying Region by Sales is NA (18079736.4, ' #> '56.99999999999999%).', #> 'Total Sales': 'Total Sales across all Regions is 31635149.12.'} narrative = narrate_descriptive(df_two, simplify = True) pprint.pprint(narrative) #> ['Total Sales across all Regions is 31635149.12.', #> 'Outlying Region by Sales is NA (18079736.4, 56.99999999999999%).', #> 'Outlying Products by Sales are Food & Beverage (12657934.2, 40.0%), ' #> 'Electronics (6971936.1, 22.0%).']"},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"changing-templates","dir":"Articles","previous_headings":"","what":"Changing Templates","title":"Editing Templates","text":"Template-based systems based calculations individual variables, combining together inside template. can return list calculated variables full narrative realization: Let’s change template narrative function rework wording well changing ‘’ ‘’ since Sales plural:","code":"df <- sales %>% group_by(Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) narrate_descriptive(df, coverage = 0.7, return_data = TRUE) #> $narrative #> $narrative$`Total Sales` #> Total Sales across all Products is 38790478.4. #> #> $narrative$`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %). #> #> #> $`Total Sales` #> $`Total Sales`$narrative_total #> Total Sales across all Products is 38790478.4. #> #> $`Total Sales`$template_total #> [1] \"Total {measure} across all {pluralize(dimension_one)} is {total}.\" #> #> $`Total Sales`$measure #> [1] \"Sales\" #> #> $`Total Sales`$dimension_one #> [1] \"Product\" #> #> $`Total Sales`$total #> [1] 38790478 #> #> $`Total Sales`$total_raw #> [1] 38790478 #> #> #> $`Product by Sales` #> $`Product by Sales`$narrative_outlier_final #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %). #> #> $`Product by Sales`$template_outlier_multiple #> [1] \"Outlying {pluralize(dimension)} by {measure} are {outlier_insight}.\" #> #> $`Product by Sales`$dimension #> [1] \"Product\" #> #> $`Product by Sales`$measure #> [1] \"Sales\" #> #> $`Product by Sales`$outlier_insight #> [1] \"Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %), Home (4599370.9, 11.9 %)\" #> #> $`Product by Sales`$n_outliers #> [1] 3 #> #> $`Product by Sales`$outlier_levels #> [1] \"Food & Beverage\" \"Electronics\" \"Home\" #> #> $`Product by Sales`$outlier_values #> [1] 15543470 8608963 4599371 #> #> $`Product by Sales`$outlier_values_p #> [1] \"40.1 %\" \"22.2 %\" \"11.9 %\" narrate_descriptive( df, template_total = \"Overall {measure} for all {pluralize(dimension_one)} are equal to {total}. \") #> $`Total Sales` #> Overall Sales for all Products are equal to 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with {measure} of {outlier_values}, making it {outlier_values_p} of total.\", template_outlier_multiple = \"{outlier_levels} are the biggest {dimension} by {measure} with {outlier_values} or {outlier_values_p} share of total {measure} respectively.\", measure = \"Sales\", dimensions = c(\"Region\", \"Product\"), coverage = 0.4) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Among Regions NA is an outlier, with Sales of 18079736.4, making it 46.6 % of total. #> #> $`NA by Product` #> In NA, significant Product by Sales is Food & Beverage (7392821, 40.9 %). #> #> $`Product by Sales` #> Among Products Food & Beverage is an outlier, with Sales of 15543469.7, making it 40.1 % of total."},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"r-environment","dir":"Articles","previous_headings":"Changing Templates","what":"R Environment","title":"Editing Templates","text":"can set templates using usethis::edit_r_environ() setting environment variable using data science platform capabilities. method little handy setting .Renviron variable names using certain convention adding use_renviron = TRUE narrate function. example created variable uses unique part function name, underscore, template name - descriptive + - + template_total","code":"Sys.getenv(\"descriptive_template_total\") narrate_descriptive( df, template_total = Sys.getenv(\"descriptive_template_total\") ) narrate_descriptive( df, use_renviron = TRUE ) #> $`Total Sales` #> Sales is equal to 38790478.4. #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %)."},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"list-templates","dir":"Articles","previous_headings":"Changing Templates","what":"List Templates","title":"Editing Templates","text":"can get templates currently available package list_templates() function:","code":"list_templates() %>% kable()"},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"editing-gadget","dir":"Articles","previous_headings":"Changing Templates","what":"Editing Gadget","title":"Editing Templates","text":"Exploring templates might easy task, narrator allows prepare templates interactively using edit_templates() function.","code":"edit_templates()"},{"path":"https://denisabd.github.io/narrator/articles/templates.html","id":"average-vs-others","dir":"Articles","previous_headings":"Changing Templates","what":"Average vs Others","title":"Editing Templates","text":"summarization set average way output calculation significantly different. Generally better way using outputs using different templates different summarization types. Giving users control template creation avoiding strict ruling look introduce additional complexity. example, use template_outlier default summarization = \"sum\" get great descriptive narrative: trying summarization = \"average\" get trouble, case compare values every level overall average Sales. Default templates handle using logic {outlier_insight} calculation. can using something like :","code":"sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with {measure} of {outlier_values}, making it {outlier_values_p} of total.\", measure = \"Sales\", dimensions = \"Region\", coverage = 0.3) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Among Regions NA is an outlier, with Sales of 18079736.4, making it 46.6 % of total. sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with {measure} of {outlier_values}, making it {outlier_values_p} of total.\", measure = \"Sales\", dimensions = \"Region\", summarization = \"average\", coverage = 0.3) #> $`Average Sales` #> Average Sales across all Regions is 3879. #> #> $`Region by Sales` #> Among Regions LATAM is an outlier, with Sales of 2303.3, making it -40.6 % of total. sales %>% narrate_descriptive( template_outlier = \"Among {pluralize(dimension)} {outlier_levels} is an outlier, with average {measure} of {outlier_values}, {outlier_values_p} lower than average {measure} across all records.\", measure = \"Sales\", dimensions = \"Region\", summarization = \"average\", coverage = 0.3) #> $`Average Sales` #> Average Sales across all Regions is 3879. #> #> $`Region by Sales` #> Among Regions LATAM is an outlier, with average Sales of 2303.3, -40.6 % lower than average Sales across all records."},{"path":"https://denisabd.github.io/narrator/articles/trend.html","id":"year-over-year","dir":"Articles","previous_headings":"","what":"Year-over-Year","title":"Trend Narratives","text":"Default narrative returned analyzing year--date (YTD) vs prior year--date (PYTD) volumes, based data set date range. current year considered max date supplied data.","code":"df <- sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"month\")) %>% dplyr::group_by(Region, Product, Date) %>% dplyr::summarise(Sales = sum(Sales, na.rm = TRUE)) df %>% head() %>% kable() narrate_trend(df) #> $`2021 YTD vs 2020 YTD` #> From 2020 YTD to 2021 YTD, Sales had an increase of 1.13 M (9.1 %, 12.42 M to 13.55 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are NA (533.1 K, 9.1 %, 5.9 M to 6.4 M), EMEA (416.9 K, 9.91 %, 4.2 M to 4.6 M). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Food & Beverage (243.3 K, 9.92 %, 2.5 M to 2.7 M), Tools (186.8 K, 31.87 %, 585.9 K to 772.7 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Electronics (312.1 K, 35.88 %, 869.7 K to 1.2 M), Food & Beverage (238.2 K, 14.54 %, 1.6 M to 1.9 M). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Food & Beverage (535.4 K, 10.63 %, 5 M to 5.6 M), Electronics (525.9 K, 19.79 %, 2.7 M to 3.2 M)."},{"path":"https://denisabd.github.io/narrator/articles/trend.html","id":"previous-period","dir":"Articles","previous_headings":"","what":"Previous Period","title":"Trend Narratives","text":"Different time frame can selected using type argument narrate_trend() function. numeric string values accepted, 1 stands ‘yoy’, 2 ‘previous period’, 3 ‘period last year’. previous period selected, compare volumes December 2021 November 2021:","code":"narrate_trend(df, type = \"previous period\") #> $`Dec 2021 vs Nov 2021` #> From Nov 2021 to Dec 2021, Sales had an increase of 176.32 K (10.3 %, 1.71 M to 1.89 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are EMEA (154.2 K, 26.54 %, 580.8 K to 735 K), NA (-111 K, -13.14 %, 844.4 K to 733.4 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Food & Beverage (97.1 K, 45.41 %, 213.8 K to 310.9 K), Tools (60.1 K, 76.53 %, 78.6 K to 138.7 K). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Tools (-87.2 K, -55.54 %, 157 K to 69.8 K), Home (-51.4 K, -44.95 %, 114.3 K to 62.9 K). #> #> $`Sales change by Product` #> Product with biggest changes of Sales is Food & Beverage (197.2 K, 31.28 %, 630.6 K to 827.8 K)."},{"path":"https://denisabd.github.io/narrator/articles/trend.html","id":"same-period-last-year","dir":"Articles","previous_headings":"","what":"Same Period Last Year","title":"Trend Narratives","text":"Alternatively, can use numeric option, comfortable . function get December 2020 data comparison:","code":"narrate_trend(df, type = 3) #> $`Dec 2021 vs Dec 2020` #> From Dec 2020 to Dec 2021, Sales had an increase of 92.89 K (5.2 %, 1.79 M to 1.89 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are EMEA (184.3 K, 33.48 %, 550.6 K to 735 K), NA (-144.3 K, -16.44 %, 877.8 K to 733.4 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Food & Beverage (104.2 K, 50.43 %, 206.7 K to 310.9 K), Tools (78.5 K, 130.46 %, 60.2 K to 138.7 K). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Clothing (-71.6 K, -76.95 %, 93.1 K to 21.5 K), Home (-44.3 K, -41.31 %, 107.2 K to 62.9 K). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Food & Beverage (118.3 K, 16.67 %, 709.5 K to 827.8 K), Electronics (108.3 K, 36.23 %, 298.8 K to 407.1 K), Baby (-79.3 K, -33.91 %, 233.9 K to 154.6 K)."},{"path":"https://denisabd.github.io/narrator/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Denis Abdullin. Author, maintainer.","code":""},{"path":"https://denisabd.github.io/narrator/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Abdullin D (2023). narrator: Create Natural Language Text Narratives Data. R package version 0.1.0, https://denisabd.github.io/narrator/.","code":"@Manual{, title = {narrator: Create Natural Language Text Narratives from the Data}, author = {Denis Abdullin}, year = {2023}, note = {R package version 0.1.0}, url = {https://denisabd.github.io/narrator/}, }"},{"path":"https://denisabd.github.io/narrator/index.html","id":"narrator-","dir":"","previous_headings":"","what":"Create Natural Language Text Narratives from the Data","title":"Create Natural Language Text Narratives from the Data","text":"Template-based NLG framework creating text narratives data enhance using ChatGPT. Demo shiny application showing core package capabilities deployed shinyapps.io. Package available R Python, core features even syntax similar. Corresponding classes data types used languages: data.frame vs pandas data frame list vs dictionary character vector vs list","code":""},{"path":"https://denisabd.github.io/narrator/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Create Natural Language Text Narratives from the Data","text":"R can install development version narrator GitHub : Python install pynarrator pip:","code":"# install.packages(\"devtools\") devtools::install_github(\"denisabd/narrator\") pip3 install pynarrator"},{"path":[]},{"path":"https://denisabd.github.io/narrator/index.html","id":"basic-use-cases","dir":"","previous_headings":"","what":"Basic Use Cases","title":"Create Natural Language Text Narratives from the Data","text":"Simple tables one categorical columns (dimensions) one measure can transformed text using narrate_descriptive() function. can analyze changes time using narrate_trend() function:","code":"library(narrator) library(dplyr) narrative_one <- sales %>% narrate_descriptive( measure = \"Sales\", dimensions = c(\"Region\", \"Product\") ) narrative_one #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %), Electronics (3182803.4, 23.5 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). narrative_two <- sales %>% narrate_trend( measure = \"Sales\", date = \"Date\", dimensions = c(\"Region\", \"Product\") ) narrative_two #> $`2021 YTD vs 2020 YTD` #> From 2020 YTD to 2021 YTD, Sales had an increase of 1.13 M (9.1 %, 12.42 M to 13.55 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are NA (533.1 K, 9.1 %, 5.9 M to 6.4 M), EMEA (416.9 K, 9.91 %, 4.2 M to 4.6 M). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Food & Beverage (243.3 K, 9.92 %, 2.5 M to 2.7 M), Tools (190.5 K, 32.72 %, 582.2 K to 772.7 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Electronics (313.1 K, 36.05 %, 868.6 K to 1.2 M), Food & Beverage (244.8 K, 15.01 %, 1.6 M to 1.9 M). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Food & Beverage (535.4 K, 10.63 %, 5 M to 5.6 M), Electronics (525.9 K, 19.79 %, 2.7 M to 3.2 M)."},{"path":"https://denisabd.github.io/narrator/index.html","id":"chatgpt","dir":"","previous_headings":"","what":"ChatGPT","title":"Create Natural Language Text Narratives from the Data","text":"narrator can use ChatGPT API improve narratives. can either set use_chatgpt = TRUE function creates narrative use enhance_narrative() improve existing narrative output. can supply list character, function collapse text sentence send request Chat GPT. Set token .Renviron file OPENAI_API_KEY supply function openai_api_key argument. functionality requires setup ChatGPT API key make accessible R. Obtain ChatGPT API key. can create API key accessing OpenAI API page Best Practices API Key Safety Change .Renviron file usethis::edit_r_environ() adding `OPENAI_API_KEY=xx-xxxxxx` company’s Total Sales across Regions reached remarkable figure 38790478.4. Outlying Regions Sales NA, generated sales figures 18079736.4, accounting 46.6% total sales. Following closely EMEA, responsible sales figures 13555412.7, representing 34.9% total sales. Analysing sales figures NA market, can identify two significant products achieved excellent results. Food & Beverage led way outstanding 7392821 sales, comprising 40.9% market share. Electronics followed closely sales figures 3789132.7, accounting estimated 21% market share. EMEA market, also see impressive figures sales Food & Beverage sector 5265113.2 accounting 38.8% market share, Electronics achieving sales 3182803.4, accounting estimated 23.5% market. Combined, Food & Beverage Electronics products driven Outlying Products Sales notable figures 15543469.7 8608962.8, represent 40.1% 22.2% market share, respectively.","code":"narrative_enhanced <- enhance_narrative(narrative_one) cat(narrative_enhanced)"},{"path":"https://denisabd.github.io/narrator/index.html","id":"translation","dir":"","previous_headings":"ChatGPT","what":"Translation","title":"Create Natural Language Text Narratives from the Data","text":"Translate text using translate_narrative() function, specify language argument English: Celkové Spojené Prodeje Společnosti napříč všemi regiony dosáhly pozoruhodné sumy 38790478.4. Regiony nad rámec očekávání jsou Severní Amerika (NA), která vygenerovala prodej ve výši 18079736.4, což představuje 46,6% celkového prodeje. Těsně na druhém místě je EMEA, zodpovědná za prodej ve výši 13555412.7, což odpovídá 34,9% celkových prodejů. Analýzou prodejů na trhu Severní Ameriky můžeme identifikovat dva významné produkty, které dosáhly vynikajících výsledků. Vedením šla kategorie Jídla Nápojů se skvělými prodeji za 7392821, což tvoří 40.9% tržního podílu. Elektronika následovala blízko za prodejovými čísly ve výši 3789132.7, což odpovídá přibližně 21% tržního podílu. Na trhu EMEA vidíme také impozantní prodejová čísla od kategorie Jídla Nápojů (5265113.2), což tudíž tvoří 38.8% tržního podílu, Elektronika s prodejem ve výši 3182803.4, což představuje 23.5% tržního podílu. Celkově kategorie Jídla Nápojů Elektronika pohánějí Outlying Produkty s významnými čísly ve výši 15543469.7 8608962.8, což odpovídá 40.1% 22.2% tržního podílu.","code":"translation <- translate_narrative(narrative_enhanced, language = \"Czech\") cat(translation)"},{"path":"https://denisabd.github.io/narrator/index.html","id":"summarization","dir":"","previous_headings":"ChatGPT","what":"Summarization","title":"Create Natural Language Text Narratives from the Data","text":"output verbose can summarize summarize_narrative() function: Total Sales 38790478.4 achieved company across regions. NA EMEA top regions sales figures 18079736.4 13555412.7, respectively. Food & Beverage Electronics leading products, impressive sales figures regions driving market share. account 40.1% 22.2% market share respectively, combining contribute overall success.","code":"summarization <- summarize_narrative(narrative_enhanced) cat(summarization)"},{"path":"https://denisabd.github.io/narrator/index.html","id":"python","dir":"","previous_headings":"","what":"Python","title":"Create Natural Language Text Narratives from the Data","text":"basic Python examples, details visit pynarrator github pynarrator website default narrate_descriptive() returns dictionary narratives names. simplify = True output list: return_data=True get list variables calculated inside function: functions, Chat GPT related calls similar R","code":"import os from pynarrator import narrate_descriptive, read_data, enhance_narrative, translate_narrative, summarize_narrative sales = read_data() narrate_descriptive( df = sales, measure = 'Sales', dimensions = ['Region', 'Product'], return_data = False, coverage = 0.5 ) narrate_descriptive( df = sales, measure = 'Sales', dimensions = 'Region', return_data = False, simplify = True, coverage = 0.5 ) narrative_two = narrate_descriptive( df = sales, measure = 'Sales', dimensions = 'Region', return_data = False, simplify = True, coverage = 0.5 ) pprint.pprint(narrative_two) narrate_descriptive( df = sales, measure = 'Sales', dimensions = ['Region', 'Product'], return_data = True, simplify = True, coverage = 0.5 ) narrative_enhanced = enhance_narrative(narrative_one) translation = translate_narrative(narrative_enhanced, language = \"Czech\") summarization = summarize_narrative(narrative_enhanced)"},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":null,"dir":"Reference","previous_headings":"","what":"Add HTML Tags to Text — add_tag","title":"Add HTML Tags to Text — add_tag","text":"Add HTML Tags Text","code":""},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add HTML Tags to Text — add_tag","text":"","code":"add_tag(text, tag = \"h3\")"},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add HTML Tags to Text — add_tag","text":"text Text string tag HTML tag like p, b, h1 ","code":""},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add HTML Tags to Text — add_tag","text":"glue character HTML tags","code":""},{"path":[]},{"path":"https://denisabd.github.io/narrator/reference/add_tag.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add HTML Tags to Text — add_tag","text":"","code":"add_tag(\"Title Text\", tag = \"h2\") #>

Title Text <\/h2> add_tag(\"bold text\", tag = \"b\") #> bold text <\/b>"},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":null,"dir":"Reference","previous_headings":"","what":"Clean HTML Tags from the Text — clean_tags","title":"Clean HTML Tags from the Text — clean_tags","text":"Clean HTML Tags Text","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Clean HTML Tags from the Text — clean_tags","text":"","code":"clean_tags(html_string)"},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Clean HTML Tags from the Text — clean_tags","text":"html_string Text html tags","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Clean HTML Tags from the Text — clean_tags","text":"character() vector text strings without tags","code":""},{"path":[]},{"path":"https://denisabd.github.io/narrator/reference/clean_tags.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Clean HTML Tags from the Text — clean_tags","text":"","code":"clean_tags(\"Total increase is equal to 14.5 % <\/b>\") #> [1] \"Total increase is equal to 14.5 %\" clean_tags(\"

Sales by Region<\/h3>\") #> [1] \"Sales by Region\""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Clean Text String — clean_text","title":"Clean Text String — clean_text","text":"Function cleans text string improving narration, removing excessive white spaces","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Clean Text String — clean_text","text":"","code":"clean_text( text, upper = c(\"YTD\", \"PYTD\"), lower = c(\"vs\", \"br>\", \"h1>\", \"h2>\", \"h3>\", \"h4>\", \"h5>\", \"h6>\", \"b>\") )"},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Clean Text String — clean_text","text":"text Text string cleaning. Can contain multiple sentences. upper Vector words need changed uppercase text lower Vector words need changed lowercase text","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Clean Text String — clean_text","text":"Text string","code":""},{"path":"https://denisabd.github.io/narrator/reference/clean_text.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Clean Text String — clean_text","text":"","code":"text <- \"Similarly in 2020 the sum of spend increased by 15.4% ( 4.3 % higher than average).\" clean_text(text) #> [1] \"Similarly in 2020 the sum of spend increased by 15.4 % (4.3 % higher than average).\" clean_text(\" Total is 12,300 Orders ( 23.5 % for East ) \") #> [1] \"Total is 12,300 Orders (23.5 % for East)\""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Correct the Sentence Using UDPIPE — correct_text","title":"Correct the Sentence Using UDPIPE — correct_text","text":"Correct Sentence Using UDPIPE","code":""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Correct the Sentence Using UDPIPE — correct_text","text":"","code":"correct_text(text, language = \"english\", download_udpipe = TRUE, measure = \"\")"},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Correct the Sentence Using UDPIPE — correct_text","text":"text Text string correction language Language udpipe model, defaults 'english' download_udpipe Download udpipe working directory measure Measure template","code":""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Correct the Sentence Using UDPIPE — correct_text","text":"Text string","code":""},{"path":"https://denisabd.github.io/narrator/reference/correct_text.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Correct the Sentence Using UDPIPE — correct_text","text":"","code":"correct_text(\"In 2020 total Sales across all Regions (EMEA, NA, ASPAC) is equal to 23.5 M\") #> Loading required namespace: udpipe #> [1] \"In 2020 total Sales across all Regions ( EMEA , NA , ASPAC ) are equal to 23.5 MS\" correct_text(\"Total Profit across all Regions are 85 M\") #> [1] \"Total Profit across all Regions is 85 M\""},{"path":"https://denisabd.github.io/narrator/reference/edit_templates.html","id":null,"dir":"Reference","previous_headings":"","what":"Interactively Edit Package Templates — edit_templates","title":"Interactively Edit Package Templates — edit_templates","text":"Interactively Edit Package Templates","code":""},{"path":"https://denisabd.github.io/narrator/reference/edit_templates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Interactively Edit Package Templates — edit_templates","text":"","code":"edit_templates()"},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":null,"dir":"Reference","previous_headings":"","what":"Enhance the narrative output with ChatGPT — enhance_narrative","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"Enhance narrative output ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"","code":"enhance_narrative( narrative, prompt = \"Improve the narrative by adding better business language for the following:\", openai_api_key = Sys.getenv(\"OPENAI_API_KEY\") )"},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"narrative List narratives returned narrate_* function, character vector string enhanced ChatGPT prompt Prompt send OpenAI API openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\")","code":""},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"character() narratives enhanced ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/enhance_narrative.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Enhance the narrative output with ChatGPT — enhance_narrative","text":"","code":"if (FALSE) { narrative <- sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% narrate_descriptive() enhance_narrative(narrative) }"},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":null,"dir":"Reference","previous_headings":"","what":"Format Numeric Values — format_num","title":"Format Numeric Values — format_num","text":"Format Numeric Values","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Format Numeric Values — format_num","text":"","code":"format_num( num, format = \"auto\", decimals = 1, threshold = 10000, format_list = c(\"\", \"K\", \"M\", \"B\", \"T\") )"},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Format Numeric Values — format_num","text":"num Number numeric vector format Format numeric output - \"auto\", \"K\", \"M\", \"B\" \"T\" decimals Number decimal numbers rounding threshold Threshold converting specific format, threshold thousand delimiters added format_list List formats use automated","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Format Numeric Values — format_num","text":"character() vector","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_num.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Format Numeric Values — format_num","text":"","code":"format_num(27334254) #> [1] \"27.3 M\" format_num(c(27334254, 12332, 23425435534)) #> [1] \"27.3 M\" \"12.3 K\" \"23.4 B\""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":null,"dir":"Reference","previous_headings":"","what":"Format numeric value — format_number","title":"Format numeric value — format_number","text":"Format numeric value","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Format numeric value — format_number","text":"","code":"format_number( num, format = \"auto\", decimals = 1, threshold = 10000, format_list = c(\"\", \"K\", \"M\", \"B\", \"T\") )"},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Format numeric value — format_number","text":"num Number numeric vector format Format numeric output - \"auto\", \"K\", \"M\", \"B\" \"T\" decimals Number decimal numbers rounding threshold Threshold converting specific format, threshold thousand delimiters added format_list List formats use automated","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Format numeric value — format_number","text":"vector numerics","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_number.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Format numeric value — format_number","text":"","code":"format_number(27334254) #> [1] \"27.3 M\" format_number(c(27334254, 12332, 23425435534)) #> [1] \"27.3 M\" \"12.3 K\" \"23.4 B\""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":null,"dir":"Reference","previous_headings":"","what":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"Add HTML Tags Colors Percentage Values Text","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"","code":"format_pct(text, positive = \"green\", negative = \"red\")"},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"text Text string character vector/list text strings positive Color highlight percentage increase negative Color highlight percentage decline","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"list() text strings","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_pct.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add HTML Tags with Colors to Percentage Values in Text — format_pct","text":"","code":"text <- \"Spend increased by 13.2 % in EMEA but decreased by -13.2 % in LATAM\" format_pct(text) #> [[1]] #> [1] \"Spend increased by 13.2 %<\/span> <\/b> in EMEA but decreased by -13.2 %<\/span> <\/b> in LATAM\" #>"},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Add HTML Tags to Add Color and Boldness — format_text","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"Function adds html code around selected string adding options colorized /bold display HTML documents.","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"","code":"format_text(text, color = \"auto\", bold = TRUE)"},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"text Text string want format color Color name, \"auto\" color determined based number parsed - red negative, green positive bold Make text bold ","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"text HTML tags","code":""},{"path":"https://denisabd.github.io/narrator/reference/format_text.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add HTML Tags to Add Color and Boldness — format_text","text":"","code":"text <- format_text(\"1.2%\", color = \"auto\", bold = TRUE) text #> [1] \" 1.2%<\/span> <\/b>\""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":null,"dir":"Reference","previous_headings":"","what":"Get Date Frequency of the Data — get_frequency","title":"Get Date Frequency of the Data — get_frequency","text":"Function group data estimate frequency time stamps, returning 'year', 'quarter', 'month', 'week' 'day'. can use raw aggregated data frames","code":""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get Date Frequency of the Data — get_frequency","text":"","code":"get_frequency(df, date_field = NULL)"},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get Date Frequency of the Data — get_frequency","text":"df data.frame() tibble() Data frame tibble, can aggregated raw date_field Date field analyzed, default first date-like column used","code":""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get Date Frequency of the Data — get_frequency","text":"frequency - \"quarter\", \"month\", \"week\" \"day\"","code":""},{"path":"https://denisabd.github.io/narrator/reference/get_frequency.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get Date Frequency of the Data — get_frequency","text":"","code":"sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"month\")) %>% get_frequency() #> [1] \"month\" sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"week\")) %>% get_frequency() #> [1] \"week\" sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"quarter\")) %>% dplyr::group_by(Region, Date) %>% dplyr::summarise(Sales = sum(Sales, na.rm = TRUE)) %>% get_frequency() #> [1] \"quarter\" get_frequency(sales) #> [1] \"day\""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":null,"dir":"Reference","previous_headings":"","what":"Test Plural State of an English Word — is_plural","title":"Test Plural State of an English Word — is_plural","text":"Test Plural State English Word","code":""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Test Plural State of an English Word — is_plural","text":"","code":"is_plural(x) is_singular(x)"},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Test Plural State of an English Word — is_plural","text":"x vector words test","code":""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Test Plural State of an English Word — is_plural","text":"logical vector","code":""},{"path":"https://denisabd.github.io/narrator/reference/is_plural.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Test Plural State of an English Word — is_plural","text":"","code":"is_singular(c(\"boats\", \"house\", \"cats\", \"river\")) #> [1] FALSE TRUE FALSE TRUE is_plural(c(\"boats\", \"house\", \"cats\", \"river\")) #> [1] TRUE FALSE TRUE FALSE"},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":null,"dir":"Reference","previous_headings":"","what":"Return a Table of all Templates Currently Available in the Package — list_templates","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"Return Table Templates Currently Available Package","code":""},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"","code":"list_templates()"},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"tibble templates functions packages","code":""},{"path":"https://denisabd.github.io/narrator/reference/list_templates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Return a Table of all Templates Currently Available in the Package — list_templates","text":"","code":"list_templates() #> # A tibble: 12 × 4 #> fun type name template #> #> 1 narrate_descriptive descriptive template_total Total {measure}… #> 2 narrate_descriptive descriptive template_average Average {measur… #> 3 narrate_descriptive descriptive template_outlier Outlying {dimen… #> 4 narrate_descriptive descriptive template_outlier_multiple Outlying {plura… #> 5 narrate_descriptive descriptive template_outlier_l2 In {level_l1}, … #> 6 narrate_descriptive descriptive template_outlier_l2_multiple In {level_l1}, … #> 7 narrate_trend trend template_total From {timeframe… #> 8 narrate_trend trend template_average Average {measur… #> 9 narrate_trend trend template_outlier {dimension} wit… #> 10 narrate_trend trend template_outlier_multiple {pluralize(dime… #> 11 narrate_trend trend template_outlier_l2 In {level_l1}, … #> 12 narrate_trend trend template_outlier_l2_multiple In {level_l1}, …"},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Descriptive Narrative — narrate_desc","title":"Create Descriptive Narrative — narrate_desc","text":"Create Descriptive Narrative","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Descriptive Narrative — narrate_desc","text":"","code":"narrate_desc( df, measure = NULL, dimensions = NULL, coverage = 0.5, coverage_limit = 5, narrative_total = \"{measure} across all {pluralize(dimension1)} is {total}. \", narrative_outlier = \"Outlying {dimension} by {measure} is {outlier_insight}. \", narrative_outlier_multiple = \"Outlying {pluralize(dimension)} by {measure} are {outlier_insight}. \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Descriptive Narrative — narrate_desc","text":"...","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_desc.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Descriptive Narrative — narrate_desc","text":"","code":"sales %>% narrate_desc(measure = \"Sales\", dimensions = c(\"Territory\", \"State\")) #> Sales across all Territories is 10032628.85. Outlying Territory by Sales is EMEA (5 M, 49.6%). Outlying State by Sales is ."},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Descriptive Text Narratives from Data — narrate_descriptive","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"narrate_descriptive() creates text narratives data frame containing one numeric one character factor text columns using glue syntax. Function can work raw aggregated data frame. automatically use first numeric column measure character factor columns dimensions","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"","code":"narrate_descriptive( df, measure = NULL, dimensions = NULL, summarization = \"sum\", coverage = 0.5, coverage_limit = 5, narration_depth = 2, use_chatgpt = FALSE, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\"), template_total = \"Total {measure} across all {pluralize(dimension_one)} is {total}.\", template_average = \"Average {measure} across all {pluralize(dimension_one)} is {total}.\", template_outlier = \"Outlying {dimension} by {measure} is {outlier_insight}.\", template_outlier_multiple = \"Outlying {pluralize(dimension)} by {measure} are {outlier_insight}.\", template_outlier_l2 = \"In {level_l1}, significant {level_l2} by {measure} is {outlier_insight}.\", template_outlier_l2_multiple = \"In {level_l1}, significant {pluralize(level_l2)} by {measure} are {outlier_insight}.\", use_renviron = FALSE, return_data = FALSE, simplify = FALSE, format_numbers = FALSE, collapse_sep = \", \", collapse_last = \" and \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"df data.frame() tibble() Data frame tibble, can aggregated raw measure Numeric measure function create calculations , NULL take first numeric field available dimensions Vector dimensions analysis, default character factor variable used summarization Approach data summarization/aggregation - 'sum', 'count' 'average' coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation narration_depth Parameter control depth analysis 1 summary 2 detailed use_chatgpt TRUE - use ChatGPT enhance narrative openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\") template_total glue template total volumes narrative template_average glue template average volumes narrative template_outlier glue template single outlier narrative template_outlier_multiple glue template multiple outliers narrative template_outlier_l2 glue template deeper hierarchical single outlier narrative template_outlier_l2_multiple glue template deeper hierarchical multiple outliers narrative use_renviron TRUE use .Renviron variables template. can also set options(narrator.use_renviron = TRUE) make global session, create environment variable \"use_renviron\" changing .Renviron file usethis::edit_r_environ() return_data TRUE - return list variables used function's templates simplify TRUE - return character vector, FALSE - named list format_numbers TRUE - format big numbers K/M/B using format_num() function collapse_sep Separator glue_collapse cases multiple values single variable collapse_last Separator glue_collapse last item, cases multiple values single variable ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"list() narratives default character() simplify = TRUE","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_descriptive.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Descriptive Text Narratives from Data — narrate_descriptive","text":"","code":"sales %>% narrate_descriptive(measure = \"Sales\", dimensions = c(\"Region\", \"Product\")) #> $`Total Sales` #> Total Sales across all Regions is 38790478.4. #> #> $`Region by Sales` #> Outlying Regions by Sales are NA (18079736.4, 46.6 %), EMEA (13555412.7, 34.9 %). #> #> $`NA by Product` #> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %), Electronics (3789132.7, 21 %). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %), Electronics (3182803.4, 23.5 %). #> #> $`Product by Sales` #> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %), Electronics (8608962.8, 22.2 %). #> sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Quantity = sum(Quantity)) %>% narrate_descriptive() #> $`Total Quantity` #> Total Quantity across all Products is 65653. #> #> $`Product by Quantity` #> Outlying Products by Quantity are Home (26697, 40.7 %), Tools (25457, 38.8 %). #> #> $`Home by Region` #> In Home, significant Regions by Quantity are NA (12204, 45.7 %), EMEA (8693, 32.6 %). #> #> $`Tools by Region` #> In Tools, significant Regions by Quantity are NA (11253, 44.2 %), EMEA (8216, 32.3 %). #> #> $`Region by Quantity` #> Outlying Regions by Quantity are NA (29819, 45.4 %), EMEA (21249, 32.4 %). #> sales %>% narrate_descriptive(measure = \"Order ID\", dimensions = \"Region\", summarization = \"count\") #> $`Total Order ID` #> Total Order ID across all Regions is 10000. #> #> $`Region by Order ID` #> Outlying Regions by Order ID are NA (3975, 39.8 %), EMEA (2986, 29.9 %). #>"},{"path":"https://denisabd.github.io/narrator/reference/narrate_forecast.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Narrative for Time Series Forecast Data Frames — narrate_forecast","title":"Create Narrative for Time Series Forecast Data Frames — narrate_forecast","text":"Create Narrative Time Series Forecast Data Frames","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_forecast.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Narrative for Time Series Forecast Data Frames — narrate_forecast","text":"","code":"narrate_forecast( df, measure = NULL, dimensions = NULL, date = NULL, frequency = NULL, summarization = \"sum\", type = \"yoy\", coverage = 0.5, coverage_limit = 5, narration_depth = 2, use_chatgpt = FALSE, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\"), forecast = \"Forecast\", actuals = \"Actuals\", template_cy = \"Forecasted volume for {current_year} is {format_num(cy_forecast)}\", template_ftm = \"Overall forecast for the next 12 months is {format_num(ftm_forecast)}\", template_ftm_change = \"Projected {trend} in the next 12 months is equal to {format_num(ftm_change)} ({ftm_change_p}%).\", use_renviron = FALSE, return_data = FALSE, simplify = FALSE, format_numbers = TRUE, collapse_sep = \", \", collapse_last = \" and \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_forecast.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Narrative for Time Series Forecast Data Frames — narrate_forecast","text":"df data.frame() tibble() Data frame tibble, can aggregated raw measure Numeric measure function create calculations , NULL take first numeric field available dimensions Vector dimensions analysis, default character factor variable used date Name date column used time based analysis frequency Level time based aggregation comparing across years summarization Approach data summarization/aggregation - 'sum', 'count' 'average' type Type trend analysis create: 1 'yoy', 2 'previous period', 3 'period last year' coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation narration_depth Parameter control depth analysis 1 summary 2 detailed use_chatgpt TRUE - use ChatGPT enhance narrative openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\") forecast Name forecast column data frame actuals Name actuals column data frame use_renviron TRUE use .Renviron variables template. can also set options(narrator.use_renviron = TRUE) make global session, create environment variable \"use_renviron\" changing .Renviron file usethis::edit_r_environ() return_data TRUE - return list variables used function's templates simplify TRUE - return character vector, FALSE - named list format_numbers TRUE - format big numbers K/M/B using format_num() function collapse_sep Separator glue_collapse cases multiple values single variable collapse_last Separator glue_collapse last item, cases multiple values single variable ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_forecast.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create Narrative for Time Series Forecast Data Frames — narrate_forecast","text":"list() narratives default character() simplify = TRUE","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_forecast.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Narrative for Time Series Forecast Data Frames — narrate_forecast","text":"","code":"library(prophet) #> Loading required package: Rcpp #> Loading required package: rlang library(dplyr) #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union library(tidyr) fit_prophet <- function(data) { model <- prophet(data) future <- make_future_dataframe(model, periods = 12, freq = \"month\") forecast <- predict(model, future) return(forecast) } grouped_data <- sales %>% dplyr::mutate(ds = lubridate::floor_date(Date, unit = \"month\")) %>% dplyr::group_by(Region, ds) %>% dplyr::summarise(y = sum(Sales, na.rm = TRUE)) %>% tidyr::nest() grouped_data$forecast <- lapply(grouped_data$data, fit_prophet) #> Disabling weekly seasonality. Run prophet with weekly.seasonality=TRUE to override this. #> Disabling daily seasonality. Run prophet with daily.seasonality=TRUE to override this. #> Disabling weekly seasonality. Run prophet with weekly.seasonality=TRUE to override this. #> Disabling daily seasonality. Run prophet with daily.seasonality=TRUE to override this. #> Disabling weekly seasonality. Run prophet with weekly.seasonality=TRUE to override this. #> Disabling daily seasonality. Run prophet with daily.seasonality=TRUE to override this. #> Disabling weekly seasonality. Run prophet with weekly.seasonality=TRUE to override this. #> Disabling daily seasonality. Run prophet with daily.seasonality=TRUE to override this. actuals <- grouped_data %>% dplyr::select(-forecast) %>% unnest(data) df <- grouped_data %>% dplyr::select(-data) %>% unnest(forecast) %>% dplyr::select(ds, yhat) %>% dplyr::left_join(actuals) %>% dplyr::rename(Actuals = y, Forecast = yhat) #> Adding missing grouping variables: `Region` #> Joining with `by = join_by(Region, ds)` narrate_forecast(df) #> $`Current Year Actuals` #> Actuals for 2021 are equal to 13.5 M #> #> $`Overall Forecast in the next 12 months` #> Overall forecast for the next 12 months is 13.8 M #> #> $`Overall increase the next 12 months` #> Projected increase in the next 12 months is equal to 447.7 K (3.3%). #>"},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Narrative for Metric Development in Time — narrate_trend","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"Create Narrative Metric Development Time","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"","code":"narrate_trend( df, measure = NULL, dimensions = NULL, date = NULL, frequency = NULL, summarization = \"sum\", type = \"yoy\", coverage = 0.5, coverage_limit = 5, narration_depth = 2, use_chatgpt = FALSE, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\"), template_total = \"From {timeframe_prev} to {timeframe_curr}, {measure} had an {trend} of {change} ({change_p}, {total_prev} to {total_curr}).\", template_average = \"Average {measure} had an {trend} of {change} ({change_p}, {total_prev} to {total_curr}).\", template_outlier = \"{dimension} with biggest changes of {measure} is {outlier_insight}.\", template_outlier_multiple = \"{pluralize(dimension)} with biggest changes of {measure} are {outlier_insight}.\", template_outlier_l2 = \"In {level_l1}, significant {level_l2} by {measure} change is {outlier_insight}.\", template_outlier_l2_multiple = \"In {level_l1}, significant {pluralize(level_l2)} by {measure} change are {outlier_insight}.\", use_renviron = FALSE, return_data = FALSE, simplify = FALSE, format_numbers = TRUE, collapse_sep = \", \", collapse_last = \" and \", ... )"},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"df data.frame() tibble() Data frame tibble, can aggregated raw measure Numeric measure function create calculations , NULL take first numeric field available dimensions Vector dimensions analysis, default character factor variable used date Name date column used time based analysis frequency Level time based aggregation comparing across years summarization Approach data summarization/aggregation - 'sum', 'count' 'average' type Type trend analysis create: 1 'yoy', 2 'previous period', 3 'period last year' coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation narration_depth Parameter control depth analysis 1 summary 2 detailed use_chatgpt TRUE - use ChatGPT enhance narrative openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\") template_total glue template total volumes narrative template_average glue template average volumes narrative template_outlier glue template single outlier narrative template_outlier_multiple glue template multiple outliers narrative template_outlier_l2 glue template deeper hierarchical single outlier narrative template_outlier_l2_multiple glue template deeper hierarchical multiple outliers narrative use_renviron TRUE use .Renviron variables template. can also set options(narrator.use_renviron = TRUE) make global session, create environment variable \"use_renviron\" changing .Renviron file usethis::edit_r_environ() return_data TRUE - return list variables used function's templates simplify TRUE - return character vector, FALSE - named list format_numbers TRUE - format big numbers K/M/B using format_num() function collapse_sep Separator glue_collapse cases multiple values single variable collapse_last Separator glue_collapse last item, cases multiple values single variable ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"list() narratives default character() simplify = TRUE","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrate_trend.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create Narrative for Metric Development in Time — narrate_trend","text":"","code":"sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"week\")) %>% dplyr::group_by(Region, Product, Date) %>% dplyr::summarise(Sales = sum(Sales, na.rm = TRUE)) %>% narrate_trend() #> $`2021 YTD vs 2020 YTD` #> From 2020 YTD to 2021 YTD, Sales had an increase of 1.08 M (8.7 %, 12.42 M to 13.5 M). #> #> $`Sales change by Region` #> Regions with biggest changes of Sales are NA (520.6 K, 8.89 %, 5.9 M to 6.4 M), EMEA (386.6 K, 9.17 %, 4.2 M to 4.6 M). #> #> $`NA by Product` #> In NA, significant Products by Sales change are Food & Beverage (239.3 K, 9.76 %, 2.5 M to 2.7 M), Tools (189.6 K, 32.51 %, 583.2 K to 772.7 K). #> #> $`EMEA by Product` #> In EMEA, significant Products by Sales change are Electronics (310.4 K, 35.72 %, 868.9 K to 1.2 M), Food & Beverage (223.4 K, 13.61 %, 1.6 M to 1.9 M). #> #> $`Sales change by Product` #> Products with biggest changes of Sales are Electronics (529.1 K, 19.95 %, 2.7 M to 3.2 M), Food & Beverage (507.9 K, 10.07 %, 5 M to 5.6 M). #>"},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":null,"dir":"Reference","previous_headings":"","what":"Server Logic for Narrator — narratorServer","title":"Server Logic for Narrator — narratorServer","text":"Server logic shiny module work together narratorUI","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Server Logic for Narrator — narratorServer","text":"","code":"narratorServer(id, df, summarization = \"sum\", ...)"},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Server Logic for Narrator — narratorServer","text":"id Namespace specification df Reactive data frame summarization Summarization/aggregation data - 'sum', 'count' 'average' ... Additional arguments narrate_* functions","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Server Logic for Narrator — narratorServer","text":"Narrative output","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorServer.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Server Logic for Narrator — narratorServer","text":"","code":"library(shiny) library(narrator) library(dplyr) #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union df <- sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) ui <- fluidPage( narratorUI(id = \"main\") ) server <- function(input, output, session) { narratorServer( id = \"main\", df = reactive(df), format = TRUE, summarization = \"sum\") } if (interactive()) shinyApp(ui, server)"},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":null,"dir":"Reference","previous_headings":"","what":"Shiny Module for Narrator — narratorUI","title":"Shiny Module for Narrator — narratorUI","text":"UI shiny module work together narratorServer","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Shiny Module for Narrator — narratorUI","text":"","code":"narratorUI( id, narration_depth = 2, coverage = 0.5, coverage_limit = 5, format = TRUE, ... )"},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Shiny Module for Narrator — narratorUI","text":"id Namespace specification narration_depth Parameter control depth analysis 1 summary 2 detailed coverage Numeric portion variability covered narrative, 0 1 coverage_limit Integer maximum number elements narrated, overrides coverage avoid extremely verbose narrative creation format TRUE - format text HTML tags ... arguments passed glue","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Shiny Module for Narrator — narratorUI","text":"UI","code":""},{"path":"https://denisabd.github.io/narrator/reference/narratorUI.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Shiny Module for Narrator — narratorUI","text":"","code":"library(shiny) library(narrator) library(dplyr) df <- sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) ui <- fluidPage( narratorUI(id = \"main\") ) server <- function(input, output, session) { narratorServer( id = \"main\", df = reactive(df), format = TRUE, summarization = \"sum\") } if (interactive()) shinyApp(ui, server)"},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":null,"dir":"Reference","previous_headings":"","what":"UI Module for Narrator — narrator_shiny","title":"UI Module for Narrator — narrator_shiny","text":"UI shiny module work together narratorServer Server logic shiny module work together narratorUI","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"UI Module for Narrator — narrator_shiny","text":"","code":"narratorUI( id, narration_depth = 2, coverage = 0.5, coverage_limit = 5, format = TRUE, ... ) narratorServer(id, df, summarization = \"sum\", format = TRUE, ...)"},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"UI Module for Narrator — narrator_shiny","text":"id Namespace specification format TRUE - format text HTML tags ... Additional arguments narrate_* functions df Reactive data frame","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"UI Module for Narrator — narrator_shiny","text":"UI Narrative output","code":""},{"path":"https://denisabd.github.io/narrator/reference/narrator_shiny.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"UI Module for Narrator — narrator_shiny","text":"","code":"library(shiny) library(narrator) library(dplyr) #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union df <- sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) #> `summarise()` has grouped output by 'Region'. You can override using the #> `.groups` argument. ui <- fluidPage( narratorUI(id = \"main\") ) server <- function(input, output, session) { narratorServer( id = \"main\", df = reactive(df), format = TRUE, summarization = \"sum\") } if (interactive()) shinyApp(ui, server)"},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":null,"dir":"Reference","previous_headings":"","what":"Pipe Operator — %>%","title":"Pipe Operator — %>%","text":"See magrittr::%>% details.","code":""},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Pipe Operator — %>%","text":"","code":"lhs %>% rhs"},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Pipe Operator — %>%","text":"lhs value magrittr placeholder. rhs function call using magrittr semantics.","code":""},{"path":"https://denisabd.github.io/narrator/reference/pipe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Pipe Operator — %>%","text":"result calling rhs(lhs).","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":null,"dir":"Reference","previous_headings":"","what":"Pluralize a Word in English — pluralize","title":"Pluralize a Word in English — pluralize","text":"Pluralize Word English","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Pluralize a Word in English — pluralize","text":"","code":"pluralize(x, n = 2, prepend = FALSE)"},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Pluralize a Word in English — pluralize","text":"x character vector words make plural n number plural (plurals change amount also impacts prepend functionality) prepend prepend value n output? Default: FALSE","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Pluralize a Word in English — pluralize","text":"character vector modified pluralized words","code":""},{"path":"https://denisabd.github.io/narrator/reference/pluralize.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Pluralize a Word in English — pluralize","text":"","code":"pluralize('test') #> [1] \"tests\" pluralize('test', 5) #> [1] \"tests\" pluralize('test', 5, TRUE) #> [1] \"5 tests\" pluralize('regex') #> [1] \"regexes\""},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":null,"dir":"Reference","previous_headings":"","what":"Synthetic Sales Data — sales","title":"Synthetic Sales Data — sales","text":"Synthetic Sales Data","code":""},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Synthetic Sales Data — sales","text":"","code":"sales"},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Synthetic Sales Data — sales","text":"tibble 10000 rows 9 variables: Order ID Unique ID order Date Date Order creation Region Region/Region shipment Product Product Name Store Store size - Big, Medium Small Promotion Promotion present Price Raw unit price quantity Quantity Number units sold Sales Final Sales, including promotional discounts","code":""},{"path":"https://denisabd.github.io/narrator/reference/sales.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Synthetic Sales Data — sales","text":"","code":"sales #> # A tibble: 10,000 × 9 #> `Order ID` Date Region Product Store Promo…¹ Price Quant…² Sales #> #> 1 QR10276 2019-01-30 EMEA Tools Big 1 89.6 28 2007. #> 2 QR15245 2020-07-26 ASPAC Tools Big 0 268. 7 1880. #> 3 QR13938 2020-03-05 EMEA Home Big 0 223. 18 4019. #> 4 QR15934 2020-10-08 LATAM Clothing Big 0 210. 27 5681. #> 5 QR10963 2019-04-15 EMEA Tools Big 0 193. 22 4248. #> 6 QR13639 2020-01-30 EMEA Food & Bever… Small 0 215. 8 1717. #> 7 QR13110 2019-12-04 LATAM Electronics Medi… 0 250. 22 5498. #> 8 QR19849 2021-12-13 EMEA Tools Big 0 223 59 13157 #> 9 QR13078 2019-12-01 EMEA Electronics Big 0 231 32 7392 #> 10 QR15064 2020-07-08 EMEA Tools Medi… 0 185. 21 3889. #> # … with 9,990 more rows, and abbreviated variable names ¹​Promotion, ²​Quantity"},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":null,"dir":"Reference","previous_headings":"","what":"Singularize a Word in English — singularize","title":"Singularize a Word in English — singularize","text":"Singularize Word English","code":""},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Singularize a Word in English — singularize","text":"","code":"singularize(x)"},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Singularize a Word in English — singularize","text":"x vector words make singular","code":""},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Singularize a Word in English — singularize","text":"modified character vector singularized words","code":""},{"path":"https://denisabd.github.io/narrator/reference/singularize.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Singularize a Word in English — singularize","text":"","code":"singularize('test') #> [1] \"test\" singularize(c(\"boats\", \"houses\", \"cats\", \"rivers\")) #> [1] \"boat\" \"house\" \"cat\" \"river\" pluralize(singularize(c(\"boats\", \"houses\", \"cats\", \"rivers\"))) #> [1] \"boats\" \"houses\" \"cats\" \"rivers\" singularize(c(\"buses\", \"wishes\", \"pitches\", \"boxexs\")) #> [1] \"bus\" \"wish\" \"pitch\" \"boxex\" pluralize(singularize(c(\"buses\", \"wishes\", \"pitches\", \"boxexs\"))) #> [1] \"buses\" \"wishes\" \"pitches\" \"boxexes\" singularize(c(\"pennies\", \"spies\", \"babies\", \"cities\", \"daisies\")) #> [1] \"penny\" \"spy\" \"baby\" \"city\" \"daisie\" pluralize(singularize(c(\"pennies\", \"spies\", \"babies\", \"cities\", \"daisies\"))) #> [1] \"pennies\" \"spies\" \"babies\" \"cities\" \"daisies\" singularize(c(\"sheep\", \"fish\", \"deer\", \"species\", \"aircraft\")) #> [1] \"sheep\" \"fish\" \"deer\" \"specie\" \"aircraft\" pluralize(singularize(c(\"sheep\", \"fish\", \"deer\", \"species\", \"aircraft\"))) #> [1] \"sheep\" \"fish\" \"deer\" \"species\" \"aircraft\""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":null,"dir":"Reference","previous_headings":"","what":"Summarize the narrative output with ChatGPT — summarize_narrative","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"Summarize narrative output ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"","code":"summarize_narrative( narrative, prompt = \"Summarize the following narrative to make it shorter:\", openai_api_key = Sys.getenv(\"OPENAI_API_KEY\") )"},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"narrative List narratives returned narrate_* function, character vector string enhanced ChatGPT prompt Prompt send OpenAI API openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\")","code":""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"character() narratives enhanced ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/summarize_narrative.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Summarize the narrative output with ChatGPT — summarize_narrative","text":"","code":"if (FALSE) { narrative <- sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% narrate_descriptive() narrative <- enhance_narrative(narrative) summarize_narrative(narrative) }"},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":null,"dir":"Reference","previous_headings":"","what":"Translate the narrative output with ChatGPT — translate_narrative","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"Translate narrative output ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"","code":"translate_narrative( narrative, prompt = \"Using professional language translate the following text to\", language, openai_api_key = Sys.getenv(\"OPENAI_API_KEY\") )"},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"narrative List narratives returned narrate_* function, character vector string enhanced ChatGPT prompt Prompt send OpenAI API language Write language translate narrative , please use English , ex. \"Spanish\" \"Español\" openai_api_key OpenAI API key, can set .Renviron file \"OPENAI_API_KEY\", function look Sys.getenv(\"OPENAI_API_KEY\")","code":""},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"character() narratives enhanced ChatGPT","code":""},{"path":"https://denisabd.github.io/narrator/reference/translate_narrative.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Translate the narrative output with ChatGPT — translate_narrative","text":"","code":"if (FALSE) { narrative <- sales %>% dplyr::filter(Product %in% c(\"Tools\", \"Clothing\", \"Home\")) %>% dplyr::group_by(Product, Region) %>% dplyr::summarise(Sales = sum(Sales)) %>% narrate_descriptive() narrative <- enhance_narrative(narrative) translate_narrative(narrative, \"Spanish\") }"},{"path":"https://denisabd.github.io/narrator/news/index.html","id":"narrator-010","dir":"Changelog","previous_headings":"","what":"narrator 0.1.0","title":"narrator 0.1.0","text":"CRAN Release Core functions narrative creation: narrate_descriptive(), narrate_trend() Output formatting functions rendering HTML Rmarkdown shiny OpenAI API, ChatGPT accessible improving, translating summarizing narratives","code":""}] diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 8c00b00..6350ffb 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -15,6 +15,9 @@ https://denisabd.github.io/narrator/articles/echarts.html + + https://denisabd.github.io/narrator/articles/forecast.html + https://denisabd.github.io/narrator/articles/formatting.html @@ -90,6 +93,9 @@ https://denisabd.github.io/narrator/reference/narrate_descriptive.html + + https://denisabd.github.io/narrator/reference/narrate_forecast.html + https://denisabd.github.io/narrator/reference/narrate_trend.html diff --git a/man/narrate_forecast.Rd b/man/narrate_forecast.Rd new file mode 100644 index 0000000..f025897 --- /dev/null +++ b/man/narrate_forecast.Rd @@ -0,0 +1,121 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/narrate_forecast.R +\name{narrate_forecast} +\alias{narrate_forecast} +\title{Create Narrative for Time Series Forecast Data Frames} +\usage{ +narrate_forecast( + df, + measure = NULL, + dimensions = NULL, + date = NULL, + frequency = NULL, + summarization = "sum", + type = "yoy", + coverage = 0.5, + coverage_limit = 5, + narration_depth = 2, + use_chatgpt = FALSE, + openai_api_key = Sys.getenv("OPENAI_API_KEY"), + forecast = "Forecast", + actuals = "Actuals", + template_cy = "Forecasted volume for {current_year} is {format_num(cy_forecast)}", + template_ftm = "Overall forecast for the next 12 months is {format_num(ftm_forecast)}", + template_ftm_change = + "Projected {trend} in the next 12 months is equal to {format_num(ftm_change)} ({ftm_change_p}\%).", + use_renviron = FALSE, + return_data = FALSE, + simplify = FALSE, + format_numbers = TRUE, + collapse_sep = ", ", + collapse_last = " and ", + ... +) +} +\arguments{ +\item{df}{\code{\link[=data.frame]{data.frame()}} or \code{\link[=tibble]{tibble()}} Data frame of tibble, can be aggregated or raw} + +\item{measure}{Numeric measure for function to create calculations with, +if NULL then it will take the first numeric field available} + +\item{dimensions}{Vector of dimensions for analysis, by default all character +or factor variable will be used} + +\item{date}{Name of the date column to be used for time based analysis} + +\item{frequency}{Level of time based aggregation for comparing across years} + +\item{summarization}{Approach for data summarization/aggregation - 'sum', 'count' or 'average'} + +\item{type}{Type of trend analysis to create: 1 or 'yoy', 2 or 'previous period', 3 or 'same period last year'} + +\item{coverage}{Numeric portion of variability to be covered by narrative, 0 to 1} + +\item{coverage_limit}{Integer maximum number of elements to be narrated, overrides +coverage to avoid extremely verbose narrative creation} + +\item{narration_depth}{Parameter to control the depth of the analysis 1 for summary and 2 for detailed} + +\item{use_chatgpt}{If \link{TRUE} - use ChatGPT to enhance the narrative} + +\item{openai_api_key}{Your OpenAI API key, you can set it up in .Renviron file as "OPENAI_API_KEY", function will look for it with \code{Sys.getenv("OPENAI_API_KEY")}} + +\item{forecast}{Name of the forecast column in the data frame} + +\item{actuals}{Name of the actuals column in the data frame} + +\item{use_renviron}{If \link{TRUE} use .Renviron variables in the template. +You can also set \code{options(narrator.use_renviron = TRUE)} to make it global for the session, +or create an environment variable "use_renviron" by changing your .Renviron file \code{usethis::edit_r_environ()}} + +\item{return_data}{If \link{TRUE} - return a list of variables used in the function's templates} + +\item{simplify}{If \link{TRUE} - return a character vector, if \link{FALSE} - named list} + +\item{format_numbers}{If \link{TRUE} - format big numbers to K/M/B using \code{\link[=format_num]{format_num()}} function} + +\item{collapse_sep}{Separator for \code{\link[glue]{glue_collapse}} in cases with multiple values in single variable} + +\item{collapse_last}{Separator for \code{\link[glue]{glue_collapse}} for the last item, in cases with multiple values in single variable} + +\item{...}{other arguments passed to \code{\link[glue]{glue}}} +} +\value{ +A \code{\link[=list]{list()}} of narratives by default and \code{\link[=character]{character()}} if \code{simplify = TRUE} +} +\description{ +Create Narrative for Time Series Forecast Data Frames +} +\examples{ +library(prophet) +library(dplyr) +library(tidyr) + +fit_prophet <- function(data) { + model <- prophet(data) + future <- make_future_dataframe(model, periods = 12, freq = "month") + forecast <- predict(model, future) + return(forecast) +} +grouped_data <- sales \%>\% + dplyr::mutate(ds = lubridate::floor_date(Date, unit = "month")) \%>\% + dplyr::group_by(Region, ds) \%>\% + dplyr::summarise(y = sum(Sales, na.rm = TRUE)) \%>\% + tidyr::nest() + +grouped_data$forecast <- lapply(grouped_data$data, fit_prophet) + +actuals <- grouped_data \%>\% + dplyr::select(-forecast) \%>\% + unnest(data) + +df <- grouped_data \%>\% + dplyr::select(-data) \%>\% + unnest(forecast) \%>\% + dplyr::select(ds, yhat) \%>\% + dplyr::left_join(actuals) \%>\% + dplyr::rename(Actuals = y, + Forecast = yhat) + +narrate_forecast(df) +} diff --git a/tests/testthat/test-narrate_forecast.R b/tests/testthat/test-narrate_forecast.R new file mode 100644 index 0000000..ade6075 --- /dev/null +++ b/tests/testthat/test-narrate_forecast.R @@ -0,0 +1,57 @@ +test_that("narrate_forecast() works", { + fit_prophet <- function(data) { + model <- prophet::prophet(data) + future <- prophet::make_future_dataframe(model, periods = 12, freq = "month") + forecast <- predict(model, future) + return(forecast) + } + + grouped_data <- sales %>% + dplyr::mutate(ds = lubridate::floor_date(Date, unit = "month")) %>% + dplyr::group_by(Region, ds) %>% + dplyr::summarise(y = sum(Sales, na.rm = TRUE)) %>% + tidyr::nest() + + grouped_data$forecast <- lapply(grouped_data$data, fit_prophet) + + actuals <- grouped_data %>% + dplyr::select(-forecast) %>% + tidyr::unnest(data) + + df <- grouped_data %>% + dplyr::select(-data) %>% + tidyr::unnest(forecast) %>% + dplyr::select(ds, yhat) %>% + dplyr::left_join(actuals) %>% + dplyr::rename(Actuals = y, + Forecast = yhat) + + expect_no_error(narrate_forecast(df)) + expect_no_error(narrate_forecast(df)) + expect_type(narrate_forecast(df), "list") + expect_type(narrate_forecast(df), "list") + expect_type(narrate_forecast(df, return_data = TRUE), "list") + expect_type(narrate_forecast(df, simplify = TRUE), "character") + expect_error(narrate_forecast(df, actuals = "y", forecast = "yhat")) + expect_error(narrate_forecast(df, coverage_limit = 0)) + expect_error(narrate_forecast(df, coverage_limit = 1.5)) + + expect_error({ + df %>% + dplyr::select(-ds) %>% + narrate_forecast() + }) + + expect_error({ + df %>% + dplyr::select(-Actuals) %>% + narrate_forecast() + }) + + expect_error({ + df %>% + dplyr::select(-Forecast) %>% + narrate_forecast() + }) +}) + diff --git a/vignettes/forecast.Rmd b/vignettes/forecast.Rmd new file mode 100644 index 0000000..f30bd67 --- /dev/null +++ b/vignettes/forecast.Rmd @@ -0,0 +1,75 @@ +--- +title: "Forecast Narratives" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Forecast Narratives} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + warning = FALSE, + message = FALSE, + comment = "#>" +) +``` + +```{r setup} +library(narrator) +library(dplyr) +library(tidyr) +library(lubridate) +library(knitr) +library(prophet) +``` + + +## Overall Forecast + +If we have a `data.frame` with a time series forecast and actuals in time, use `narrate_forecast()` to create the narrative around overall forecast, anticipated changes in the next time period and current year volumes. + +Let's use `prophet` as an example. Notice that we require a data frame here, so if you are using `ts` objects, please make relevant conversions first. + +```{r} +fit_prophet <- function(data) { + model <- prophet::prophet(data) + future <- prophet::make_future_dataframe(model, periods = 12, freq = "month") + forecast <- predict(model, future) + return(forecast) +} + +grouped_data <- sales %>% + dplyr::mutate(ds = lubridate::floor_date(Date, unit = "month")) %>% + dplyr::group_by(Region, ds) %>% + dplyr::summarise(y = sum(Sales, na.rm = TRUE)) %>% + tidyr::nest() + +grouped_data$forecast <- lapply(grouped_data$data, fit_prophet) + +actuals <- grouped_data %>% + dplyr::select(-forecast) %>% + tidyr::unnest(data) + +df <- grouped_data %>% + dplyr::select(-data) %>% + tidyr::unnest(forecast) %>% + dplyr::select(ds, yhat) %>% + dplyr::left_join(actuals) %>% + dplyr::rename(Actuals = y, + Forecast = yhat) +``` + + +```{r} +df %>% + head() %>% + kable() +``` + +Actuals in the most recent year, overall forecast for the next year (if available in forecast data frame) and projected YoY change for next vs last twelve months: +```{r} +narrate_forecast(df, forecast = "Forecast", actuals = "Actuals") +``` +