notebooks/00-quick_intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quick introduction\n",
    "\n",
    "gliderpy can be installed with conda\n",
    "\n",
    "```\n",
    "conda install --channel conda-forge gliderpy\n",
    "```\n",
    "\n",
    "or pip\n",
    "\n",
    "```\n",
    "pip install gliderpy\n",
    "```\n",
    "\n",
    "gliderpy aims to make querying and downloading glider data easier.\n",
    "Here is how one would build a query using erddapy:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from erddapy import ERDDAP\n",
    "\n",
    "e = ERDDAP(\n",
    "    server=\"https://gliders.ioos.us/erddap\",\n",
    "    protocol=\"tabledap\",\n",
    "    response=\"csv\",\n",
    ")\n",
    "e.dataset_id = \"whoi_406-20160902T1700\"\n",
    "\n",
    "e.variables = [\n",
    "    \"depth\",\n",
    "    \"latitude\",\n",
    "    \"longitude\",\n",
    "    \"salinity\",\n",
    "    \"temperature\",\n",
    "    \"profile_id\",\n",
    "    \"time\",\n",
    "]\n",
    "\n",
    "df = e.to_pandas(\n",
    "    index_col=\"time (UTC)\",\n",
    "    parse_dates=True,\n",
    ")\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And here is how to use gliderpy to obtain the same results but with fewer lines and a cleaner code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gliderpy.fetchers import GliderDataFetcher\n",
    "\n",
    "glider_grab = GliderDataFetcher()\n",
    "\n",
    "glider_grab.fetcher.dataset_id = \"whoi_406-20160902T1700\"\n",
    "df = glider_grab.to_pandas()\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Much easier, right?\n",
    "The variable names are standardized by gliderpy,\n",
    "making it easier to fetch from different data sources and comparing the results.\n",
    "\n",
    "The gliderpy library can subset the data on the server side by passing a geographic bounding box and time interval."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Querying multiple datasets\n",
    "\n",
    "The most common use is to search all datasets for data that falls within the certain space-time bounds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glider_grab = GliderDataFetcher()\n",
    "\n",
    "df = glider_grab.query(\n",
    "    min_lat=10,\n",
    "    max_lat=40,\n",
    "    min_lon=-90,\n",
    "    max_lon=8,\n",
    "    min_time=\"2010-01-01\",\n",
    "    max_time=\"2013-06-02\",\n",
    ")\n",
    "df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datasets = glider_grab.to_pandas()\n",
    "datasets.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "datasets[\"ru23-20121025T1944\"].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dataset search\n",
    "\n",
    "One can query all dataset_ids available in the server."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gliderpy.fetchers import DatasetList\n",
    "\n",
    "datasets = DatasetList()\n",
    "ds_ids = datasets.get_ids()\n",
    "\n",
    "print(f\"found {len(ds_ids)} glider datasets on {datasets.e.server}.\")"
   ]
  }
 ],
 "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}