adjusted ais module to easier understand date formats and added help

docs/tutorials.rst

@@ -29,3 +29,4 @@ e.g.:
    tutorials_stats
    tutorials_triple_collocation
    tutorials_gridder
+   tutorials_ais

docs/tutorials_ais.rst

@@ -0,0 +1,35 @@
+Retrieve AIS
+############
+
+**wavy** offers the possibility to retrieve AIS data which essentially is data on characteristics and location of marine vessels. This works as follows:
+
+.. code-block:: python3
+
+    >>> import wavy.ais_module as ais
+    >>> import pytest
+
+    >>> bbox = ['5.89', '62.3', '6.5', '62.7']
+    >>> sd = '2017-01-03 08'
+    >>> ed = '2017-01-03 09'
+
+    >>>ais_ds = ais.get_AIS_data(bbox, sd, ed)
+
+The output is an xarray dataset and looks like the following:
+
+.. code-block:: python3
+
+    >>> ais_ds
+    <xarray.Dataset> Size: 12MB
+    Dimensions:       (time: 155292)
+    Coordinates:
+      * time          (time) datetime64[ns] 1MB 2017-01-02T09:00:00 ... 2017-01-0...
+    Data variables:
+        mmsi          (time) int64 1MB 259098000 219770000 ... 259097000 259257000
+        lons          (time) float64 1MB 6.33 6.189 6.28 6.192 ... 6.279 6.337 6.124
+        lats          (time) float64 1MB 62.38 62.56 62.6 ... 62.62 62.41 62.47
+        grosstonnage  (time) float64 1MB 2.967e+03 218.0 769.0 ... 2.967e+03 380.0
+        dwt           (time) float64 1MB 970.0 nan 250.0 27.0 ... nan nan 891.0 nan
+        length        (time) float64 1MB 109.5 26.2 64.32 29.2 ... nan 109.5 34.6
+        breadth       (time) float64 1MB 16.99 9.2 11.26 9.0 ... 10.6 nan 17.0 10.6
+        draught       (time) float64 1MB 3.0 1.64 nan 1.5 1.64 ... nan nan 3.425 nan
+        shiptypeeng   (time) object 1MB 'Vehicles Carrier' ... 'Passenger Ship'

tests/test_aismod.py

@@ -6,11 +6,11 @@
 @pytest.mark.need_credentials
 def test_get_ais_data():
 
-    bbound = ['5.89', '62.3', '6.5', '62.7']
-    sd = '201701030800'
-    ed = '201701030900'
+    bbox = ['5.89', '62.3', '6.5', '62.7']
+    sd = '2017-01-03 08'
+    ed = '2017-01-03 09'
 
-    ais_ds = ais.get_AIS_data(bbound, sd, ed)
+    ais_ds = ais.get_AIS_data(bbox, sd, ed)
     assert len(ais_ds['time']) > 0
     assert not all(np.isnan(v) for v in ais_ds['time'])
     assert not all(np.isnan(v) for v in ais_ds['lons'])

wavy/ais_module.py

@@ -1,19 +1,25 @@
-from wavy.credentials import credentials_from_netrc
 import requests
 import xarray as xr
 import pandas as pd
 import os
 import json
+from wavy.credentials import credentials_from_netrc
+from wavy.utils import parse_date
 
 
-def get_AIS_data(bbox, sd, ed, minspeed=0.5):
+def get_AIS_data(bbox, sd=None, ed=None, minspeed=0.5):
     '''
     Args:
         bbox: list of strings [lon min, lat min,
                                lon max, lat max]
         sd, ed: start and end dates, as strings
                 under "yyyymmddHHMM" format
     '''
+    sd = parse_date(sd)
+    ed = parse_date(ed)
+    sd_str = sd.strftime('%Y%m%d%H%M')
+    ed_str = ed.strftime('%Y%m%d%H%M')
+
     # get token
     auth = credentials_from_netrc('kystdatahuset.no')
     url = "https://kystdatahuset.no/ws/api/auth/login"
@@ -32,8 +38,8 @@ def get_AIS_data(bbox, sd, ed, minspeed=0.5):
 
     dict_data = {
                  "bbox": ",".join(bbox),
-                 "start": sd,
-                 "end": ed,
+                 "start": sd_str,
+                 "end": ed_str,
                  "minSpeed": minspeed
                 }