example1.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Performing a mocserver query on a simple cone region"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy import coordinates\n",
    "from regions import CircleSkyRegion\n",
    "\n",
    "# mocserver object derived from astroquery.query.BaseQuery\n",
    "from cds.core import cds\n",
    "from cds.dataset import Dataset\n",
    "from cds.constraints import Constraints\n",
    "from cds.spatial_constraints import Cone\n",
    "from cds.output_format import OutputFormat\n",
    "\n",
    "from pprint import pprint"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A cone search region is defined using the CircleSkyRegion module from the regions package.\n",
    "Here, a cone is defined by a location (dec, ra) expressed in degree and a radius."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "center = coordinates.SkyCoord(10.8, 32.2, unit=\"deg\")\n",
    "radius = coordinates.Angle(1.5, 'deg')\n",
    "circle_sky_region = CircleSkyRegion(center, radius)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This above cone region can be seen as a spatial constraint for the mocserver. The aim of the mocserver relies on returning all the datasets which contain at least one source (i.e. spatial object) lying in the previously defined cone region.\n",
    "\n",
    "A Constraints object allows us to specify the constraints that will be sent to the mocserver so that it returns all the matching datasets. For the purpose of this tutorial, we will only bind a Cone spatial constraint to our query but keep in mind that it is also possible to associate to the Constraints object a constraint on the dataset properties. It is even possible to associate both of them (i.e. a spatial constraint and a properties constraint) as we will see in a future tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [],
   "source": [
    "cds_constraints = Constraints(sc=Cone(circle_sky_region, intersect='overlaps'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we have created a Constraints object and we have bound to it a Cone spatial constraint. The argument `intersect` specifies that the datasets need to intersect the cone region so that they match the mocserver query. Other possible `intersect` argument values are `covers` and `enclosed`.\n",
    "\n",
    "Now it is time to perform the query. We call the query_region method from the mocserver object that we imported and pass it the mocserver constraints object with an OutputFormat object which specify what we want to retrieve. In the code below, we have chosen to retrieve all the properties from the datasets, but keep in mind that it is possible, as in the MocServer http://alasky.unistra.fr/MocServer/query, to get only some specific fields from the matching datasets (`ID`, `dataproduct_type` and `moc_sky_fraction` are typical example of fields/properties bound to a dataset).\n",
    "\n",
    "Finally, we pass a `max_rec` parameter to the OutputFormat constructor which limits the number of matching datasets returned (otherwise we would have a plenty of datasets for this cone spatial constraint)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Final Request payload before requesting to alasky\n",
      "{'DEC': '32.2',\n",
      " 'MAXREC': '5',\n",
      " 'RA': '10.8',\n",
      " 'SR': '1.5',\n",
      " 'casesensitive': 'true',\n",
      " 'fmt': 'json',\n",
      " 'get': 'record',\n",
      " 'intersect': 'overlaps'}\n",
      "{'CDS/B/assocdata/obscore': <mocserver.dataset.Dataset object at 0x7fd5a100ca58>,\n",
      " 'CDS/B/cb/lmxbdata': <mocserver.dataset.Dataset object at 0x7fd5a07c0828>,\n",
      " 'CDS/B/cfht/cfht': <mocserver.dataset.Dataset object at 0x7fd5a07c07b8>,\n",
      " 'CDS/B/cfht/obscore': <mocserver.dataset.Dataset object at 0x7fd5a10e4470>,\n",
      " 'CDS/B/chandra/chandra': <mocserver.dataset.Dataset object at 0x7fd5a1155048>}\n"
     ]
    }
   ],
   "source": [
    "datasets_d = cds.query_region(cds_constraints,\n",
    "                                  OutputFormat(format=OutputFormat.Type.record,\n",
    "                                               max_rec=5))\n",
    "\n",
    "pprint(datasets_d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We got a dictionary of mocserver.dataset.Dataset objects indexed by their IDs. To get the properties of one dataset, say `CDS/B/cb/lmxbdata`, just do the following :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'ID': 'CDS/B/cb/lmxbdata',\n",
      " 'TIMESTAMP': 1521555687000.0,\n",
      " 'bib_reference': '2003A&A...404..301R',\n",
      " 'cs_service_url': 'http://vizier.u-strasbg.fr/viz-bin/votable/-A?-source=B%2Fcb%2Flmxbdata&',\n",
      " 'data_ucd': ['time.period',\n",
      "              'src.orbital.inclination',\n",
      "              'phot.mag;em.opt.V',\n",
      "              'meta.id',\n",
      "              'phys.mass',\n",
      "              'src.class',\n",
      "              'src.spType',\n",
      "              'pos.eq.dec',\n",
      "              'phys.mass;arith.ratio',\n",
      "              'phys.luminosity;arith.ratio',\n",
      "              'pos.eq.ra'],\n",
      " 'dataproduct_type': 'catalog',\n",
      " 'moc_access_url': 'http://alasky.unistra.fr/footprints/tables/vizier/B_cb_lmxbdata/MOC?nside=2048',\n",
      " 'moc_order': 11.0,\n",
      " 'moc_sky_fraction': 2.066e-06,\n",
      " 'nb_rows': 108.0,\n",
      " 'obs_astronomy_kw': ['Novae', 'Binaries:cataclysmic'],\n",
      " 'obs_collection': 'CV',\n",
      " 'obs_collection_label': ['CB', 'CV'],\n",
      " 'obs_copyright_url': 'http://cdsarc.u-strasbg.fr/viz-bin/Cat?B%2Fcb',\n",
      " 'obs_description': 'Catalogue of Low-Mass X-Ray Binaries',\n",
      " 'obs_description_url': 'http://cdsarc.u-strasbg.fr/viz-bin/Cat?B%2Fcb',\n",
      " 'obs_id': 'B/cb/lmxbdata',\n",
      " 'obs_initial_dec': 32.90817697165526,\n",
      " 'obs_initial_fov': 0.028629053431811713,\n",
      " 'obs_initial_ra': 65.4345703125,\n",
      " 'obs_label': 'lmxbdata',\n",
      " 'obs_release_date': '2010-03-21T13:03:47Z',\n",
      " 'obs_title': 'Cataclysmic Binaries, LMXBs, and related objects (Ritter+, '\n",
      "              '2004) (lmxbdata)',\n",
      " 'publisher_id': 'ivo://CDS',\n",
      " 'tap_tablename': 'viz7.B/cb/lmxbdata',\n",
      " 'vizier_popularity': 3.0,\n",
      " 'web_access_url': 'http://vizier.u-strasbg.fr/viz-bin/VizieR-2?-source=B%2Fcb%2Flmxbdata&'}\n"
     ]
    }
   ],
   "source": [
    "pprint(datasets_d['CDS/B/cb/lmxbdata'].properties)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to get only the datasets ``ID``s, the ``number``\n",
    "of matching datasets or just the ``moc`` resulting from the union of all\n",
    "the mocs of the matching datasets (mocpy object). (See the OutputFormat definition class and its ``format`` type)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Final Request payload before requesting to alasky\n",
      "{'DEC': '32.2',\n",
      " 'RA': '10.8',\n",
      " 'SR': '1.5',\n",
      " 'casesensitive': 'true',\n",
      " 'fmt': 'json',\n",
      " 'get': 'moc',\n",
      " 'intersect': 'overlaps',\n",
      " 'order': 14}\n",
      "{'10': [655471,\n",
      "        655479,\n",
      "        655481,\n",
      "        655482,\n",
      "        655483,\n",
      "        655511,\n",
      "        655515,\n",
      "        655527,\n",
      "        655531,\n",
      "        655553,\n",
      "        655554,\n",
      "        655555,\n",
      "        655650,\n",
      "        655651,\n",
      "        655653,\n",
      "        655654,\n",
      "        655655,\n",
      "        655734,\n",
      "        655735,\n",
      "        656418,\n",
      "        656428,\n",
      "        656430,\n",
      "        656431,\n",
      "        656442,\n",
      "        656532,\n",
      "        656534,\n",
      "        656535,\n",
      "        656584,\n",
      "        656586,\n",
      "        656587,\n",
      "        656614,\n",
      "        656976,\n",
      "        656978,\n",
      "        657022,\n",
      "        657108,\n",
      "        657110,\n",
      "        657116,\n",
      "        657118,\n",
      "        657140,\n",
      "        657928,\n",
      "        657929,\n",
      "        657931,\n",
      "        657956,\n",
      "        657957,\n",
      "        657959,\n",
      "        657977,\n",
      "        657980,\n",
      "        657981,\n",
      "        657983,\n",
      "        658117,\n",
      "        658128,\n",
      "        658129,\n",
      "        658132,\n",
      "        658133,\n",
      "        658280,\n",
      "        658281,\n",
      "        658288,\n",
      "        658289,\n",
      "        658290,\n",
      "        658304,\n",
      "        658305,\n",
      "        658308,\n",
      "        658309,\n",
      "        658512,\n",
      "        658513,\n",
      "        658514,\n",
      "        658520,\n",
      "        658522,\n",
      "        658540,\n",
      "        658542,\n",
      "        658612,\n",
      "        658613,\n",
      "        658614,\n",
      "        658616,\n",
      "        658617,\n",
      "        658618,\n",
      "        658632,\n",
      "        658948,\n",
      "        658949,\n",
      "        658950,\n",
      "        658952,\n",
      "        5199703,\n",
      "        5199709,\n",
      "        5199710,\n",
      "        5199711,\n",
      "        5199729,\n",
      "        5199731,\n",
      "        5199815,\n",
      "        5199821,\n",
      "        5199823,\n",
      "        5201348,\n",
      "        5201349,\n",
      "        5201351,\n",
      "        5201357,\n",
      "        5201359,\n",
      "        5201401,\n",
      "        5201403,\n",
      "        5201748,\n",
      "        5201749,\n",
      "        5201751],\n",
      " '11': [2621871,\n",
      "        2621879,\n",
      "        2621881,\n",
      "        2621882,\n",
      "        2621883,\n",
      "        2621903,\n",
      "        2621914,\n",
      "        2621915,\n",
      "        2621921,\n",
      "        2621922,\n",
      "        2621923,\n",
      "        2622043,\n",
      "        2622053,\n",
      "        2622054,\n",
      "        2622055,\n",
      "        2622057,\n",
      "        2622058,\n",
      "        2622059,\n",
      "        2622101,\n",
      "        2622102,\n",
      "        2622103,\n",
      "        2622105,\n",
      "        2622106,\n",
      "        2622107,\n",
      "        2622117,\n",
      "        2622118,\n",
      "        2622119,\n",
      "        2622121,\n",
      "        2622122,\n",
      "        2622123,\n",
      "        2622209,\n",
      "        2622210,\n",
      "        2622211,\n",
      "        2622575,\n",
      "        2622586,\n",
      "        2622587,\n",
      "        2622590,\n",
      "        2622591,\n",
      "        2622595,\n",
      "        2622598,\n",
      "        2622599,\n",
      "        2622609,\n",
      "        2622610,\n",
      "        2622611,\n",
      "        2622762,\n",
      "        2622763,\n",
      "        2622766,\n",
      "        2622767,\n",
      "        2622778,\n",
      "        2622779,\n",
      "        2622930,\n",
      "        2622931,\n",
      "        2622934,\n",
      "        2622935,\n",
      "        2625676,\n",
      "        2625678,\n",
      "        2625679,\n",
      "        2625690,\n",
      "        2625716,\n",
      "        2625718,\n",
      "        2625719,\n",
      "        2625762,\n",
      "        2625772,\n",
      "        2625774,\n",
      "        2625775,\n",
      "        2626134,\n",
      "        2626314,\n",
      "        2626342,\n",
      "        2626362,\n",
      "        2626448,\n",
      "        2626450,\n",
      "        2626451,\n",
      "        2626460,\n",
      "        2626462,\n",
      "        2626530,\n",
      "        2626536,\n",
      "        2626538,\n",
      "        2626539,\n",
      "        2627916,\n",
      "        2627918,\n",
      "        2628048,\n",
      "        2628050,\n",
      "        2628056,\n",
      "        2628058,\n",
      "        2628080,\n",
      "        2628082,\n",
      "        2628083,\n",
      "        2628568,\n",
      "        2628570,\n",
      "        2628592,\n",
      "        2628594,\n",
      "        2628600,\n",
      "        2631720,\n",
      "        2631721,\n",
      "        2631723,\n",
      "        2631812,\n",
      "        2631813,\n",
      "        2631833,\n",
      "        2631904,\n",
      "        2631905,\n",
      "        2631928,\n",
      "        2631929,\n",
      "        2632449,\n",
      "        2632452,\n",
      "        2632453,\n",
      "        2632464,\n",
      "        2632465,\n",
      "        2633128,\n",
      "        2633129,\n",
      "        2633132,\n",
      "        2633136,\n",
      "        2633137,\n",
      "        2633138,\n",
      "        2633140,\n",
      "        2633141,\n",
      "        2633164,\n",
      "        2633165,\n",
      "        2633168,\n",
      "        2633169,\n",
      "        2633170,\n",
      "        2633172,\n",
      "        2633280,\n",
      "        2633281,\n",
      "        2633284,\n",
      "        2633285,\n",
      "        2633296,\n",
      "        2634060,\n",
      "        2634061,\n",
      "        2634062,\n",
      "        2634084,\n",
      "        2634086,\n",
      "        2634164,\n",
      "        2634165,\n",
      "        2634166,\n",
      "        2634172,\n",
      "        2634176,\n",
      "        2634177,\n",
      "        2634178,\n",
      "        2634184,\n",
      "        2634460,\n",
      "        2634476,\n",
      "        2634480,\n",
      "        2634512,\n",
      "        2634513,\n",
      "        2634514,\n",
      "        2634520,\n",
      "        2634532,\n",
      "        2634534,\n",
      "        2634536,\n",
      "        2634537,\n",
      "        2634538,\n",
      "        2635804,\n",
      "        2635812,\n",
      "        2635813,\n",
      "        2635814,\n",
      "        2635816,\n",
      "        2635817,\n",
      "        2635840,\n",
      "        20798807,\n",
      "        20798811,\n",
      "        20798829,\n",
      "        20798831,\n",
      "        20798833,\n",
      "        20798834,\n",
      "        20798835,\n",
      "        20798909,\n",
      "        20798911,\n",
      "        20798921,\n",
      "        20798923,\n",
      "        20799253,\n",
      "        20799254,\n",
      "        20799255,\n",
      "        20799281,\n",
      "        20799283,\n",
      "        20799289,\n",
      "        20799290,\n",
      "        20799291,\n",
      "        20799397,\n",
      "        20799399,\n",
      "        20799405,\n",
      "        20799407,\n",
      "        20804869,\n",
      "        20804871,\n",
      "        20804877,\n",
      "        20804879,\n",
      "        20804901,\n",
      "        20804903,\n",
      "        20804909,\n",
      "        20804911,\n",
      "        20804997,\n",
      "        20804999,\n",
      "        20805005,\n",
      "        20805007,\n",
      "        20805029,\n",
      "        20805031,\n",
      "        20805400,\n",
      "        20805401,\n",
      "        20805403,\n",
      "        20805425,\n",
      "        20805427,\n",
      "        20805525,\n",
      "        20805527,\n",
      "        20805533,\n",
      "        20805600,\n",
      "        20805601,\n",
      "        20805603,\n",
      "        20806981,\n",
      "        20807000,\n",
      "        20807001,\n",
      "        20807003,\n",
      "        20807028,\n",
      "        20807029,\n",
      "        20807031],\n",
      " '14': [],\n",
      " '6': [2562, 2563, 2568, 2569],\n",
      " '7': [10246, 10247, 10264, 10266, 10281, 10284, 10288],\n",
      " '8': [40971,\n",
      "       40973,\n",
      "       40974,\n",
      "       40975,\n",
      "       40979,\n",
      "       40982,\n",
      "       41032,\n",
      "       41034,\n",
      "       41035,\n",
      "       41060,\n",
      "       41062,\n",
      "       41068,\n",
      "       41070,\n",
      "       41121,\n",
      "       41140,\n",
      "       41141,\n",
      "       41156,\n",
      "       41160,\n",
      "       41161,\n",
      "       41162,\n",
      "       324989,\n",
      "       324991,\n",
      "       325077,\n",
      "       325079,\n",
      "       325085],\n",
      " '9': [163871,\n",
      "       163879,\n",
      "       163883,\n",
      "       163889,\n",
      "       163890,\n",
      "       163891,\n",
      "       163914,\n",
      "       163915,\n",
      "       163932,\n",
      "       163934,\n",
      "       163935,\n",
      "       164106,\n",
      "       164132,\n",
      "       164134,\n",
      "       164135,\n",
      "       164152,\n",
      "       164154,\n",
      "       164155,\n",
      "       164246,\n",
      "       164252,\n",
      "       164254,\n",
      "       164276,\n",
      "       164278,\n",
      "       164284,\n",
      "       164286,\n",
      "       164480,\n",
      "       164481,\n",
      "       164483,\n",
      "       164492,\n",
      "       164493,\n",
      "       164568,\n",
      "       164569,\n",
      "       164632,\n",
      "       164633,\n",
      "       164634,\n",
      "       164652,\n",
      "       164656,\n",
      "       164736,\n",
      "       1299933,\n",
      "       1299934,\n",
      "       1299935,\n",
      "       1299961,\n",
      "       1299963,\n",
      "       1300305,\n",
      "       1300307,\n",
      "       1300313,\n",
      "       1300315,\n",
      "       1300348,\n",
      "       1300349,\n",
      "       1300351]}\n"
     ]
    }
   ],
   "source": [
    "moc = cds.query_region(cds_constraints,\n",
    "                                  OutputFormat(format=OutputFormat.Type.moc,\n",
    "                                               moc_order=14))\n",
    "pprint(moc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result of a mocserver query depends on the OutputFormat object we have passed to the query_region method.\n",
    "If we query for the ``ID``s of the datasets then we get a python list of all the  ``ID``s matching the condition.\n",
    "If a user query for the ``number`` of datasets, he gets an int.\n",
    "If you want all the record of the matching datasets (the ``ID``s plus its properties/fields) you get\n",
    "as we have seen above, a dictionary indexed by the ``ID``s of the datasets and as each value a Dataset object.\n",
    "This Dataset object allows you to query a specific service (if available for this dataset) such as a tap service, a cone search service...\n",
    "\n",
    "The service then returns a VOTable containing all the matching sources of the dataset you have submitted a query. We can see that the dataset `CDS/B/cb/lmxbdata` contains the field `cs_service_url` referring the url of the cone search service for this dataset. To query this service, we call the following command, specifying we want to query the Simple Cone Search service with a cone of center `pos` and of radius `radius`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Table masked=True length=1>\n",
       "_RAJ2000 _DEJ2000    _r      Name   ...   mag1   Orb.Per  SpType2  Refs \n",
       "  deg      deg      deg             ...   mag       d                   \n",
       "float64  float64  float64  bytes12  ... float32  float64   bytes7 bytes4\n",
       "-------- -------- ------- --------- ... ------- --------- ------- ------\n",
       " 11.2033  33.0092 0.87761 0042+3244 ...    18.8 11.600000           Refs"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "votable = datasets_d['CDS/B/cb/lmxbdata'].search(Dataset.ServiceType.cs, pos=(10.8, 32.2), radius=1.5)\n",
    "votable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The returned VOTable shows us why the dataset has been returned by the mocserver : there is a source from that dataset which lies into the cone defined as the spatial constraint for the mocserver query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}