Add usage examples to readme

README.md

@@ -4,7 +4,141 @@ Scientific Information for Land Owners (SILO) is a database of Australian climat
 
 https://silo.longpaddock.qld.gov.au
 
-The climate variables are:
+There are two different data types:
+
+#### Point data:
+Get multiple climate variables at a single point (accessible with this python module).
+
+#### Gridded data:
+Get a single climate variable for the entire Australian continent (accessible on the SILO website).
+
+## Point data ##
+
+### Installation ###
+
+```
+git clone http://git.wrl.unsw.edu.au:3000/danh/silo.git
+pip install -e silo
+```
+
+## Usage ##
+```python
+import silo
+
+variables = ['daily_rain', 'max_temp', 'min_temp']
+api_key = 'BcfJnotlnVgX9gyLmZh2dURqNH8xAD3m8Am7V9OY'
+start = '18990101'
+finish = '20180101'
+lat = -33
+lon = 151
+
+silo.pointdata(variables, api_key, start, finish, lat=lat, lon=lon,
+               output='silo-data.csv')
+```
+
+**silo-data.csv**
+
+| date                   | latitude | longitude | daily_rain_mm | daily_rain_source | max_temp_Celsius | max_temp_source | min_temp_Celsius | min_temp_source |
+|------------------------|----------|-----------|---------------|-------------------|------------------|-----------------|------------------|-----------------|
+| 1899-01-01             | -33      | 151       | 0.9           | 24                | 31.4             | 35              | 14.8             | 35              |
+| 1899-01-02             | -33      | 151       | 0             | 24                | 30.1             | 35              | 18.3             | 35              |
+| 1899-01-03             | -33      | 151       | 0             | 24                | 33.3             | 35              | 14.3             | 35              |
+| ...                    |          |           |               |                   |                  |                 |                  |                 |
+
+## Gridded data ##
+
+Gridded datasets are available here:
+
+https://silo.longpaddock.qld.gov.au/gridded-data
+
+### Example: generate timeseries at specific location ###
+
+```python
+import xarray as xr
+import pandas as pd
+import calendar
+import matplotlib.pyplot as plt
+
+# Open netcdf dataset
+fname = '2000.monthly_rain.nc'
+ds = xr.open_dataset(fname)
+
+# Convert to pandas dataframe
+df = ds.to_dataframe().drop(columns=['crs'])
+
+# Set coordinates
+lat = -33.75
+lon = 151.25
+
+# Create temporary dataframe at specific location
+df1 = df.loc[lat, lon]
+
+# Plot time series
+fig, ax = plt.subplots(1, 1, figsize=(6, 4))
+ax.plot(df1.index, df1.values)
+
+# Tidy up figure
+ax.set_xticks(df1.index)
+ax.set_xticklabels([calendar.month_abbr[i] for i in df1.index.month])
+ax.set_ylabel('Rainfall (mm)', labelpad=10)
+ax.spines['right'].set_visible(False)
+ax.spines['top'].set_visible(False)
+
+plt.show()
+```
+<img src="doc/gridded-timeseries-demo.png" width=500px>
+
+### Example: generate maps at specific dates ###
+
+```python
+import xarray as xr
+import pandas as pd
+import calendar
+import matplotlib.pyplot as plt
+
+# Open netcdf dataset
+fname = '2000.monthly_rain.nc'
+ds = xr.open_dataset(fname)
+
+# Convert to pandas dataframe
+df = ds.to_dataframe().drop(columns=['crs'])
+
+# Get index values
+lats = df.index.get_level_values('lat').unique()
+lons = df.index.get_level_values('lon').unique()
+dates = df.index.get_level_values('time').unique()
+
+fig, ax = plt.subplots(3, 4)
+
+for i, date in enumerate(dates):
+    # Get temporary dataframe with only one date
+    df1 = df[df.index.get_level_values('time') == date]
+
+    # Remove date from multi-index
+    df1.index = df1.index.droplevel(-1)
+
+    # Split multi-index so that rows=latitude and columns=longitude
+    grid = df1.unstack()
+
+    # Plot colour map for current month
+    a = ax.ravel()[i]
+    im = a.imshow(grid, cmap='Blues', vmin=-100, vmax=800)
+    a.set_title(calendar.month_abbr[i + 1])
+    a.invert_yaxis()
+    a.axis('off')
+
+# Add colour bar
+cbax = fig.add_axes([0.95, 0.3, 0.02, 0.4])
+cb = fig.colorbar(im, cax=cbax)
+cb.set_ticks([0, 200, 400, 600, 800])
+cbax.set_ylabel('Monthly rainfall (mm)', labelpad=10)
+
+plt.show()
+```
+<img src="doc/gridded-map-demo.png" width=600px>
+
+
+## Available climate variables ##
 
 | code                | name                                                                                    | units   |
 |---------------------|-----------------------------------------------------------------------------------------|---------|
@@ -27,23 +161,3 @@ The climate variables are:
 | et_morton_potential | Evapotranspiration - Morton's potential evapotranspiration                              | mm      |
 | et_morton_wet       | Evapotranspiration - Morton's wet-environment areal evapotranspiration   over land      | mm      |
 | mslp                | Mean sea level pressure                                                                 | hPa     |
-
-There are two different data types:
-1. Point data (accessible with this python module)
-2. Gridded data (accessible on the SILO website)
-
-
-## Point data ##
-
-### Installation ###
-
-```
-git clone http://git.wrl.unsw.edu.au:3000/danh/silo.git
-pip install -e silo
-```
-
-## Usage ##
-
-
-
-## Gridded data ##