{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "# A OOP approach to hierarchically indexed data tables \n",
    "This notebook defines the schema and relations that will be implemented to facilitate the workflows projecting global data sets on a hierarchical index and manipulating different layers together. \n",
    "Mainly, this approach aims to solve the following challenges:\n",
    "- User friendly : ideally have a familiar sytax to pandas users\n",
    "- Scalable : be able to work with national, continetal and even global data sets of fine spatial resolution (ex: 100m,1000m grids)\n",
    "- Flexible : it should provide a easily exportable type of data to use across different types of processes and analyses.\n",
    "\n",
    "The main tools chosen to do this are : \n",
    "\n",
    "* Using H3 : https://uber.github.io/h3-py/\n",
    "* Using DuckDB : https://duckdb.org/docs/guides/python/execute_sql \n",
    "* Using ibis : https://ibis-project.org \n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Base workflow\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One of the main contributions of this workflow is a method to efficiently project raster grids of any size into a format that is more efficient to work with and perform geometric operations with other types. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Minimal input\n",
    "\n",
    "[ polars.DataFrame, pyarrow.Table, pandas.DataFrame, geopandas.GeoDataFrame(not recommended), ibis.table ]\n",
    "\n",
    "WIth non ambiguous columns for the coordinates, ex ('x','y'), ('lon','lat') etc .... and variables containing numeric values with a suffix *var* or containing categorical values with suffix *cat* preceding the actual column name *{band}*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "| lon   | lat   | {band}_var  |    ...        |\n",
    "|-------|-------|-------------|---------------|\n",
    "| float | float | [float,int] | ...   |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "| lon   | lat   | {band}_cat | ... |\n",
    "|-------|-------|----------|-----|\n",
    "| float | float | str      | ... |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Minimal output\n",
    "\n",
    "The data is projected to the h3 grid for a resolution which is refered to later on as the native resolution. It should be the highest possible resolution that makes sense for a given data layer. For example for points data, any resolution is possible, and the choise will most likely depend on the type of processing that is done with it. \n",
    "In the case of polygons, a resolution high enough to give a good description of the original shape, but coarse enough to be efficient to work with. Once again, this is context specific and will most likely depend on the type of analysis.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "| lon   | lat   | {band}_cat | ... | h3_id     |\n",
    "|-------|-------|----------|-----|-----------|\n",
    "| float | float | str      | ... | [str,int] |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "| lon   | lat   | {band}_var  |    ... |   h3_id   |\n",
    "|-------|-------|-------------|--------|-----------|\n",
    "| float | float | [float,int] | ...    | [str,int] |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A mix of the two previous tyopes of numeric or categorical variables can be present as long as the *coordinates* and *h3_id* columns are unambiguiously identified. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The object to which the data is associated contains additional attributes and methods descrbed next:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Attributes\n",
    "- base_res : base resolution, the original resolution into which the data was projected on the h3 grid\n",
    "- current_res : current resolution, the resolution in which the data currently is after potential processing. \n",
    "### Methods\n",
    "- set_res(res) : int(4,18), set the resolution of the data to a specifed one.\n",
    "- change_res(level) : int, change the resolution of the data by a value provided. the reuslting resolution will be equal to *current_res*+*level*\n",
    "- add_layer()"
   ]
  }
 ],
 "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.12.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}