#!/usr/bin/env python
# coding: utf-8

# 
# # Charts Tutorial
# <br>
# The python [**Charts**](https://github.com/arnoutaertgeerts/python-highcharts) library enables you to use the amazing [Highcharts](http://www.highcharts.com/) javascript library in your Python code to create beautiful and interactive charts. The library is structured in such a way that anything you can do with Highcharts, you can do with **Charts**... Even right in your IPython Notebook!
# 
# **Contents**
# - [Installation](#Installation)
# - [Data configuration](#Data-configuration)
# - [Variable searcher and settings editor](#Variable-searcher-and-settings-editor)
# - [Chart options](#Chart-options)
# - [Chart types](#Chart-types)
# - [Async plots](http://nbviewer.ipython.org/github/arnoutaertgeerts/python-highcharts/blob/master/Async%20plotting.ipynb)

# ## Installation

# All you need to do to get started is download the library using pip:
# 
#     pip install charts
#     
# Import the libary in Python to get started:

# In[2]:


import charts


# Chart has two main functions which essentialy do the same thing, plot a chart: 
# 
# - `charts.plot(series, options)`
# - `charts.plotasync(series, options)`
# 
# In this quickstart we will discuss the `plot()` method and leave `plotasync()` for a different notebook. 

# ## Data configuration
# 
# In *charts*, each data serie you want to plot has to have a name. You can specify this name in three ways:
# 
# 1. If you want to plot a single series, you can use the `name` argument: 
# ```
# charts.plot(data, name='My list')
# ```
# 2. If you want to plot multiple series, you have to use the **series** format. This format is a dictionary containing two properties: data and name: 
# ```
# charts.plot(dict(data=data, name='My series'))
# ``` 
# To plot multiple series in one chart, just create a list of the series dictionaries: 
# ```
# charts.plot([series])
# ```
# 3. You can also use a pandas dataframe: 
# ```
# charts.plot(dataframe)
# ```
# 
# The data itself has to be one of these two options:
# 
# 1. A single list (or numpy array): 
# ```
# data = [1,2,5,9,6,3,4,8]
# ```
# 
# 2. A list containing x,y pairs: 
# ```
# data = [[1,8],[2,7],[3,4],[4,3],[5,9],[6,0],[7,10],[8,5]]
# ```

# Lets try this for the 3 different methods. Note that we add the option `show='inline'` to show the charts inline in the notebook:
# 
# 1) A single series with the name argument

# In[3]:


data = [1,2,5,9,6,3,4,8]
options = dict(height=400, title=dict(text='My first chart!'))
charts.plot(data, options=options, name='List data', save='temp.svg', show='inline')


# In[4]:


data = [[1,8],[2,7],[3,4],[4,3],[5,9],[6,0],[7,10],[8,5]]
charts.plot(data, name='Second list data', show='inline', options=dict(title=dict(text='My second chart!')))


# 2) If we want both we have to use the series approach:

# In[5]:


s1 = dict(name='List data', data=[1,2,5,9,6,3,4,8], color='#2b908f')
s2 = dict(name='Second list data', data=[[1,8],[2,7],[3,4],[4,3],[5,9],[6,0],[7,10]])

options = {
    'title': {'text': 'A chart with two lines, wow!'}
}

charts.plot([s1, s2], show='inline', options=options)


# 3) You can also directly use a pandas dataframe. (If you do not have pandas installed just skip this cell)
# 
# First we create a pandas dataframe based on dates and then plot it using charts. Notice we use two new options: `stock=True` and `display=['A', 'Q', 'Z']`.
# - The `stock` option can be set to True to use [Higstock](charts.com/stock/demo) instead of Highcharts, which is a specialized version of the library for timeseries.
# - In our case we have a dataframe with 26 variables which can be become difficult to plot all in one chart. *Charts* gives you the option to add all these variables to the chart but *initially* only show a selection. We do this by setting the `display` argument and provide it with a list of names we want to view initially.
# 
# After the chart is plotted you can still change which variables are shown by clicking the button in the left corner and adding/removing variables from the chart!

