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()
[########################################] | 100% Completed | 10.1s
[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()
[########################################] | 100% Completed |  5.5s
[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()
[########################################] | 100% Completed |  5.7s
gifsicle: warning: trivial adaptive palette (only 226 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()
[########################################] | 100% Completed |  6.0s
gifsicle: warning: trivial adaptive palette (only 243 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()
[########################################] | 100% Completed |  6.0s
gifsicle: warning: trivial adaptive palette (only 246 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()
[########################################] | 100% Completed |  5.9s
[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()
[########################################] | 100% Completed |  6.1s
[8]:

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

affixes

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

[9]:
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()
[########################################] | 100% Completed |  6.0s
[9]:

replacements

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

[10]:
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()
[########################################] | 100% Completed |  5.9s
gifsicle: warning: trivial adaptive palette (only 231 colors in source)
[10]: