docs/performances.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# HIDDEN CELL\n",
    "import sys, os\n",
    "\n",
    "# Importing argopy in dev mode:\n",
    "on_rtd = os.environ.get('READTHEDOCS', None) == 'True'\n",
    "if not on_rtd:\n",
    "    sys.path.insert(0, \"/Users/gmaze/git/github/euroargodev/argopy\")\n",
    "    import git\n",
    "    import argopy\n",
    "    from argopy.options import OPTIONS\n",
    "    print(\"argopy:\", argopy.__version__, \n",
    "          \"\\nsrc:\", argopy.__file__, \n",
    "          \"\\nbranch:\", git.Repo(search_parent_directories=True).active_branch.name, \n",
    "          \"\\noptions:\", OPTIONS)\n",
    "else:\n",
    "    sys.path.insert(0, os.path.abspath('..'))\n",
    "\n",
    "import xarray as xr\n",
    "# xr.set_options(display_style=\"html\");\n",
    "xr.set_options(display_style=\"text\");"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import argopy\n",
    "from argopy import DataFetcher as ArgoDataFetcher"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Performance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Caching data"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "If you want to avoid retrieving the same data serveral time during a working session, or if you fetched a large amount of data, you may want to temporarily save data in a cache file.\n",
    "\n",
    "You can cache fetched data with the fetchers option ``cache``. Note that cached data will persists on the machine they are retrieved as long as you don't clear the cache.\n",
    "\n",
    ".. note::\n",
    "\n",
    "  At this point, caching is only available for:\n",
    "  \n",
    "  - the ``erddap`` data source for data fetcher (see :doc:`data_fetching`),\n",
    "  - both ``erddap`` and ``localftp`` data sources for the index fetcher (see :doc:`metadata_fetching`).\n",
    "\n",
    "The default cache folder is under your home directory at ``~./.cache/argopy``. But you can specify the path you want to use in several ways:\n",
    "\n",
    "- with **argopy** global options:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "outputs": [],
   "source": [
    "argopy.set_options(cachedir='mycache_folder')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- in a temporary context:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with argopy.set_options(cachedir='mycache_folder'):\n",
    "    ds = ArgoDataFetcher(cache=True).profile(6902746, 34).to_xarray()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- when instantiating the data fetcher:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ds = ArgoDataFetcher(cache=True, cachedir='mycache_folder').profile(6902746, 34).to_xarray()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. warning::\n",
    "\n",
    "  You really need to set the ``cache`` option to ``True``. Specifying only the ``cachedir`` won't trigger caching !"
   ]
  }
 ],
 "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.7"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}