From 1101eed0ba92710ec6fcc7b4e0caa96df8ae5b29 Mon Sep 17 00:00:00 2001 From: Denis Abdullin Date: Mon, 3 Jul 2023 16:31:43 +0200 Subject: [PATCH] trend narrative fixed for time periods and shorter time series --- R/helpers.R | 13 ++++- R/narrate_trend.R | 131 +++++++++++++++++++++++++--------------------- README.md | 46 ---------------- docs/index.html | 7 --- docs/pkgdown.yml | 2 +- docs/search.json | 2 +- package_prep.R | 1 - 7 files changed, 84 insertions(+), 118 deletions(-) diff --git a/R/helpers.R b/R/helpers.R index 24969a3..6c841b1 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -264,6 +264,14 @@ pytd_volume <- function( previous_year <- lubridate::year(py_date) } + df <- df %>% + dplyr::mutate(year = lubridate::year(base::get(date))) %>% + dplyr::filter(year == previous_year, + base::get(date) <= py_date) + + # return NA rather than 0 if there are no records for previous year + if (nrow(df) == 0) return(NA) + py_volume <- df %>% dplyr::mutate(year = lubridate::year(base::get(date))) %>% dplyr::filter(year == previous_year, @@ -413,7 +421,10 @@ get_trend_outliers <- function( ) %>% dplyr::ungroup() %>% dplyr::select(-data) %>% - dplyr::arrange(-abs_change) + dplyr::arrange(-abs_change) %>% + dplyr::filter(!is.na(change)) + + if (nrow(table) == 0) return(NULL) if (summarization %in% c("sum", "count")) { diff --git a/R/narrate_trend.R b/R/narrate_trend.R index 7444327..b40d50f 100644 --- a/R/narrate_trend.R +++ b/R/narrate_trend.R @@ -241,76 +241,83 @@ narrate_trend <- function( narrative_name <- glue::glue("{timeframe_curr} vs {timeframe_prev}") change <- round(total_curr_raw - total_prev_raw, 1) - change_p <- paste(round((total_curr_raw/total_prev_raw - 1)*100, 1), "%") - trend <- ifelse(change > 0, "increase", "decrease") - if (format_numbers == TRUE) { - total_curr <- format_num(total_curr_raw, decimals = 2) - total_prev <- format_num(total_prev_raw, decimals = 2) - change <- format_num(change, decimals = 2) - } else { - total_curr <- total_curr_raw - total_prev <- total_prev_raw - change <- format_num(change, decimals = 2) - } + if (!is.na(change)) { - # Sum/Count --------------------------------------------------------------- - if (summarization %in% c("sum", "count")) { + change_p <- paste(round((total_curr_raw/total_prev_raw - 1)*100, 1), "%") + trend <- ifelse(change > 0, "increase", "decrease") - narrative_total <- glue::glue( - template_total, - .transformer = collapse_transformer(sep = collapse_sep, last = collapse_last) - ) + if (format_numbers == TRUE) { + total_curr <- format_num(total_curr_raw, decimals = 2) + total_prev <- format_num(total_prev_raw, decimals = 2) + change <- format_num(change, decimals = 2) + } else { + total_curr <- total_curr_raw + total_prev <- total_prev_raw + change <- format_num(change, decimals = 2) + } + + # Sum/Count --------------------------------------------------------------- + if (summarization %in% c("sum", "count")) { - narrative <- list(narrative_total) %>% - rlang::set_names(narrative_name) - - variables <- list( - list( - narrative_total = narrative_total, - template_total = template_total, - measure = measure, - total_curr = total_curr, - total_curr_raw = total_curr_raw, - total_prev = total_prev, - total_prev_raw = total_prev_raw, - timeframe_curr = timeframe_curr, - timeframe_prev = timeframe_prev, - change = change, - change_p = change_p, - trend = trend + narrative_total <- glue::glue( + template_total, + .transformer = collapse_transformer(sep = collapse_sep, last = collapse_last) ) - ) %>% - rlang::set_names(narrative_name) - # Average ------------------------------------------------------------ - } else if (summarization == "average") { + narrative <- list(narrative_total) %>% + rlang::set_names(narrative_name) - narrative_average <- glue::glue( - template_average, - .transformer = collapse_transformer(sep = collapse_sep, last = collapse_last) - ) + variables <- list( + list( + narrative_total = narrative_total, + template_total = template_total, + measure = measure, + total_curr = total_curr, + total_curr_raw = total_curr_raw, + total_prev = total_prev, + total_prev_raw = total_prev_raw, + timeframe_curr = timeframe_curr, + timeframe_prev = timeframe_prev, + change = change, + change_p = change_p, + trend = trend + ) + ) %>% + rlang::set_names(narrative_name) - narrative <- list(narrative_average) %>% - rlang::set_names(narrative_name) - - variables <- list( - list( - narrative_average = narrative_average, - template_average = template_average, - measure = measure, - total_curr = total_curr, - total_curr_raw = total_curr_raw, - total_prev = total_prev, - total_prev_raw = total_prev_raw, - timeframe_curr = timeframe_curr, - timeframe_prev = timeframe_prev, - change = change, - change_p = change_p, - trend = trend + # Average ------------------------------------------------------------ + } else if (summarization == "average") { + + narrative_average <- glue::glue( + template_average, + .transformer = collapse_transformer(sep = collapse_sep, last = collapse_last) ) - ) %>% - rlang::set_names(narrative_name) + + narrative <- list(narrative_average) %>% + rlang::set_names(narrative_name) + + variables <- list( + list( + narrative_average = narrative_average, + template_average = template_average, + measure = measure, + total_curr = total_curr, + total_curr_raw = total_curr_raw, + total_prev = total_prev, + total_prev_raw = total_prev_raw, + timeframe_curr = timeframe_curr, + timeframe_prev = timeframe_prev, + change = change, + change_p = change_p, + trend = trend + ) + ) %>% + rlang::set_names(narrative_name) + } + } else { + narrative <- list() + variables <- list() } # Adding Date as dimension and leaving last two years only @@ -558,6 +565,8 @@ narrate_trend <- function( } # Output ------------------------------------------------------------------ + if (length(narrative) == 0) return(NULL) + if (return_data == TRUE) { return(variables) } diff --git a/README.md b/README.md index bf5e672..614b772 100644 --- a/README.md +++ b/README.md @@ -135,26 +135,6 @@ narrative_enhanced <- enhance_narrative(narrative_one) cat(narrative_enhanced) ``` -The Total Sales generated across all Regions amounted to a staggering -38790478.4. Upon closer examination, it was found that the Outlying -Regions, namely NA and EMEA, contributed significantly to this -impressive figure. NA accounted for 18079736.4, which translates to -46.6%, while EMEA contributed 13555412.7, which is 34.9% of the Total -Sales. - -Further analysis of the sales data revealed that within NA, the -significant Products that contributed to these sales figures were Food & -Beverage, generating 7392821 or 40.9%, followed by Electronics, which -generated 3789132.7 or 21%. Similarly, within EMEA, the significant -Products were Food & Beverage, generating 5265113.2 or 38.8%, followed -by Electronics, which generated 3182803.4 or 23.5%. - -It is noteworthy to mention that the Outlying Products that contributed -to the Total Sales were primarily Food & Beverage, generating 15543469.7 -or 40.1%, followed by Electronics, which generated 8608962.8 or 22.2%. -These sales figures are a testament to the strong performance of the -Food & Beverage category across all Regions. - ### Translation Translate you text using `translate_narrative()` function, specify @@ -165,25 +145,6 @@ translation <- translate_narrative(narrative_enhanced, language = "Czech") cat(translation) ``` -Celkové tržby vygenerované ve všech oblastech dosáhly ohromujícího čísla -38790478.4. Po bližším prozkoumání bylo zjištěno, že odlehlé oblasti, -konkrétně NA a EMEA, významně přispěly k tomuto úžasnému číslu. NA -představuje 18079736.4, což představuje 46,6%, zatímco EMEA přispěla -13555412.7, což je 34,9% celkových tržeb. - -Další analýza prodejních dat odhalila, že v rámci NA jsou významné -produkty, které přispěly k těmto prodejním číslům, potraviny a nápoje, -které vygenerovaly 7392821 nebo 40,9%, následované elektronikou, která -vygenerovala 3789132.7 nebo 21%. Podobně v rámci EMEA jsou významné -produkty potraviny a nápoje, které vygenerovaly 5265113.2 nebo 38,8%, -následované elektronikou, která vygenerovala 3182803.4 nebo 23,5%. - -Je důležité zmínit, že odlehlé produkty, které přispěly k celkovým -tržbám, byly především potraviny a nápoje, které vygenerovaly 15543469.7 -nebo 40,1%, následované elektronikou, která vygenerovala 8608962.8 nebo -22,2%. Tyto prodejní čísla jsou důkazem silného výkonu kategorie -potravin a nápojů ve všech oblastech. - ### Summarization If your output is too verbose you can summarize it with @@ -194,13 +155,6 @@ summarization <- summarize_narrative(narrative_enhanced) cat(summarization) ``` -Total sales were 38790478.4, with significant contributions from North -America (46.6%) and EMEA (34.9%). Food & Beverage was the top-selling -product in both regions, generating 40.9% and 38.8% of sales, -respectively. Electronics followed with 21% and 23.5% of sales. Food & -Beverage and Electronics were also the top-selling products overall, -contributing 40.1% and 22.2% to total sales, respectively. - # Python Here are some basic Python examples, for more details visit [pynarrator diff --git a/docs/index.html b/docs/index.html index 2c94f46..2dc4264 100644 --- a/docs/index.html +++ b/docs/index.html @@ -173,9 +173,6 @@

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

