Metadata-Version: 2.1
Name: pandas-alive
Version: 0.1.8
Summary: Animated plotting extension for Pandas with Matplotlib
Home-page: https://github.com/JackMcKew/pandas_alive
License: MIT
Author: JackMcKew
Author-email: jackmckew2@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: matplotlib (>=3.2.1,<4.0.0)
Requires-Dist: pandas (>=1.0.3,<2.0.0)
Project-URL: Repository, https://github.com/JackMcKew/pandas_alive
Project-URL: issues, https://github.com/JackMcKew/pandas_alive/issues
Description-Content-Type: text/markdown

# Pandas_Alive

Animated plotting extension for Pandas with Matplotlib

**Pandas_Alive** is intended to provide a plotting backend for animated [matplotlib](https://matplotlib.org/) charts for [Pandas](https://pandas.pydata.org/) DataFrames, similar to the already [existing Visualization feature of Pandas](https://pandas.pydata.org/pandas-docs/stable/visualization.html).

With **Pandas_Alive**, creating stunning, animated visualisations is as easy as calling:

``` python
df.plot_animated()
```

![Example Bar Chart](examples/example-barh-chart.gif)

## Installation

Install with `pip install pandas_alive`

## Usage

As this package builds upon [`bar_chart_race`](https://github.com/dexplo/bar_chart_race), the example data set is sourced from there.

Must begin with a pandas DataFrame containing 'wide' data where:

- Every row represents a single period of time
- Each column holds the value for a particular category
- The index contains the time component (optional)

The data below is an example of properly formatted data. It shows total deaths from COVID-19 for the highest 20 countries by date.

![Example Data Table](https://raw.githubusercontent.com/dexplo/bar_chart_race/master/images/wide_data.png)
[Example Table](examples/example_dataset_table.md)

To produce the above visualisation:

- Check [Requirements](#requirements) first to ensure you have the tooling installed!
- Call `plot_animated()` on the DataFrame
    - Either specify a file name to write to with `df.plot_animated(filename='example.mp4')` or use `df.plot_animated().get_html5_video` to return a HTML5 video
- Done!

``` python
import pandas_alive

df = pandas_alive.load_dataset()

df.plot_animated(filename='example-barh-chart.gif')

```

### Currently Supported Chart Types

`pandas_alive` current supports:

- [Horizontal Bar Charts](#horizontal-bar-charts)
- [Vertical Bar Charts](#vertical-bar-charts)
- [Line Charts](#line-charts)

#### Horizontal Bar Charts

``` python
import pandas_alive

df = pandas_alive.load_dataset()

df.plot_animated(filename='example-barh-chart.gif')
```

![Example Barh Chart](examples/example-barh-chart.gif)

#### Vertical Bar Charts

``` python
import pandas_alive

df = pandas_alive.load_dataset()

df.plot_animated(filename='example-barv-chart.gif',orientation='v')
```

![Example Barv Chart](examples/example-barv-chart.gif)

#### Line Charts

With as many lines as data columns in DataFrame.

``` python
import pandas_alive

df = pandas_alive.load_dataset()

df.diff().fillna(0).plot_animated(filename='example-line-chart.gif',kind='line')
```

![Example Line Chart](examples/example-line-chart.gif)

### Multiple Charts

`pandas_alive` supports multiple animated charts in a single visualisation.

- Create a list of all charts to include in animation
- Use `animate_multiple_plots` with a `filename` and the list of charts (this will use `matplotlib.subplots`)
- Done!

``` python
import pandas_alive

df = pandas_alive.load_dataset()

animated_line_chart = df.diff().fillna(0).plot_animated(kind='line',period_length=200)

animated_bar_chart = df.plot_animated(kind='barh',period_length=200,n_visible=10)

pandas_alive.animate_multiple_plots('example-bar-and-line-chart.gif',[animated_bar_chart,animated_line_chart]
```

![Example Bar & Line Chart](examples/example-bar-and-line-chart.gif)

``` python
import pandas_alive

urban_df = pandas_alive.load_dataset("urban_pop")

animated_line_chart = (
    urban_df.sum(axis=1)
    .pct_change()
    .dropna()
    .plot_animated(kind="line", title="Total % Change in Population",show_period_annotation=False)
)

animated_bar_chart = urban_df.plot_animated(kind='barh',n_visible=10,title='Top 10 Populous Countries')

pandas_alive.animate_multiple_plots('examples/example-bar-and-line-urban-chart.gif',[animated_bar_chart,animated_line_chart],title='Urban Population 1977 - 2018')
```

![Urban Population Bar & Line Chart](examples/example-bar-and-line-urban-chart.gif)

## Inspiration

The inspiration for this project comes from:

- [bar_chart_race](https://github.com/dexplo/bar_chart_race) by [Ted Petrou](https://github.com/tdpetrou)
- [Pandas-Bokeh](https://github.com/PatrikHlobil/Pandas-Bokeh) by [Patrik Hlobil](https://github.com/PatrikHlobil)

## Requirements

If you get an error such as `TypeError: 'MovieWriterRegistry' object is not an iterator`, this signals there isn't a writer library installed on your machine.

This package utilises the [matplotlib.animation function](https://matplotlib.org/3.2.1/api/animation_api.html), thus requiring a writer library.

Ensure to have one of the supported tooling software installed prior to use!

- [ffmpeg](https://ffmpeg.org/)
- [ImageMagick](https://imagemagick.org/index.php)
- [Pillow](https://pillow.readthedocs.io/en/stable/)
- See more at <https://matplotlib.org/3.2.1/api/animation_api.html#writer-classes>

## Documentation

Documentation is provided at <https://jackmckew.github.io/pandas_alive/>

## Contributing

Pull requests are welcome! Please help to cover more and more chart types!

