{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "t3-header",
   "metadata": {},
   "source": [
    "# Tutorial 3: Open Two Panels with 2D-1D Interactions\n",
    "\n",
    "This tutorial shows how to create a coupled 2D + 1D panel setup where interacting with the 2D map panel updates the 1D time-series panel."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-intro",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "Scivianna supports **cross-panel interactions** where selecting a region on the 2D map panel triggers updates in the 1D panel. This is useful for:\n",
    "- Showing a geographic map with time-series data that updates when you click on a country\n",
    "- Linking spatial selection to temporal data visualization\n",
    "- Synchronizing multiple views of the same dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-setup",
   "metadata": {},
   "source": [
    "## Step 1: Basic Setup\n",
    "\n",
    "Import the necessary modules and configure the panels using the Europe Grid example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t3-setup-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scivianna.slave import ComputeSlave\n",
    "from scivianna.panel.panel_2d import Panel2D\n",
    "from scivianna.panel.panel_1d import Panel1D\n",
    "from scivianna.layout.split import SplitLayout, SplitItem, SplitDirection\n",
    "from scivianna.enums import UpdateEvent\n",
    "from pathlib import Path\n",
    "\n",
    "# Import the Europe Grid interfaces\n",
    "from scivianna_example.europe_grid.europe_grid import EuropeGridInterface\n",
    "from scivianna_example.europe_grid.country_time_series import CountryTimeSeriesInterface"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-panel-creation",
   "metadata": {},
   "source": [
    "## Step 2: Create the 2D Map Panel\n",
    "\n",
    "Create a `ComputeSlave` with the `EuropeGridInterface` and configure the 2D panel to display a geographic map of Europe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t3-2d-panel-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the ComputeSlave for the 2D map\n",
    "slave_map = ComputeSlave(EuropeGridInterface)\n",
    "\n",
    "# Load the time series data linked to the map\n",
    "time_series_path = str(Path(__file__).parent.parent / 'src' / 'scivianna_example' / 'europe_grid' / 'time_series.csv')\n",
    "slave_map.read_file(time_series_path, \"TimeSeries\")\n",
    "\n",
    "# Create the 2D panel (map)\n",
    "map_panel = Panel2D(\n",
    "    slave=slave_map,\n",
    "    name=\"Map\",\n",
    "    display_polygons=True,\n",
    ")\n",
    "\n",
    "# Set the field to display (e.g., 'solar_pv')\n",
    "map_panel.set_field(\"solar_pv\")\n",
    "\n",
    "# Configure update event for mouse cell changes\n",
    "map_panel.sync_field = True\n",
    "\n",
    "print(f\"2D Panel field: {map_panel.field}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-1d-panel",
   "metadata": {},
   "source": [
    "## Step 3: Create a 1D Panel for Time-Series\n",
    "\n",
    "Create a separate `ComputeSlave` with the `CountryTimeSeriesInterface` for the 1D time-series panel. This panel will display data for the selected country."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t3-1d-panel-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the ComputeSlave for time series data\n",
    "slave_result = ComputeSlave(CountryTimeSeriesInterface)\n",
    "slave_result.read_file(time_series_path, \"TimeSeries\")\n",
    "\n",
    "# Create the 1D panel (plot)\n",
    "line_panel = Panel1D(\n",
    "    slave=slave_result,\n",
    "    name=\"Plot\",\n",
    ")\n",
    "\n",
    "# Set update event to react when the selected cell changes in the 2D map\n",
    "line_panel.update_event = UpdateEvent.MOUSE_CELL_CHANGE\n",
    "line_panel.sync_field = True\n",
    "line_panel.set_field(\"solar_pv\")\n",
    "\n",
    "print(f\"1D Panel update event: {line_panel.update_event}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-coupled-layout",
   "metadata": {},
   "source": [
    "## Step 4: Create a Coupled Layout\n",
    "\n",
    "Combine the 2D map panel and 1D time-series panel in a `SplitLayout`. The `sync_field` setting ensures both panels stay synchronized on the selected field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t3-coupled-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the split layout (vertical arrangement: map on top, plot below)\n",
    "split_item = SplitItem(\n",
    "    panel_1=map_panel,\n",
    "    panel_2=line_panel,\n",
    "    direction=SplitDirection.VERTICAL,\n",
    ")\n",
    "\n",
    "# Create the coupled layout with additional interfaces\n",
    "coupled_layout = SplitLayout(\n",
    "    split_item,\n",
    "    additional_interfaces={\n",
    "        \"EuropeGrid\": EuropeGridInterface,\n",
    "        \"TimeSeries\": CountryTimeSeriesInterface\n",
    "    },\n",
    ")\n",
    "\n",
    "# Display the layout\n",
    "coupled_layout"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-interaction-demo",
   "metadata": {},
   "source": [
    "### How the Interaction Works\n",
    "\n",
    "When you **click on a country** in the 2D map panel:\n",
    "1. The `MOUSE_CELL_CHANGE` event is triggered with the selected country's cell ID\n",
    "2. The 1D panel receives this update and queries the time-series data for that country\n",
    "3. The plot updates to show the time-series for the selected country\n",
    "\n",
    "The `sync_field = True` setting ensures both panels use the same field (e.g., `solar_pv`)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t3-summary",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this tutorial, you learned:\n",
    "1. How to create a 2D map panel using `EuropeGridInterface` with polygon display\n",
    "2. How to create a 1D time-series panel using `CountryTimeSeriesInterface`\n",
    "3. How to configure update events (`MOUSE_CELL_CHANGE`) to link panels together\n",
    "4. How to use `SplitLayout` to arrange multiple panels in a coupled layout\n",
    "5. How cross-panel interactions work: clicking a country on the map updates the time-series plot\n",
    "\n",
    "## Key Components Used\n",
    "\n",
    "- **`EuropeGridInterface`**: Handles 2D geographic data for European countries\n",
    "- **`CountryTimeSeriesInterface`**: Handles time-series data for countries\n",
    "- **`Panel2D`**: Displays the geographic map with country polygons\n",
    "- **`Panel1D`**: Displays time-series plots for selected regions\n",
    "- **`SplitLayout`**: Combines panels in a vertical or horizontal arrangement\n",
    "\n",
    "## Next Steps\n",
    "\n",
    "- [Tutorial 4: Developing an Interface (Dev)](./4_develop_interface.ipynb)\n",
    "- [Tutorial 5: Developing an Extension (Dev)](./5_develop_extension.ipynb)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}