From f0208044577d9cbe8adbf8a518070fcb91641a73 Mon Sep 17 00:00:00 2001 From: Leonardo Uieda Date: Mon, 9 Dec 2019 14:13:23 -0800 Subject: [PATCH] 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 | 11 +++++++++-- examples/trend.py | 35 +++++++++++++++++------------------ verde/datasets/sample_data.py | 30 +++++++++++++++++++++++++++++- 3 files changed, 55 insertions(+), 21 deletions(-) diff --git a/data/examples/rio_magnetic.py b/data/examples/rio_magnetic.py index 839ba6d3c..c8618a43d 100644 --- a/data/examples/rio_magnetic.py +++ b/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 diff --git a/examples/trend.py b/examples/trend.py index 7840d6017..f301150de 100644 --- a/examples/trend.py +++ b/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,27 +37,27 @@ 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") @@ -64,17 +65,15 @@ def plot_data(column, i, title): # 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() diff --git a/verde/datasets/sample_data.py b/verde/datasets/sample_data.py index 0f71085ea..6f975b7b6 100644 --- a/verde/datasets/sample_data.py +++ b/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 - `__. + `__. If the file isn't already in your data directory, it will be downloaded automatically.