{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tutorial on how to use `timestaps` in Field construction"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from parcels import Field\n",
    "from glob import glob\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some NetCDF files, such as for example those from the [World Ocean Atlas](https://www.nodc.noaa.gov/OC5/woa18/), have time calendars that can't be parsed by `xarray`. These result in a `ValueError: unable to decode time units`, for example when the calendar is in 'months since' a particular date.\n",
    "\n",
    "In these cases, a workaround in Parcels is to use the `timestamps` argument in `Field` (or `FieldSet`) creation. Here, we show how this works for example temperature data from the World Ocean Atlas in the Pacific Ocean"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following cell would give an error, since the calendar of the World Ocean Atlas data is in \"months since 1955-01-01 00:00:00\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# tempfield = Field.from_netcdf(glob('WOA_data/woa18_decav_*_04.nc'), 't_an', \n",
    "#                               {'lon': 'lon', 'lat': 'lat', 'time': 'time'})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, we can create our own numpy array of timestamps associated with each of the 12 snapshots in the netcdf file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "timestamps = np.expand_dims(np.array([np.datetime64('2001-%.2d-15' %m) for m in range(1,13)]), axis=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then we can add the `timestamps` as an extra argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "WARNING: File WOA_data/woa18_decav_t10_04.nc could not be decoded properly by xarray (version 0.12.1).\n",
      "         It will be opened with no decoding. Filling values might be wrongly parsed.\n",
      "WARNING: Casting depth data to np.float32\n"
     ]
    }
   ],
   "source": [
    "tempfield = Field.from_netcdf(glob('WOA_data/woa18_decav_*_04.nc'), 't_an', \n",
    "                              {'lon': 'lon', 'lat': 'lat', 'time': 'time'}, \n",
    "                              timestamps=timestamps)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note, by the way, that adding the `time_periodic=True` argument to `Field.from_netcdf()` will also mean that the climatology can be cycled for multiple years."
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}