notebooks/pymt_dbseabed.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "persistent-worst",
   "metadata": {},
   "source": [
    "<img src=\"https://github.com/gantian127/pymt_dbseabed/blob/master/docs/_static/logo.png?raw=true\" width='600' align='center'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "political-argentina",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "increasing-cooper",
   "metadata": {},
   "source": [
    "[pymt_dbseabed](https://github.com/gantian127/pymt_dbseabed) is a package that uses the [bmi_dbseabed](https://github.com/gantian127/bmi_dbseabed) pacakge to convert [dbSEABED](https://instaar.colorado.edu/~jenkinsc/dbseabed/) datasets into a reusable, plug-and-play data component for PyMT modeling framework developed by Community Surface Dynamics Modeling System ([CSDMS](https://csdms.colorado.edu/wiki/Main_Page)). This allows dbSEABED datasets to be easily coupled with other datasets or models that expose a Basic Model Interface.\n",
    "\n",
    "To install pymt_dbseabed, please follow the instructions [here](https://github.com/gantian127/pymt_dbseabed#pymt_dbseabed).\n",
    "\n",
    "Suggested citation: Gan, T. (2024). Jupyter Notebooks for the dbSEABED Data Component, HydroShare, https://www.hydroshare.org/resource/e43626941b054b84828e3717d58a6f1a/"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "thermal-lodge",
   "metadata": {},
   "source": [
    "## Coding Example"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3ffcc219",
   "metadata": {},
   "source": [
    "Import DbSeabedData class and instantiate it. A configuration file (yaml file) is required to provide the parameter settings for data download. An example yaml file is provided in the same folder with this Jupyter Notebook. For more details of the parameters specified in the configuration file, please check with the [link](https://bmi-dbseabed.readthedocs.io/en/latest/#parameter-settings) here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "secret-briefing",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "from pymt.models import DbSeabedData\n",
    "\n",
    "# initiate a data component\n",
    "data_comp = DbSeabedData()\n",
    "data_comp.initialize('config_file.yaml')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffb55d03-145f-4880-910d-d1d18e281984",
   "metadata": {},
   "source": [
    "Let's look at the contents in this configuration file. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43889844",
   "metadata": {},
   "outputs": [],
   "source": [
    "!cat config_file.yaml"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "comic-shannon",
   "metadata": {},
   "source": [
    "Use variable related methods to check the variable information of the dbSEABED dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dedicated-receipt",
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable info\n",
    "var_name = data_comp.output_var_names[0]\n",
    "var_unit = data_comp.var_units(var_name)\n",
    "var_location = data_comp.var_location(var_name)\n",
    "var_type = data_comp.var_type(var_name)\n",
    "var_grid = data_comp.var_grid(var_name)\n",
    "var_itemsize = data_comp.var_itemsize(var_name)\n",
    "var_nbytes = data_comp.var_nbytes(var_name)\n",
    "\n",
    "print(f'{var_name=} \\n{var_unit=} \\n{var_location=} \\n{var_type=} \\n{var_grid=} \\n{var_itemsize=} \\n{var_nbytes=}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "analyzed-norman",
   "metadata": {},
   "source": [
    "Use grid related methods to check the grid information of the dbSEABED dataset. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "violent-michigan",
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable grid info\n",
    "grid_type = data_comp.grid_type(var_grid)\n",
    "grid_rank = data_comp.grid_ndim(var_grid)\n",
    "grid_shape = data_comp.grid_shape(var_grid)\n",
    "grid_spacing = data_comp.grid_spacing(var_grid)\n",
    "grid_origin = data_comp.grid_origin(var_grid)\n",
    "\n",
    "print(f'{grid_type=} \\n{grid_rank=} \\n{grid_shape=} \\n{grid_spacing=} \\n{grid_origin=}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "monetary-exception",
   "metadata": {},
   "source": [
    "Use get_value( ) method to get the carbonate data as a numpy array. Please note that the default behavior of pymt components is to flatten data arrays. So make a new variable that restores the dimensionality of the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ideal-grave",
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable data\n",
    "data = data_comp.get_value(var_name)\n",
    "data_2D = data.reshape(grid_shape)\n",
    "\n",
    "print(data.shape, data_2D.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aggressive-synthesis",
   "metadata": {},
   "source": [
    "Now let's make a plot of the carbonate data. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aerial-austria",
   "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",
   "id": "going-discussion",
   "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,
   "id": "published-vault",
   "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}