plot¶

pandas_alive.plotting.plot(input_df: pandas.core.frame.DataFrame, filename: str = None, kind: str = 'race', interpolate_period: bool = True, steps_per_period: int = 5, period_length: int = 500, period_fmt: str = '%d/%m/%Y', figsize: Tuple[float, float] = 6.5, 3.5, title: str = None, fig: matplotlib.figure.Figure = None, cmap: Union[str, matplotlib.colors.Colormap, List[str]] = 'dark24', tick_label_size: Union[int, float, str] = 7, period_label: Union[bool, Dict[str, Union[int, float, str]]] = True, period_summary_func: Callable = None, fixed_max: bool = False, dpi: int = 144, writer: str = None, enable_progress_bar: bool = False, orientation: str = 'h', sort: str = 'desc', label_bars: bool = True, bar_label_size: Union[int, float] = 7, n_visible: int = None, fixed_order: Union[bool, list] = False, perpendicular_bar_func: Union[Callable, str] = None, line_width: int = 2, label_events: Dict[str, datetime.datetime] = None, fill_under_line_color: str = None, add_legend: bool = True, size: int = 2, x_data_label: str = None, y_data_label: str = None, size_data_label: Union[int, float, str] = 2, color_data_label: str = 'blue', vmin: Union[int, float] = None, vmax: Union[int, float] = None, **kwargs) → Union[pandas_alive.charts.BarChart, pandas_alive.charts.BarChartRace, pandas_alive.charts.BubbleChart, pandas_alive.charts.LineChart, pandas_alive.charts.PieChart, pandas_alive.charts.ScatterChart][source]¶

Create animated charts with matplotlib and pandas

Data must be in ‘wide’ format where each row represents a single time period and each column represents a distinct category. Optionally, the index can label the time period. Bar height and location change linearly from one time period to the next. This is resource intensive - Start with just a few rows of data to test.

Parameters

filename (str, optional) – If a string, save animation to that filename location. Defaults to None.
kind (str, optional) – Type of chart to use. Defaults to “race”. Supported kinds are: “race”, “line”, “scatter”,”pie”,”bar”,”bubble”
interpolate_period (bool, optional) –
Whether to interpolate the period. Only valid for datetime or numeric indexes. Defaults to True. When set to True, for example, the two consecutive periods 2020-03-29 and 2020-03-30 would yield a new index of
```
>>> df.plot_animated(interpolate_period=True,steps_per_period=4)
    2020-03-29 00:00:00
    2020-03-29 06:00:00
    2020-03-29 12:00:00
    2020-03-29 18:00:00
    2020-03-30 00:00:00
```
steps_per_period (int, optional) – The number of steps to go from one time period to the next. Animation will interpolate between time periods. Defaults to 10.
period_length (int, optional) – Number of milliseconds to animate each period (row). Defaults to 500.
period_fmt (str, optional) –
Either a string with date directives or a new-style (Python 3.6+) formatted string. For a string with a date directive, find the complete list here https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes

String with date directives .. code-block:
```
df.plot_animated(period_fmt='%B %d, %Y')
```
Will change 2020/03/29 to March 29, 2020

