Improve readme

The readme is a bit stale after some of the recent changes, we should update it. Also, there are a few chunks of python code that can probably just stay in the example Jupyter notebook (DRY, a pointer to the example will probably be good enough).