# In[6]:


import pandas as pd
import numpy as np
start = pd.Timestamp("20150101")
end = pd.Timestamp("20150201")
index = pd.DatetimeIndex(freq='900S', start=start, end=end)
columns = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 
'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z']

data = np.zeros((26, len(index)))
for i, c in enumerate(columns):
    data[i] = i*np.linspace(0, 100, len(index))

df = pd.DataFrame(index=index, columns=columns, data=data.T)


# In[7]:


options = {
    'title': {'text': 'An entire pandas dataframe'}
}

charts.plot(df, options=options, show='inline', stock=True, display=['A', 'Q', 'Z'])


# ## Variable searcher and settings editor
# 
# Now, lets go over some extra features of the **Charts** library in comparison with Highcharts.
# - **The variable searcher**: As you can see we added a variable searcher above the chart which can be used to add and remove series from the chart and is indexed by the name of the series. Try typing in a letter of the alphabet and select it. This is especially usefull if you have a large amount of data you want to plot at the same time.
# - **The settings editor**: When you press the *SETTINGS* button, a JSON editor appears which contains all of the charts settings. You can change every setting of the chart right there! Try changing the title of the chart, located under `object > title > text`.
# 
# These features are the main differences between Charts and Highcharts and we try to stay out of your way for the rest.

# ## Chart options
# 
# In *Charts*, there are two types of options:
# 
# 1. **Highchart options**
# 2. **Charts options**
# 
# 1) **The Highchart options** are identical to the options you can specify with Highcharts and can be found in their [API](api.highcharts.com). You can set them by using a dictionary containing the options. 
# Let's try this to set the title of the chart and allow us to zoom in in both X and Y. When searching the API we can find how to set the [title](http://api.highcharts.com/highcharts#title) and the [zoomType](http://api.highcharts.com/highcharts#chart.zoomType):

# In[8]:


options = dict(
    title=dict(text='Zoom me!'),
    chart=dict(zoomType='xy')
)

charts.plot([s1, s2], options=options, show='inline')


# Notice the title of the chart and try zooming in. Any option that is available on the highcharts API can be used in *Charts* by setting it in the `options` dictionary.
# 
# 2) **Charts options** are options independent of the Highchart api and can be set when calling the `plot()` function as keyword arguments
# 
# - *type*: Type of the chart (*line, area, spline, pie, bar, ...*). This will set the Highchart option {chart: {type:*type*}}.
# - *height*: Height of the chart in pixels
# - *save*: A filename to save the chart. Currently you have two options: save the chart as an svg image or save the generated HTML file. Note that this HTML file can be used as a standalone webpage and is ideal to share your charts.
# - *stock*: Set to true to use HighStock instead of HighCharts
# - *show*: Determine how the chart is shown. Can be `inline`, `tab` or `window`
# - *display*: A list containing the names of the variables you want to show initially. Set to `True` to show everything and to `False` to show nothing

# **Save your settings!**
# 
# You can save your options by expanding the settings editor, choosing a name for your settings and pressing the *save* button. This will store your settings in a json file so you can use them again when you replot the chart. Note that you have to add `.json` to be able to save the file.
# 
# You can plot a chart using these settings by specifying the name of the settings to the options parameter:

# In[13]:


charts.plot([s1, s2], options='my-settings.json', show='inline')


# This way you can replot a chart and keep the options you previously set!

# ## Chart types
# 
# All chart types or demos that you can find on the highchart website can be recreated using *Charts*. Make sure to take [a look around](http://www.highcharts.com/demo) and try some of the examples with *Charts*. To help you we plotted some common chart types in the next lines:

# ### Area chart
# To create an area chart, we simply define some data and set the type to *area*.

