ESMValTool Notebook API design

ESMValTool Notebook API design.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import iris\n",
    "from esmvalcore import Variable, Dataset, DatasetList, compute, Config"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Configure ESMValTool"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg = Config('~/config-file.yml')\n",
    "cfg.output_dir = '~/results'\n",
    "print(cfg.session_dir)\n",
    "> '~/results/20200213_142731'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Define a variable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pr = Variable('pr', mip='day', project='CMIP6')\n",
    "pr.find_datasets(exp='historical')  # keyword arguments optional, will return a DatasetList (see below)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Define datasets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define a dataset\n",
    "esm1_2_hr = Dataset(pr, 'ESM1-2-HR', exp='historical', ensemble='r1i1p1f1', grid='gn')\n",
    "\n",
    "# Define another dataset\n",
    "bcc_esm1 = Dataset(pr, 'BCC-ESM1', exp='historical', ensemble='r1i1p1f1', grid='gn')\n",
    "bcc_esm1.find_input_files()\n",
    "> ['/home/bandela/esmvaltool_input/CMIP6/pr_Amon_BCC-ESM1_historical_r1i1p1f1_gn_185001-201412.nc']\n",
    "\n",
    "# Configure preprocessor functions\n",
    "# See https://esmvaltool.readthedocs.io/projects/esmvalcore/en/latest/api/esmvalcore.preprocessor.html for available functions\n",
    "bcc_esm1.apply('extract_time', 2000, 1, 1, 2005, 1, 1)\n",
    "bcc_esm1.apply('extract_region', start_latitude=-20, end_latitude=20, start_longitude=0, end_longitude=100)\n",
    "bcc_esm1.apply('regrid', target_grid=esm1_2_hr, scheme='linear')\n",
    "# Inspect preprocessor\n",
    "print(bcc_esm1.preprocessor)\n",
    "# will print\n",
    "{\n",
    "    'extract_time': {'start_year': 2000, 'start_month': 1, 'start_day': 1, 'end_year': 2005, 'end_month': 1, 'end_day': 1},\n",
    "    'extract_region': , {'start_latitude': -20, 'end_latitude': 20, 'start_longitude': 0, 'end_longitude': 100},\n",
    "    'regrid', {'target_grid': 'esm1_2_hr', 'scheme': 'linear'},\n",
    "}\n",
    "\n",
    "\n",
    "# Get a iris.cube.CubeList of iris.cube.Cube objects\n",
    "bcc_esm1.cubes\n",
    "> iris cube(s)\n",
    "\n",
    "# Plot the data on a map\n",
    "iris.plot.pcolormesh(bcc_esm1.cubes[0])\n",
    "\n",
    "# Compute and save (optional)\n",
    "bcc_esm1.save()\n",
    "bcc_esm1.filename\n",
    "> '~/results/20200213_142731/preproc/bcc_esm1/pr/CMIP6_BCC-ESM1_day_historical_r1i1p1f1_pr_2000-2002.nc'\n",
    "\n",
    "# Visualize provenance\n",
    "from prov.dot import prov_to_dot\n",
    "figure = prov_to_dot(bcc_esm1.provenance)\n",
    "figure.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Combine multiple datasets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pr_datasets = DatasetList(esm1_2_hr, bcc_esm1)\n",
    "\n",
    "# Define preprocessor functions to homogenize masks, compute the mean of all datasets, and compute monthly means\n",
    "pr_datasets.apply('mask_fillvalues', threshold_fraction=0)\n",
    "pr_datasets.apply('multi_model_statistics', span='overlap', statistic='mean')\n",
    "pr_datasets.apply('monthly_statistics', operator='mean')\n",
    "\n",
    "# Compute and save results (optional)\n",
    "pr_datasets.save()\n",
    "print(pr_datasets.filenames)\n",
    "# will print:\n",
    "[\n",
    "    '~/results/20200213_142731/preproc/datasets1/pr/CMIP6_BCC-ESM1_day_historical_r1i1p1f1_pr_2000-2002.nc',\n",
    "    '~/results/20200213_142731/preproc/datasets1/pr/CMIP6_MPI-ESM1-2-HR_day_historical_r1i1p1f1_pr_2000-2002.nc',\n",
    "    '~/results/20200213_142731/preproc/datasets1/pr/MultiModelMean_day_historical_r1i1p1f1_pr_2000-2002.nc',\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Use a pre-defined diagnostic script"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "diagnostic = Diagnostic('examples/diagnostic.py', datasets=pr_datasets, quickplot={'plot_type': 'pcolormesh'})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Run the diagnostic"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Compute and save one or more diagnostic(s), datasets, datasetlists\n",
    "compute(diagnostic)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Export to recipe and import from recipe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Export to recipe\n",
    "diagnostic.export('recipe_example_diagnostic.yml')\n",
    "\n",
    "# Import from recipe\n",
    "diagnostics = esmvalcore.load('examples/recipe_r.yml')\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}