doc/source/tutorial/tutorial_combine_arrays.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Combining arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the LArray library:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from larray import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load the 'demography_eurostat' dataset\n",
    "demography_eurostat = load_example_data('demography_eurostat')\n",
    "\n",
    "# load 'gender' and 'time' axes\n",
    "gender = demography_eurostat.gender\n",
    "time = demography_eurostat.time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load the 'population' array from the 'demography_eurostat' dataset\n",
    "population = demography_eurostat.population\n",
    "\n",
    "# show 'population' array \n",
    "population"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load the 'population_benelux' array from the 'demography_eurostat' dataset\n",
    "population_benelux = demography_eurostat.population_benelux\n",
    "\n",
    "# show 'population_benelux' array \n",
    "population_benelux"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The LArray library offers several methods and functions to combine arrays:\n",
    "\n",
    "- [insert](../_generated/larray.Array.insert.rst#larray.Array.insert): inserts an array in another array along an axis\n",
    "- [append](../_generated/larray.Array.append.rst#larray.Array.append): adds an array at the end of an axis.\n",
    "- [prepend](../_generated/larray.Array.prepend.rst#larray.Array.prepend): adds an array at the beginning of an axis.\n",
    "- [extend](../_generated/larray.Array.extend.rst#larray.Array.extend): extends an array along an axis.\n",
    "- [stack](../_generated/larray.stack.rst#larray.stack): combines several arrays along a new axis.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Insert"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "other_countries = zeros((Axis('country=Luxembourg,Netherlands'), gender, time), dtype=int)\n",
    "\n",
    "# insert new countries before 'France'\n",
    "population_new_countries = population.insert(other_countries, before='France')\n",
    "population_new_countries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# insert new countries after 'France'\n",
    "population_new_countries = population.insert(other_countries, after='France')\n",
    "population_new_countries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [insert](../_generated/larray.Array.insert.rst#larray.Array.insert) for more details and examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Append\n",
    "\n",
    "Append one element to an axis of an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# append data for 'Luxembourg'\n",
    "population_new = population.append('country', population_benelux['Luxembourg'], 'Luxembourg')\n",
    "population_new"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The value being appended can have missing (or even extra) axes as long as common axes are compatible:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population_lux = stack({'Male': -1, 'Female': 1}, gender)\n",
    "population_lux"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population_new = population.append('country', population_lux, 'Luxembourg')\n",
    "population_new"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The value being appended can also have the axis along which we are appending:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population_nelux = population_benelux[['Netherlands', 'Luxembourg']]\n",
    "population_nelux"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "population_extended = population.append('country', population_nelux)\n",
    "population_extended"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [append](../_generated/larray.Array.append.rst#larray.Array.append) for more details and examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prepend\n",
    "\n",
    "Prepend one element to an axis of an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# append data for 'Luxembourg'\n",
    "population_new = population.prepend('country', population_benelux['Luxembourg'], 'Luxembourg')\n",
    "population_new"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [prepend](../_generated/larray.Array.prepend.rst#larray.Array.prepend) for more details and examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Stack\n",
    "\n",
    "Stack several arrays together to create an entirely new dimension\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# imagine you have loaded data for each country in different arrays \n",
    "# (e.g. loaded from different Excel sheets)\n",
    "population_be = population['Belgium']\n",
    "population_fr = population['France']\n",
    "population_de = population['Germany']\n",
    "\n",
    "print(population_be)\n",
    "print(population_fr)\n",
    "print(population_de)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create a new array with an extra axis 'country' by stacking the three arrays population_be/fr/de\n",
    "population_stacked = stack({'Belgium': population_be, 'France': population_fr, 'Germany': population_de}, 'country')\n",
    "population_stacked"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [stack](../_generated/larray.stack.rst#larray.stack) for more details and examples."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}