{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Histogram Plot](Viz_Histogram.ipynb) | [Index](Index.ipynb) | [Regional Map](Viz_RegionalMap.ipynb)>\n",
    "\n",
    "<a href=\"https://colab.research.google.com/github/simonscmap/pycmap/blob/master/docs/Viz_TimeSeries.ipynb\"><img align=\"left\" src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open in Colab\" title=\"Open and Execute in Google Colaboratory\"></a>\n",
    "\n",
    "<a href=\"https://mybinder.org/v2/gh/simonscmap/pycmap/master?filepath=docs%2FViz_TimeSeries.ipynb\"><img align=\"right\" src=\"https://mybinder.org/badge_logo.svg\" alt=\"Open in Colab\" title=\"Open and Execute in Binder\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## *plot_timeseries(tables, variables, dt1, dt2, lat1, lat2, lon1, lon2, depth1, depth2, exportDataFlag=False, show=True, interval=None)*\n",
    "\n",
    "Creates a timeseries graph for each variable according to the specified space-time constraints (dt1, dt2, lat1, lat2, lon1, lon2, depth1, depth2). By definition, timeseries data points are aggregated by time: at each time interval the mean and standard deviation of the variable values within the space-time constraints are computed. The sequence of these values construct the timeseries. If the **interval** parameter is set, timeseries can be binned weekly, monthly, quarterly, or annually, (this feature is not applicable to climatological datasets).\n",
    "\n",
    "<br />Change the [API's **vizEngine**](API.ipynb) parameter if you wish to use a different visualization library.\n",
    "<br />Returns the generated graph objects in form of a python list. One may use the returned objects to modify the graph properties. \n",
    "\n",
    "<br />**Note:**\n",
    "<br />This method requires a valid [API key](API.ipynb). It is not necessary to set the API key every time because the API properties are stored locally after being called the first time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Parameters:** \n",
    ">> **tables: list of string**\n",
    ">>  <br />Table names (each dataset is stored in a table). A full list of table names can be found in [catalog](Catalog.ipynb).\n",
    ">> <br />\n",
    ">> <br />**variable: list of string**\n",
    ">>  <br />Variable short name which directly corresponds to a field name in the table. A full list of variable short names can be found in [catalog](Catalog.ipynb).\n",
    ">> <br />\n",
    ">> <br />**dt1: string**\n",
    ">>  <br />Start date or datetime. This parameter sets the lower bound of the temporal cut. <br />Example values: '2016-05-25' or '2017-12-10 17:25:00'\n",
    ">> <br />\n",
    ">> <br />**dt2: string**\n",
    ">>  <br />End date or datetime. This parameter sets the upper bound of the temporal cut. \n",
    ">> <br />\n",
    ">> <br />**lat1: float**\n",
    ">>  <br />Start latitude [degree N]. This parameter sets the lower bound of the meridional cut. Note latitude ranges from -90&deg; to 90&deg;.\n",
    ">> <br />\n",
    ">> <br />**lat2: float**\n",
    ">>  <br />End latitude [degree N]. This parameter sets the upper bound of the meridional cut. Note latitude ranges from -90&deg; to 90&deg;.\n",
    ">> <br />\n",
    ">> <br />**lon1: float**\n",
    ">>  <br />Start longitude [degree E]. This parameter sets the lower bound of the zonal cut. Note latitude ranges from -180&deg; to 180&deg;.\n",
    ">> <br />\n",
    ">> <br />**lon2: float**\n",
    ">>  <br />End longitude [degree E]. This parameter sets the upper bound of the zonal cut. Note latitude ranges from -180&deg; to 180&deg;.\n",
    ">> <br />\n",
    ">> <br />**depth1: float**\n",
    ">>  <br />Start depth [m]. This parameter sets the lower bound of the vertical cut. Note depth is a positive number (it is 0 at surface and grows towards ocean floor).\n",
    ">> <br />\n",
    ">> <br />**depth2: float**\n",
    ">>  <br />End depth [m]. This parameter sets the upper bound of the vertical cut. Note depth is a positive number (it is 0 at surface and grows towards ocean floor).\n",
    ">> <br />\n",
    ">> <br />**exportDataFlag: boolean, default: False**\n",
    ">>  <br />If True, the graph data points are stored on the local machine. The export path and file format are set by the [API's parameters](API.ipynb). \n",
    ">> <br />\n",
    ">> <br />**show: boolean, default: True**\n",
    ">>  <br />If True, the graph object is returned and is displayed. The graph file is saved on the local machine at the [**figureDir**](API.ipynb) directory. \n",
    "<br />If False, the graph object is returned but not displayed. \n",
    ">> <br />\n",
    ">> <br />**interval: None or string, default: None**\n",
    ">>  <br />The timeseries bin size. If None, the native dataset time resolution is used as the bin size. <br />Below is a list of interval values for other binning options:\n",
    "* **'w'** or **'week'** for weekly timeseries.\n",
    "* **'m'** or **'month'** for monthly timeseries.\n",
    "* **'s'** or **'q'** for seasonal/quarterly timeseries.\n",
    "* **'a'** or **'y'** for annual/yearly timeseries.\n",
    "\n",
    "\n",
    ">**Returns: list of graph objects** \n",
    ">>  A list of graph objects. Below are the graph's properties and methods.\n",
    ">>> **Properties:**\n",
    ">>>> **data: dataframe**\n",
    ">>>>  <br />Graph data points to be visualized. \n",
    ">>>> <br />\n",
    ">>>> <br />**line: boolean, default: True**\n",
    ">>>>  <br />If True, line plot is superimposed on markers.\n",
    ">>>> <br />\n",
    ">>>> <br />**color: string**\n",
    ">>>>  <br />Line and marker colors (e.g. 'red', 'green', ..) or rgb hex '#FF0023'.\n",
    ">>>> <br />\n",
    ">>>> <br />**msize: int**\n",
    ">>>>  <br />Marker size.\n",
    ">>>> <br />\n",
    ">>>> <br />**height: int**\n",
    ">>>>  <br />Graph's height in pixels.\n",
    ">>>> <br />\n",
    ">>>> <br />**width: int**\n",
    ">>>>  <br />Graph's width in pixels.\n",
    ">>>> <br />\n",
    ">>>> <br />**xlabel: str**\n",
    ">>>>  <br />The graphs's x-axis label.\n",
    ">>>> <br />\n",
    ">>>> <br />**ylabel: str**\n",
    ">>>>  <br />The graphs's y-axis label.\n",
    ">>>> <br />\n",
    ">>>> <br />**title: str**\n",
    ">>>>  <br />The graphs's title.\n",
    "\n",
    ">>> **Methods:**\n",
    ">>>> **render()**\n",
    ">>>>  <br />Displayes the plot according to the set properties. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example\n",
    "\n",
    "This example generates two timeseries graphs showing remotly sensed [sea level anomaly](https://cmap.readthedocs.io/en/latest/catalog/datasets/Altimetry_REP.html#altimetry-rep), and [sea surface salinity](https://cmap.readthedocs.io/en/latest/catalog/datasets/SSS.html#sss) over a weekly-binned one-year period. \n",
    "<br />The graphs are made using the default visualization library (plotly) which may be changed by:\n",
    "`pycmap.API(vizEngine='bokeh')`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#!pip install pycmap -q     #uncomment to install pycmap, if necessary\n",
    "# uncomment the lines below if the API key has not been registered on your machine, previously.\n",
    "# import pycmap\n",
    "# pycmap.API(token='<YOUR_API_KEY>')     \n",
    "\n",
    "\n",
    "from pycmap.viz import plot_timeseries\n",
    "\n",
    "go = plot_timeseries(\n",
    "                    tables=['tblAltimetry_REP', 'tblSSS_NRT'], \n",
    "                    variables=['sla', 'sss'], \n",
    "                    dt1='2016-04-30', \n",
    "                    dt2='2017-04-30', \n",
    "                    lat1=30, \n",
    "                    lat2=32, \n",
    "                    lon1=-160, \n",
    "                    lon2=-158, \n",
    "                    depth1=0, \n",
    "                    depth2=0, \n",
    "                    exportDataFlag=False,\n",
    "                    show=True,\n",
    "                    interval='w'\n",
    "                    )\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# here is how to modify a graph:\n",
    "\n",
    "go[0].line = False\n",
    "go[0].msize = 10\n",
    "go[0].color='#FF0023'\n",
    "go[0].title= \"graph's title\"\n",
    "go[0].width = 600\n",
    "go[0].height = 600\n",
    "go[0].render()\n",
    "\n",
    "# the graph data is held in the 'data' property\n",
    "# go[0].data"
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}