The Total Sales generated across all Regions amounted to a staggering 38790478.4. Upon closer examination, it was found that the Outlying Regions, namely NA and EMEA, contributed significantly to this impressive figure. NA accounted for 18079736.4, which translates to 46.6%, while EMEA contributed 13555412.7, which is 34.9% of the Total Sales.

-

Further analysis of the sales data revealed that within NA, the significant Products that contributed to these sales figures were Food & Beverage, generating 7392821 or 40.9%, followed by Electronics, which generated 3789132.7 or 21%. Similarly, within EMEA, the significant Products were Food & Beverage, generating 5265113.2 or 38.8%, followed by Electronics, which generated 3182803.4 or 23.5%.

-

It is noteworthy to mention that the Outlying Products that contributed to the Total Sales were primarily Food & Beverage, generating 15543469.7 or 40.1%, followed by Electronics, which generated 8608962.8 or 22.2%. These sales figures are a testament to the strong performance of the Food & Beverage category across all Regions.

Translation

@@ -183,9 +180,6 @@

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

-

Celkové tržby vygenerované ve všech oblastech dosáhly ohromujícího čísla 38790478.4. Po bližším prozkoumání bylo zjištěno, že odlehlé oblasti, konkrétně NA a EMEA, významně přispěly k tomuto úžasnému číslu. NA představuje 18079736.4, což představuje 46,6%, zatímco EMEA přispěla 13555412.7, což je 34,9% celkových tržeb.

