{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "a586d9f1-59a1-4359-9954-bf807c8d1cd6",
   "metadata": {},
   "source": [
    "# Introduction to Unfolded Map SDK\n",
    "\n",
    "[![open_in_colab][colab_badge]][colab_notebook_link]\n",
    "[![open_in_binder][binder_badge]][binder_notebook_link]\n",
    "\n",
    "[colab_badge]: https://colab.research.google.com/assets/colab-badge.svg\n",
    "[colab_notebook_link]: https://colab.research.google.com/github/foursquare/unfolded-sdk-examples/blob/master/notebooks/01%20-%20Introduction.ipynb\n",
    "[binder_badge]: https://mybinder.org/badge_logo.svg\n",
    "[binder_notebook_link]: https://mybinder.org/v2/gh/foursquare/unfolded-sdk-examples/master?urlpath=lab/tree/notebooks/01%20-%20Introduction.ipynb"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83d160e4-f70a-4cb8-9d70-1e90a8768d4f",
   "metadata": {},
   "source": [
    "This notebook demonstrates how to create a local Unfolded map and then how to add a simple dataset to it."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e107ed78",
   "metadata": {},
   "source": [
    "## Dependencies\n",
    "\n",
    "This notebook requires the following Python dependencies:\n",
    "\n",
    "- `unfolded.map-sdk`: The Unfolded Map SDK\n",
    "- `sidecar`: Jupyter sidecar widget to allow rendering Unfolded Studio in a sidebar.\n",
    "- `pandas`: DataFrame library\n",
    "\n",
    "If running this notebook in Binder, these dependencies should already be installed. If running in Colab, the next cell will install these dependencies."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fa03764d",
   "metadata": {},
   "outputs": [],
   "source": [
    "# If in Colab, install this notebook's required dependencies\n",
    "import sys\n",
    "if \"google.colab\" in sys.modules:\n",
    "    !pip install 'unfolded.map_sdk>=1.0' sidecar pandas"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa4d57c9",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9f4507a6",
   "metadata": {},
   "outputs": [],
   "source": [
    "from unfolded.map_sdk import create_map\n",
    "from sidecar import Sidecar\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89f042b9",
   "metadata": {},
   "source": [
    "## Creating a Map"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d5b1840-09b8-4f7f-81a3-5327eab9ee9f",
   "metadata": {},
   "source": [
    "First, let's create a map instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6252a03d-7e1f-4218-a7c1-55d0bef9f6a5",
   "metadata": {},
   "outputs": [],
   "source": [
    "unfolded_map = create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a67e292-55d5-4db9-bd5a-5ea95625b6eb",
   "metadata": {},
   "source": [
    "In environments that support Jupyter Widgets, such as Jupyter Notebook, JupyterLab, and Google Colab, simply put the map variable as the last or only line in a cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "83ba1569-854a-44d4-b384-b50eeea58823",
   "metadata": {},
   "outputs": [],
   "source": [
    "unfolded_map"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf1ff946-85f4-46ca-9dab-e90ceeb3194a",
   "metadata": {},
   "source": [
    "In Jupyter Lab we also have the option of displaying a map as a separate side pane using the [`Sidecar`](https://github.com/jupyter-widgets/jupyterlab-sidecar) package. In other environments than Jupyter Lab, using `sidecar` will probably not work."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f14794d3-b596-4568-ad6b-4005cd3e472f",
   "metadata": {},
   "outputs": [],
   "source": [
    "sc = Sidecar(title='Unfolded Map', anchor='split-right')\n",
    "with sc:\n",
    "    display(unfolded_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34c2509f-ed30-40b5-86b0-54857a45eeff",
   "metadata": {},
   "source": [
    "## Adding data"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c494832a-3bbc-4bb5-b599-73edf41c14c8",
   "metadata": {},
   "source": [
    "We can now add a dataframe as a dataset to the map: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "93c4b4ca-5842-44b5-a8c4-7edf96b64929",
   "metadata": {},
   "outputs": [],
   "source": [
    "unfolded_map.add_dataset({\n",
    "    'data': pd.DataFrame({\n",
    "        'City': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],\n",
    "        'Country': ['Argentina', 'Brazil', 'Chile', 'Colombia', 'Venezuela'],\n",
    "        'Latitude': [-34.58, -15.78, -33.45, 4.60, 10.48],\n",
    "        'Longitude': [-58.66, -47.91, -70.66, -74.08, -66.86]\n",
    "    })\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f2b85d5d-f55c-42e7-aeeb-a59a7ab20cd0",
   "metadata": {},
   "source": [
    "## Set view state"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf5e6eba-f34a-4d3c-a19a-9d9a8a648df8",
   "metadata": {},
   "source": [
    "Now let's change the map viewport to better see the data points we just added:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73bdcdb6-6301-47e0-841d-93a919d49abd",
   "metadata": {},
   "outputs": [],
   "source": [
    "unfolded_map.set_view({\n",
    "    'longitude': -60, \n",
    "    'latitude': -20,\n",
    "    'zoom': 2\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ad0ec00-39e3-47ff-be7c-de1e9789f046",
   "metadata": {},
   "source": [
    "There are many more things you can control in Unfolded maps via the SDK. Check out the rest of the examples in this directory."
   ]
  }
 ],
 "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.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}