Add CSV examples.

docs/Makefile

@@ -72,17 +72,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/agate.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/leather.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/agate.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/leather.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/agate"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/agate"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/leather"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/leather"
 	@echo "# devhelp"
 
 epub:

docs/examples.rst

@@ -0,0 +1,86 @@
+========
+Examples
+========
+
+Data
+====
+
+Simple pairs
+------------
+
+.. literalinclude:: ../examples/simple_pairs.py
+    :language: python
+
+.. figure:: ../examples/charts/simple_pairs.svg
+
+Table from csv.reader
+---------------------
+
+Leather does not automatically convert numerical strings, such as those stored in a CSV. If you want that you'll need to use a smarter table reader, such as `agate <http://agate.rtfd.io/>`_
+
+.. literalinclude:: ../examples/csv_reader.py
+    :language: python
+
+.. figure:: ../examples/charts/csv_reader.svg
+
+Table from csv.DictReader
+-------------------------
+
+See previous example for note on strings from CSVs.
+
+.. literalinclude:: ../examples/csv_dict_reader.py
+    :language: python
+
+.. figure:: ../examples/charts/csv_dict_reader.svg
+
+Custom data
+-----------
+
+TKTK
+
+Shapes
+======
+
+Bars
+----
+
+TKTK
+
+Columns
+-------
+
+TKTK
+
+Dots
+----
+
+TKTK
+
+Lines
+-----
+
+.. literalinclude:: ../examples/lines.py
+    :language: python
+
+.. figure:: ../examples/charts/lines.svg
+
+Scales
+======
+
+TKTK
+
+Axes
+====
+
+TKTK
+
+Styling
+=======
+
+TKTK
+
+
+.. literalinclude:: ../examples/colorized_dots.py
+    :language: python
+
+.. figure:: ../examples/charts/colorized_dots.svg

docs/index.rst

@@ -10,16 +10,18 @@ leather |release|
 
     about
     install
+    examples
     api
     release_process
     license
 
 Show me docs
 ============
 
-* `About <about.html>`_ - why you should use leather and the principles that guide its development
+* `About <about.html>`_ - why you should use leather
 * `Install <install.html>`_ - how to install for users and developers
-* `API <api.html>`_ - technical documentation for every agate feature
+* `Examples <examples.html>`_ - code + output examples of every feature of leather
+* `API <api.html>`_ - technical documentation for the leather API
 
 Show me code
 ============

examples/csv_dict_reader.py

@@ -0,0 +1,15 @@
+import csv
+
+import leather
+
+with open('examples/realdata/gii.csv') as f:
+    reader = csv.DictReader(f)
+    data = list(reader)[:10]
+
+    for row in data:
+        mmr = row['Maternal mortality ratio']
+        row['Maternal mortality ratio'] = float(mmr) if mmr is not None else None
+
+chart = leather.Chart('Data from CSV reader')
+chart.add_bars(data, x='Maternal mortality ratio', y='Country')
+chart.to_svg('examples/charts/csv_dict_reader.svg')

examples/csv_reader.py

@@ -0,0 +1,15 @@
+import csv
+
+import leather
+
+with open('examples/realdata/gii.csv') as f:
+    reader = csv.reader(f)
+    next(reader)
+    data = list(reader)[:10]
+
+    for row in data:
+        row[1] = float(row[1]) if row[1] is not None else None
+
+chart = leather.Chart('Data from CSV reader')
+chart.add_bars(data, x=1, y=0)
+chart.to_svg('examples/charts/csv_reader.svg')

examples/realdata/gii.csv

