demos/R Python Vignette equivalents.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Equivalents to R Vignette Examples"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from dataretrieval import nwis\n",
    "from dataretrieval import wqp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dataRetrieval package was created as a python equivalent to the R dataRetrieval tool.\n",
    "\n",
    "The following shows python equivalents for methods outlined in the R dataRetrieval Vignette with the equivalent R code in comments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "library(dataRetrieval)\n",
    "# Choptank River near Greensboro, MD\n",
    "siteNumber <- \"01491000\"\n",
    "ChoptankInfo <- readNWISsite(siteNumber)\n",
    "parameterCd <- \"00060\"\n",
    "\n",
    "#Raw daily data:\n",
    "rawDailyData <- readNWISdv(siteNumber,parameterCd,\n",
    "                      \"1980-01-01\",\"2010-01-01\")\n",
    "\n",
    "# Sample data Nitrate:\n",
    "parameterCd <- \"00618\"\n",
    "qwData <- readNWISqw(siteNumber,parameterCd,\n",
    "                      \"1980-01-01\",\"2010-01-01\")\n",
    "\n",
    "pCode <- readNWISpCode(parameterCd)\n",
    "'''\n",
    "\n",
    "# Choptank River near Greensboro, MD\n",
    "siteNumber = '01491000'\n",
    "chop_tank_info, md = nwis.get_info(sites=siteNumber)\n",
    "parameterCd = '00060'\n",
    "\n",
    "# raw daily data\n",
    "rawDailyData, md = nwis.get_dv(sites=siteNumber, parameterCd=parameterCd, start=\"1980-01-01\", end=\"2010-01-01\")\n",
    "\n",
    "# sample data Nitrate:\n",
    "parameterCd = \"00618\"\n",
    "qwData, md = nwis.get_qwdata(sites=siteNumber, parameterCd=parameterCd, start=\"1980-01-01\", end=\"2010-01-01\")\n",
    "\n",
    "pCode, md = nwis.get_pmcodes(parameterCd=parameterCd)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "{r getSite, echo=TRUE, eval=FALSE}\n",
    "siteNumbers <- c(\"01491000\",\"01645000\")\n",
    "siteINFO <- readNWISsite(siteNumbers)\n",
    "'''\n",
    "siteNumbers = [\"01491000\",\"01645000\"]\n",
    "siteINFO, md = nwis.get_iv(sites=siteNumbers)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "# Continuing from the previous example:\n",
    "# This pulls out just the daily, mean data:\n",
    "dailyDataAvailable <- whatNWISdata(siteNumbers,\n",
    "                    service=\"dv\", statCd=\"00003\")\n",
    "'''\n",
    "\n",
    "dailyDataAvailable, md = nwis.get_dv(sites=siteNumbers, statCd=\"00003\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "is_executing": false
    }
   },
   "outputs": [],
   "source": [
    "'''\n",
    "# Using defaults:\n",
    "parameterCd <- \"00618\" \n",
    "parameterINFO <- readNWISpCode(parameterCd)\n",
    "'''\n",
    "\n",
    "pCode, md = nwis.get_pmcodes(parameterCd=\"00618\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "# Choptank River near Greensboro, MD:\n",
    "siteNumber <- \"01491000\"\n",
    "parameterCd <- \"00060\"  # Discharge\n",
    "startDate <- \"2009-10-01\"  \n",
    "endDate <- \"2012-09-30\" \n",
    "\n",
    "discharge <- readNWISdv(siteNumber, \n",
    "                    parameterCd, startDate, endDate)\n",
    "'''\n",
    "# Choptank River near Greensboro, MD:\n",
    "siteNumber = \"01491000\"\n",
    "parameterCd = \"00060\"  # Discharge\n",
    "startDate = \"2009-10-01\"  \n",
    "endDate = \"2012-09-30\" \n",
    "\n",
    "discharge, md = nwis.get_dv(sites=siteNumber, parameterCd=parameterCd, start=startDate, end=endDate)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "siteNumber <- \"01491000\"\n",
    "parameterCd <- c(\"00010\",\"00060\")  # Temperature and discharge\n",
    "statCd <- c(\"00001\",\"00003\")  # Mean and maximum\n",
    "startDate <- \"2012-01-01\"\n",
    "endDate <- \"2012-05-01\"\n",
    "\n",
    "temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, \n",
    "        startDate, endDate, statCd=statCd)\n",
    "'''\n",
    "siteNumber = \"01491000\"\n",
    "parameterCd = [\"00010\",\"00060\"]  # Temperature and discharge\n",
    "statCd = [\"00001\",\"00003\"]  # Mean and maximum\n",
    "startDate = \"2012-01-01\"\n",
    "endDate = \"2012-05-01\"\n",
    "\n",
    "temperatureAndFlow, md = nwis.get_dv(sites=siteNumber, parameterCd=parameterCd,\n",
    "                                     start=startDate, end=endDate, statCd=statCd)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "parameterCd <- \"00060\"  # Discharge\n",
    "startDate <- \"2012-05-12\" \n",
    "endDate <- \"2012-05-13\" \n",
    "dischargeUnit <- readNWISuv(siteNumber, parameterCd, \n",
    "        startDate, endDate)\n",
    "'''\n",
    "siteNumber = \"01491000\"\n",
    "parameterCd = \"00060\"  # Discharge\n",
    "startDate = \"2012-05-12\" \n",
    "endDate = \"2012-05-13\" \n",
    "dischargeUnit, md = nwis.get_iv(sites=siteNumber, parameterCd=parameterCd,\n",
    "                            start=startDate, end=endDate)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "# Dissolved Nitrate parameter codes:\n",
    "parameterCd <- c(\"00618\",\"71851\")\n",
    "startDate <- \"1985-10-01\"\n",
    "endDate <- \"2012-09-30\"\n",
    "dfLong <- readNWISqw(siteNumber, parameterCd, \n",
    "      startDate, endDate)\n",
    "# Or the wide return:\n",
    "dfWide <- readNWISqw(siteNumber, parameterCd,\n",
    "      startDate, endDate, reshape=TRUE)\n",
    "'''\n",
    "siteNumber = \"01491000\"\n",
    "parameterCd = [\"00618\",\"71851\"]\n",
    "startDate = \"1985-10-01\"\n",
    "endDate = \"2012-09-30\"\n",
    "dfLong, md = nwis.get_qwdata(sites=siteNumber, parameterCd=parameterCd,\n",
    "                             start=startDate, end=endDate)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "siteNumber <- \"434400121275801\"\n",
    "groundWater <- readNWISgwl(siteNumber)\n",
    "'''\n",
    "siteNumber = \"434400121275801\"\n",
    "groundWater, md = nwis.get_gwlevels(sites=siteNumber)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "siteNumber <- '01594440'\n",
    "peakData <- readNWISpeak(siteNumber)\n",
    "'''\n",
    "siteNumber = '01594440'\n",
    "peakData, md = nwis.get_discharge_peaks(sites=siteNumber)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "ratingData <- readNWISrating(siteNumber, \"base\")\n",
    "attr(ratingData, \"RATING\")\n",
    "'''\n",
    "ratings_data, md = nwis.get_ratings(site='01594440', file_type=\"base\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''surfaceData <- readNWISmeas(siteNumber)'''\n",
    "siteNumber = '01594440'\n",
    "surface_data, md = nwis.get_discharge_measurements(sites=siteNumber)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "allegheny <- readNWISuse(stateCd = \"Pennsylvania\",\n",
    "                         countyCd = \"Allegheny\")\n",
    "national <- readNWISuse(stateCd = NULL, \n",
    "                        countyCd = NULL, \n",
    "                        transform = TRUE)\n",
    "'''\n",
    "allegheny, md = nwis.get_water_use(state=\"PA\", counties=\"003\")\n",
    "\n",
    "national, md = nwis.get_water_use()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "discharge_stats <- readNWISstat(siteNumbers=c(\"02319394\"),\n",
    "                   parameterCd=c(\"00060\"),\n",
    "                   statReportType=\"annual\") \n",
    "'''\n",
    "discharge_stats, md = nwis.get_stats(sites='02319394', parameterCd=\"00060\", statReportType='annual', statTypeCd='all')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# '''\n",
    "# specificCond <- readWQPqw('WIDNR_WQX-10032762',\n",
    "#                           'Specific conductance',\n",
    "#                           '2011-05-01','2011-09-30')\n",
    "# '''\n",
    "# specific_cond, md = wqp.get_results(siteid='WIDNR_WQX-10032762',\n",
    "#                           characteristicName = 'Specific conductance',\n",
    "#                           startDateLo='2011-05-01', startDateHi='2011-09-30')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# '''\n",
    "# dischargeWI <- readNWISdata(service=\"dv\",\n",
    "#                            stateCd=\"WI\",\n",
    "#                            parameterCd=\"00060\",\n",
    "#                            drainAreaMin=\"50\",\n",
    "#                            statCd=\"00003\")\n",
    "# '''\n",
    "# dischargeWI, md = nwis.get_dv(stateCd=\"WI\", parameterCd=\"00060\", drainAreaMin=\"50\", statCd=\"00003\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# '''\n",
    "# sitesNJ <- whatWQPsites(statecode=\"US:34\",\n",
    "#                        characteristicName=\"Chloride\")\n",
    "# '''\n",
    "# sitesNJ, md = wqp.what_sites(statecode=\"US:34\", characteristicName=\"Chloride\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# '''\n",
    "# dataPH <- readWQPdata(statecode=\"US:55\", \n",
    "#                  characteristicName=\"pH\")\n",
    "# '''\n",
    "# dataPH, md = wqp.what_sites(statecode=\"US:55\", characteristicName=\"pH\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# '''\n",
    "# type <- \"Stream\"\n",
    "# sites <- whatWQPdata(countycode=\"US:55:025\",siteType=type)\n",
    "# '''\n",
    "# streamType = \"Stream\"\n",
    "# sites, md = wqp.get_results(countycode=\"US:55:025\", siteType=streamType)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''site <- whatWQPsamples(siteid=\"USGS-01594440\")'''\n",
    "\n",
    "site, md = wqp.what_sites(siteid=\"USGS-01594440\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "'''\n",
    "type <- \"Stream\"\n",
    "sites <- whatWQPmetrics(countycode=\"US:55:025\",siteType=type)\n",
    "'''\n",
    "streamType = \"Stream\"\n",
    "sites, md = wqp.what_sites(countycode=\"US:55:025\",siteType=streamType)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Embedded Metadata\n",
    "\n",
    "All service methods return the DataFrame containing requested data and Metadata as a tuple.  Note, a call using get_record will only return the DataFrame to remain compatible with previous usage.\n",
    "\n",
    "\n",
    "```\n",
    "national, md = nwis.get_water_use()\n",
    "```\n",
    "\n",
    "md is an object with the following attributes\n",
    "\n",
    "```\n",
    "Metadata\n",
    "    url # the resulting url to query usgs\n",
    "    query_time # the time it took to query usgs\n",
    "    site_info # a method to call site_info with the site parameters supplied\n",
    "    header # any headers attached to the response object\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.8.13 ('py38')",
   "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.13"
  },
  "vscode": {
   "interpreter": {
    "hash": "2da9d245c691c2995f0592d1f809d130e15c1d01d60d03d4ca8d56ea51bb4095"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}