plotly-undp-theme

A Python package that adds a UNDP-branded template for theming Plotly figures in line with the UNDP Design System and UNDP data viz library.

Table of Contents

• Installation
• Usage
• Features
• Contributing
• License
• Contact

Installation

Currently, the package is distributed via GitHub only. You can install it with pip:

 pip install git+https://github.com/undp-data/[email protected]

You can also add it to your requirements.txt:

plotly-undp-theme @ git+https://github.com/undp-data/[email protected]

See VCS Support for more details.

Usage

When you import the package, it will automatically register undp template with plotly. You can then use the template to style a specific figure or set it as the default to style all figures.

import plotly.express as px
import plotly.io as pio
import plotly_undp_theme  # registers `undp` template

df = px.data.iris()

# use the template to style a single figure
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", template="undp")
fig.show()

# or set it as the default to style all figures
pio.templates.default = "undp"
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")
fig.show()

See this example notebook for a quick walkthrough.

Features

The package ships a UNDP-branded template to enhance the look and feel of plotly figures. It is extremely lightweight. Its main features include:

• Colours and colour schemes in line with the UNDP Design System and UNDP data viz library.
• Proxima Nova font settings.
• A single dependency (plotly).

Note

Plotly uses system fonts. You must have Proxima Nova font installed on your machine for the package to be able to use it. If the font is missing, plotly will fall back to using some other sans-serif font without a warning.

Contributing

All contributions must follow Conventional Commits. The codebase is formatted with black and isort. Use the provided Makefile for these routine operations.

1. Clone or fork the repository
2. Create a new branch (git checkout -b feature-branch)
3. Make your changes
4. Ensure your code is properly formatted (make format)
5. Commit your changes (git commit -m 'Add some feature')
6. Push to the branch (git push origin feature-branch)
7. Open a pull request

License

This project is licensed under the BSD 3-Clause License. However, entities or individuals not affiliated with UNDP are strictly prohibited from using this package or any of its components to create, share, publish, or distribute works that resemble, claim affiliation with, or imply endorsement by UNDP.

UNDP’s name, emblem and its abbreviation are the exclusive property of UNDP and are protected under international law. Their unauthorized use is prohibited, and they may not be reproduced or used in any manner without UNDP’s prior written permission.

Contact

This project is part of Data Futures Exchange (DFx) at UNDP. If you are facing any issues or would like to make some suggestions, feel free to open an issue. For enquiries about DFx, visit Contact Us.