Figures¶

Constants and utility functions related to making figures.

class oi_tools.figures.OIColors( *values, )¶

Main Opportunity Insights color scheme.

BLUE = '#0073A2'¶

DARK_GREEN = '#2B8F43'¶

LIGHT_GREEN = '#6BBD45'¶

LIME_GREEN = '#A4CE4E'¶

NAVY = '#003A4F'¶

ORANGE = '#FAA523'¶

PURPLE = '#7F4892'¶

RED = '#E54060'¶

TEAL = '#29B6A4'¶

YELLOW = '#FFD400'¶

classmethod dict( lowercase: bool = False, ) → Mapping[str, str]¶

Return all OI colors as a mapping of name to hex code.

Parameters:: lowercase (bool) – If True, return lowercase color names. Default is False.
Returns:: Mapping of color name to hex code.
Return type:: Mapping[str, str]

Examples

>>> OIColors.dict()["TEAL"]
'#29B6A4'
>>> OIColors.dict(lowercase=True)["teal"]
'#29B6A4'

classmethod list() → Sequence[str]¶

Return all OI colors as an ordered list.

Returns:: Hex color codes in order.
Return type:: Sequence[str]

Examples

>>> OIColors.list()[:2]
['#29B6A4', '#FAA523']

classmethod primary() → str¶

Return the primary OI color.

Returns:: Hex color code for the primary color (teal).
Return type:: str

Examples

>>> OIColors.primary()
'#29B6A4'

classmethod secondary() → str¶

Return the secondary OI color.

Returns:: Hex color code for the secondary color (orange).
Return type:: str

Examples

>>> OIColors.secondary()
'#FAA523'

oi_tools.figures.save_figure(

figure: ggplot,

path: Path,

*,

filetype: str | Collection[str] = ['.pdf', '.svg', '.png'],

**kwargs,

) → None¶

Save a single figure to one or more file formats.

Parameters:

figure (ggplot) – The figure to save.
path (Path) – Destination path without extension.
filetype (str | Collection[str]) – File extension(s) to save. Defaults to DEFAULT_FILETYPES.
**kwargs – Additional keyword arguments passed to figure.save.

Return type:

None

Examples

>>> fig = pn.ggplot() + pn.geom_blank()
>>> save_figure(fig, "output/my_figure")

oi_tools.figures.save_figures_to_folder(

figures: Mapping[str | Path, ggplot],

*,

folder: Path | None = None,

filetype: str | Collection[str] = ['.pdf', '.svg', '.png'],

use_subfolders: bool = False,

**kwargs,

) → None¶

Save multiple named figures to a folder.

Parameters:

figures (Mapping[str | Path, ggplot]) – A mapping of file names to figures.
folder (Path | None) – Destination folder. Defaults to the current working directory.
filetype (str | Collection[str]) – File extension(s) to save. Defaults to DEFAULT_FILETYPES.
use_subfolders (bool) – If True, save each figure to its own subfolder. Default is False.
**kwargs – Additional keyword arguments passed to save_figure.

Return type:

None

Examples

>>> fig1 = pn.ggplot() + pn.geom_blank()
>>> fig2 = pn.ggplot() + pn.geom_blank()
>>> save_figures_to_folder(
...     {"fig1": fig1, "fig2": fig2}, folder="output/"
... )

oi_tools.figures.save_figures_to_pdf(

figures: Iterable[ggplot],

path: Path | str,

*,

width: int | float = 11,

height: int | float = 8.5,

apply_theme: bool | theme = True,

**kwargs,

) → None¶

Save multiple figures to a single PDF file.

Parameters:

figures (Iterable[ggplot]) – The figures to save.
path (Path | str) – Destination file path.
width (int | float) – Page width in inches. Default is 11.
height (int | float) – Page height in inches. Default is 8.5.
apply_theme (bool | theme) – Theme to apply to all figures. Pass True to use theme_oi, False for no theme, or a custom theme object. Default is True.
**kwargs – Additional keyword arguments passed to pn.save_as_pdf_pages.

Return type:

None

Examples

>>> fig1 = pn.ggplot() + pn.geom_blank()
>>> fig2 = pn.ggplot() + pn.geom_blank()
>>> save_figures_to_pdf([fig1, fig2], "output/figures.pdf")

oi_tools.figures.scale_color_oi(

**kwargs,

) → pn.scale_color_manual¶

Create a custom OI color scale for plotnine.

Parameters:: **kwargs – Additional keyword arguments passed to pn.scale_color_manual.
Returns:: A plotnine color scale using the OI color palette.
Return type:: pn.scale_color_manual

oi_tools.figures.scale_fill_oi(

**kwargs,

) → pn.scale_fill_manual¶

Create a custom OI fill scale for plotnine.

Parameters:: **kwargs – Additional keyword arguments passed to pn.scale_fill_manual.
Returns:: A plotnine fill scale using the OI color palette.
Return type:: pn.scale_fill_manual

oi_tools.figures.set_default_filetypes( filetypes: Collection[str], ) → None¶

Set the default file types used when saving figures.

Parameters:: filetypes (Collection[str]) – File extensions to use by default (e.g. [".pdf", ".png"]).
Return type:: None

Examples

>>> set_default_filetypes([".png"])
>>> DEFAULT_FILETYPES
['.png']

oi_tools.figures.theme_oi( base_size: int = 11, base_family: str = 'Helvetica', width: int | float = 7, height: int | float = 5, ) → theme¶

Create the standard Opportunity Insights plotnine theme.

Parameters:

base_size (int) – Base font size in points. Default is 11.
base_family (str) – Base font family. Default is "Helvetica".
width (int | float) – Figure width in inches. Default is 7.
height (int | float) – Figure height in inches. Default is 5.

Returns:

A plotnine theme object.

Return type:

pn.theme

oi_tools.figures.view_colors( colors: Sequence[str] | Mapping[str, str] = {'BLUE': '#0073A2', 'DARK_GREEN': '#2B8F43', 'LIGHT_GREEN': '#6BBD45', 'LIME_GREEN': '#A4CE4E', 'NAVY': '#003A4F', 'ORANGE': '#FAA523', 'PURPLE': '#7F4892', 'RED': '#E54060', 'TEAL': '#29B6A4', 'YELLOW': '#FFD400'}, show: bool = False, ) → pn.ggplot¶

Create a plotnine figure showing the specified colors.

Parameters:

colors (Sequence[str] | Mapping[str, str]) – Colors to display. Can be a sequence of hex codes or a name-to-hex mapping. Defaults to the full OI color palette.
show (bool) – If True, display the figure immediately. Default is False.

Returns:

A plotnine figure with one tile per color.

Return type:

pn.ggplot

Examples

>>> type(view_colors(["#29B6A4", "#FAA523"])).__name__
'ggplot'