.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorials/overview.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note Click :ref:`here ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_tutorials_overview.py: .. _overview: Overview ======== Verde provides classes and functions for processing spatial data, like bathymetry, GPS, temperature, gravity, or anything else that is measured along a surface. The main focus is on methods for gridding such data (interpolating on a regular grid). You'll also find other analysis methods that are often used in combination with gridding, like trend removal and blocked operations. Conventions ----------- Before we get started, here are a few of the conventions we use across Verde: * Coordinates can be Cartesian or Geographic. We generally make no assumptions about which one you're using. * All functions and classes expect coordinates in the order: West-East and South-North. This applies to the actual coordinate values, bounding regions, grid spacing, etc. Exceptions to this rule are the ``dims`` and ``shape`` arguments. * We don't use names like "x" and "y" to avoid ambiguity. Cartesian coordinates are "easting" and "northing" and Geographic coordinates are "longitude" and "latitude". * The term "region" means the bounding box of the data. It is ordered west, east, south, north. The library ----------- Most classes and functions are available through the :mod:`verde` top level package. The only exception is the :mod:`verde.synthetic` module that has functionality for generating synthetic data. Throughout the documentation we'll use ``vd`` as the alias for :mod:`verde`. .. GENERATED FROM PYTHON SOURCE LINES 45-49 .. code-block:: default import matplotlib.pyplot as plt import verde as vd .. GENERATED FROM PYTHON SOURCE LINES 50-70 .. _gridder_interface: The gridder interface --------------------- All gridding and trend estimation classes in Verde share the same interface (they all inherit from :class:`verde.base.BaseGridder`). Since most gridders in Verde are linear models, we based our gridder interface on the `scikit-learn `__ estimator interface: they all implement a :meth:`~verde.base.BaseGridder.fit` method that estimates the model parameters based on data and a :meth:`~verde.base.BaseGridder.predict` method that calculates new data based on the estimated parameters. Unlike scikit-learn, our data model is not a feature matrix and a target vector (e.g., ``est.fit(X, y)``) but a tuple of coordinate arrays and a data vector (e.g., ``grd.fit((easting, northing), data)``). This makes more sense for spatial data and is common to all classes and functions in Verde. As an example, let's generate some synthetic data using :class:`verde.synthetic.CheckerBoard`: .. GENERATED FROM PYTHON SOURCE LINES 70-75 .. code-block:: default data = vd.synthetic.CheckerBoard().scatter(size=500, random_state=0) print(data.head()) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none northing easting scalars 0 -3448.095870 2744.067520 -417.745960 1 -3134.825681 3575.946832 -10.460197 2 -2375.147789 3013.816880 914.277006 3 -1247.024885 2724.415915 -534.571829 4 -3332.462671 2118.273997 407.865799 .. GENERATED FROM PYTHON SOURCE LINES 76-78 The data are random points taken from a checkerboard function and returned to us in a :class:`pandas.DataFrame`: .. GENERATED FROM PYTHON SOURCE LINES 78-84 .. code-block:: default plt.figure() plt.scatter(data.easting, data.northing, c=data.scalars, cmap="RdBu_r") plt.colorbar() plt.show() .. image-sg:: /tutorials/images/sphx_glr_overview_001.png :alt: overview :srcset: /tutorials/images/sphx_glr_overview_001.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 85-87 Now we can use the bi-harmonic spline method [Sandwell1987]_ to fit this data. First, we create a new :class:`verde.Spline`: .. GENERATED FROM PYTHON SOURCE LINES 87-92 .. code-block:: default spline = vd.Spline() # Printing a gridder shows the class and all of it's configuration options. print(spline) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none Spline() .. GENERATED FROM PYTHON SOURCE LINES 93-95 Before we can use the spline, we need to fit it to our synthetic data. After that, we can use the spline to predict values anywhere: .. GENERATED FROM PYTHON SOURCE LINES 95-108 .. code-block:: default spline.fit((data.easting, data.northing), data.scalars) # Generate coordinates for a regular grid with 100 m grid spacing (assuming # coordinates are in meters). grid_coords = vd.grid_coordinates(region=(0, 5000, -5000, 0), spacing=100) gridded_scalars = spline.predict(grid_coords) plt.figure() plt.pcolormesh(grid_coords[0], grid_coords[1], gridded_scalars, cmap="RdBu_r") plt.colorbar() plt.show() .. image-sg:: /tutorials/images/sphx_glr_overview_002.png :alt: overview :srcset: /tutorials/images/sphx_glr_overview_002.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 109-113 We can compare our predictions with the true values for the checkerboard function using the :meth:`~verde.Spline.score` method to calculate the `R² coefficient of determination `__. .. GENERATED FROM PYTHON SOURCE LINES 113-117 .. code-block:: default true_values = vd.synthetic.CheckerBoard().predict(grid_coords) print(spline.score(grid_coords, true_values)) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none /usr/share/miniconda3/envs/test/lib/python3.9/site-packages/verde/base/base_classes.py:359: FutureWarning: The default scoring will change from R² to negative root mean squared error (RMSE) in Verde 2.0.0. This may change model selection results slightly. warnings.warn( 0.9950450871662572 .. GENERATED FROM PYTHON SOURCE LINES 118-124 Generating grids and profiles ----------------------------- A more convenient way of generating grids is through the :meth:`~verde.base.BaseGridder.grid` method. It will automatically generate coordinates and output an :class:`xarray.Dataset`. .. GENERATED FROM PYTHON SOURCE LINES 124-128 .. code-block:: default grid = spline.grid(spacing=30) print(grid) .. rst-class:: sphx-glr-script-out Out: .. code-block:: none /usr/share/miniconda3/envs/test/lib/python3.9/site-packages/verde/base/base_classes.py:463: FutureWarning: The 'spacing', 'shape' and 'region' arguments will be removed in Verde v2.0.0. Please use the 'verde.grid_coordinates' function to define grid coordinates and pass them as the 'coordinates' argument. warnings.warn( Dimensions: (northing: 168, easting: 167) Coordinates: * easting (easting) float64 23.48 53.42 83.37 ... 4.964e+03 4.994e+03 * northing (northing) float64 -4.997e+03 -4.967e+03 ... -30.88 -0.9571 Data variables: scalars (northing, easting) float64 495.6 521.3 549.0 ... -184.7 -139.6 Attributes: metadata: Generated by Spline() .. GENERATED FROM PYTHON SOURCE LINES 129-132 :meth:`~verde.base.BaseGridder.grid` uses default names for the coordinates ("easting" and "northing") and data variables ("scalars"). You can overwrite these names by setting the ``dims`` and ``data_names`` arguments. .. GENERATED FROM PYTHON SOURCE LINES 132-140 .. code-block:: default grid = spline.grid(spacing=30, dims=["latitude", "longitude"], data_names="gravity") print(grid) plt.figure() grid.gravity.plot.pcolormesh() plt.show() .. image-sg:: /tutorials/images/sphx_glr_overview_003.png :alt: overview :srcset: /tutorials/images/sphx_glr_overview_003.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out Out: .. code-block:: none /usr/share/miniconda3/envs/test/lib/python3.9/site-packages/verde/base/base_classes.py:463: FutureWarning: The 'spacing', 'shape' and 'region' arguments will be removed in Verde v2.0.0. Please use the 'verde.grid_coordinates' function to define grid coordinates and pass them as the 'coordinates' argument. warnings.warn( Dimensions: (latitude: 168, longitude: 167) Coordinates: * longitude (longitude) float64 23.48 53.42 83.37 ... 4.964e+03 4.994e+03 * latitude (latitude) float64 -4.997e+03 -4.967e+03 ... -30.88 -0.9571 Data variables: gravity (latitude, longitude) float64 495.6 521.3 549.0 ... -184.7 -139.6 Attributes: metadata: Generated by Spline() .. GENERATED FROM PYTHON SOURCE LINES 141-144 Gridders can also be used to interpolate data on a straight line between two points using the :meth:`~verde.base.BaseGridder.profile` method. The profile data are returned as a :class:`pandas.DataFrame`. .. GENERATED FROM PYTHON SOURCE LINES 144-153 .. code-block:: default prof = spline.profile(point1=(0, 0), point2=(5000, -5000), size=200) print(prof.head()) plt.figure() plt.plot(prof.distance, prof.scalars, "-") plt.show() .. image-sg:: /tutorials/images/sphx_glr_overview_004.png :alt: overview :srcset: /tutorials/images/sphx_glr_overview_004.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out Out: .. code-block:: none northing easting distance scalars 0 0.000000 0.000000 0.000000 66.785376 1 -25.125628 25.125628 35.533004 92.895113 2 -50.251256 50.251256 71.066008 124.644012 3 -75.376884 75.376884 106.599012 163.870392 4 -100.502513 100.502513 142.132016 209.836541 .. GENERATED FROM PYTHON SOURCE LINES 154-165 Wrap up ------- This covers the basics of using Verde. Most use cases and examples in the documentation will involve some variation of the following workflow: 1. Load data (coordinates and data values) 2. Create a gridder 3. Fit the gridder to the data 4. Predict new values (using :meth:`~verde.base.BaseGridder.predict` or :meth:`~verde.base.BaseGridder.grid`) .. rst-class:: sphx-glr-timing **Total running time of the script:** ( 0 minutes 0.841 seconds) .. _sphx_glr_download_tutorials_overview.py: .. only :: html .. container:: sphx-glr-footer :class: sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: overview.py ` .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: overview.ipynb ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_