README.rmd

---
output: github_document
editor_options: 
  markdown: 
    wrap: 72
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

sales <- narrator::sales
```

<!-- README.md is generated from README.Rmd. Please edit that file -->

# Narrator <img src="man/figures/hex.png" align="right" width="160"/>

<!-- badges: start -->

![CRAN status](https://www.r-pkg.org/badges/version/narrator)
[![Codecov test
coverage](https://codecov.io/gh/denisabd/narrator/branch/main/graph/badge.svg)](https://app.codecov.io/gh/denisabd/narrator?branch=main)
[![R-CMD-check](https://github.com/denisabd/narrator/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/denisabd/narrator/actions/workflows/R-CMD-check.yaml)
[![Lifecycle:
stable](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)

<!-- badges: end -->

Template-based NLG framework for creating text narratives out of data
and enhance them using ChatGPT. Demo [shiny
application](https://deny.shinyapps.io/narrator_app/) showing core
package capabilities is deployed on shinyapps.io.

Package is available in both R and Python, with all core features and even syntax being the same or similar. Corresponding classes and data types are used in both languages:

- data.frame vs pandas data frame
- list vs dictionary
- character vector vs list

```{r, include = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  message = FALSE,
  warning = FALSE
)

library(reticulate)
```

# Installation

For R you can install the development version of narrator from
[GitHub](https://github.com/) with:

```{r, eval=FALSE}
# install.packages("devtools")
devtools::install_github("denisabd/narrator")
```

For Python install `pynarrator` from pip:

```{bash, eval=FALSE}
pip3 install pynarrator
```

# R

## Basic Use Cases

Simple tables with one or more categorical columns (dimensions) and one
measure can be transformed to text using `narrate_descriptive()`
function.

```{r message=FALSE, warning=FALSE}
library(narrator)
library(dplyr)
```

```{r}
narrative_one <- sales %>%
  narrate_descriptive(
    measure = "Sales",
    dimensions = c("Region", "Product")
  )

narrative_one
```

You can analyze changes over time using `narrate_trend()` function:

```{r}
narrative_two <- sales %>%
  narrate_trend(
    measure = "Sales",
    date = "Date",
    dimensions = c("Region", "Product")
  )

narrative_two
```

## ChatGPT

`narrator` can use ChatGPT API to improve your narratives. To do so you
can either set `use_chatgpt = TRUE` in any function that creates
narrative or use `enhance_narrative()` to improve existing narrative
output. You can supply `list` or `character`, function will collapse all
text into a sentence and send a request to Chat GPT. Set your token in
`.Renviron` file as `OPENAI_API_KEY` or supply it to a function as
`openai_api_key` argument.

This functionality requires you to setup the ChatGPT API key and make it
accessible from R.

-   Obtain your ChatGPT API key. You can create an API key by accessing
    [OpenAI API page](https://platform.openai.com/account/api-keys)

-   [Best Practices for API Key
    Safety](https://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety)

-   Change your `.Renviron` file with `usethis::edit_r_environ()` by
    adding \``` OPENAI_API_KEY=xx-xxxxxx` ``

```{r results='asis'}
narrative_enhanced <- enhance_narrative(narrative_one)
cat(narrative_enhanced)
```


### Translation

Translate you text using `translate_narrative()` function, specify `language` argument in English:

```{r results='asis'}
translation <- translate_narrative(narrative_enhanced, language = "Czech")
cat(translation)
```

### Summarization

If your output is too verbose you can summarize it with `summarize_narrative()` function:

```{r results='asis'}
summarization <- summarize_narrative(narrative_enhanced)
cat(summarization)
```


# Python

Here are some basic Python examples, for more details visit [pynarrator github](https://github.com/denisabd/pynarrator) and [pynarrator website](https://denisabd.github.io/pynarrator/)

```{python eval=FALSE}
import os
from pynarrator import narrate_descriptive, read_data, enhance_narrative, translate_narrative, summarize_narrative
```

```{python eval=FALSE}
sales = read_data()
```

By default `narrate_descriptive()` returns a dictionary of narratives with names.
```{python eval=FALSE}
narrate_descriptive(
  df = sales, 
  measure = 'Sales', 
  dimensions = ['Region', 'Product'], 
  return_data = False, 
  coverage = 0.5
  )
```

When `simplify = True` the output is a list:
```{python eval=FALSE}
narrate_descriptive(
  df = sales, 
  measure = 'Sales', 
  dimensions = 'Region', 
  return_data = False, 
  simplify = True,
  coverage = 0.5
  )
```

```{python eval=FALSE}
narrative_two = narrate_descriptive(
  df = sales, 
  measure = 'Sales', 
  dimensions = 'Region', 
  return_data = False, 
  simplify = True,
  coverage = 0.5
  )
  
pprint.pprint(narrative_two)
```

When `return_data=True` we get a list of variables calculated inside of the function:
```{python eval=FALSE}
narrate_descriptive(
  df = sales, 
  measure = 'Sales', 
  dimensions = ['Region', 'Product'], 
  return_data = True, 
  simplify = True,
  coverage = 0.5
  )
```

As all other functions, Chat GPT related calls are to similar to those in R
```{python eval=FALSE}
narrative_enhanced = enhance_narrative(narrative_one)
translation = translate_narrative(narrative_enhanced, language = "Czech")
summarization = summarize_narrative(narrative_enhanced)
```