Using the Flourish API in Python or R

Note: the Flourish API is an enterprise-level bolt-on and not available to all customers. View the full documentation for Flourish charts inside R and Python here.

flourishcharts are Python & R packages for creating data visualizations with Flourish inside Jupyter notebooks or R Markdown documents.

Installation of Flourish charts

To start using Flourish charts inside of Python or R, download the package from PyPi or CRAN (or alternatively, from this GitHub repository). The next step is to generate a Flourish API key using the steps here.

Python package installation

If installing to a virtual environment, you can install flourishcharts using pipenv:

pipenv install flourishcharts

If using a local machine Python installation, install Flourish Charts to your global Python installation with pip:

python3 -m pip install --upgrade flourishcharts

R package installation

To install from CRAN, run:

install.packages("flourishcharts")

To install the latest R package version from GitHub (as the CRAN package will only be updated on a quarterly basis instead of every two weeks):

remotes::install_github("canva-public/flourish-charts", subdir = "R_package")

Flourish API key

After you have generated your API key, follow these steps dependent on which program you intend to use.

Flourish API key inside Python

1. Python users can store their Flourish API key in one of three potential places:

   • Inside the Flourish() function, which has a parameter called api_key. Pass a string to this argument.
   • If you install a global copy of the package: in a ~/.zshrc or ~/.bashrc file where you can store sensitive bits of information or, alternatively, information you want accessible. This is safer as the API key cannot be accessed if you decide to share the Python file containing flourishcharts code.
   • If you install to a virtual environment: in a .envrc file where you can store sensitive bits of information or, alternatively, information you want accessible every time you run Python code within the environment. This is safer as the information cannot be accessed if you decide to share the Python file containing flourishcharts code.

If you choose of the latter two options, store your key in the file as follows:

export FLOURISH_API_KEY="..."

2. Restart your terminal after saving the variable for it to take effect or (if using a virtual environment) run direnv allow in your directory.

Flourish API key inside R

1. R users can store their Flourish API key in one of two places:
   • Inside the flourish() function which has a parameter called api_key. Pass a string to this argument.
   • In you ~/.Renviron file where you can store sensitive bits of information or, alternatively, information you want available every time you run R code. This is safer as the API key cannot be accessed if you decide to share the R file containing flourishcharts code.

If you choose the latter, please store your key in the file as follows:

FLOURISH_API_KEY="..."

The flourish() function will recognize this variable, grabbing the API key without the end-user needing to specify every single time.

1. If you do not have an ~/.Renviron file, create one from your terminal by running touch ~/.Renviron && open ~/.Renviron

2. Restart R after saving the variable for it to take effect.

Creating Flourish graphs in R and Python

Building Flourish charts inside R and Python primarily depends on two main functions.

• Python: Flourish() and a bind_..._data() function.
• R: flourish() and a bind_..._data() function.

The ... depends on the chart type. A list of chart types can be found flourish_api_documentation['chart_type'] in R or reference['chart_type'] in Python.

In Python you can wrap the function in help() to see the docstrings and also shift tab to view the docstrings dynamically while coding.

In R, you can find a list of Flourish functions by running flourishcharts::, typing ?flourishcharts in your console, or heading over to the references page in the main documentation.

To see examples and get started with creating your own Flourish charts, please visit the full documentation here.