Add deprecation warning for Rio sample data (#213)

Licensing for the dataset is unclear it's best to remove it. We'll
deprecate first and then remove in a future major release. Add warnings
to the docstrings and sample data example. Replace the Rio data with
Texas wind in the Trend gallery example (it's already used in the trend
estimation tutorial). See #201 for more context.

data/examples/rio_magnetic.py

@@ -1,6 +1,13 @@
 """
-Magnetic data from Rio de Janeiro
-=================================
+[DEPRECATED] Magnetic data from Rio de Janeiro
+==============================================
+
+.. warning::
+
+    **The Rio magnetic anomaly dataset is deprecated and will be removed in
+    Verde v2.0.0** (functions :func:`verde.datasets.fetch_rio_magnetic` and
+    :func:`verde.datasets.setup_rio_magnetic_map`). Please use another dataset
+    instead.
 
 We provide sample total-field magnetic anomaly data from an airborne survey of Rio de
 Janeiro, Brazil, from the 1970s. The data are made available by the Geological Survey of

examples/trend.py

@@ -5,26 +5,27 @@
 Verde offers the :class:`verde.Trend` class to fit a 2D polynomial trend to your data.
 This can be useful for isolating a regional component of your data, for example, which
 is a common operation for gravity and magnetic data. Let's look at how we can use Verde
-to remove the clear positive trend from the Rio de Janeiro magnetic anomaly data.
+to remove the clear trend from our Texas temperature dataset
+(:func:`verde.datasets.fetch_texas_wind`).
 """
 import numpy as np
 import matplotlib.pyplot as plt
 import cartopy.crs as ccrs
 import verde as vd
 
-# Load the Rio de Janeiro total field magnetic anomaly data as a pandas.DataFrame
-data = vd.datasets.fetch_rio_magnetic()
+# Load the Texas wind and temperature data as a pandas.DataFrame
+data = vd.datasets.fetch_texas_wind()
 print("Original data:")
 print(data.head())
 
-# Fit a 2nd degree 2D polynomial to the anomaly data
+# Fit a 1st degree 2D polynomial to the data
 coordinates = (data.longitude, data.latitude)
-trend = vd.Trend(degree=2).fit(coordinates, data.total_field_anomaly_nt)
+trend = vd.Trend(degree=1).fit(coordinates, data.air_temperature_c)
 print("\nTrend estimator:", trend)
 
 # Add the estimated trend and the residual data to the DataFrame
 data["trend"] = trend.predict(coordinates)
-data["residual"] = data.total_field_anomaly_nt - data.trend
+data["residual"] = data.air_temperature_c - data.trend
 print("\nUpdated DataFrame:")
 print(data.head())
 
@@ -36,45 +37,43 @@ def plot_data(column, i, title):
     ax = plt.subplot(2, 2, i, projection=ccrs.Mercator())
     ax.set_title(title)
     # Set vmin and vmax to the extremes of the original data
-    maxabs = vd.maxabs(data.total_field_anomaly_nt)
+    maxabs = vd.maxabs(data.air_temperature_c)
     mappable = ax.scatter(
         data.longitude,
         data.latitude,
         c=data[column],
-        s=1,
+        s=50,
         cmap="seismic",
         vmin=-maxabs,
         vmax=maxabs,
         transform=crs,
     )
     # Set the proper ticks for a Cartopy map
-    vd.datasets.setup_rio_magnetic_map(ax)
+    vd.datasets.setup_texas_wind_map(ax)
     return mappable
 
 
-plt.figure(figsize=(9, 8))
+plt.figure(figsize=(10, 9.5))
 
 # Plot the data fields and capture the mappable returned by scatter to use for
 # the colorbar
-mappable = plot_data("total_field_anomaly_nt", 1, "Original magnetic anomaly")
+mappable = plot_data("air_temperature_c", 1, "Original data")
 plot_data("trend", 2, "Regional trend")
 plot_data("residual", 3, "Residual")
 
 # Make histograms of the data and the residuals to show that the trend was
 # removed
 ax = plt.subplot(2, 2, 4)
 ax.set_title("Distribution of data")
-ax.hist(data.total_field_anomaly_nt, bins="auto", alpha=0.7, label="Original data")
+ax.hist(data.air_temperature_c, bins="auto", alpha=0.7, label="Original data")
 ax.hist(data.residual, bins="auto", alpha=0.7, label="Residuals")
 ax.legend()
-ax.set_xlabel("Total field anomaly (nT)")
+ax.set_xlabel("Air temperature (C)")
 
 # Add a single colorbar on top of the histogram plot where there is some space
-cax = plt.axes((0.58, 0.44, 0.18, 0.015))
-cb = plt.colorbar(
-    mappable, cax=cax, orientation="horizontal", ticks=np.arange(-800, 801, 400)
-)
-cb.set_label("nT")
+cax = plt.axes((0.35, 0.44, 0.10, 0.01))
+cb = plt.colorbar(mappable, cax=cax, orientation="horizontal",)
+cb.set_label("C")
 
 plt.tight_layout()
 plt.show()

verde/datasets/sample_data.py

@@ -2,6 +2,7 @@
 Functions to load sample data
 """
 import os
+import warnings
 
 import numpy as np
 import pandas as pd
@@ -17,6 +18,9 @@
 from ..version import full_version
 
 
+# Otherwise, DeprecationWarning won't be shown, kind of defeating the purpose.
+warnings.simplefilter("default")
+
 POOCH = pooch.create(
     path=["~", ".verde", "data"],
     base_url="https://github.com/fatiando/verde/raw/{version}/data/",
@@ -113,6 +117,13 @@ def fetch_rio_magnetic():
     """
     Fetch total-field magnetic anomaly data from Rio de Janeiro, Brazil.
 
+    .. warning::
+
+        **The Rio magnetic anomaly dataset is deprecated and will be removed in
+        Verde v2.0.0** (functions :func:`verde.datasets.fetch_rio_magnetic` and
+        :func:`verde.datasets.setup_rio_magnetic_map`). Please use another
+        dataset instead.
+
     These data were cropped from the northwestern part of an airborne survey of
     Rio de Janeiro, Brazil, conducted in 1978. The data are made available by
     the Geological Survey of Brazil (CPRM) through their `GEOSGB portal
@@ -145,6 +156,11 @@ def fetch_rio_magnetic():
     setup_rio_magnetic_map: Utility function to help setup a Cartopy map.
 
     """
+    warnings.warn(
+        "The Rio magnetic anomaly dataset is deprecated and will be removed "
+        "in Verde v2.0.0. Use a different dataset instead.",
+        DeprecationWarning,
+    )
     data_file = POOCH.fetch("rio-magnetic.csv.xz")
     data = pd.read_csv(data_file, compression="xz")
     return data
@@ -154,6 +170,13 @@ def setup_rio_magnetic_map(ax, region=(-42.6, -42, -22.5, -22)):
     """
     Setup a Cartopy map for the Rio de Janeiro magnetic anomaly dataset.
 
+    .. warning::
+
+        **The Rio magnetic anomaly dataset is deprecated and will be removed in
+        Verde v2.0.0** (functions :func:`verde.datasets.fetch_rio_magnetic` and
+        :func:`verde.datasets.setup_rio_magnetic_map`). Please use another
+        dataset instead.
+
     Parameters
     ----------
     ax : matplotlib Axes
@@ -170,6 +193,11 @@ def setup_rio_magnetic_map(ax, region=(-42.6, -42, -22.5, -22)):
     fetch_rio_magnetic: Magnetic anomaly data from Rio de Janeiro, Brazil.
 
     """
+    warnings.warn(
+        "The Rio magnetic anomaly dataset is deprecated and will be removed "
+        "in Verde v2.0.0. Use a different dataset instead.",
+        DeprecationWarning,
+    )
     _setup_map(
         ax,
         xticks=np.arange(-42.5, -42, 0.1),
@@ -256,7 +284,7 @@ def fetch_texas_wind():
 
     Data are average wind speed and air temperature for data for February 26
     2018. The original data was downloaded from `Iowa State University
-              <https://mesonet.agron.iastate.edu/request/download.phtml>`__.
+    <https://mesonet.agron.iastate.edu/request/download.phtml>`__.
 
     If the file isn't already in your data directory, it will be downloaded
     automatically.