doc/source/tutorial/tutorial_string_syntax.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pythonic VS String Syntax"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the LArray library:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from larray import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The LArray library offers two syntaxes to build axes and make selections and aggregations.\n",
    "The first one is more ``Pythonic`` (uses Python structures) \n",
    "For example, you can create an *age_category* axis as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "age_category = Axis([\"0-9\", \"10-17\", \"18-66\", \"67+\"], \"age_category\")\n",
    "age_category"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second one consists of using ``strings`` that are parsed.\n",
    "It is shorter to type. The same *age_category* axis could have been generated as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "age_category = Axis(\"age_category=0-9,10-17,18-66,67+\")\n",
    "age_category"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "  **Warning:** The drawback of the string syntax is that some characters such as `, ; = : .. [ ] >>`\n",
    "have a special meaning and cannot be used with the ``String`` syntax. \n",
    "If you need to work with labels containing such special characters (when importing data from an external source for example), you have to use the ``Pythonic`` syntax which allows to use any character in labels.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## String Syntax"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Axes And Arrays creation\n",
    "\n",
    "The string syntax allows to easily create axes.\n",
    "\n",
    "When creating one axis, the labels are separated using ``,``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = Axis('a=a0,a1,a2,a3')\n",
    "a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The special syntax ``start..stop`` generates a sequence of labels:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = Axis('a=a0..a3')\n",
    "a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When creating an array, it is possible to define several axes in the same string using ``;``"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "arr = zeros(\"a=a0..a2; b=b0,b1; c=c0..c5\")\n",
    "arr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selection\n",
    "\n",
    "Starting from the array: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "immigration = load_example_data('demography_eurostat').immigration\n",
    "immigration.info"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "an example of a selection using the ``Pythonic`` syntax is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# since the labels 'Belgium' and 'Netherlands' also exists in the 'citizenship' axis, \n",
    "# we need to explicitly specify that we want to make a selection over the 'country' axis\n",
    "immigration_subset = immigration[X.country['Belgium', 'Netherlands'], 'Female', 2015:]\n",
    "immigration_subset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the ``String`` syntax, the same selection becomes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "immigration_subset = immigration['country[Belgium,Netherlands]', 'Female', 2015:]\n",
    "immigration_subset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Aggregation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An example of an aggregation using the ``Pythonic`` syntax is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "immigration.sum((X.time[2014::2] >> 'even_years', X.time[::2] >> 'odd_years'), 'citizenship')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the ``String`` syntax, the same aggregation becomes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "immigration.sum('time[2014::2] >> even_years; time[::2] >> odd_years', 'citizenship')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where we used ``;`` to separate groups of labels from the same axis."
   ]
  }
 ],
 "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
}