Merge pull request #3 from sjoshistrats/feature/docs

Add docs to README

Author: sjoshistrats

README.md

@@ -1,4 +1,55 @@
 [![<sjoshistrats>](https://circleci.com/gh/sjoshistrats/fastgrouper.svg?style=svg)](https://app.circleci.com/pipelines/github/sjoshistrats/fastgrouper?branch=master)
 
 # fastgrouper
-Efficient tools for groupby-apply operations, in python.
+Allows for fast groupby-apply operations, in python.
+
+# Usage
+
+Use the `arr` interface, for numpy array focused applications.
+
+```python
+import numpy as np
+import fastgrouper.li
+  
+def baz(x, y):
+    return np.mean(x + y) - 3
+
+# Sample arrays, to slice
+xvals = np.array([1, 2, 10])
+yvals = np.array([4, 5, 6])
+  
+# Group IDS
+gids  = np.array([1, -3, 1])
+
+# Perform groupby-apply; note that keyword args are supported as well.
+grpd = fastgrouper.arr.Grouped(gids)
+result = grpd.apply(baz, xvals, y=yvals) # np.array([7.5, 4])
+
+# Perform groupby-apply, and then expand results back to align with the gids provided.
+result = grpd.apply_expand(baz, xvals, yvals) # np.array([7.5, 4. , 7.5])
+
+# Perform groupby-apply, and then expand results back to align with the gids provided.
+result = grpd.apply_expand(baz, xvals, yvals) # np.array([7.5, 4. , 7.5])
+```
+
+The `li` interface returns the results over the groups as a list (instead of an array); this may be useful for functions that return different-sized results. Note that in all interfaces (e.g. both `arr` and `li`), the order in which the group elements appear is preserved when the group slices are passed to the function being applied.
+
+  
+```python
+import numpy as np
+import fastgrouper.li
+  
+def bop(x):
+    return list(x)
+
+# Sample arrays, to slice
+xvals = np.array([2, 3, 4])
+  
+# Group IDS
+gids  = np.array([10, -20, 10])
+
+grpd = fastgrouper.li.Grouped(gids)
+grpd.apply(bop, xvals) # returns [[2, 4], [3]]
+```
+  
+For additional examples, checkout the [tests](https://github.com/sjoshistrats/fastgrouper/tree/master/python/fastgrouper/test).