src/python/rdams_client_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# rdams_client.py Example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "rdams_client.py can work as a command line script or python module to interact with python objects directly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### First, let's import the module and see what we can do."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make sure this is in the same directory as this notebook or is in your PATH environment variable.\n",
    "import rdams_client as rc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**We can use the query() function to make calls, or we can call the function itself.**\n",
    "\n",
    "**Let's try to get a summary of a dataset.**\n",
    "\n",
    "NOTE: when executing this command for the first time, you may be asked to authenticate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# You might want to use query() if you are more familiar with the command line calls.\n",
    "# By default, query will print the result.\n",
    "# You can turn this off with the -noprint or -np option\n",
    "result = rc.query(['-get_summary', 'ds633.0'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Same thing as above, but we call the function directly\n",
    "result = rc.get_summary('633.0')\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Of course, we could have always done this on the command line.\n",
    "# NOTE: This cell will only work if it's the current directory\n",
    "! ./rdams_client.py -get_summary '633.0'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example workflow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dsid = 'ds083.2'\n",
    "param_response = rc.query(['-get_param_summary', dsid, '-np'])\n",
    "\n",
    "# get_param_summary() returns an RDA response object that has more info that we need, so we'll filter it out\n",
    "param_data = param_response['data']['data']\n",
    "\n",
    "# Next we will just pull out the descriptions or long name of each of the parameters.\n",
    "params = list(map(lambda x: x['param_description'], param_data))\n",
    "print('\\n'.join(params))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Great!**\n",
    "\n",
    "**But, these parameters are just the long name, so let's put them in dictionary to map the long name to the actual variable name. This way, we can use the variable in a subset request.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "param_map = {}\n",
    "for _param in param_data:\n",
    "    long_name = _param['param_description']\n",
    "    short_name = _param['param']\n",
    "    param_map[long_name] = short_name\n",
    "\n",
    "for k,v in param_map.items(): print('{:7} : {}'.format(v, k))\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Now, let's get full metadata and filter it.\n",
    "\n",
    "For more advanced use cases, we will need to use `get_metadata()` to get everything we need about a variable. We can manipulate the result to filter variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For large datasets this may take a while as you're pulling all the metadata.\n",
    "metadata_response = rc.query(['-get_metadata', dsid])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**This is too much information, so let's filter it down.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# List of dicts representing a variable\n",
    "_vars = metadata_response['data']['data']\n",
    "\n",
    "# Just get temperature variables\n",
    "TMP_variables = list(filter(lambda v: v['param'] == 'TMP',_vars)) \n",
    "\n",
    "# Let's say we're only interested in 2010\n",
    "TMP_2010_variables = list(filter(\n",
    "        lambda v: v['start_date'] < 201001010000 and v['end_date'] > 201101010000 ,TMP_variables\n",
    "        )) \n",
    "\n",
    "# We only should have 1 variable\n",
    "assert len(TMP_2010_variables) == 1\n",
    "my_var = TMP_2010_variables[0]\n",
    "\n",
    "# Now let's look at the levels available:\n",
    "for lev in my_var['levels']:\n",
    "    print('{:6} {:10} {}'.format(lev['level'], lev['level_value'],lev['level_description']))\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### But let's say I only want Isobaric surfaces between 100 and 500Hpa. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ISBL_levels = set()\n",
    "ISBL_levels_printed = []\n",
    "for lev in my_var['levels']:\n",
    "    if lev['level_description'] == 'Isobaric surface' \\\n",
    "            and float(lev['level_value']) >= 100 \\\n",
    "            and float(lev['level_value']) <= 500:\n",
    "        ISBL_levels.add(lev['level_value'])\n",
    "        ISBL_levels_printed.append(lev)\n",
    "for lev in ISBL_levels_printed:\n",
    "    print('{:6} {:10} {}'.format(lev['level'], lev['level_value'],lev['level_description']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Finally, let's get make a request"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's get a template. \n",
    "response = rc.get_control_file_template(dsid)\n",
    "template = response['data']['template'] # Template string\n",
    "\n",
    "# Parse the string\n",
    "template_dict = rc.read_control_file(template)\n",
    "\n",
    "# Insert our TMP param\n",
    "template_dict['param'] = 'TMP'\n",
    "template_dict['level'] = 'ISBL:' + '/'.join(ISBL_levels)\n",
    "template_dict"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Now We can submit a request\n",
    "response = rc.submit_json(template_dict)\n",
    "assert response['http_response'] == 200\n",
    "print(response)\n",
    "\n",
    "print(\"Success!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.8.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}