notebooks/bmi_roms.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://github.com/gantian127/bmi_roms/blob/master/docs/source/_static/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 demonstrate how to use the bmi_roms package to download the [ROMS model](https://www.myroms.org/) datasets. \n",
    "\n",
    "This tutorial includes the following sections:\n",
    "\n",
    "1. [Brief Introduction](#section1)\n",
    "\n",
    "   This section provides basic information about bmi_roms package. \n",
    "   <br>\n",
    "   \n",
    "2. [Start with Examples](#section2)\n",
    "   \n",
    "   This section provides an example to demonstrate how to use the bmi_roms package to download the ROMS model output dataset for visualization.\n",
    "   <br>\n",
    "   \n",
    "\n",
    "\n",
    "**Suggested citation**: Gan, T. (2023). Jupyter Notebooks for the ROMS Data Component, HydroShare, https://www.hydroshare.org/resource/5bed8401cfe04c38b0f84119b1999482/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='section1'></a>\n",
    "## 1. Brief Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "bmi_roms package is an implementation of the Basic Model Interface ([BMI](https://bmi.readthedocs.io/en/latest/)) for the [ROMS model](https://www.myroms.org/) dataset. This package is not implemented for people to use but is the key element to convert the ROMS output dataset into a data component for the [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",
    "The current implementation supports 2D, 3D and 4D ROMS output datasets defined with geospatial and/or time dimensions (e.g., dataset defined with dimensions as [time, s_rho, eta_rho, xi_rho] )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To install bmi_roms package, please follow the instructions [here](https://github.com/gantian127/bmi_roms#install-package)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='section2'></a>\n",
    "## 2. Code Example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This section provides an example to demonstrate how to use the bmi_roms package to access and load the ROMS dataset for visualization."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import BmiRoms class and instantiate it. A configuration file (yaml file) is required to provide the parameter settings. An example config_file.yaml file is provided in the same folder with this Jupyter Notebook. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "from bmi_roms import BmiRoms\n",
    "\n",
    "data_comp = BmiRoms()\n",
    "data_comp.initialize(\"config_file.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you check the content in the config_file.yaml, you will find that the parameter includes a file name to load the local ROMS model dataset. The example.nc file is provided in the same folder with this Jupyter Notebook. You can also set the \"filename\" value with an OPeNDAP Data URL to access remote dataset and donwload it by setting the \"download\" parameter as True. Please see more details [here](https://bmi-roms.readthedocs.io/en/latest/?badge=latest#parameters) for the parameter settings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cat config_file.yaml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use variable related methods from BmiRoms class to check the variable information. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable info\n",
    "for var_name in data_comp.get_output_var_names():\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",
    "    var_itemsize = data_comp.get_var_itemsize(var_name)\n",
    "    var_nbytes = data_comp.get_var_nbytes(var_name)\n",
    "\n",
    "    print(\n",
    "        f\"{var_name=} \\n{var_unit=} \\n{var_location=} \\n{var_type=} \\n{var_grid=} \\n{var_itemsize=} \\n{var_nbytes=} \\n\"\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use time related methods from BmiRoms class to check the time information. The time values are stored in a format which follows [CF convention](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.pdf)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get time info\n",
    "start_time = data_comp.get_start_time()\n",
    "end_time = data_comp.get_end_time()\n",
    "time_step = data_comp.get_time_step()\n",
    "time_unit = data_comp.get_time_units()\n",
    "time_steps = int((end_time - start_time) / time_step) + 1\n",
    "\n",
    "print(f\"{start_time=} \\n{end_time=} \\n{time_step=} \\n{time_unit=} \\n{time_steps=} \\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use grid related methods of BmiRoms class to check the grid information. You will find out that the variables are defined on different grids."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable grid info\n",
    "for var_name in data_comp.get_output_var_names():\n",
    "    var_grid = data_comp.get_var_grid(var_name)\n",
    "\n",
    "    grid_rank = data_comp.get_grid_rank(var_grid)\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(\n",
    "        f\"{var_name=} \\n{var_grid=} \\n{grid_rank=} \\n{grid_size=} \\n{grid_shape=} \\n{grid_spacing=} \\n{grid_origin=} \\n\"\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use get_value( ) method to get the variable data as a numpy array. Please note that the get_value( ) method is to flatten data arrays. So make a new variable that restores the dimensionality of the data.\n",
    "\n",
    "The code below shows how to get the variable values for the 'time-averaged salinity' and make a contour plot. The latitude and longitude values can be obtained from the 'latitude of RHO-points' and 'longitude of RHO-points' variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get variable data\n",
    "data = np.empty(1026080, \"float64\")\n",
    "data_comp.get_value(\"time-averaged salinity\", data)\n",
    "data_3D = data.reshape([40, 106, 242])\n",
    "\n",
    "# get lon and lat data\n",
    "lat = np.empty(25652, \"float64\")\n",
    "data_comp.get_value(\"latitude of RHO-points\", lat)\n",
    "\n",
    "lon = np.empty(25652, \"float64\")\n",
    "data_comp.get_value(\"longitude of RHO-points\", lon)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# make a contour plot\n",
    "fig = plt.figure(figsize=(10, 7))\n",
    "im = plt.contourf(\n",
    "    lon.reshape([106, 242]), lat.reshape([106, 242]), data_3D[0], levels=36\n",
    ")\n",
    "fig.colorbar(im)\n",
    "plt.axis(\"equal\")\n",
    "plt.xlabel(\"Longitude [degree_east]\")\n",
    "plt.ylabel(\"Latitude [degree_north]\")\n",
    "plt.title(\"ROMS model data of time-averaged salinity\")"
   ]
  },
  {
   "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
}