# In[14]:


series = [{
    'name': 'John',
    'data': [5, 3, 4, 7, 2]
}, {
    'name': 'Jane',
    'data': [2, -2, -3, 2, 1]
}, {
    'name': 'Joe',
    'data': [3, 4, 4, -2, 5]
}]

options = dict(title=dict(text='Area chart'))

charts.plot(series, options=options, show='inline', type='area')


# ### But I wanted a bar chart...
# No problem! Just change the type to *bar* and you are done. Note that you can even change the `type` in the settings editor! Try changing this bar chart back to an area chart by setting `object > chart > type` back to *area*.

# In[15]:


options = {
    'title': {'text': 'A bar chart'},
    'plotOptions': {
        'bar': {
            'dataLabels': {'enabled': True}
        }
    }
}

charts.plot(series, options=options, show='inline', type='bar')


# ### Do you have more?
# Well, if highcharts has more, we have more! Every [example](http://www.highcharts.com/demo) on their website can easily be recreated using **Charts**!
# 
# A spline chart...

# In[16]:


charts.plot(series, options={'title': {'text': 'A Spline chart'}}, show='inline', type='spline')


# ... and a scatter chart. All these charts will work separatly and stay interactive even after the notebook was shut down or in a static notebook on the web (Maybe you are even viewing a static notebook now!)

# In[17]:


charts.plot(series, options={'title': {'text': 'A scatter chart'}}, show='inline', type='scatter')


# ### Well that seems easy as pie!
# Yep. Know that you mention it, I wanted to show you another chart type: The Pie chart. This chart type does need a different series format but for everything else behaves just the same as the other charts. 

# In[18]:


series =  [{
    'type': 'pie',
    'name': 'Browser share',
    'data': [
        ['Firefox',   45.0],
        ['IE',       26.8],
        {
            'name': 'Chrome',
            'y': 12.8,
            'sliced': True,
            'selected': True
        },
        ['Safari',    8.5],
        ['Opera',     6.2],
        ['Others',   0.7]
    ]
}]

charts.plot(series, options={'title': {'text': 'A pie chart'}}, show='inline')


# ### You didn't set the chart type to pie?
# If you don't set a chart type globally, you can still set a chart type individually for every series. I can hear you asking: "Does that mean we can plot different types in the same graph?" Ofcourse! Highcharts has us covered there:

# In[19]:


series = [{
    'type': 'column',
    'name': 'Jane',
    'data': [3, 2, 1, 3, 4]
}, {
    'type': 'line',
    'name': 'John',
    'data': [2, 3, 5, 7, 6]
}, {
    'type': 'column',
    'name': 'Joe',
    'data': [4, 3, 3, 9, 0]
}, {
    'type': 'spline',
    'name': 'Average',
    'data': [3, 2.67, 3, 6.33, 3.33],
    'marker': {
        'lineWidth': 2,
        'lineColor': '#90ed7d',
        'fillColor': 'white'
    }
}]

charts.plot(series, options={'title': {'text': 'A Combination chart'}}, show='inline')


# ### What's next? I want more!
# Well we have some more features :)
# - For smaller data series, `charts.plot()` can creates an HTML file with all data embedded in the file. This means you can easily share the HTML file and your friend just has to double click the file to see and interact with your chart!
# - For larger data series (for example 100 series of 4MB+), no browser can load the HTML file (this would mean loading an HTML file of over 400MB!) Charts provides the `charts.plotasync()` method as a solution which has the exact same functionality as the `charts.plot()`. Every series is saved in a separate JSON file and loaded asynchrounously when needed, preventing memory issues
# - Lot's of other things we haven't even tried yet. Due to the direct link between Charts and Highcharts, their are no limitations!
# 
# <br>
# 
# Now go and try it! If you have any questions, feature requests or want to help visit the [github](https://github.com/arnoutaertgeerts/python-highcharts) page!

# In[ ]: