.. _quickstart: Quickstart ========== Have :ref:`quick_data`. Want to make chart. .. _quick_bar: Bar --- Bar charts:: import vincent bar = vincent.Bar(list_data) .. image:: /images/quick_bar1.png .. _quick_axislabels: Axis Labels ----------- Labeling the axes is simple:: bar = vincent.Bar(multi_iter1['y1']) bar.axis_titles(x='Index', y='Value') .. image:: /images/quick_bar2.png You can also control aspects of the layout:: import vincent from vincent import AxisProperties, PropertySet, ValueRef bar = vincent.Bar(multi_iter1['y1']) bar.axis_titles(x='Index', y='Value') #rotate x axis labels ax = AxisProperties( labels = PropertySet(angle=ValueRef(value=90))) bar.axes[0].properties = ax .. image:: /images/quick_bar3.png .. _quick_line: Line ---- Line charts:: line = vincent.Line(list_data) line.axis_titles(x='Index', y='Value') .. image:: /images/quick_line1.png .. _quick_legend: Legends ------- Most plots create a separate set of scales that allow for categorical legends that are generated automatically. Adding the legend is straightforward:: line = vincent.Line(multi_iter1, iter_idx='index') line.axis_titles(x='Index', y='Value') line.legend(title='Categories') .. image:: /images/quick_line2.png Using the stocks data:: line = vincent.Line(price[['GOOG', 'AAPL']]) line.axis_titles(x='Date', y='Price') line.legend(title='GOOG vs AAPL') .. image:: /images/quick_line3.png .. _quick_scatter: Scatter -------- Scatter charts:: scatter = vincent.Scatter(multi_iter2, iter_idx='index') scatter.axis_titles(x='Index', y='Data Value') scatter.legend(title='Categories') .. image:: /images/quick_scatter1.png .. _quick_colors: Colors ------ All of the `Color Brewer `_ scales are built-in to Vincent:: scatter.colors(brew='Set3') .. image:: /images/quick_scatter2.png .. _quick_area: Area ---- Area charts take similar data to Line:: area = vincent.Area(list_data) .. image:: /images/quick_area1.png .. _quick_stackedarea: Stacked Area ------------ Stacked areas allow you to visualize multiple categories with one chart:: stacked = vincent.StackedArea(multi_iter1, iter_idx='index') stacked.axis_titles(x='Index', y='Value') stacked.legend(title='Categories') .. image:: /images/quick_stackarea1.png More categories, more colors:: stacked = vincent.StackedArea(df_1) stacked.axis_titles(x='Index', y='Value') stacked.legend(title='Categories') stacked.colors(brew='Spectral') .. image:: /images/quick_stackarea2.png Stocks data:: stacked = vincent.StackedArea(price) stacked.axis_titles(x='Date', y='Price') stacked.legend(title='Tech Stocks') stacked.colors(brew='Accent') .. image:: /images/quick_stackarea3.png .. _quick_stackedbar: Stacked Bar ------------ Similar to stacked areas, stacked bars let you visualize multiple ordinal categories and groups:: stack = vincent.StackedBar(df_2) stack.legend(title='Categories') .. image:: /images/quick_stackbar1.png Adding some bar padding is often helpful:: stack = vincent.StackedBar(df_farm) stack.axis_titles(x='Total Produce', y='Farms') stack.legend(title='Produce Types') stack.scales['x'].padding = 0.2 stack.colors(brew='Pastel1') .. image:: /images/quick_stackbar2.png .. _quick_groupedbar: Grouped Bar ----------- Grouped bars are another way to view grouped ordinal data:: group = vincent.GroupedBar(df_2) group.legend(title='Categories') group.colors(brew='Spectral') group.width=750 .. image:: /images/quick_grouped1.png Farm data:: group = vincent.GroupedBar(df_farm) group.axis_titles(x='Total Produce', y='Farms') group.legend(title='Produce Types') group.colors(brew='Set1') .. image:: /images/quick_grouped2.png .. _simple_map: Simple Map ---------- You can find all of the TopoJSON data in the `vincent_map_data `_ repo. A simple world map:: world_topo = r'world-countries.topo.json' geo_data = [{'name': 'countries', 'url': world_topo, 'feature': 'world-countries'}] vis = vincent.Map(geo_data=geo_data, scale=200) .. image:: /images/world_map.png You can also pass multiple map layers:: geo_data = [{'name': 'counties', 'url': county_topo, 'feature': 'us_counties.geo'}, {'name': 'states', 'url': state_topo, 'feature': 'us_states.geo'}] vis = vincent.Map(geo_data=geo_data, scale=1000, projection='albersUsa') del vis.marks[1].properties.update vis.marks[0].properties.update.fill.value = '#084081' vis.marks[1].properties.enter.stroke.value = '#fff' vis.marks[0].properties.enter.stroke.value = '#7bccc4' .. image:: /images/us_map.png .. _map_data_binding: Map Data Binding ---------------- Maps can be bound to data via Pandas DataFrames to create Choropleths:: geo_data = [{'name': 'counties', 'url': county_topo, 'feature': 'us_counties.geo'}] vis = vincent.Map(data=merged, geo_data=geo_data, scale=1100, projection='albersUsa', data_bind='Employed_2011', data_key='FIPS', map_key={'counties': 'properties.FIPS'}) vis.marks[0].properties.enter.stroke_opacity = ValueRef(value=0.5) vis.to_json('vega.json') .. image:: /images/map_binding1.png The data can be rebound for new columns with different color brewer scales on the fly:: vis.rebind(column='Unemployment_rate_2011', brew='YlGnBu') vis.to_json('vega.json') .. image:: /images/map_binding2.png .. _output: Output ------ To write the Vega spec to JSON, use the ``to_json`` method:: bar.to_json('bar.json') If no path is included, it writes it as a string to the REPL:: >>>bar.to_json() #Really long string of JSON A simple HTML template to read and display the chart is built-in to Vincent, and can be output along with the JSON:: >>>bar.to_json('bar.json', html_out=True, html_path='bar_template.html') The HTML will need to be served somehow- luckily, Python makes this easy. Start a simple HTTP Server, then point your browser to localhost:8000:: $python -m SimpleHTTPServer 8000 .. _IPython_integration: IPython integration ------------------- It is possible to run the above examples inside `IPython notebook `_ by adding a few extra lines:: import vincent vincent.core.initialize_notebook() bar = vincent.Bar(multi_iter1['y1']) bar.axis_titles(x='Index', y='Value') bar.display() .. image:: /images/ipynb.png .. _quick_data: Data ---- These are the datasets used in the :ref:`quickstart` charts above:: import pandas as pd import random #Iterable list_data = [10, 20, 30, 20, 15, 30, 45] #Dicts of iterables cat_1 = ['y1', 'y2', 'y3', 'y4'] index_1 = range(0, 21, 1) multi_iter1 = {'index': index_1} for cat in cat_1: multi_iter1[cat] = [random.randint(10, 100) for x in index_1] cat_2 = ['y' + str(x) for x in range(0, 10, 1)] index_2 = range(1, 21, 1) multi_iter2 = {'index': index_2} for cat in cat_2: multi_iter2[cat] = [random.randint(10, 100) for x in index_2] #Pandas import pandas as pd farm_1 = {'apples': 10, 'berries': 32, 'squash': 21, 'melons': 13, 'corn': 18} farm_2 = {'apples': 15, 'berries': 43, 'squash': 17, 'melons': 10, 'corn': 22} farm_3 = {'apples': 6, 'berries': 24, 'squash': 22, 'melons': 16, 'corn': 30} farm_4 = {'apples': 12, 'berries': 30, 'squash': 15, 'melons': 9, 'corn': 15} farm_data = [farm_1, farm_2, farm_3, farm_4] farm_index = ['Farm 1', 'Farm 2', 'Farm 3', 'Farm 4'] df_farm = pd.DataFrame(farm_data, index=farm_index) #As DataFrames index_3 = multi_iter2.pop('index') df_1 = pd.DataFrame(multi_iter2, index=index_3) df_1 = df_1.reindex(columns=sorted(df_1.columns)) cat_4 = ['Metric_' + str(x) for x in range(0, 10, 1)] index_4 = ['Data 1', 'Data 2', 'Data 3', 'Data 4'] data_3 = {} for cat in cat_4: data_3[cat] = [random.randint(10, 100) for x in index_4] df_2 = pd.DataFrame(data_3, index=index_4) import pandas.io.data as web all_data = {} for ticker in ['AAPL', 'GOOG', 'IBM', 'YHOO', 'MSFT']: all_data[ticker] = web.get_data_yahoo(ticker, '1/1/2010', '1/1/2013') price = pd.DataFrame({tic: data['Adj Close'] for tic, data in all_data.iteritems()}) #Map Data Binding import json import pandas as pd #Map the county codes we have in our geometry to those in the #county_data file, which contains additional rows we don't need with open('us_counties.topo.json', 'r') as f: get_id = json.load(f) #A little FIPS code munging new_geoms = [] for geom in get_id['objects']['us_counties.geo']['geometries']: geom['properties']['FIPS'] = int(geom['properties']['FIPS']) new_geoms.append(geom) get_id['objects']['us_counties.geo']['geometries'] = new_geoms with open('us_counties.topo.json', 'w') as f: json.dump(get_id, f) #Grab the FIPS codes and load them into a dataframe geometries = get_id['objects']['us_counties.geo']['geometries'] county_codes = [x['properties']['FIPS'] for x in geometries] county_df = pd.DataFrame({'FIPS': county_codes}, dtype=str) county_df = county_df.astype(int) #Read into Dataframe, cast to string for consistency df = pd.read_csv('data/us_county_data.csv', na_values=[' ']) df['FIPS_Code'] = df['FIPS'].astype(str) #Perform an inner join, pad NA's with data from nearest county merged = pd.merge(df, county_df, on='FIPS', how='inner') merged = merged.fillna(method='pad')