{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Aggregations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the LArray library:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from larray import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load the `population` array and related axes from the `demography_eurostat` dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load the 'demography_eurostat' dataset\n",
    "demography_eurostat = load_example_data('demography_eurostat')\n",
    "\n",
    "# extract the 'country', 'gender' and 'time' axes\n",
    "country = demography_eurostat.country\n",
    "gender = demography_eurostat.gender\n",
    "time = demography_eurostat.time\n",
    "\n",
    "# extract the 'population_5_countries' array as 'population'\n",
    "population = demography_eurostat.population_5_countries\n",
    "\n",
    "# show the 'population' array\n",
    "population"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The LArray library provides many aggregation functions. The list is given in the [Aggregation Functions](../api.rst#aggregation-functions) subsection of the [API Reference](../api.rst) page.\n",
    "\n",
    "Aggregation operations can be performed on axes or groups. Axes and groups can be mixed. \n",
    "\n",
    "The main rules are: \n",
    "\n",
    "-  Axes are separated by commas ``,``\n",
    "-  Groups belonging to the same axis are grouped inside parentheses ()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calculate the sum along an axis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population.sum(gender)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or several axes (axes are separated by commas ``,``):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population.sum(country, gender)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calculate the sum along all axes except one by appending `_by` to the aggregation function:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population.sum_by(time)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calculate the sum along groups (the groups belonging to the same axis must grouped inside parentheses ()):\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "benelux = population.country['Belgium', 'Netherlands', 'Luxembourg'] >> 'benelux'\n",
    "fr_de = population.country['France', 'Germany'] >> 'FR+DE'\n",
    "\n",
    "population.sum((benelux, fr_de))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mixing axes and groups in aggregations:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population.sum(gender, (benelux, fr_de))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "**Warning:** Mixing slices and individual labels inside the `[ ]` will generate **several groups** (a tuple of groups) instead of a single group.<br>If you want to create a single group using both slices and individual labels, you need to use the `.union()` method (see below).\n",
    "  \n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# mixing slices and individual labels leads to the creation of several groups (a tuple of groups)\n",
    "except_2016 = time[:2015, 2017]\n",
    "except_2016"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# leading to potentially unexpected results\n",
    "population.sum(except_2016)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# the union() method allows to mix slices and individual labels to create a single group\n",
    "except_2016 = time[:2015].union(time[2017])\n",
    "except_2016"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population.sum(except_2016)"
   ]
  }
 ],
 "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}