Configuring

Besides being super convenient, ahlive is super customizable.

keywords

Common settings can be accessed through documented keywords.

For a list of documented keywords, see help(ah.Array).

[1]:
import ahlive as ah
ah.Array([0, 1, 2], [3, 4, 5], figsize=(3, 3)).render()
[########################################] | 100% Completed |  4.7s
gifsicle: warning: trivial adaptive palette (only 175 colors in source)
[1]:

Do not expect all the keywords exposed in ahlive to match the matplotlib keywords!

This is because some keywords are too generic in matplotlib, e.g. plt.margins(x=1) is exposed as xmargins=1

Any keywords not documented are assumed to be plot keywords.

For example in vanilla matplotlib, to change the marker type:

[2]:
import matplotlib.pyplot as plt
_ = plt.scatter([0], [3], marker='o')
_ = plt.scatter([1], [4], marker='^')
_ = plt.scatter([2], [5], marker='v')
../_images/customizations_configuring_5_0.png

Here, although marker is not documented in ahlive’s docstring, it can still be used.

[3]:
import ahlive as ah
ah.Array([0, 1, 2], [3, 4, 5], marker=['o', '^', 'v']).render()
[########################################] | 100% Completed |  5.5s
gifsicle: warning: trivial adaptive palette (only 216 colors in source)
[3]:

These plot keywords can be a scalar too.

[4]:
import ahlive as ah
ah.Array([0, 1, 2], [3, 4, 5], marker='^').render()
[########################################] | 100% Completed |  5.5s
gifsicle: warning: trivial adaptive palette (only 210 colors in source)
[4]:

config

However, because matplotlib is huge, not all keywords can be exposed. Instead, ahlive has a generic config method.

To set figsize without the built-in keyword, first pass the name of the method followed by the keyword arguments.

For example, to set figsize in vanilla matplotlib:

[5]:
import matplotlib.pyplot as plt
_ = plt.figure(figsize=(3, 3))
<Figure size 216x216 with 0 Axes>

The method is figure so that will be the first positional argument passed to config, and then the keyword argument is figsize=(3, 3).

[6]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5])
arr.config('figure', figsize=(3, 3)).render()
[########################################] | 100% Completed |  4.7s
gifsicle: warning: trivial adaptive palette (only 175 colors in source)
[6]:

Or another way of doing this is to pass a nested dictionary; this way, multiple methods can be configured simultaneously.

[7]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5])
arr.config(**{
    'figure': {'figsize': (3, 3)},
    'axes': {'xlim': [0, 4], 'ylim': [0, 10]}
}).render()
[########################################] | 100% Completed |  4.8s
gifsicle: warning: trivial adaptive palette (only 219 colors in source)
[7]:

However not all methods are named exactly as their matplotlib counterpart!

For example to set color in vanilla matplotlib:

[8]:
import matplotlib.pyplot as plt
plt.scatter([0, 1, 2], [3, 4, 5], color='red')
[8]:
<matplotlib.collections.PathCollection at 0x7fe120f4ffa0>
../_images/customizations_configuring_17_1.png

The method is not scatter in ahlive, instead it’s plot! This is so that ahlive can handle plot, scatter, bar, etc. without too complex internal code.

[9]:
import ahlive as ah
arr = ah.Array([0, 1, 2], [3, 4, 5])
arr.config('plot', color='red').render()
[########################################] | 100% Completed |  5.6s
gifsicle: warning: trivial adaptive palette (only 198 colors in source)
[9]:

Furthermore, methods are often prefixed: ref_ for references, grid_ for grids, remark_ for remarks, etc.

[10]:
import ahlive as ah
arr = ah.Reference([0, 1, 2])
arr.config('ref_plot', color='red').render()
[########################################] | 100% Completed |  5.3s
[10]:

To get a full list of configurable methods:

[11]:
import ahlive as ah
for key, val in ah.CONFIGURABLES.items():
    print(key.upper())
    print(val)
CANVAS
['figure', 'suptitle', 'compute', 'animate', 'durations', 'savefig', 'watermark', 'spacing', 'interpolate', 'output']
SUBPLOT
['axes', 'plot', 'preset', 'legend', 'grid', 'xticks', 'yticks', 'limits', 'margins', 'hooks']
LABEL
['state', 'inline', 'xlabel', 'ylabel', 'title', 'subtitle', 'caption', 'note', 'preset_inline']
GEO
['crs', 'projection', 'borders', 'coastline', 'land', 'lakes', 'ocean', 'rivers', 'states', 'tiles']
COLOR
['colorbar', 'clabel', 'cticks']
REMARK
['remark_plot', 'remark_inline']
GRID
['grid_plot', 'grid_inline']
REF
['ref_plot', 'ref_inline']

hooks

Still, there’s lots to be desired that ahlive is incapable of doing. Therefore, if there’s a need, things can be done the vanilla matplotlib way first and wrapped into a function listed in hooks.

[12]:
import ahlive as ah
import matplotlib.pyplot as plt
import numpy as np

def add_twinx(fig, ax):
    ax2 = ax.twinx()
    ax2.set_ylabel('The twin axes')
    ax2.set_ylim(0, 24)

ah.Array([0, 1], [0, 12], hooks=[add_twinx]).render()
[########################################] | 100% Completed |  5.5s
gifsicle: warning: trivial adaptive palette (only 254 colors in source)
[12]:

hooks accept multiple custom functions.

style

Setting style='minimal' reduces the number of tick labels and grid lines.

[13]:
import ahlive as ah
ah.Array([0, 1, 2], [3, 4, 5], style='minimal').render()
[########################################] | 100% Completed |  2.3s
gifsicle: warning: trivial adaptive palette (only 200 colors in source)
[13]:

Setting style='bare' removes all tick labels, grid lines, borders, and spacing around the subplot.

[14]:
import ahlive as ah
ah.Array([0, 1, 2], [3, 4, 5], style='bare').render()
[########################################] | 100% Completed |  2.0s
gifsicle: warning: trivial adaptive palette (only 70 colors in source)
[14]:

defaults

To get a full list of configurable defaults:

[15]:
import ahlive as ah
for key, val in ah.DEFAULTS.items():
    print(key.upper())
    print(val)
    print("")
DURATIONS_KWDS
{'aggregate': 'max', 'transition_frames': 0.016666666666666666, 'final_frame': 0.55}

LABEL_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}}

PRESET_KWDS
{'trail': {'chart': 'scatter', 'expire': 100, 'stride': 1, 'zorder': 0}, 'morph_trail': {'chart': 'line', 'expire': 1, 'stride': 1, 'zorder': 0}, 'race': {'bar_label': True, 'limit': 5, 'ascending': False}, 'delta': {'bar_label': True, 'capsize': 6}, 'scan': {'color': 'black', 'stride': 1}}

PLOT_KWDS
{'pie': {'normalize': False}}

REF_PLOT_KWDS
{'rectangle': {'facecolor': 'darkgray', 'alpha': 0.45}, 'scatter': {'color': 'darkgray', 'marker': 'x'}, 'axvline': {'color': 'darkgray', 'linestyle': '--'}, 'axhline': {'color': 'darkgray', 'linestyle': '--'}, 'axvspan': {'color': 'darkgray', 'alpha': 0.45}, 'axhspan': {'color': 'darkgray', 'alpha': 0.45}}

XLABEL_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}}

YLABEL_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}}

CLABEL_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}}

TITLE_KWDS
{'fontsize': 19, 'replacements': {'_': ' '}, 'loc': 'left'}

SUBTITLE_KWDS
{'fontsize': 13, 'replacements': {'_': ' '}, 'loc': 'right'}

NOTE_KWDS
{'x': 0.05, 'y': 0.05, 'ha': 'left', 'va': 'top', 'fontsize': 9}

CAPTION_KWDS
{'x': 0, 'y': -0.28, 'alpha': 0.7, 'ha': 'left', 'va': 'bottom', 'fontsize': 11}

SUPTITLE_KWDS
{'fontsize': 19, 'replacements': {'_': ' '}}

STATE_KWDS
{'fontsize': 48, 'replacements': {'_': ' '}, 'alpha': 0.5, 'xy': (0.988, 0.01), 'ha': 'right', 'va': 'bottom', 'xycoords': 'axes fraction'}

INLINE_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}, 'textcoords': 'offset points'}

REF_INLINE_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}, 'textcoords': 'offset points'}

GRID_INLINE_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}, 'textcoords': 'offset points'}

PRESET_INLINE_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}, 'textcoords': 'offset points'}

REMARK_INLINE_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}, 'textcoords': 'offset points', 'xytext': (1, -1), 'ha': 'left', 'va': 'top'}

LEGEND_KWDS
{'fontsize': 16, 'replacements': {'_': ' '}, 'framealpha': 0, 'loc': 'upper left'}

COLORBAR_KWDS
{'orientation': 'vertical'}

TICKS_KWDS
{'replacements': {'_': ' '}, 'length': 0, 'which': 'both', 'labelsize': 13}

XTICKS_KWDS
{'replacements': {'_': ' '}, 'length': 0, 'which': 'both', 'labelsize': 13, 'axis': 'x'}

YTICKS_KWDS
{'replacements': {'_': ' '}, 'length': 0, 'which': 'both', 'labelsize': 13, 'axis': 'y'}

CTICKS_KWDS
{'replacements': {'_': ' '}, 'length': 0, 'which': 'both', 'labelsize': 13, 'num_colors': 11}

GRID_KWDS
{'show': True}

TILES_KWDS
{'style': 'toner'}

LAND_KWDS
{'facecolor': 'whitesmoke'}

NUM_KWDS
{'default': 1, 'bounds': (1, None), 'constant': True, 'precedence': 14}

WATERMARK_KWDS
{'x': 0.995, 'y': 0.005, 'alpha': 0.28, 'ha': 'right', 'va': 'bottom', 'fontsize': 9, 's': 'animated using ahlive'}

SAVEFIG_KWDS
{'format': 'png', 'backend': 'agg', 'facecolor': 'white', 'transparent': False}

COMPUTE_KWDS
{'num_workers': 1, 'scheduler': 'single-threaded', 'progress': True}

ANIMATE_KWDS
{'mode': 'I', 'loop': 0, 'pygifsicle': True}