{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Aggregating subannual timeseries data\n",
    "\n",
    "The **pyam** package offers many tools to facilitate processing of scenario data.\n",
    "In this notebook, we illustrate methods to aggregate timeseries data that is given at a sub-annual resolution using timeslices (seasons, representative days, etc.).\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "The features for working with subannual time resolution are still in an experimental status.\n",
    "The functions illustrated in this tutorial are operational and tested, but other tools such as the plotting library may not work as expected (yet) when working with subannual data.\n",
    "\n",
    "</div>\n",
    "\n",
    "## Overview\n",
    "\n",
    "This notebook illustrates the following features:\n",
    "\n",
    "0. Import data from file and inspect the scenario\n",
    "1. Aggregate timeseries data given at a sub-annual time resolution to a yearly value\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 0. Import data from file and inspect the scenario\n",
    "\n",
    "The stylized scenario used in this tutorial has data for primary-energy timeseries for two subannual timeslices `summer` and `winter`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyam import IamDataFrame\n",
    "\n",
    "df = IamDataFrame(data=\"tutorial_data_subannual_time.csv\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.timeseries()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Aggregating timeseries across sub-annual timesteps\n",
    "\n",
    "Per default, the [aggregate_time()](https://pyam-iamc.readthedocs.io/en/stable/api.html#pyam.IamDataFrame.aggregate_time) function\n",
    "aggregates (by summation) the data from all sub-annual timesteps (given in the column `subannual`) to a `year` value.\n",
    "\n",
    "The function returns an **IamDataFrame**, so we can use [timeseries()](https://pyam-iamc.readthedocs.io/en/stable/api.html#pyam.IamDataFrame.timeseries) to display the resulting data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.aggregate_time(\"Primary Energy\").timeseries()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function also supports directly appending the aggregated data to the original **IamDataFrame**.\n",
    "You can also pass a a list of variables, or call [variables()](https://pyam-iamc.readthedocs.io/en/stable/api.html#pyam.IamDataFrame.variables) to perform the aggregation on all timeseries data.\n",
    "\n",
    "A user can also manually set the \"target\" sub-annual value and the components to be aggregated;\n",
    "for example, this can then be used to process an aggregate of hourly data to monthly values.\n",
    "\n",
    "You will notice that the following cell returns a larger dataset compared to calling the same function above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.aggregate_time(\n",
    "    df.variable, value=\"year\", components=[\"summer\", \"winter\"], append=True\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.timeseries()"
   ]
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}