notebooks/bmi_dbseabed.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://github.com/gantian127/bmi_dbseabed/blob/master/docs/source/_static/bmi_dbseabed_logo.png?raw=true\" width='600' align='center'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quick Start Tutorial "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook will help you get started using the bmi_dbseabed package to download the dbSEABED marine substrates datasets. \n",
    "\n",
    "This tutorial includes the following sections:\n",
    "\n",
    "1. [Brief Introduction](#section1)\n",
    "\n",
    "   This section provides basic information about bmi_dbseabed package. \n",
    "   <br>\n",
    "   \n",
    "2. [Start with Examples](#section2)\n",
    "   \n",
    "   This section provides two examples to demonstrate how to use bmi_dbseabed to download datasets for visualization.\n",
    "   <br>\n",
    "   \n",
    "**Suggested citation**: Gan, T. (2024). Jupyter Notebooks for the dbSEABED Data Component, HydroShare, https://www.hydroshare.org/resource/e43626941b054b84828e3717d58a6f1a/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='section1'></a>\n",
    "## 1. Brief Introduction\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "bmi_dbseabed package provides a set of functions that allows downloading of the datasets from [dbSEABED](https://instaar.colorado.edu/~jenkinsc/dbseabed/), a system for marine substrates datasets across the globe. This system uses very large amounts of diverse observational data and applies math methods to integrate/harmonize those and produces gridded data on the major properties of the seabed. The scope is the global ocean and across all depth zones.\n",
    "\n",
    "The current page serves only the data for the Gulf of Mexico region. An overview of the entire collection of data is available at\n",
    "[this webpage](https://csdms.colorado.edu/wiki/Data:DBSEABED). Please note that the data will be updated from time to time, approximately annually.\n",
    "\n",
    "bmi_dbseabed package also includes a Basic Model Interface ([BMI](https://bmi.readthedocs.io/en/latest/)), which converts the dbSEABED dataset into a reusable, plug-and-play data component for [PyMT](https://pymt.readthedocs.io/en/latest/?badge=latest) modeling framework developed by Community Surface Dynamics Modeling System ([CSDMS](https://csdms.colorado.edu/wiki/Main_Page)). \n",
    "\n",
    "\n",
    "To install bmi_dbseabed package, please follow the instructions [here](https://github.com/gantian127/bmi_dbseabed/tree/master?tab=readme-ov-file#install-package)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='section2'></a>\n",
    "## 2. Start with Examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In bmi_dbseabed package, DbSeabed class is designed for users to download datasets. BmiDbSeabed class is designed to convert the dbSEABED dataset as a data component for the [PyMT](https://pymt.readthedocs.io/en/latest/?badge=latest) modeling framework. The following examples demonstrate how to download the same dataset using DbSeabed and BmiDbSeabed for data visualization. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 1: use DbSeabed class to download data (Recommended method)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import DbSeabed class and download data with **get_data( )** method. You can check the details of the [parameter settings](https://bmi-dbseabed.readthedocs.io/en/latest/#parameter-settings) for get_data( ) method to better understand the parameter values used in the example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from bmi_dbseabed import DbSeabed\n",
    "\n",
    "# get data from dbSEABED\n",
    "dbseabed = DbSeabed()\n",
    "data = dbseabed.get_data(\n",
    "    var_name=\"carbonate\",\n",
    "    west=-98,\n",
    "    south=18,\n",
    "    east=-80,\n",
    "    north=31,\n",
    "    output=\"download.tif\",\n",
    "    local_file=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To know the metadata of the dataset, you can check the \"metadata\" attributes. The downloaded dataset is stored in a GeoTiff file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# show metadata\n",
    "for key, value in dbseabed.metadata.items():\n",
    "    print(f\"{key}: {value}\\n\")\n",
    "\n",
    "# show GeoTiff file path\n",
    "print(f\"file path: {dbseabed.tif_file}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dbSEABED dataset is loaded as a DataArray object (xarray). You can directly plot the data using its plot( ) method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# plot data\n",
    "data.plot(figsize=(9, 5))\n",
    "plt.title(\"dbSEABED dataset (Carbonate in %)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Aside from the \"carbonate\" dataset shown above, there are multiple datasets available from dbSEABED. You can check the **data_services** attributes to learn more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# list all the available data services\n",
    "dbseabed.data_services"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 2: use BmiDbSeabed class to download data (Demonstration of how to use BMI)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import BmiDbSeabed class and instantiate it. A configuration file (yaml file) is required to provide the parameter settings for data download. An example configure_file.yaml file is provided in the same folder with this Jupyter Notebook file. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "from bmi_dbseabed import BmiDbSeabed\n",
    "\n",
    "# initiate a data component\n",
    "data_comp = BmiDbSeabed()\n",
    "data_comp.initialize(\"config_file.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use variable related methods from BmiDbSeabed class to check the variable information of the dataset. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable info\n",
    "var_name = data_comp.get_output_var_names()[0]\n",
    "var_unit = data_comp.get_var_units(var_name)\n",
    "var_location = data_comp.get_var_location(var_name)\n",
    "var_type = data_comp.get_var_type(var_name)\n",
    "var_grid = data_comp.get_var_grid(var_name)\n",
    "\n",
    "print(f\"{var_name=} \\n{var_unit=} \\n{var_location=} \\n{var_type=} \\n{var_grid=}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use grid related methods of BmiDbSeabed class to check the grid information of the dataset. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable grid info\n",
    "grid_rank = data_comp.get_grid_rank(var_grid)\n",
    "\n",
    "grid_size = data_comp.get_grid_size(var_grid)\n",
    "\n",
    "grid_shape = np.empty(grid_rank, int)\n",
    "data_comp.get_grid_shape(var_grid, grid_shape)\n",
    "\n",
    "grid_spacing = np.empty(grid_rank)\n",
    "data_comp.get_grid_spacing(var_grid, grid_spacing)\n",
    "\n",
    "grid_origin = np.empty(grid_rank)\n",
    "data_comp.get_grid_origin(var_grid, grid_origin)\n",
    "\n",
    "print(f\"{grid_rank=} \\n{grid_size=} \\n{grid_shape=} \\n{grid_spacing=} \\n{grid_origin=}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use get_value( ) method to get the data as a numpy 2D array. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable data\n",
    "data = np.empty(grid_size, var_type)\n",
    "data_comp.get_value(var_name, data)\n",
    "data_2D = data.reshape(grid_shape)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get X, Y extent for plot\n",
    "min_y, min_x = grid_origin\n",
    "max_y = min_y + grid_spacing[0] * (grid_shape[0] - 1)\n",
    "max_x = min_x + grid_spacing[1] * (grid_shape[1] - 1)\n",
    "dy = grid_spacing[0] / 2\n",
    "dx = grid_spacing[1] / 2\n",
    "extent = [min_x - dx, max_x + dx, min_y - dy, max_y + dy]\n",
    "\n",
    "# plot data\n",
    "fig, ax = plt.subplots(1, 1, figsize=(9, 5))\n",
    "im = ax.imshow(data_2D, extent=extent)\n",
    "fig.colorbar(im)\n",
    "plt.xlabel(\"X\")\n",
    "plt.ylabel(\"Y\")\n",
    "plt.title(\"dbSEABED dataset (Carbonate in %)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Complete the example by finalizing the component. finalize( ) method performs tasks that take place after using the data component, such as deallocating memory and closing files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_comp.finalize()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}