{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#Downloading Solar Data with SunPy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This lesson covers the functionality in SunPy to download solar physics data from various places. It has been written for the current release (v0.5.4), despite the fact there are large improvements in the downloading software for SunPy v0.6."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This lesson will cover the core downloaders available in the `sunpy.net` submodule, we will cover the following topics:\n",
    "\n",
    "* The Virtual Solar Observatory.\n",
    "* The SunPy query syntax.\n",
    "* Downloading data and managing files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Virtual Solar Observatory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The VSO is a centralised portal to many different sources of solar physics data. SunPy has a very powerful and easy to use VSO client, which we are going to use to download an AIA image."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the `vso` module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a client instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Query the VSO:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Download the File:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SunPy Query Syntax"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Having done a quick demo of the VSO client, we will now go through the steps in more detail and explain them. The  main part of the VSO interface is the query syntax.\n",
    "The query syntax allows you to perform very complex queries, by using the logical and `&` and logical or `|` operators on the individual query attributes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The query attributes live in the `sunpy.net.vso.attrs` namespace, which we have imported as `vso.attrs`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The attributes available for use in a VSO query are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can combine these attributes to make simple or more complex queries.\n",
    "First, let's explain the example we used earlier:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`vclient.query(vso.attrs.Time('2015/03/15T00:00:00', '2015/03/15T00:00:01') & vso.attrs.Instrument('AIA'))`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Time` attribute, specifies a time range for the data, you must specify a start and an end value to `Time`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Instrument` attribute specifies the name of the instrument used to collect the data, the list of available instruments is on the VSO website: http://sdac.virtualsolar.org/cgi/show_details?keyword=INSTRUMENT"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we passed these into `query()` we used the `&` symbol to tell `query()` that we wanted VSO to look for records that satisfied both attributes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to use the `|` operator to get multiple results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also construct these queries outside of the `query()` method, to make it easier to read or to make multiple queries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style='background:#B1E0A8; padding:10px 10px 10px 10px;'>\n",
    "<h2>Challenges</h2>\n",
    "<p>\n",
    "<ol>\n",
    "<li> Create a query that searches for an AIA image on your last birthday</li>\n",
    "<li> Create a query that retrieves an image from AIA, HMI and LASCO C2 taken approximately at the same time.</li>\n",
    "</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Retreiving Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far we have been downloading files using `get()` with the default options. In this section we are going to look at how to customise these options and save the files to different directories."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once we have obtained the results we can download them with the `get()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The important parameters for the get method are the `path` and the `methods` keyword arguments.\n",
    "\n",
    "`path` allows you to specify where the data is downloaded to, by default it goes to the SunPy data directory, which defaults to `~/sunpy/data`, this (and other options) can be set in the SunPy config file `~/.sunpy/sunpyrc`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The parameters that you can use for the path formatting is anything that is in the `QueryResponse` object, or the results from query:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Things that have multiple nested properties can be acessed via `.` i.e. `time.start` or `wave.wavemin`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`method` allows you to request the data in a different form, such as a tarball or a RICE compressed image for AIA:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style='background:#B1E0A8; padding:10px 10px 10px 10px;'>\n",
    "<h2>Challenges</h2>\n",
    "<p>\n",
    "<ol>\n",
    "<li>Download an image of your choice and display it using SunPy's Map class.</li>\n",
    "<li>Download a set of AIA images (RICE compressed) and put them into folders based on their wavelength.</li>\n",
    "</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Solution 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###Solution 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}