@@ -0,0 +1 @@
+Country,GII Index,GII Rank,Maternal mortality ratio,Adolescent birth rate,Share of seats in parliamentNorway,0.067,9,4,7.8,39.6Australia,0.110,19,6,12.1,30.5Switzerland,0.028,2,6,1.9,28.5Denmark,0.048,4,5,5.1,38.0Netherlands,0.062,7,6,6.2,36.9Germany,0.041,3,7,3.8,36.9Ireland,0.113,21,9,8.2,19.9United States,0.280,55,28,31.0,19.4Canada,0.129,25,11,14.5,28.2New Zealand,0.157,32,8,25.3,31.4Singapore,0.088,13,6,6.0,25.3"Hong Kong, China (SAR)",,,,3.3,Liechtenstein,,,,,20.0Sweden,0.055,6,4,6.5,43.6United Kingdom,0.177,39,8,25.8,23.5Iceland,0.087,12,4,11.5,41.3Korea (Republic of),0.125,23,27,2.2,16.3Israel,0.101,18,2,7.8,22.5Luxembourg,0.100,17,11,8.3,28.3Japan,0.133,26,6,5.4,11.6Belgium,0.063,8,6,6.7,42.4France,0.088,13,12,5.7,25.7Austria,0.053,5,4,4.1,30.3Finland,0.075,11,4,9.2,42.5Slovenia,0.016,1,7,0.6,27.7Spain,0.095,16,4,10.6,38.0Italy,0.068,10,4,4.0,30.1Czech Republic,0.091,15,5,4.9,18.9Greece,0.146,29,5,11.9,21.0Estonia,0.164,33,11,16.8,19.8Brunei Darussalam,,,27,23.0,Cyprus,0.124,22,10,5.5,12.5Qatar,0.524,116,6,9.5,0.0Andorra,,,,,50.0Slovakia,0.164,33,7,15.9,18.7Poland,0.138,28,3,12.2,22.1Lithuania,0.125,23,11,10.6,23.4Malta,0.227,46,9,18.2,13.0Saudi Arabia,0.284,56,16,10.2,19.9Argentina,0.376,75,69,54.4,36.8United Arab Emirates,0.232,47,8,27.6,17.5Chile,0.338,65,22,55.3,15.8Portugal,0.111,20,8,12.6,31.3Hungary,0.209,42,14,12.1,10.1Bahrain,0.265,51,22,13.8,15.0Latvia,0.167,36,13,13.5,18.0Croatia,0.149,30,13,12.7,25.8Kuwait,0.387,79,14,14.5,1.5Montenegro,0.171,37,7,15.2,17.3Belarus,0.151,31,1,20.6,30.1Russian Federation,0.276,54,24,25.7,14.5Oman,0.275,53,11,10.6,9.6Romania,0.333,64,33,31.0,12.0Uruguay,0.313,61,14,58.3,11.5Bahamas,0.298,58,37,28.5,16.7Kazakhstan,0.267,52,26,29.9,20.1Barbados,0.357,69,52,48.4,19.6Antigua and Barbuda,,,,49.3,25.7Bulgaria,0.212,44,5,35.9,20.4Palau,,,,,10.3Panama,0.454,96,85,78.5,19.3Malaysia,0.209,42,29,5.7,14.2Mauritius,0.419,88,73,30.9,11.6Seychelles,,,,56.3,43.8Trinidad and Tobago,0.371,73,84,34.8,24.7Serbia,0.176,38,16,16.9,34.0Cuba,0.356,68,80,43.1,48.9Lebanon,0.385,78,16,12.0,3.1Costa Rica,0.349,66,38,60.8,33.3Iran (Islamic Republic of),0.515,114,23,31.6,3.1Venezuela (Bolivarian Republic of),0.476,103,110,83.2,17.0Turkey,0.359,71,20,30.9,14.4Sri Lanka,0.370,72,29,16.9,5.8Mexico,0.373,74,49,63.4,37.1Brazil,0.457,97,69,70.8,9.6Georgia,0.382,77,41,46.8,11.3Saint Kitts and Nevis,,,,,6.7Azerbaijan,0.303,59,26,40.0,15.6Grenada,,,23,35.4,25.0Jordan,0.473,102,50,26.5,11.6The former Yugoslav Republic of Macedonia,0.164,33,7,18.3,33.3Ukraine,0.286,57,23,25.7,11.8Algeria,0.413,85,89,10.0,25.7Peru,0.406,82,89,50.7,22.3Albania,0.217,45,21,15.3,20.7Armenia,0.318,62,29,27.1,10.7Bosnia and Herzegovina,0.201,41,8,15.1,19.3Ecuador,0.407,83,87,77.0,41.6Saint Lucia,,,34,56.3,20.7China,0.191,40,32,8.6,23.6Fiji,0.418,87,59,42.8,14.0Mongolia,0.325,63,68,18.7,14.9Thailand,0.380,76,26,41.0,6.1Dominica,,,,,21.9Libya,0.134,27,15,2.5,16.0Tunisia,0.240,48,46,4.6,31.3Colombia,0.429,92,83,68.5,20.9Saint Vincent and the Grenadines,,,45,54.5,13.0Jamaica,0.430,93,80,70.1,16.7Tonga,0.666,148,120,18.1,0.0Belize,0.426,90,45,71.4,13.3Dominican Republic,0.477,104,100,99.6,19.1Suriname,0.463,100,130,35.2,11.8Maldives,0.243,49,31,4.2,5.9Samoa,0.457,97,58,28.3,6.1Botswana,0.480,106,170,44.2,9.5Moldova (Republic of),0.248,50,21,29.3,20.8Egypt,0.573,131,45,43.0,2.2Turkmenistan,,,61,18.0,25.8Gabon,0.514,113,240,103.0,16.2Indonesia,0.494,110,190,48.3,17.1Paraguay,0.472,101,110,67.0,16.8"Palestine, State of",,,,45.8,Uzbekistan,,,36,38.8,16.4Philippines,0.420,89,120,46.8,27.1El Salvador,0.427,91,69,76.0,27.4South Africa,0.407,83,140,50.9,40.7Viet Nam,0.308,60,49,29.0,24.3Bolivia (Plurinational State of),0.444,94,200,71.9,51.8Kyrgyzstan,0.353,67,75,29.3,23.3Iraq,0.539,123,67,68.7,26.5Cabo Verde,,,53,70.6,20.8Micronesia (Federated States of),,,96,18.6,0.0Guyana,0.515,114,250,88.5,31.3Nicaragua,0.449,95,100,100.8,39.1Morocco,0.525,117,120,35.8,11.0Namibia,0.401,81,130,54.9,37.7Guatemala,0.533,119,140,97.2,13.3Tajikistan,0.357,69,44,42.8,15.2India,0.563,130,190,32.8,12.2Honduras,0.480,106,120,84.0,25.8Bhutan,0.457,97,120,40.9,8.3Timor-Leste,,,270,52.2,38.5Syrian Arab Republic,0.533,119,49,41.6,12.4Vanuatu,,,86,44.8,0.0Congo,0.593,137,410,126.7,11.5Kiribati,,,130,16.6,8.7Equatorial Guinea,,,290,112.6,19.7Zambia,0.587,132,280,125.4,12.7Ghana,0.554,127,380,58.4,10.9Lao People's Democratic Republic,,,,65.0,25.0Bangladesh,0.503,111,170,80.6,20.0Cambodia,0.477,104,170,44.3,19.0Sao Tome and Principe,,,210,65.1,18.2Kenya,0.552,126,400,93.6,20.8Nepal,0.489,108,190,73.7,29.5Pakistan,0.536,121,170,27.3,19.7Myanmar,0.413,85,200,12.1,4.7Angola,,,460,170.2,36.8Swaziland,0.557,128,310,72.0,14.7Tanzania (United Republic of),0.547,125,410,122.7,36.0Nigeria,,,560,119.6,6.6Cameroon,0.587,132,590,115.8,27.1Madagascar,,,440,122.8,20.5Zimbabwe,0.504,112,470,60.3,35.1Mauritania,0.610,139,320,73.3,22.2Solomon Islands,,,130,64.9,2.0Papua New Guinea,0.611,140,220,62.1,2.7Comoros,,,350,51.1,3.0Yemen,0.744,155,270,47.0,0.7Lesotho,0.541,124,490,89.4,26.8Togo,0.588,134,450,91.5,17.6Haiti,0.603,138,380,42.0,3.5Rwanda,0.400,80,320,33.6,57.5Uganda,0.538,122,360,126.6,35.0Benin,0.614,142,340,90.2,8.4Sudan,0.591,135,360,84.0,23.8Djibouti,,,230,18.6,12.7South Sudan,,,730,75.3,24.3Senegal,0.528,118,320,94.4,42.7Afghanistan,0.693,152,400,86.8,27.6Cote d'Ivoire,0.679,151,720,130.3,9.2Malawi,0.611,140,510,144.8,16.7Ethiopia,0.558,129,420,78.4,25.5Gambia,0.622,143,430,115.8,9.4Congo (Democratic Republic of the),0.673,149,730,135.3,8.2Liberia,0.651,146,640,117.4,10.7Guinea-Bissau,,,560,99.3,13.7Mali,0.677,150,550,175.6,9.5Mozambique,0.591,135,480,137.8,39.6Sierra Leone,0.650,145,"1,100",100.7,12.4Guinea,,,650,131.0,21.9Burkina Faso,0.631,144,400,115.4,13.3Burundi,0.492,109,740,30.3,34.9Chad,0.706,153,980,152.0,14.9Eritrea,,,380,65.3,22.0Central African Republic,0.655,147,880,98.3,12.5Niger,0.713,154,630,204.8,13.3Korea (Democratic People's Rep. of),,,87,0.6,16.3Marshall Islands,,,,,3.0Monaco,,,,,20.8Nauru,,,,,5.3San Marino,,,,,16.7Somalia,,,850,110.4,13.8Tuvalu,,,,,6.7

examples/realdata/index.md

@@ -0,0 +1,3 @@
+## gii.csv
+
+A subset of data taken from the UN's [Gender Inequality Index](http://hdr.undp.org/en/composite/GII).

examples/simple_pairs.py

@@ -0,0 +1,12 @@
+import leather
+
+data = [
+    (0, 3),
+    (4, 5),
+    (7, 9),
+    (8, 4)
+]
+
+chart = leather.Chart('Simple pairs')
+chart.add_dots(data)
+chart.to_svg('examples/charts/simple_pairs.svg')

leather/chart.py

@@ -80,41 +80,41 @@ def add_series(self, series):
 
         self._layers.append(series)
 
-    def add_bars(self, data, name=None, color=None):
+    def add_bars(self, data, x=None, y=None, name=None, color=None):
         """
         Create and add a :class:`.Series` rendered with :class:`.Bars`.
         """
         if not color:
             color = self._series_colors.pop(0)
 
-        self.add_series(Series(data, Bars(color), name=name))
+        self.add_series(Series(data, Bars(color), x=x, y=y, name=name))
 
-    def add_columns(self, data, name=None, color=None):
+    def add_columns(self, data, x=None, y=None, name=None, color=None):
         """
         Create and add a :class:`.Series` rendered with :class:`.Columns`.
         """
         if not color:
             color = self._series_colors.pop(0)
 
-        self.add_series(Series(data, Columns(color), name=name))
+        self.add_series(Series(data, Columns(color), x=x, y=y, name=name))
 
-    def add_dots(self, data, name=None, color=None, radius=None):
+    def add_dots(self, data, x=None, y=None, name=None, color=None, radius=None):
         """
         Create and add a :class:`.Series` rendered with :class:`.Dots`.
         """
         if not color:
             color = self._series_colors.pop(0)
 
-        self.add_series(Series(data, Dots(color, radius), name=name))
+        self.add_series(Series(data, Dots(color, radius), x=x, y=y, name=name))
 
-    def add_lines(self, data, name=None, color=None, width=None):
+    def add_lines(self, data, x=None, y=None, name=None, color=None, width=None):
         """
         Create and add a :class:`.Series` rendered with :class:`.Lines`.
         """
         if not color:
             color = self._series_colors.pop(0)
 
-        self.add_series(Series(data, Lines(color, width), name=name))
+        self.add_series(Series(data, Lines(color, width), x=x, y=y, name=name))
 
     def _validate_dimension(self, dimension):
         """

leather/series.py

@@ -41,22 +41,16 @@ class Series(Iterable):
     :param name:
         An optional name to be used in labeling this series.
     """
-    def __init__(self, data, shape, x=0, y=1, name=None):
+    def __init__(self, data, shape, x=None, y=None, name=None):
         self._data = data
-        self._len = len(data)
         self._shape = shape
         self._name = name
 
         self._keys = [
-            self._make_key(x),
-            self._make_key(y)
+            self._make_key(x if x is not None else X),
+            self._make_key(y if y is not None else Y)
         ]
 
-        if callable(y):
-            self._keys[Y] = y
-        else:
-            self._keys[Y] = lambda row, index: row[y]
-
         self._types = [None, None]
 
         for i in DIMENSIONS:
@@ -95,7 +89,8 @@ def _infer_type(self, dimension):
         while key(self._data[i], i) is None:
             i += 1
 
-        # TKTK: raise an exception if we hit the end of the data
+        if i == len(self._data):
+            raise ValueError('Entire value column was null.')
 
         return DataType.infer(key(self._data[i], i))
 

setup.py

@@ -13,7 +13,7 @@
     long_description=open('README.rst').read(),
     author='Christopher Groskopf',
     author_email='chrisgroskopf@gmail.com',
-    # url='http://agate.readthedocs.org/',
+    url='http://leather.readthedocs.io/',
     license='MIT',
     classifiers=[
         'Development Status :: 2 - Pre-Alpha',

test.py

@@ -1,18 +1,13 @@
-#!/usr/bin/env python
-
-from datetime import date, datetime
+import csv
 
 import leather
 
+with open('examples/realdata/gii.csv') as f:
+    reader = csv.reader(f)
+    next(reader)
 
-data = [
-    (datetime(2010, 1, 1), 4),
-    (datetime(2011, 5, 4), 3),
-    (datetime(2012, 6, 1, 11), 5),
-    (datetime(2013, 1, 1), 6),
-    (datetime(2014, 12, 1), 10)
-]
+    data = list(reader)[:10]
 
-chart = leather.Chart("X axis ftw")
-chart.add_lines(data)
+chart = leather.Chart('Test')
+chart.add_bars(data, x=1, y=0)
 chart.to_svg('test.svg')