For new-style formatted string. Use curly braces and the variable x, which will be passed the current period’s index value. .. code-block:
```
'Period {x:10.2f}'
```
Date directives will only be used for datetime indexes. Defaults to “%d/%m/%Y”.
figsize (typing.Tuple[float, float], optional) – matplotlib figure size in inches. Will be overridden if figure supplied to fig. Defaults to (6.5, 3.5).
title (str, optional) – Title of plot. Defaults to None.
fig (plt.Figure, optional) – For greater control over the aesthetics, supply your own figure. Defaults to None.
cmap (typing.Union[str, Colormap, typing.List[str]], optional) – Provide string of colormap name, colormap instance, single color instance or list of colors as supported by https://matplotlib.org/2.0.2/api/colors_api.html. Defaults to “dark24”.
tick_label_size (typing.Union[int, float, str], optional) – Size in points of tick labels. Defaults to 7.
period_label (typing.Union[bool, typing.Dict[str, typing.Union[int, float, str]]], optional) –
If True or dict, use the index as a large text label on the axes whose value changes. Use a dictionary to supply the exact position of the period along with any valid parameters of the matplotlib text method. At a minimum, you must supply both ‘x’ and ‘y’ in axes coordinates .. code-block:
```
custom_period_location = {
    'x': .99,
    'y': .8,
    'ha': 'right',
    'va': 'center'
    }

df.plot_animated(period_label=custom_period_location)
```
If False - don’t place label on axes. Defaults to True.
period_summary_func (typing.Callable, optional) –
Custom text added to the axes each period. Create a user-defined function that accepts two pandas Series of the current time period’s values and ranks. It must return a dictionary containing at a minimum the keys “x”, “y”, and “s” which will be passed to the matplotlib text method. Defaults to None. .. code-block:
```
def func(values):
    total = values.sum()
    s = f'Total Generation: {total}'
    return {'x': .85, 'y': .2, 's': s, 'ha': 'right', 'size': 11}

df.plot_animated(period_summary_func=func)
```
dpi (float, optional) – It is possible for some bars to be out of order momentarily during a transition since both height and location change linearly. Defaults to 144.
writer (str, optional) – Specify writer library, must be within list of available writers (matplotlib.animation.writers.list()) and pillow is not supported. Defaults to None.
enable_progress_bar (bool,optional) – Enable tqdm bar to show progress on generating animation, see more details at https://github.com/tqdm/tqdm. Defaults to False.
sort (str, optional) – ‘asc’ or ‘desc’. Choose how to sort the bars. Use ‘desc’ to put largest bars on top and ‘asc’ to place largest bars on bottom. Defaults to “desc”.
label_bars (bool, optional) – Whether to label the bars with their value on their right. Defaults to True.
bar_label_size (typing.Union[int, float], optional) – Size in points or relative size str of numeric labels just outside of the bars. Defaults to 7.
n_visible (int, optional) – Choose the maximum number of bars to display on the graph. By default, use all bars. New bars entering the race will appear from the edge of the axes. Defaults to None.
fixed_order (typing.Union[bool, list], optional) – When False, bar order changes every time period to correspond with sort. When True, bars remained fixed according to their final value corresponding with sort. Otherwise, provide a list of the exact order of the categories for the entire duration. Defaults to False.
fixed_max (bool, optional) – Whether to fix the maximum value of the axis containing the values. When False, the axis for the values will have its maximum (xlim/ylim) just after the largest bar of the current time period. The axis maximum will change along with the data. When True, the maximum axis value will remain constant for the duration of the animation. For example, in a horizontal bar chart, if the largest bar has a value of 100 for the first time period and 10,000 for the last time period. The xlim maximum will be 10,000 for each frame. Defaults to False.
perpendicular_bar_func (typing.Union[typing.Callable, str], optional) –
Creates a single bar perpendicular to the main bars that spans the length of the axis.

Use either a string that the DataFrame agg method understands or a user-defined function.

DataFrame strings - ‘mean’, ‘median’, ‘max’, ‘min’, etc..

The function is passed two pandas Series of the current time period’s data and ranks. It must return a single value. .. code-block:
```
def func(values):
    return values.quantile(.75).
```
Defaults to None.
line_width (int, optional) – Line width provided on line charts. Defaults to 2.

label_events (typing.Dict[str,datetime.datetime],optional) –

Provide list of events to label with a vertical bar on line charts. Defaults to None.

To be used with strptime or any datetime object

Sample use: .. code-block:

df.plot_animated(
        kind='line',
        filename='test.mp4',
        label_events={
            'Ruby Princess Disembark':datetime.strptime("19/03/2020", "%d/%m/%Y"),
            'Lockdown':datetime.strptime("31/03/2020", "%d/%m/%Y")
        },
    )

fill_under_line_color (str,optional) –
Color to show under line to create an area chart equivalent

String passed must be in list of named colors by matplotlib https://matplotlib.org/3.1.1/gallery/color/named_colors.html#sphx-glr-gallery-color-named-colors-py
size (int, optional) – Size of scatter points on scatter charts. Defaults to 2.
x_data_label (str,optional) –
For use with Scatter plots, label passed must be in level 0 column in multiindex

Label passed all values will be used for the x-axis
y_data_label (str,optional) –
For use with Scatter plots, label passed must be in level 0 column in multiindex

Label passed all values will be used for the y-axis
size_data_label (typing.Union[int,str],optional) –
For use with Scatter plots, label passed must be in level 0 column in multiindex. Defaults to 2.

Label passed all values will be used for the size of each point on the plot. Otherwise a int can be passed for all points to be that size.
color_data_label (str,optional) –
For use with Scatter plots, label passed must be in level 0 column in multiindex. Defaults to “blue”.

Label passed all values will be used to create a colourmap for points. Otherwise a string can be passed of a named color by matplotlib for all points to be that color.

Raises

ValueError – If chart type is not supported, raise error

Returns

Return instance of chart type. Can be used with pandas_alive.animate_multiple_plots or .save().

Return type

typing.Union[BarChart, BarChartRace, BubbleChart, LineChart, PieChart, ScatterChart]