hydroshare_howto.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HydroShare howto : CUAHSI VU : Snow Hydrology"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## HydroShare\n",
    "\n",
    "[HydroShare](https://www.hydroshare.org/) is CUAHSI's online collaboration environment for sharing data, models, and code. We will use it in this course to upload your model results. For this to work, you must create a HydroShare account first. From HydroShare you can download the results to your local machine or share them with others. In this notebook we will show you how to upload and download resources to HydroShare."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Uploading resources to HydroShare"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have some functions that will allow you to create a HydroShare resource and upload it to your own HydroShare account directly from the notebook. You will need  to authenticate to HydroShare (or login) before you can upload this notebook to HydroShare, but you will do that inside this notebook. The reason that you need to authenticate is that that will allow you to post something to your own account. You may not be asked to authenticate every time.\n",
    "\n",
    "The python interfaces for SUMMA and HydroShare are a work in progress and they are somewhat inconsistent at this time. Don't worry about that for now. These interfaces will likely continue to change for the time being. For now to authenticate to HydroShare, we'll use some functionality from the pysumma package. We'll create an object that we'll use to upload data and which will ask us to authenticate. Just use your HydroShare account information when you are asked for it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pysumma.hydroshare import hydroshare\n",
    "hs_up = hydroshare.hydroshare()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are going to upload the current notebook back to HydroShare. To do that we will need the path to this notebook. Right-click on the notebook in the left panel and select \"_Copy Path_\" from the pop-up menu. Then add that path below if it is different than the one shown (remember that you need to preceed the path it gives you with `/home/jovyan`),"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "notebook_file = '/home/jovyan/work/hydroshare_howto.ipynb'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can then assign a number of other entries that we can use as meta-data for the resource when it is uploaded to HydroShare. There is much more information on the HydroShare web site about different [resource types](https://help.hydroshare.org/hydroshare-resource-types/). We'll use a `GenericResource` for now."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# write meta data such as abstract, title, keywords, resource type\n",
    "abstract = 'Test upload of a Jupyter notebook'\n",
    "title = 'Jupyter notebook for snow course'\n",
    "keywords = ('test', 'Jupyter', 'notebook') # currently you need to include at least two keywords or the upload will fail\n",
    "resource_type = 'genericresource'\n",
    "files = notebook_file, # yes, you do need the comma after the file here. It's a python thing (tuple)\n",
    "metadata = '[{\"creator\":{\"name\":\"Diligent student\"}}]'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now create a resource on HydroShare. We'll make the resource private for now."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# post simulation results of simpleResistance back to HS\n",
    "resource_id = hs_up.createHydroShareResource(title=title, content_files=files, keywords=keywords, abstract=abstract, \n",
    "                                             resource_type=resource_type, public=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you click the link that is returned when you run the cell, you can see your resource on HydroShare and you can download it to your local machine or whatever else you would like to do with it. Go ahead and delete it if you do not plan to save it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Downloading resources from HydroShare"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use a different python package to download from HydroShare. As with the other software, these python packages are already installed. The package to download data is called `hs_restclient`. We only need some specific functions from this package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from hs_restclient import HydroShare"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, if you do not get any messages, then this worked correctly. To actually download a resource from HydroShare, we create a `HydroShare` object and use it to download the resource. You'll have to authenticate again so HydroShare can check permissions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hs = HydroShare()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This command just creates the `HydroShare` object and assigns it to `hs`. We can now use `hs.getResource()` to get the actual resource. To use this function, you will need the resource ID on HydroShare and a destination where the file should be stored locally (the function will download a zip file with the whole archive)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So the first thing you'll need is the HydroShare resource ID. You can find this on [Hydroshare](https://www.hydroshare.org/). For example, the SUMMA test cases, which we will install in the example notebook, can be found by clicking the `Discover` link on HydroShare and then searching for \"_SUMMA sopron_\" (Sopron is a place in Hungary where we used SUMMA in a workshop in spring 2018). The resource we want is called \"_SUMMA Sopron workshop version(lubuntu-16.10)_\". If you click on that resource it will take you to a page describing the resource. The resource ID we are looking for is the last part of the URL (the part in the address bar after `resource/` with all the letters and numbers, but without the trailing slash). In this case. the resource ID is `a5dbd5b198c9468387f59f3fefc11e22`.  \n",
    "\n",
    "Note that these test cases are for an older version of SUMMA. We are just using this as an example for downloading a HydroShare resource. Use the `install_summa_test_cases()` function in the `install_summa_model_configurations.ipynb` notebook if you want to install SUMMA test cases that are compatible with the version of SUMMA installed in your virtual machine.\n",
    "\n",
    "To download the resource into your `work` directory execute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "resource_id = 'a5dbd5b198c9468387f59f3fefc11e22'\n",
    "hs.getResource(resource_id, \n",
    "               destination='/home/jovyan/work/')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you do this, you will see a file named `a5dbd5b198c9468387f59f3fefc11e22.zip` appear in your `~/work/` directory (`~` is shorthand for your home directory, so `/home/jovyan`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You would need to unpack the file to use it, but for now we'll just delete it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!rm /home/jovyan/work/a5dbd5b198c9468387f59f3fefc11e22.zip"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Uploading homeworks\n",
    "\n",
    "Both your homework folders have an `upload_notebooks.ipynb` notebook that you can adapt to upload your homework assignments to HydroShare."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}