Labeling#

Viewers can better understand the animation if labeled; ahlive makes this easy!

annotating keywords#

ahlive has these keywords for annotating data:

ahlive keyword

default location

scope

dynamic

description

suptitle

upper center

figure

False

figure heading

watermark

outer bottom right

figure

False

figure’s acknowledgements

title

upper left

subplot

False

subplots’ headings

subtitle

upper right

subplot

False

smaller subplots’ headings

xlabel

outer left

subplot

False

x-axes’ names

ylabel

outer bottom

subplot

False

y-axes’ names

clabel

outer right

subplot

False

colorbars’ names

note

lower left

subplot

False

subplots’ comment

caption

outer bottom left

subplot

False

subplots’ descriptions

state_labels

lower right

subplot

True

states’ values

inline_labels

upper right of last value

item

True

items’ values

label

top left

item

False

legend items’ names

group

top left

items

False

group of items’ names

grid

frame

subplot

False

grid

static labels#

To use any static label, simply pass a str value to the keyword.

[1]:
import ahlive as ah
arr1 = ah.Array(
    [0, 1, 2], [3, 4, 1], cs=[6, 7, 8],
    suptitle='the "suptitle"', watermark='the "watermark"',
    title='the "title"', subtitle='the "subtitle"',
    xlabel='the "xlabel"', ylabel='the "ylabel"', clabel='the "clabel"',
    note='the "note"', caption='the "caption"', label='the "label" for arr1',
    grid=True
)
arr2 = ah.Array(
    [0, 1, 2], [1.5, 3, 9], label='the "label" for arr2', marker='^'
)
(arr1 * arr2).render()
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
/home/docs/checkouts/readthedocs.org/user_builds/ahlive/conda/main/lib/python3.11/site-packages/ahlive-1.0.3.post6+dirty-py3.11.egg/ahlive/animation.py:443: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'vmin', 'vmax' will be ignored
gifsicle: warning: trivial adaptive palette (only 139 colors in source)
[1]:

group labels#

Group labels batches multiple legend labels into a single legend label.

This can also slightly optimize runtime because the same groups are plotted simultaneously.

[2]:
import ahlive as ah
import pandas as pd
df = pd.DataFrame({
    'x': [0, 1, 2, 3, 4, 5],
    'y': [3, 4, 5, 6, 7, 8],
    'label': ['a', 'a', '1', '1', '2', '3'],
    'group': ['alpha', 'alpha', 'number', 'number', 'number', 'number']})
arr = ah.DataFrame(df, 'x', 'y', label='label', group='group')
arr.render()
gifsicle: warning: trivial adaptive palette (only 54 colors in source)
[2]:

state labels#

To use state_labels, simply pass an Iterable to the keyword; the length should match the values passed to xs and ys.

[3]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5], state_labels=['a', 'b', 'c'])
arr.render()
gifsicle: warning: trivial adaptive palette (only 54 colors in source)
[3]:

If using ah.DataFrame and ah.Dataset, instead of passing an Iterable to the keyword, pass a str referencing the column / label of the pd.DataFrame or xr.Dataset.

[4]:
import ahlive as ah
import pandas as pd
df = pd.DataFrame({'x': [0, 1, 2], 'y': [3, 4, 5], 'state': [10, 11, 12]})
arr = ah.DataFrame(df, 'x', 'y', state_labels='state')
arr.render()
gifsicle: warning: trivial adaptive palette (only 53 colors in source)
[4]:

state_labels can also reside in the title by setting xy in config.

[5]:
import ahlive as ah
import pandas as pd
df = pd.DataFrame({'x': [0, 1, 2], 'y': [3, 4, 5], 'state': [10, 11, 12]})
arr = ah.DataFrame(df, 'x', 'y', title="Title", state_labels='state')
arr.config("state", xy="title").render()
gifsicle: warning: trivial adaptive palette (only 53 colors in source)
[5]:

Other valid xy locations are listed below.

[6]:
from ahlive.configuration import OPTIONS
print(OPTIONS["state_xy"])
['title', 'subtitle', 'suptitle', 'title_start', 'subtitle_start', 'suptitle_start']

inline labels#

To use inline_labels, simply pass an Iterable to the keyword; the length should match the values passed to xs and ys.

[7]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5], inline_labels=['3', 'four', '5.0'])
arr.render()
[7]:

To use inline_labels for ah.DataFrame and ah.Dataset, pass the column / label.

[8]:
import ahlive as ah
import pandas as pd
df = pd.DataFrame({'x': [0, 1, 2], 'y': [3, 4, 5]})
arr = ah.DataFrame(df, 'x', 'y', inline_labels='y')
arr.render()
[8]:

Both state_labels and inline_labels support various input types, e.g. str, int, float, or datetime.

adjust text#

To prevent overlap, adjust_text can be set to True.

[9]:
import ahlive as ah
arr1 = ah.Array([0, 1, 2], [3, 4, 5], inline_labels="red", adjust_text=True)
arr2 = ah.Array([0, 1, 2], [2, 4, 4], inline_labels="blue")
arr1.overlay(arr2).config("adjust_text", precision=1).render()
[9]:

Setting adjust_text=True may slow down the rendering significantly because for each frame, it iteratively moves them to reduce overlaps. Reducing precision or lims may help performance; see adjustText’s docs for more options.

affixes#

All labels can be suffixed, prefixed, and/or added units through config.

[10]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5], inline_labels=['3', 'four', '5.0'])
arr.config("inline", prefix="P ", suffix=" S", units="u").render()
[10]:

width#

If labels are too long, they can be wrapped automatically so every line is up to the max number of characters specified as width.

[11]:
import ahlive as ah
caption = (
    "Super long caption that will wrap onto the next line automatically! "
    "Isn't ahlive awesome?"
)
arr = ah.Array([0, 1, 2], [3, 4, 5], caption=caption)
arr.config("caption", width=50).render()
gifsicle: warning: trivial adaptive palette (only 52 colors in source)
[11]:

replacements#

replacements can also be made to any labels by specifying a dict in config.

[12]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5], state_labels=['3', 'four', '5.0'])
arr.config("state", replacements={"[": "(", "]": ")"}, units="u").render()
gifsicle: warning: trivial adaptive palette (only 56 colors in source)
[12]: