{
 "metadata": {
  "name": "",
  "signature": "sha256:77ab35415e38567d49af91382dac230998db0223d904a781aafade553a673424"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "As you can see from the examples in simple_service_discovery,\n",
      "a search will often return more than one record,\n",
      "and so sometimes you need to review some of the\n",
      "resource metadata to determine which one or ones you want.  You may\n",
      "have noticed that the results behave similarly to the results from the\n",
      "data access services. Like them, registry search results are returned\n",
      "as a `~pyvo.registry.regtap.RegistryResults` instance, and each\n",
      "record is represented as a `~pyvo.registry.regtap.RegistryResource` instance. \n",
      "\n",
      "A `~pyvo.registry.regtap.RegistryRecord` record acts like a\n",
      "dictionary where the keys are the column names from the results table;\n",
      "using our NVSS example from simple_service_discovery."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import pyvo as vo\n",
      "colls = vo.regsearch(keywords=[\"NVSS\"], servicetype='sia')\n",
      "nvss = colls[0]\n",
      "print(nvss.res_title)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nvss.keys()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If you are looking for a particular data collection or catalog, as we\n",
      "did above when we looked for the NVSS archive, often simply reviewing\n",
      "the titles is sufficient.  Other times, particularly when you are not\n",
      "sure what you are looking for, it helps to look deeper.  \n",
      "\n",
      "The resource description, available via the \n",
      "`~pyvo.registry.regtap.ResourceRecord.res_description` property,\n",
      "tends to be the most revealing.  It contains a paragraph (or two)\n",
      "summarizing the catalog or data collection.  It will often describe\n",
      "the scientific intent behind the collection.  \n",
      "\n",
      "The `~pyvo.registry.regtap.RegistryResource.short_name` can also be\n",
      "helpful, as well.  This name is meant to be short--16 characters or\n",
      "fewer; consequently, the value is often includes the abbreviation for the\n",
      "project or observatory that produced the collection or catalog.  \n",
      "\n",
      "A selection of the resource metadata, including the title, shortname and\n",
      "desription, can be printed out in a summary form with\n",
      "the `~pyvo.registry.regtap.RegistryResource.describe` function."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nvss.describe()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Registry Records can be converted to a service object"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nvss = colls[0].service  # converts record to service object\n",
      "print(nvss.baseurl)\n",
      "query = nvss.create_query(size=0.25, format=\"image/fits\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Thus, not only does this service instance contain the base URL but it\n",
      "also includes all of the metadata from the registry that desribes the\n",
      "service.  With this service object, we can either call its \n",
      "`~pyvo.dal.sia.SIAService.search` function directly or \n",
      "create query objects to get cutouts for a whole list of sources."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Our discussion of service metadata offers an opportunity to highlight\n",
      "another important property, the service's *IVOA Identifier* (sometimes\n",
      "referred to as its *ivoid*).  This is a globally-unique identifier\n",
      "that takes the form of a \n",
      "`URI <http://en.wikipedia.org/wiki/Uniform_resource_identifier>`_:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "colls = vo.regsearch(keywords=[\"NVSS\"], servicetype='sia')\n",
      "for coll in colls:\n",
      "    print coll.ivoid"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This identifier can be used to uniquely retrieve a service desription\n",
      "from the registry."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "nvss = vo.registry.ivoid2service('ivo://nasa.heasarc/skyview/nvss')\n",
      "nvss.baseurl"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "cutouts1 = nvss.search(pos=(148.8888, 69.065), size=0.2)\n",
      "nvssq = nvss.create_query(size=0.2)  # or create a query object\n",
      "nvssq.pos = (350.85, 58.815)\n",
      "cutouts2 = nvssq.execute()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "As we end this discussion of the service objects, you can hopefully\n",
      "see that there is a straight-forward chain of discovery classes that\n",
      "connect the registry down through to a dataset.  Spelled out in all\n",
      "its detail, it looks like this:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "services = vo.regsearch(keywords=[\"NVSS\"],\n",
      "                        servicetype='sia')     # RegistryResults\n",
      "nvss = services[0]                             # RegistryResource\n",
      "nvsss = nvss.service                           # SIAService\n",
      "nq = nvss.create_query(pos=(350.85, 58.815),\n",
      "                      size=0.25, \n",
      "                      format=\"image/fits\")     # SIAQuery\n",
      "images = nq.execute()                          # SIAResults\n",
      "firstim = images[0]                            # SIARecord\n",
      "\n",
      "print(type(services))\n",
      "print(type(nvss))\n",
      "print(type(nq))\n",
      "print(type(images))\n",
      "print(type(firstim))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Most of the time, it's not necessary to follow all these steps\n",
      "yourself, so there are functions and methods that provide syntactic\n",
      "shortcuts.  However, when you need some finer control over the\n",
      "process, it is possible to jump off the fast track and work directly\n",
      "with an underlying object.  "
     ]
    }
   ],
   "metadata": {}
  }
 ]
}