Add sample airborne magnetic data from Rio (fatiando#24)

Use a subsection from the survey to limit file size. Original data are
made freely available by the Geological Survey of Brazil (CPRM) through
their [GEOSGB portal](http://geosgb.cprm.gov.br/).
Adds pandas as a dependency.

Author: leouieda

.codacy.yml

@@ -5,3 +5,4 @@ exclude_paths:
   - '**/__init__.py'
   - '**/tests/**'
   - 'examples/**'
+  - 'data/examples/**'

data/README.md

@@ -15,3 +15,12 @@ These files are used as sample data in Harmonica:
   from the EIGEN-6C4 gravity field model. Both grids were generated by the
   [ICGEM Calculation Service](http://icgem.gfz-potsdam.de). The data are stored in a
   netCDF file and then `xz` compressed using Python's `lzma` library.
+* `rio-magnetic.csv.xz`: Total-field magnetic anomaly data from the northwestern part of
+  an airborne survey of Rio de Janeiro, Brazil, conducted in 1978. Columns are
+  longitude, latitude, total field anomaly (nanoTesla), observation height above the
+  WGS84 ellipsoid (meters), type of flight line (LINE or TIE), and flight line number.
+  The anomaly is calculated with respect to the IGRF field at the center of the survey
+  area at 500 m altitude for the year 1978.3. This dataset was cropped from the original
+  survey, made available by the Geological Survey of Brazil (CPRM) through their [GEOSGB
+  portal](http://geosgb.cprm.gov.br/). See the original data for more processing
+  information.

data/examples/rio_magnetic.py

@@ -0,0 +1,47 @@
+"""
+Total Field Magnetic Anomaly from Rio de Janeiro
+================================================
+
+A subsection from an airborne survey of the state of Rio de Janeiro, Brazil, conducted
+in 1978. The data are stored in a :class:`pandas.DataFrame` with columns: longitude,
+latitude, total field anomaly (nanoTesla), observation height above the WGS84 ellipsoid
+(meters), type of flight line (LINE or TIE), and flight line number. See the
+documentation for :func:`harmonica.datasets.fetch_rio_magnetic` for more information.
+"""
+import matplotlib.pyplot as plt
+import cartopy.crs as ccrs
+import verde as vd
+import harmonica as hm
+
+# Fetch the data in a pandas.DataFrame
+data = hm.datasets.fetch_rio_magnetic()
+print(data)
+
+# Plot the observations in a Mercator map using Cartopy
+fig = plt.figure(figsize=(10, 6))
+ax = plt.axes(projection=ccrs.Mercator())
+ax.set_title("Magnetic data from Rio de Janeiro", pad=25)
+maxabs = vd.maxabs(data.total_field_anomaly_nt)
+tmp = ax.scatter(
+    data.longitude,
+    data.latitude,
+    c=data.total_field_anomaly_nt,
+    s=0.8,
+    cmap="seismic",
+    vmin=-maxabs,
+    vmax=maxabs,
+    transform=ccrs.PlateCarree(),
+)
+plt.colorbar(
+    tmp,
+    ax=ax,
+    label="total field magnetic anomaly [nT]",
+    orientation="horizontal",
+    aspect=50,
+    shrink=0.7,
+    pad=0.06,
+)
+ax.set_extent(vd.get_region((data.longitude, data.latitude)))
+ax.gridlines(draw_labels=True)
+plt.tight_layout()
+plt.show()

data/rio-magnetic.csv.xz

@@ -47,6 +47,7 @@ Datasets
 
     datasets.fetch_gravity_earth
     datasets.fetch_topography_earth
+    datasets.fetch_rio_magnetic
 
 Utilities
 ---------

doc/api/index.rst

@@ -21,9 +21,11 @@ Dependencies
 
 * `numpy <http://www.numpy.org/>`__
 * `scipy <https://docs.scipy.org/doc/scipy/reference/>`__
-* `pooch <http://www.fatiando.org/pooch/>`__
-* `attrs <https://www.attrs.org/>`__
+* `pandas <http://pandas.pydata.org/>`__
 * `xarray <https://xarray.pydata.org/>`__
+* `attrs <https://www.attrs.org/>`__
+* `pooch <http://www.fatiando.org/pooch/>`__
+* `verde <http://www.fatiando.org/verde/>`__
 
 Most of the examples in the :ref:`gallery` also use:
 

doc/install.rst

@@ -7,6 +7,7 @@ dependencies:
     - pip
     - numpy
     - scipy
+    - pandas
     - pooch
     - verde
     - attrs

environment.yml

@@ -1,2 +1,2 @@
 # pylint: disable=missing-docstring
-from .sample_data import fetch_gravity_earth, fetch_topography_earth
+from .sample_data import fetch_gravity_earth, fetch_topography_earth, fetch_rio_magnetic

harmonica/datasets/__init__.py

@@ -1,2 +1,3 @@
 etopo1-0.5deg.nc.xz 9f21f7c946e649389dce28631de94fa05217750e9ebc77df4311458c33f0682b
 gravity-earth-0.5deg.nc.xz 02c62a251225e2e76722a80d87c488160fbdcae2c1a8bbc2386c32e68ea8f43a
+rio-magnetic.csv.xz 134542c1a0c4b89040a4b7d0e52ff55b97e4a3fb7cbda7004a739166897a5eeb

harmonica/datasets/registry.txt

@@ -7,6 +7,7 @@
 import shutil
 
 import xarray as xr
+import pandas as pd
 import pooch
 
 from ..version import full_version
@@ -72,6 +73,41 @@ def fetch_topography_earth():
     return data
 
 
+def fetch_rio_magnetic():
+    """
+    Fetch total-field magnetic anomaly data from Rio de Janeiro, Brazil.
+
+    These data are a subsection of an airborne survey of the state of Rio de Janeiro,
+    Brazil, conducted in 1978. The data are made available by the Geological Survey of
+    Brazil (CPRM) through their `GEOSGB portal <http://geosgb.cprm.gov.br/>`__.
+
+    The columns of the data table are longitude, latitude, total-field magnetic anomaly
+    (nanoTesla), observation height above the WGS84 ellipsoid (in meters), flight line
+    type (LINE or TIE), and flight line number for each data point.
+
+    The anomaly is calculated with respect to the IGRF field parameters listed on the
+    table below. See the original data for more processing information.
+
+    +----------+-----------+----------------+-------------+-------------+
+    |               IGRF for year 1978.3 at 500 m height                |
+    +----------+-----------+----------------+-------------+-------------+
+    | Latitude | Longitude | Intensity (nT) | Declination | Inclination |
+    +==========+===========+================+=============+=============+
+    |  -22º15' |  -42º15'  |     23834      |   -19º19'   |   -27º33'   |
+    +----------+-----------+----------------+-------------+-------------+
+
+    If the file isn't already in your data directory, it will be downloaded
+    automatically.
+
+    Returns
+    -------
+    data : :class:`pandas.DataFrame`
+        The magnetic anomaly data.
+
+    """
+    return pd.read_csv(POOCH.fetch("rio-magnetic.csv.xz"), compression="xz")
+
+
 def _load_xz_compressed_grid(fname, **kwargs):
     """
     Load a netCDF grid that has been xz compressed. Keyword arguments are passed to

harmonica/datasets/sample_data.py

@@ -3,7 +3,11 @@
 """
 import numpy.testing as npt
 
-from ..datasets.sample_data import fetch_gravity_earth, fetch_topography_earth
+from ..datasets.sample_data import (
+    fetch_gravity_earth,
+    fetch_topography_earth,
+    fetch_rio_magnetic,
+)
 
 
 def test_gravity_earth():
@@ -22,3 +26,20 @@ def test_topography_earth():
     assert grid.topography.shape == (361, 721)
     npt.assert_allclose(grid.topography.max(), 5622)
     npt.assert_allclose(grid.topography.min(), -8397)
+
+
+def test_rio_magnetic():
+    "Sanity checks for the loaded dataset"
+    data = fetch_rio_magnetic()
+    assert data.shape == (81796, 6)
+    npt.assert_allclose(data.longitude.min(), -43.199966)
+    npt.assert_allclose(data.longitude.max(), -41.950012)
+    npt.assert_allclose(data.latitude.min(), -22.569992)
+    npt.assert_allclose(data.latitude.max(), -22.050003)
+    npt.assert_allclose(data.total_field_anomaly_nt.min(), -636.180000)
+    npt.assert_allclose(data.total_field_anomaly_nt.max(), 875.120000)
+    npt.assert_allclose(data.altitude_m.min(), 62.180000)
+    npt.assert_allclose(data.altitude_m.max(), 300.000000)
+    npt.assert_allclose(data.line_number.min(), 1680)
+    npt.assert_allclose(data.line_number.max(), 9600)
+    assert set(data.line_type.unique()) == {"TIE", "LINE"}

harmonica/tests/test_sample_data.py

@@ -1,5 +1,6 @@
 numpy
 scipy
+pandas
 pooch
 attrs
 xarray

requirements.txt

@@ -40,7 +40,7 @@
     "harmonica.datasets": ["registry.txt"],
     "harmonica.tests": ["data/*", "baseline/*"],
 }
-INSTALL_REQUIRES = ["numpy", "scipy", "pooch", "attrs", "xarray", "verde"]
+INSTALL_REQUIRES = ["numpy", "scipy", "pandas", "pooch", "attrs", "xarray", "verde"]
 PYTHON_REQUIRES = ">=3.5"
 
 if __name__ == "__main__":