05-xWCPS_intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img style=\"float: right;\" src=\"./img/es2_logo_tiny.jpg\"></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 05-Extension to the WCPS core: XPath-Enabled WCPS (xWCPS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"./04-WCPS_intro.ipynb\"><< 04-WCPS_extension</a>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space> <a href=\"./06-Ressources.ipynb\">06-Ressources>></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why xWCPS?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "xWCPS created to offer additional features to the WCPS service described in the [previous tutorial](./04-WCPS_intro.ipynb).\n",
    "These features consist of:\n",
    "\n",
    "* <b><a style=\"font-size:110%; color:black;\"> Coverage Identification Based on Metadata </a></b>  \n",
    "One of the fundamental operations a query language must offer is that of querying for all data residing in the database without prior knowledge of their internal representation. WCPS requires the specification of coverage identifiers in selection queries. \n",
    "xWCPS is introduced to fill this gap offering a unified language by combining two already well known standards, WCPS and XPath 2.0, aiming at being rich, expressive and user friendly. \n",
    "In the following query all coverages from the \"access.planetserver.eu\" service will be encoded in 'png' format and returned as a result.\n",
    "\n",
    ">**Example**: *<br /> for \\$c in /server[@endpoint='http://access.planetserver.eu:8080/rasdaman/ows']/coverage <br />\n",
    "          return encode(\\$c, \"png\")*\n",
    "\n",
    "* <b><a style=\"font-size:110%; color:black;\">Exploitation of Descriptive Metadata</a></b>  \n",
    "Coverage filtering based on the available metadata using XPath 2.0. For and where clauses can contain XPath 2.0 expressions in order to restrict results to specific metadata.\n",
    "\n",
    ">**Example**: *<br /> for \\$c in /server/coverage <br /> metadata(\\$c)\\$c//gml:cat_solar_longitude[text()>86.122] <br /> return encode(\\$c, \"png\")*\n",
    "\n",
    "* <b><a style=\"font-size:110%; color:black;\">Repetitiveness Reduction</a></b>  \n",
    "xWCPS supports variable manipulation via 'let' clause, which allows assigning complex expressions to variables and using them for subsequent references, avoiding repetitiveness.\n",
    "\n",
    ">**Example**: *<br /> let \\$value = 85; <br /> for \\$c in /server/coverage <br /> where metadata(\\$c)\\$c//gml:cat_solar_longitude[text()>\\$value] <br /> return encode(\\$c, \"png\")*\n",
    "\n",
    "* <b><a style=\"font-size:110%; color:black;\">Extended Set of Results Support</a></b>  \n",
    "An important feature of xWCPS is the ability to return the data accompanied with their metadata. This can be achieved using the 'mixed' clause of xWCPS.\n",
    "\n",
    ">**Example**: *<br /> for \\$c in /server/coverage <br /> return mixed(encode(\\$c, \"png\", metadata(\\$c))*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## XPath-Enabled Web Coverage Processing Service (xWCPS) requests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A xWCPS quer consists of three components:\n",
    "\n",
    "* **For** variableName **in** <font color=\"green\">for expression</font>,\n",
    "* **where** <font color=\"red\">where expression</font> (optional)\n",
    "* **return** <font color=\"blue\">return expression</font>.\n",
    "\n",
    "Moreover may contain variable declaration (via **let** clause) anywhere in a query.   \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " \n",
    "> <font color=\"green\">For expression</font> may contain:  \n",
    "* List of coverage ids\n",
    "* XPath 2.0 expression (ex. specific endpoints)\n",
    "\n",
    ">> Examples: \n",
    "+ for coverage in (coverageId1, coverageId2, ... )\n",
    "+ for coverage in /server/coverage\n",
    "+ for coverage in /server[@endpoint='http://access.planetserver.eu:8080/rasdaman/ows']/coverage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> <font color=\"red\">Where expression</font> may contain:  \n",
    "* Metadata expression\n",
    "* XPath 2.0 expression\n",
    "\n",
    ">> Example: where metadata(c)//gml:cat_solar_longitude[text()<86.0122]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> <font color=\"blue\">Return expression</font> may contain:  \n",
    "* Metadata expression\n",
    "* XPath 2.0 expression\n",
    "* Mixed function\n",
    "\n",
    ">> Examples: \n",
    "* return metadata(c)\n",
    "* return metadata(c)//gml:cat_solar_longitude\n",
    "* return mixed(encode (return {red: 0; green: 0; blue: 128} ,\"png\"), metadata(c))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id=xwcps_examples></a>Examples: xWCPS requests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following examples show a variety of xWCPS queries that can be applied to the data of a WCS Server, when metadata are harvested and stored in database. Examples are based on the following services: \n",
    "http://access.planetserver.eu:8080/rasdaman/ows and https://rsg.pml.ac.uk/rasdaman/ows\n",
    "\n",
    "- [Basic xWCPS request](#basic_xwcps)\n",
    "- [xWCPS request with Xpath on For/Where Clause](#xpath_for_where_xwcps)\n",
    "- [xWCPS request with Xpath on Return Clause](#xpath_return_xwcps)\n",
    "- [xWCPS request with Mixed Result](#xpath_mixed_result)\n",
    "\n",
    "All requests can be executed in http://earthserver-devel.vhosts.cite.gr/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='basic_xwcps'></a><font color=\"black\">Basic xWCPS requests</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Retrieve metadata from a specific coverage with id **CCI_V2_monthly_rrs_670** \n",
    "\n",
    ">for \\$c in ( CCI_V2_monthly_rrs_670 ) return metadata(\\$c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Retrieve metadata for **all** available coverages\n",
    "\n",
    ">for \\$c in /server/coverage return metadata(\\$c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='xpath_for_where_xwcps'></a><font color=\"black\">Xpath Filtering on For/Where Clause</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Get metadata of all coverages **on endpoint \"https://rsg.pml.ac.uk/rasdaman/ows\"**\n",
    "\n",
    ">for \\$c in /server[@endpoint='https://rsg.pml.ac.uk/rasdaman/ows']/coverage return metadata(\\$c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Retrieve metadata for all coverages **on endpoint \"http://access.planetserver.eu:8080/rasdaman/ows\"** that have **gml:cat_solar_longitude attribute less than 86.0122**\n",
    "\n",
    ">for \\$c in /server[@endpoint='http://access.planetserver.eu:8080/rasdaman/ows']/coverage where metadata(\\$c)//gml:cat_solar_longitude[text()<86.0122] return metadata(\\$c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='xpath_return_xwcps'></a><font color=\"black\">xWCPS request with Xpath on Return Clause</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Get value of **gml:cat_solar_longitude** for all coverages **on endpoint \"http://access.planetserver.eu:8080/rasdaman/ows\"** that have **gml:cat_solar_longitude attribute less than 86.0122**\n",
    "\n",
    ">for \\$c in /server[@endpoint='http://access.planetserver.eu:8080/rasdaman/ows']/coverage <br /> where metadata(\\$c)//gml:cat_solar_longitude[text()<86.0122] return metadata(\\$c)//gml:cat_solar_longitude"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='xpath_mixed_result'></a><font color=\"black\">xWCPS request with Mixed Result</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Get a mixed value containing the image of coverage with id \"frt0000cc22_07_if165l_trr3\" and all its metadata\n",
    "\n",
    ">for data in (frt0000cc22_07_if165l_trr3) return mixed(encode( { red: (int)(255 / (max((data.band_233 != 65535) \\* data.band_233) - min(data.band_233))) \\* (data.band_233 - min(data.band_233)); green: (int)(255 / (max((data.band_13 != 65535) \\* data.band_13) - min(data.band_13))) \\* (data.band_13 - min(data.band_13)); blue: (int)(255 / (max((data.band_78 != 65535) \\* data.band_78) - min(data.band_78))) \\* (data.band_78 - min(data.band_78)) ; alpha: (data.band_100 != 65535) \\* 255}, \"png\", \"nodata=null\"), metadata(data))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a rel=\"license\" href=\"http://creativecommons.org/licenses/by-nc/4.0/\"><img style=\"float: right;\" alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-nc/4.0/88x31.png\" /></a>"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}