-

Další analýza prodejních dat odhalila, že v rámci NA jsou významné produkty, které přispěly k těmto prodejním číslům, potraviny a nápoje, které vygenerovaly 7392821 nebo 40,9%, následované elektronikou, která vygenerovala 3789132.7 nebo 21%. Podobně v rámci EMEA jsou významné produkty potraviny a nápoje, které vygenerovaly 5265113.2 nebo 38,8%, následované elektronikou, která vygenerovala 3182803.4 nebo 23,5%.

-

Je důležité zmínit, že odlehlé produkty, které přispěly k celkovým tržbám, byly především potraviny a nápoje, které vygenerovaly 15543469.7 nebo 40,1%, následované elektronikou, která vygenerovala 8608962.8 nebo 22,2%. Tyto prodejní čísla jsou důkazem silného výkonu kategorie potravin a nápojů ve všech oblastech.

Summarization @@ -194,7 +188,6 @@

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

-

Total sales were 38790478.4, with significant contributions from North America (46.6%) and EMEA (34.9%). Food & Beverage was the top-selling product in both regions, generating 40.9% and 38.8% of sales, respectively. Electronics followed with 21% and 23.5% of sales. Food & Beverage and Electronics were also the top-selling products overall, contributing 40.1% and 22.2% to total sales, respectively.

diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 9f70c28..9152f2c 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -8,7 +8,7 @@ articles: formatting: formatting.html templates: templates.html trend: trend.html -last_built: 2023-06-25T17:52Z +last_built: 2023-07-03T14:29Z urls: reference: https://denisabd.github.io/narrator/reference article: https://denisabd.github.io/narrator/articles diff --git a/docs/search.json b/docs/search.json index ae2321b..b660a42 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/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 #> #> $`12 Month Projection` #> 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 302.9 K (2.24%). #> #> $`2022 YTD vs 2021 YTD` #> From 2021 YTD to 2022 YTD, Forecast had an increase of 302.88 K (2.2 %, 13.55 M to 13.85 M). #> #> $`Forecast change by Region` #> Regions with biggest changes of Forecast are NA (217.7 K, 3.41 %, 6.4 M to 6.6 M), ASPAC (148.4 K, 10.32 %, 1.4 M to 1.6 M). #> #> $`NA by Month` #> In NA, significant Months by Forecast change are May (121 K, 28.93 %, 418.2 K to 539.2 K), Dec (106 K, 14.45 %, 733.4 K to 839.4 K), Apr (-75.5 K, -12.79 %, 590.2 K to 514.7 K), Jul (71.2 K, 20.24 %, 351.7 K to 422.9 K). #> #> $`ASPAC by Month` #> In ASPAC, significant Months by Forecast change are May (40.5 K, 37.34 %, 108.6 K to 149.1 K), Jul (35.5 K, 57.07 %, 62.2 K to 97.7 K), Nov (-34.1 K, -19.14 %, 178.2 K to 144.1 K), Sep (26.3 K, 29.15 %, 90.3 K to 116.6 K). #> #> $`Forecast change by Month` #> Months with biggest changes of Forecast are May (141.3 K, 13.62 %, 1 M to 1.2 M), Mar (138 K, 13.94 %, 989.3 K to 1.1 M), Nov (-108.8 K, -6.36 %, 1.7 M to 1.6 M), Sep (97.4 K, 8.68 %, 1.1 M to 1.2 M)."},{"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). #> #> $`Food & Beverage by Month` #> In Food & Beverage, significant Months by Sales change are Oct (-141.6 K, -23.39 %, 605.4 K to 463.8 K), Sep (132.7 K, 37.27 %, 356.2 K to 489 K), Dec (118.3 K, 16.67 %, 709.5 K to 827.8 K), May (99 K, 28.12 %, 352 K to 451 K). #> #> $`Electronics by Month` #> In Electronics, significant Months by Sales change are Nov (170.7 K, 70.62 %, 241.7 K to 412.4 K), Dec (108.3 K, 36.23 %, 298.8 K to 407.1 K), May (-74.1 K, -26.73 %, 277.3 K to 203.2 K), Feb (70.6 K, 38.24 %, 184.6 K to 255.3 K). #> #> $`Sales change by Month` #> Months with biggest changes of Sales are Nov (386.5 K, 29.17 %, 1.3 M to 1.7 M), Apr (226.6 K, 24.4 %, 928.6 K to 1.2 M), Jan (162.2 K, 23.06 %, 703.4 K to 865.6 K)."},{"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` Total Sales generated across Regions amounted staggering 38790478.4. Upon closer examination, found Outlying Regions, namely NA EMEA, contributed significantly impressive figure. NA accounted 18079736.4, translates 46.6%, EMEA contributed 13555412.7, 34.9% Total Sales. analysis sales data revealed within NA, significant Products contributed sales figures Food & Beverage, generating 7392821 40.9%, followed Electronics, generated 3789132.7 21%. Similarly, within EMEA, significant Products Food & Beverage, generating 5265113.2 38.8%, followed Electronics, generated 3182803.4 23.5%. noteworthy mention Outlying Products contributed Total Sales primarily Food & Beverage, generating 15543469.7 40.1%, followed Electronics, generated 8608962.8 22.2%. sales figures testament strong performance Food & Beverage category across Regions.","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é tržby vygenerované ve všech oblastech dosáhly ohromujícího čísla 38790478.4. Po bližším prozkoumání bylo zjištěno, že odlehlé oblasti, konkrétně NA EMEA, významně přispěly k tomuto úžasnému číslu. NA představuje 18079736.4, což představuje 46,6%, zatímco EMEA přispěla 13555412.7, což je 34,9% celkových tržeb. Další analýza prodejních dat odhalila, že v rámci NA jsou významné produkty, které přispěly k těmto prodejním číslům, potraviny nápoje, které vygenerovaly 7392821 nebo 40,9%, následované elektronikou, která vygenerovala 3789132.7 nebo 21%. Podobně v rámci EMEA jsou významné produkty potraviny nápoje, které vygenerovaly 5265113.2 nebo 38,8%, následované elektronikou, která vygenerovala 3182803.4 nebo 23,5%. Je důležité zmínit, že odlehlé produkty, které přispěly k celkovým tržbám, byly především potraviny nápoje, které vygenerovaly 15543469.7 nebo 40,1%, následované elektronikou, která vygenerovala 8608962.8 nebo 22,2%. Tyto prodejní čísla jsou důkazem silného výkonu kategorie potravin nápojů ve všech oblastech.","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, significant contributions North America (46.6%) EMEA (34.9%). Food & Beverage top-selling product regions, generating 40.9% 38.8% sales, respectively. Electronics followed 21% 23.5% sales. Food & Beverage Electronics also top-selling products overall, contributing 40.1% 22.2% total sales, respectively.","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 written 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\") ... arguments passed gpt_get_completions()","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] \"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: 15 × 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_forecast forecast template_cy Forecasted volu… #> 8 narrate_forecast forecast template_ftm Overall forecas… #> 9 narrate_forecast forecast template_ftm_change Projected {tren… #> 10 narrate_trend trend template_total From {timeframe… #> 11 narrate_trend trend template_average Average {measur… #> 12 narrate_trend trend template_outlier {dimension} wit… #> 13 narrate_trend trend template_outlier_multiple {pluralize(dime… #> 14 narrate_trend trend template_outlier_l2 In {level_l1}, … #> 15 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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0, 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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics. 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, 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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0, 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 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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics. forecast Name forecast column data frame actuals Name actuals column data frame template_cy glue template current year volumes narrative template_ftm glue template future 12 months projection template_ftm_change glue template projected change next 12 months 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 #> #> $`12 Month Projection` #> 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 302.9 K (2.24%). #> #> $`2022 YTD vs 2021 YTD` #> From 2021 YTD to 2022 YTD, Forecast had an increase of 302.88 K (2.2 %, 13.55 M to 13.85 M). #> #> $`Forecast change by Region` #> Regions with biggest changes of Forecast are NA (217.7 K, 3.41 %, 6.4 M to 6.6 M), ASPAC (148.4 K, 10.32 %, 1.4 M to 1.6 M). #> #> $`NA by Month` #> In NA, significant Months by Forecast change are May (121 K, 28.93 %, 418.2 K to 539.2 K), Dec (106 K, 14.45 %, 733.4 K to 839.4 K), Apr (-75.5 K, -12.79 %, 590.2 K to 514.7 K), Jul (71.2 K, 20.24 %, 351.7 K to 422.9 K). #> #> $`ASPAC by Month` #> In ASPAC, significant Months by Forecast change are May (40.5 K, 37.34 %, 108.6 K to 149.1 K), Jul (35.5 K, 57.07 %, 62.2 K to 97.7 K), Nov (-34.1 K, -19.14 %, 178.2 K to 144.1 K), Sep (26.3 K, 29.15 %, 90.3 K to 116.6 K). #> #> $`Forecast change by Month` #> Months with biggest changes of Forecast are May (141.3 K, 13.62 %, 1 M to 1.2 M), Mar (138 K, 13.94 %, 989.3 K to 1.1 M), Nov (-108.8 K, -6.36 %, 1.7 M to 1.6 M), Sep (97.4 K, 8.68 %, 1.1 M to 1.2 M). #>"},{"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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0, 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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics. 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 = \"month\")) %>% 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.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). #> #> $`Food & Beverage by Month` #> In Food & Beverage, significant Months by Sales change are Oct (-141.6 K, -23.39 %, 605.4 K to 463.8 K), Sep (132.7 K, 37.27 %, 356.2 K to 489 K), Dec (118.3 K, 16.67 %, 709.5 K to 827.8 K), May (99 K, 28.12 %, 352 K to 451 K). #> #> $`Electronics by Month` #> In Electronics, significant Months by Sales change are Nov (170.7 K, 70.62 %, 241.7 K to 412.4 K), Dec (108.3 K, 36.23 %, 298.8 K to 407.1 K), May (-74.1 K, -26.73 %, 277.3 K to 203.2 K), Feb (70.6 K, 38.24 %, 184.6 K to 255.3 K). #> #> $`Sales change by Month` #> Months with biggest changes of Sales are Nov (386.5 K, 29.17 %, 1.3 M to 1.7 M), Apr (226.6 K, 24.4 %, 928.6 K to 1.2 M), Jan (162.2 K, 23.06 %, 703.4 K to 865.6 K). #> sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"quarter\")) %>% 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.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). #> #> $`Food & Beverage by Quarter` #> In Food & Beverage, significant Quarters by Sales change are Q2 (261.4 K, 24.46 %, 1.1 M to 1.3 M), Q3 (211.7 K, 21.84 %, 969.1 K to 1.2 M). #> #> $`Electronics by Quarter` #> In Electronics, significant Quarter by Sales change is Q4 (340.8 K, 40.13 %, 849.1 K to 1.2 M). #> #> $`Sales change by Quarter` #> Quarters with biggest changes of Sales are Q4 (508.5 K, 11.41 %, 4.5 M to 5 M), Q2 (354.3 K, 13.35 %, 2.7 M to 3 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, narrative_type = \"descriptive\", 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 narrative_type Type narrative 'descriptive', 'trend' 'forecast' 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) 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\") ... arguments passed gpt_get_completions()","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/to_html.html","id":null,"dir":"Reference","previous_headings":"","what":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"Format Narrative HTML tags Interactive Reports Applications","code":""},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"","code":"to_html(narrative, format_percentage = TRUE, title_tag = \"h3\", ...)"},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"narrative List narratives returned narrate_* function format_percentage Add percentage formatting text title_tag HTML tag added names narrative ... arguments passed format_pct() function","code":""},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"html character() text strings","code":""},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"","code":"library(dplyr) sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) %>% narrate_descriptive() %>% to_html() #>

