diff --git a/doc/api/index.rst b/doc/api/index.rst index 685ee963862..3ed783430eb 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -210,8 +210,10 @@ and store them in the GMT cache folder. .. autosummary:: :toctree: generated + datasets.list_sample_data datasets.load_earth_age datasets.load_earth_relief + datasets.load_sample_data datasets.load_fractures_compilation datasets.load_hotspots datasets.load_japan_quakes diff --git a/pygmt/datasets/__init__.py b/pygmt/datasets/__init__.py index 298e054907e..93b7210a73e 100644 --- a/pygmt/datasets/__init__.py +++ b/pygmt/datasets/__init__.py @@ -5,11 +5,13 @@ from pygmt.datasets.earth_age import load_earth_age from pygmt.datasets.earth_relief import load_earth_relief from pygmt.datasets.samples import ( + list_sample_data, load_fractures_compilation, load_hotspots, load_japan_quakes, load_mars_shape, load_ocean_ridge_points, load_sample_bathymetry, + load_sample_data, load_usgs_quakes, ) diff --git a/pygmt/datasets/samples.py b/pygmt/datasets/samples.py index daf89014f06..bd0006f0c44 100644 --- a/pygmt/datasets/samples.py +++ b/pygmt/datasets/samples.py @@ -1,13 +1,91 @@ """ Functions to load sample data. """ +import warnings + import pandas as pd +from pygmt.exceptions import GMTInvalidInput from pygmt.src import which -def load_japan_quakes(): +def list_sample_data(): + """ + Report datasets available for tests and documentation examples. + + Returns + ------- + dict + Names and short descriptions of available sample datasets. + + See Also + -------- + load_sample_data : Load an example dataset from the GMT server. """ - Load a table of earthquakes around Japan as a pandas.DataFrame. + names = { + "bathymetry": "Table of ship bathymetric observations off Baja California", + "fractures": "Table of hypothetical fracture lengths and azimuths", + "hotspots": "Table of locations, names, and symbol sizes of hotpots from " + " Mueller et al., 1993", + "japan_quakes": "Table of earthquakes around Japan from NOAA NGDC database", + "mars_shape": "Table of topographic signature of the hemispheric dichotomy of " + " Mars from Smith and Zuber (1996)", + "ocean_ridge_points": "Table of ocean ridge points for the entire world", + "usgs_quakes": "Table of global earthquakes from the USGS", + } + return names + + +def load_sample_data(name): + """ + Load an example dataset from the GMT server. + + The data are downloaded to a cache directory (usually ``~/.gmt/cache``) the + first time you invoke this function. Afterwards, it will load the data from + the cache. So you'll need an internet connection the first time around. + + Parameters + ---------- + name : str + Name of the dataset to load. + + Returns + ------- + :class:`pandas.DataFrame` or :class:`xarray.DataArray` + Sample dataset loaded as a pandas.DataFrame for tabular data or + xarray.DataArray for raster data. + + See Also + -------- + list_sample_data : Report datasets available for tests and documentation + examples. + """ + names = list_sample_data() + if name not in names: + raise GMTInvalidInput(f"Invalid dataset name '{name}'.") + + load_func = { + "bathymetry": load_sample_bathymetry, + "fractures": load_fractures_compilation, + "hotspots": load_hotspots, + "japan_quakes": load_japan_quakes, + "mars_shape": load_mars_shape, + "ocean_ridge_points": load_ocean_ridge_points, + "usgs_quakes": load_usgs_quakes, + } + + data = load_func[name](suppress_warning=True) + + return data + + +def load_japan_quakes(**kwargs): + """ + (Deprecated) Load a table of earthquakes around Japan as a + pandas.DataFrame. + + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="japan_quakes")`` and will be removed in + v0.9.0. Data is from the NOAA NGDC database. This is the ``@tut_quakes.ngdc`` dataset used in the GMT tutorials. @@ -22,6 +100,16 @@ def load_japan_quakes(): The data table. Columns are year, month, day, latitude, longitude, depth (in km), and magnitude of the earthquakes. """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be " + "removed in v0.9.0. Please use " + "load_sample_data(name='japan_quakes') instead.", + category=FutureWarning, + stacklevel=2, + ) + fname = which("@tut_quakes.ngdc", download="c") data = pd.read_csv(fname, header=1, sep=r"\s+") data.columns = [ @@ -33,14 +121,19 @@ def load_japan_quakes(): "depth_km", "magnitude", ] + return data -def load_ocean_ridge_points(): +def load_ocean_ridge_points(**kwargs): """ - Load a table of ocean ridge points for the entire world as a + (Deprecated) Load a table of ocean ridge points for the entire world as a pandas.DataFrame. + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="ocean_ridge_points")`` and will be removed in + v0.9.0. + This is the ``@ridge.txt`` dataset used in the GMT tutorials. The data are downloaded to a cache directory (usually ``~/.gmt/cache``) the @@ -52,6 +145,16 @@ def load_ocean_ridge_points(): data : pandas.DataFrame The data table. Columns are longitude and latitude. """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be removed " + "in v0.9.0. Please use load_sample_data(name='ocean_ridge_points') " + "instead.", + category=FutureWarning, + stacklevel=2, + ) + fname = which("@ridge.txt", download="c") data = pd.read_csv( fname, sep=r"\s+", names=["longitude", "latitude"], skiprows=1, comment=">" @@ -59,10 +162,14 @@ def load_ocean_ridge_points(): return data -def load_sample_bathymetry(): +def load_sample_bathymetry(**kwargs): """ - Load a table of ship observations of bathymetry off Baja California as a - pandas.DataFrame. + (Deprecated) Load a table of ship observations of bathymetry off Baja + California as a pandas.DataFrame. + + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="bathymetry")`` and will be removed in + v0.9.0. This is the ``@tut_ship.xyz`` dataset used in the GMT tutorials. @@ -75,6 +182,15 @@ def load_sample_bathymetry(): data : pandas.DataFrame The data table. Columns are longitude, latitude, and bathymetry. """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be " + "removed in v0.9.0. Please use " + "load_sample_data(name='bathymetry') instead.", + category=FutureWarning, + stacklevel=2, + ) fname = which("@tut_ship.xyz", download="c") data = pd.read_csv( fname, sep="\t", header=None, names=["longitude", "latitude", "bathymetry"] @@ -82,9 +198,14 @@ def load_sample_bathymetry(): return data -def load_usgs_quakes(): +def load_usgs_quakes(**kwargs): """ - Load a table of global earthquakes form the USGS as a pandas.DataFrame. + (Deprecated) Load a table of global earthquakes from the USGS as a + pandas.DataFrame. + + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="usgs_quakes")`` and will be removed in + v0.9.0. This is the ``@usgs_quakes_22.txt`` dataset used in the GMT tutorials. @@ -98,15 +219,28 @@ def load_usgs_quakes(): The data table. Use ``print(data.describe())`` to see the available columns. """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be " + "removed in v0.9.0. Please use " + "load_sample_data(name='usgs_quakes') instead.", + category=FutureWarning, + stacklevel=2, + ) fname = which("@usgs_quakes_22.txt", download="c") data = pd.read_csv(fname) return data -def load_fractures_compilation(): +def load_fractures_compilation(**kwargs): """ - Load a table of fracture lengths and azimuths as hypothetically digitized - from geological maps as a pandas.DataFrame. + (Deprecated) Load a table of fracture lengths and azimuths as + hypothetically digitized from geological maps as a pandas.DataFrame. + + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="fractures")`` and will be removed in + v0.9.0. This is the ``@fractures_06.txt`` dataset used in the GMT tutorials. @@ -120,15 +254,28 @@ def load_fractures_compilation(): The data table. Use ``print(data.describe())`` to see the available columns. """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be " + "removed in v0.9.0. Please use " + "load_sample_data(name='fractures') instead.", + category=FutureWarning, + stacklevel=2, + ) fname = which("@fractures_06.txt", download="c") data = pd.read_csv(fname, header=None, sep=r"\s+", names=["azimuth", "length"]) return data[["length", "azimuth"]] -def load_hotspots(): +def load_hotspots(**kwargs): """ - Load a table with the locations, names, and suggested symbol sizes of - hotspots. + (Deprecated) Load a table with the locations, names, and suggested symbol + sizes of hotspots. + + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="hotspots")`` and will be removed in + v0.9.0. This is the ``@hotspots.txt`` dataset used in the GMT tutorials, with data from Mueller, Royer, and Lawver, 1993, Geology, vol. 21, pp. 275-278. The @@ -145,15 +292,28 @@ def load_hotspots(): The data table with columns "longitude", "latitude", "symbol_size", and "placename". """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be " + "removed in v0.9.0. Please use " + "load_sample_data(name='hotspots') instead.", + category=FutureWarning, + stacklevel=2, + ) fname = which("@hotspots.txt", download="c") columns = ["longitude", "latitude", "symbol_size", "place_name"] data = pd.read_table(filepath_or_buffer=fname, sep="\t", skiprows=3, names=columns) return data -def load_mars_shape(): +def load_mars_shape(**kwargs): """ - Load a table of data for the shape of Mars. + (Deprecated) Load a table of data for the shape of Mars. + + .. warning:: Deprecated since v0.6.0. This function has been replaced with + ``load_sample_data(name="mars_shape")`` and will be removed in + v0.9.0. This is the ``@mars370d.txt`` dataset used in GMT examples, with data and information from Smith, D. E., and M. T. Zuber (1996), The shape of Mars @@ -169,6 +329,15 @@ def load_mars_shape(): data : pandas.DataFrame The data table with columns "longitude", "latitude", and "radius(m)". """ + + if "suppress_warning" not in kwargs: + warnings.warn( + "This function has been deprecated since v0.6.0 and will be " + "removed in v0.9.0. Please use " + "load_sample_data(name='mars_shape') instead.", + category=FutureWarning, + stacklevel=2, + ) fname = which("@mars370d.txt", download="c") data = pd.read_csv( fname, sep="\t", header=None, names=["longitude", "latitude", "radius(m)"] diff --git a/pygmt/tests/test_datasets_samples.py b/pygmt/tests/test_datasets_samples.py index 1a52a3da2f3..d2859a2c15c 100644 --- a/pygmt/tests/test_datasets_samples.py +++ b/pygmt/tests/test_datasets_samples.py @@ -2,6 +2,7 @@ Test basic functionality for loading sample datasets. """ import pandas as pd +import pytest from pygmt.datasets import ( load_fractures_compilation, load_hotspots, @@ -9,15 +10,42 @@ load_mars_shape, load_ocean_ridge_points, load_sample_bathymetry, + load_sample_data, load_usgs_quakes, ) +from pygmt.exceptions import GMTInvalidInput + + +def test_load_sample_invalid(): + """ + Check that the function raises error for unsupported filenames. + """ + with pytest.raises(GMTInvalidInput): + load_sample_data(name="bad.filename") def test_japan_quakes(): """ Check that the dataset loads without errors. """ - data = load_japan_quakes() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_japan_quakes() + assert len(record) == 1 + assert data.shape == (115, 7) + summary = data.describe() + assert summary.loc["min", "year"] == 1987 + assert summary.loc["max", "year"] == 1988 + assert summary.loc["min", "month"] == 1 + assert summary.loc["max", "month"] == 12 + assert summary.loc["min", "day"] == 1 + assert summary.loc["max", "day"] == 31 + + +def test_load_sample_data(): + """ + Check that the dataset loads without errors. + """ + data = load_sample_data(name="japan_quakes") assert data.shape == (115, 7) summary = data.describe() assert summary.loc["min", "year"] == 1987 @@ -32,7 +60,9 @@ def test_ocean_ridge_points(): """ Check that the @ridge.txt dataset loads without errors. """ - data = load_ocean_ridge_points() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_ocean_ridge_points() + assert len(record) == 1 assert data.shape == (4146, 2) summary = data.describe() assert summary.loc["min", "longitude"] == -179.9401 @@ -45,7 +75,9 @@ def test_sample_bathymetry(): """ Check that the @tut_ship.xyz dataset loads without errors. """ - data = load_sample_bathymetry() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_sample_bathymetry() + assert len(record) == 1 assert data.shape == (82970, 3) summary = data.describe() assert summary.loc["min", "longitude"] == 245.0 @@ -60,7 +92,9 @@ def test_usgs_quakes(): """ Check that the dataset loads without errors. """ - data = load_usgs_quakes() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_usgs_quakes() + assert len(record) == 1 assert data.shape == (1197, 22) @@ -68,7 +102,9 @@ def test_fractures_compilation(): """ Check that the @fractures_06.txt dataset loads without errors. """ - data = load_fractures_compilation() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_fractures_compilation() + assert len(record) == 1 assert data.shape == (361, 2) summary = data.describe() assert summary.loc["min", "length"] == 98.6561 @@ -81,7 +117,9 @@ def test_mars_shape(): """ Check that the @mars370d.txt dataset loads without errors. """ - data = load_mars_shape() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_mars_shape() + assert len(record) == 1 assert data.shape == (370, 3) summary = data.describe() assert summary.loc["min", "longitude"] == 0.008 @@ -96,7 +134,9 @@ def test_hotspots(): """ Check that the @hotspots.txt dataset loads without errors. """ - data = load_hotspots() + with pytest.warns(expected_warning=FutureWarning) as record: + data = load_hotspots() + assert len(record) == 1 assert data.shape == (55, 4) assert data.columns.values.tolist() == [ "longitude",