Repository: fatiando/verde (python)

Issue:
Include GMT ship bathymetry data
The GMT tutorial uses bathymetry from Baja California to illustrate gridding. That's a good data set. We can package that in the original form and also a decimated version (using `gmt blockmedian`) to get better results while GMT/Python isn't available.

Pull request description:
Function to fetch sample bathymetry data
Adds function `verde.datasets.fetch_baja_bathymetry` that loads the data
into a `pandas.DataFrame`. Include a gallery example for the data using
cartopy to plot with projections.

Fixes #20 


Patch:
diff --git a/environment.yml b/environment.yml
index e571e92..7c9f23d 100644
--- a/environment.yml
+++ b/environment.yml
@@ -13,6 +13,7 @@ dependencies:
     - requests
     # Development requirements
     - matplotlib
+    - cartopy
     - jupyter
     - pytest
     - pytest-cov
diff --git a/examples/baja_bathymetry.py b/examples/baja_bathymetry.py
new file mode 100644
index 0000000..7819cb2
--- /dev/null
+++ b/examples/baja_bathymetry.py
@@ -0,0 +1,35 @@
+"""
+Sample bathymetry data
+======================
+
+We provide sample bathymetry data from Baja California to test the gridding
+methods. This is the ``@tut_ship.xyz`` sample data from the `GMT
+<http://gmt.soest.hawaii.edu/>`__ tutorial. The data is downloaded to a local
+directory if it's not there already.
+"""
+import matplotlib.pyplot as plt
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+from verde.datasets import fetch_baja_bathymetry
+
+
+# The data are in a pandas.DataFrame
+data = fetch_baja_bathymetry()
+print(data.head())
+
+# Make a plot of the data using Cartopy to handle projections and coastlines
+plt.figure(figsize=(7, 6))
+ax = plt.axes(projection=ccrs.Mercator())
+ax.set_title('Bathymetry from Baja California', pad=25)
+# Plot the land as a solid color
+ax.add_feature(cfeature.LAND, edgecolor='black')
+# Plot the bathymetry as colored circles.
+# Cartopy requires setting the projection of the original data through the
+# transform argument. Use PlateCarree for geographic data.
+plt.scatter(data.longitude, data.latitude, c=data.bathymetry_m, s=0.1,
+            transform=ccrs.PlateCarree())
+cb = plt.colorbar(pad=0.08)
+cb.set_label('meters')
+ax.gridlines(draw_labels=True)
+plt.tight_layout()
+plt.show()
diff --git a/examples/checkerboard.py b/examples/checkerboard.py
index 84169be..8393d6b 100644
--- a/examples/checkerboard.py
+++ b/examples/checkerboard.py
@@ -5,8 +5,8 @@ Checkerboard synthetic data
 The :class:`verde.datasets.CheckerBoard` class generates synthetic data in a
 checkerboard pattern. Use it like any gridder class.
 """
-import verde as vd
 import matplotlib.pyplot as plt
+import verde as vd
 
 # Instantiate the data generator class and fit it to set the data region.
 synth = vd.datasets.CheckerBoard().fit()
diff --git a/requirements.txt b/requirements.txt
index cc6d33d..e60f2f8 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -6,6 +6,7 @@ scikit-learn
 requests
 # Development requirements
 matplotlib
+cartopy
 jupyter
 pytest
 pytest-cov
diff --git a/verde/datasets/__init__.py b/verde/datasets/__init__.py
index 3253b02..8d7b91e 100644
--- a/verde/datasets/__init__.py
+++ b/verde/datasets/__init__.py
@@ -2,3 +2,4 @@
 Loading test data and generating synthetic datasets.
 """
 from .synthetic import CheckerBoard
+from .sample_data import fetch_baja_bathymetry
diff --git a/verde/datasets/sample_data.py b/verde/datasets/sample_data.py
new file mode 100644
index 0000000..8892a6e
--- /dev/null
+++ b/verde/datasets/sample_data.py
@@ -0,0 +1,34 @@
+"""
+Functions to load sample data
+"""
+import pandas as pd
+
+from .download import fetch_data
+
+
+def fetch_baja_bathymetry(force_download=False):
+    """
+    Fetch sample bathymetry data from Baja California.
+
+    This is the ``@tut_ship.xyz`` sample data from the `GMT
+    <http://gmt.soest.hawaii.edu/>`__ tutorial.
+
+    If the file isn't already in your data directory (``$HOME/.verde/data`` by
+    default), it will be downloaded.
+
+    Parameters
+    ----------
+    force_download : bool
+        If True, will download the file even if it already exists.
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        The bathymetry data. Columns are longitude, latitude, and bathymetry
+        (in meters) for each data point.
+
+    """
+    data_file = fetch_data('baja-california-bathymetry.csv.xz',
+                           force_download=force_download)
+    data = pd.read_csv(data_file, compression='xz')
+    return data


Test patch:
diff --git a/verde/tests/test_datasets.py b/verde/tests/test_datasets.py
index 1f20873..d107bd6 100644
--- a/verde/tests/test_datasets.py
+++ b/verde/tests/test_datasets.py
@@ -8,6 +8,7 @@ from requests.exceptions import HTTPError
 import pytest
 
 from ..datasets.download import fetch_data
+from ..datasets import fetch_baja_bathymetry
 
 
 def compare_tiny_data(datapath):
@@ -51,3 +52,11 @@ def test_fetch_data_from_store_remote_fail():
         assert len(warn) == 1
         assert issubclass(warn[-1].category, UserWarning)
         assert str(warn[-1].message).split()[0] == "Downloading"
+
+
+def test_fetch_baja_bathymetry():
+    "Make sure the data are loaded properly"
+    data = fetch_baja_bathymetry()
+    assert data.size == 248910
+    assert data.shape == (82970, 3)
+    assert all(data.columns == ['longitude', 'latitude', 'bathymetry_m'])