Total Sales <\/h3> Total Sales across all Regions is 38790478.4.

Region by Sales <\/h3> Outlying Regions by Sales are NA (18079736.4, 46.6 %<\/span><\/b>), EMEA (13555412.7, 34.9 %<\/span><\/b>).

NA by Product <\/h3> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %<\/span><\/b>), Electronics (3789132.7, 21 %<\/span><\/b>).

EMEA by Product <\/h3> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %<\/span><\/b>), Electronics (3182803.4, 23.5 %<\/span><\/b>).

Product by Sales <\/h3> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %<\/span><\/b>), Electronics (8608962.8, 22.2 %<\/span><\/b>)."},{"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\") ... arguments passed gpt_get_completions()","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(), narrate_forecast() 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 #> #> $`12 Month Projection` #> 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 302.9 K (2.24%). #> #> $`2022 YTD vs 2021 YTD` #> From 2021 YTD to 2022 YTD, Forecast had an increase of 302.88 K (2.2 %, 13.55 M to 13.85 M). #> #> $`Forecast change by Region` #> Regions with biggest changes of Forecast are NA (217.7 K, 3.41 %, 6.4 M to 6.6 M), ASPAC (148.4 K, 10.32 %, 1.4 M to 1.6 M). #> #> $`NA by Month` #> In NA, significant Months by Forecast change are May (121 K, 28.93 %, 418.2 K to 539.2 K), Dec (106 K, 14.45 %, 733.4 K to 839.4 K), Apr (-75.5 K, -12.79 %, 590.2 K to 514.7 K), Jul (71.2 K, 20.24 %, 351.7 K to 422.9 K). #> #> $`ASPAC by Month` #> In ASPAC, significant Months by Forecast change are May (40.5 K, 37.34 %, 108.6 K to 149.1 K), Jul (35.5 K, 57.07 %, 62.2 K to 97.7 K), Nov (-34.1 K, -19.14 %, 178.2 K to 144.1 K), Sep (26.3 K, 29.15 %, 90.3 K to 116.6 K). #> #> $`Forecast change by Month` #> Months with biggest changes of Forecast are May (141.3 K, 13.62 %, 1 M to 1.2 M), Mar (138 K, 13.94 %, 989.3 K to 1.1 M), Nov (-108.8 K, -6.36 %, 1.7 M to 1.6 M), Sep (97.4 K, 8.68 %, 1.1 M to 1.2 M)."},{"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). #> #> $`Food & Beverage by Month` #> In Food & Beverage, significant Months by Sales change are Oct (-141.6 K, -23.39 %, 605.4 K to 463.8 K), Sep (132.7 K, 37.27 %, 356.2 K to 489 K), Dec (118.3 K, 16.67 %, 709.5 K to 827.8 K), May (99 K, 28.12 %, 352 K to 451 K). #> #> $`Electronics by Month` #> In Electronics, significant Months by Sales change are Nov (170.7 K, 70.62 %, 241.7 K to 412.4 K), Dec (108.3 K, 36.23 %, 298.8 K to 407.1 K), May (-74.1 K, -26.73 %, 277.3 K to 203.2 K), Feb (70.6 K, 38.24 %, 184.6 K to 255.3 K). #> #> $`Sales change by Month` #> Months with biggest changes of Sales are Nov (386.5 K, 29.17 %, 1.3 M to 1.7 M), Apr (226.6 K, 24.4 %, 928.6 K to 1.2 M), Jan (162.2 K, 23.06 %, 703.4 K to 865.6 K)."},{"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`","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:","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:","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 written narrative by adding better business language for the following:\", openai_api_key = Sys.getenv(\"OPENAI_API_KEY\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0 )"},{"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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics.","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] \"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: 15 × 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_forecast forecast template_cy Forecasted volu… #> 8 narrate_forecast forecast template_ftm Overall forecas… #> 9 narrate_forecast forecast template_ftm_change Projected {tren… #> 10 narrate_trend trend template_total From {timeframe… #> 11 narrate_trend trend template_average Average {measur… #> 12 narrate_trend trend template_outlier {dimension} wit… #> 13 narrate_trend trend template_outlier_multiple {pluralize(dime… #> 14 narrate_trend trend template_outlier_l2 In {level_l1}, … #> 15 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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0, 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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics. 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, 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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0, 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 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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics. forecast Name forecast column data frame actuals Name actuals column data frame template_cy glue template current year volumes narrative template_ftm glue template future 12 months projection template_ftm_change glue template projected change next 12 months 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 #> #> $`12 Month Projection` #> 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 302.9 K (2.24%). #> #> $`2022 YTD vs 2021 YTD` #> From 2021 YTD to 2022 YTD, Forecast had an increase of 302.88 K (2.2 %, 13.55 M to 13.85 M). #> #> $`Forecast change by Region` #> Regions with biggest changes of Forecast are NA (217.7 K, 3.41 %, 6.4 M to 6.6 M), ASPAC (148.4 K, 10.32 %, 1.4 M to 1.6 M). #> #> $`NA by Month` #> In NA, significant Months by Forecast change are May (121 K, 28.93 %, 418.2 K to 539.2 K), Dec (106 K, 14.45 %, 733.4 K to 839.4 K), Apr (-75.5 K, -12.79 %, 590.2 K to 514.7 K), Jul (71.2 K, 20.24 %, 351.7 K to 422.9 K). #> #> $`ASPAC by Month` #> In ASPAC, significant Months by Forecast change are May (40.5 K, 37.34 %, 108.6 K to 149.1 K), Jul (35.5 K, 57.07 %, 62.2 K to 97.7 K), Nov (-34.1 K, -19.14 %, 178.2 K to 144.1 K), Sep (26.3 K, 29.15 %, 90.3 K to 116.6 K). #> #> $`Forecast change by Month` #> Months with biggest changes of Forecast are May (141.3 K, 13.62 %, 1 M to 1.2 M), Mar (138 K, 13.94 %, 989.3 K to 1.1 M), Nov (-108.8 K, -6.36 %, 1.7 M to 1.6 M), Sep (97.4 K, 8.68 %, 1.1 M to 1.2 M). #>"},{"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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0, 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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics. 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 = \"month\")) %>% 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.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). #> #> $`Food & Beverage by Month` #> In Food & Beverage, significant Months by Sales change are Oct (-141.6 K, -23.39 %, 605.4 K to 463.8 K), Sep (132.7 K, 37.27 %, 356.2 K to 489 K), Dec (118.3 K, 16.67 %, 709.5 K to 827.8 K), May (99 K, 28.12 %, 352 K to 451 K). #> #> $`Electronics by Month` #> In Electronics, significant Months by Sales change are Nov (170.7 K, 70.62 %, 241.7 K to 412.4 K), Dec (108.3 K, 36.23 %, 298.8 K to 407.1 K), May (-74.1 K, -26.73 %, 277.3 K to 203.2 K), Feb (70.6 K, 38.24 %, 184.6 K to 255.3 K). #> #> $`Sales change by Month` #> Months with biggest changes of Sales are Nov (386.5 K, 29.17 %, 1.3 M to 1.7 M), Apr (226.6 K, 24.4 %, 928.6 K to 1.2 M), Jan (162.2 K, 23.06 %, 703.4 K to 865.6 K). #> sales %>% dplyr::mutate(Date = lubridate::floor_date(Date, unit = \"quarter\")) %>% 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.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). #> #> $`Food & Beverage by Quarter` #> In Food & Beverage, significant Quarters by Sales change are Q2 (261.4 K, 24.46 %, 1.1 M to 1.3 M), Q3 (211.7 K, 21.84 %, 969.1 K to 1.2 M). #> #> $`Electronics by Quarter` #> In Electronics, significant Quarter by Sales change is Q4 (340.8 K, 40.13 %, 849.1 K to 1.2 M). #> #> $`Sales change by Quarter` #> Quarters with biggest changes of Sales are Q4 (508.5 K, 11.41 %, 4.5 M to 5 M), Q2 (354.3 K, 13.35 %, 2.7 M to 3 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, narrative_type = \"descriptive\", 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 narrative_type Type narrative 'descriptive', 'trend' 'forecast' 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) 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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0 )"},{"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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics.","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/to_html.html","id":null,"dir":"Reference","previous_headings":"","what":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"Format Narrative HTML tags Interactive Reports Applications","code":""},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"","code":"to_html(narrative, format_percentage = TRUE, title_tag = \"h3\", ...)"},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"narrative List narratives returned narrate_* function format_percentage Add percentage formatting text title_tag HTML tag added names narrative ... arguments passed format_pct() function","code":""},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"html character() text strings","code":""},{"path":"https://denisabd.github.io/narrator/reference/to_html.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Format the Narrative with HTML tags for Interactive Reports and Applications — to_html","text":"","code":"library(dplyr) sales %>% group_by(Region, Product) %>% summarise(Sales = sum(Sales, na.rm = TRUE)) %>% arrange(desc(Sales)) %>% narrate_descriptive() %>% to_html() #>

Total Sales <\/h3> Total Sales across all Regions is 38790478.4.

Region by Sales <\/h3> Outlying Regions by Sales are NA (18079736.4, 46.6 %<\/span><\/b>), EMEA (13555412.7, 34.9 %<\/span><\/b>).

NA by Product <\/h3> In NA, significant Products by Sales are Food & Beverage (7392821, 40.9 %<\/span><\/b>), Electronics (3789132.7, 21 %<\/span><\/b>).

EMEA by Product <\/h3> In EMEA, significant Products by Sales are Food & Beverage (5265113.2, 38.8 %<\/span><\/b>), Electronics (3182803.4, 23.5 %<\/span><\/b>).

Product by Sales <\/h3> Outlying Products by Sales are Food & Beverage (15543469.7, 40.1 %<\/span><\/b>), Electronics (8608962.8, 22.2 %<\/span><\/b>)."},{"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\"), max_tokens = 1024, temperature = 0.5, top_p = 1, frequency_penalty = 0, presence_penalty = 0 )"},{"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\") max_tokens maximum number tokens generate chat completion. temperature sampling temperature use, 0 2. Higher values like 0.8 make output random, lower values like 0.2 make focused deterministic. top_p alternative sampling temperature, called nucleus sampling, model considers results tokens top_p probability mass. 0.1 means tokens comprising top 10% probability mass considered. frequency_penalty Number -2.0 2.0. Positive values penalize new tokens based existing frequency text far, decreasing model's likelihood repeat line verbatim. presence_penalty Number -2.0 2.0. Positive values penalize new tokens based whether appear text far, increasing model's likelihood talk new topics.","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(), narrate_forecast() Output formatting functions rendering HTML Rmarkdown shiny OpenAI API, ChatGPT accessible improving, translating summarizing narratives","code":""}] diff --git a/package_prep.R b/package_prep.R index 28226d8..19efa1b 100644 --- a/package_prep.R +++ b/package_prep.R @@ -28,7 +28,6 @@ pkgdown::build_site(lazy = FALSE, new_process = TRUE) # devtools checks and test --------------------------------------------------------- devtools::test() - devtools::check() # code coverage