guide/01-getting-started/using-the-jupyter-lab-environment.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using the JupyterLab Environment\n",
    "\n",
    "JupyterLab is a modern interactive development environment (IDE) that allows you to work with code, data, and the Jupyter notebook format. Starting with v1.5.0, the ArcGIS API for Python can be used in JupyterLab for a truly powerful development experience.\n",
    "\n",
    "-----\n",
    "\n",
    "![](../../static/img/jlab_workflow.gif)\n",
    "\n",
    "-----\n",
    "\n",
    "\n",
    "JupyterLab builds upon all of the major components of the classic Jupyter Notebook experience (notebooks, terminal, text editor, file browser, ipywidgets, etc.) to create a flexible and powerful user experience. Click [here](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906) or [here](https://github.com/jupyterlab/jupyterlab) to read more about JupyterLab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started\n",
    "\n",
    "## Installation\n",
    "\n",
    "1. Install >=v1.5.0 of the ArcGIS API for Python in a new conda environment. Activate that environment.\n",
    "\n",
    "2. Run the following 2 commands:\n",
    "```\n",
    "jupyter labextension install @jupyter-widgets/jupyterlab-manager\n",
    "jupyter labextension install arcgis-map-ipywidget@1.5.0\n",
    "```\n",
    "\n",
    "    - __IMPORTANT__: replace `1.5.0` with the _exact_ version number of the Python API you have installed.\n",
    "    - You may need to have `npm` and/or `nodejs` installed on your computer and in this environment in order to succesfully complete this step.\n",
    "\n",
    "3. Now that you have set up the arcgis extensions, run `jupyter lab` from the same command prompt to launch an instance of JupyterLab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## File Explorer\n",
    "\n",
    "Just like the classic Jupyter Notebook experience, JupyterLab offers a file explorer to open existing notebooks, create new notebooks, and organize your content. JupyterLab's file explorer is on the left pane of the main view.\n",
    "\n",
    "------\n",
    "\n",
    "![](../../static/img/jlab_file_explorer.gif)\n",
    "\n",
    "------\n",
    "\n",
    "__JupyterLab interacts with the same .ipynb notebook format__. The only difference is the user interface, and the additions of some other external extensions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Windows and Tabs\n",
    "\n",
    "You may notice that Jupyter has a concept of 'windows' and 'tabs', unlike the classic Jupyter Notebook experience. This is a very powerful feature of JupyterLab: you can stack notebooks, place notebooks side by side, organize notebooks by tabs, etc. Simply click and drag any 'tab' as seen below:\n",
    "\n",
    "------\n",
    "\n",
    "![](../../static/img/jlab_navigate_windows.gif)\n",
    "\n",
    "------\n",
    "\n",
    "\n",
    "__Any window can be dragged like this__. JupyterLab lets you view and edit file types such as _.csv_, _.json_, etc. in new windows, as seen above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Cell Utilities\n",
    "\n",
    "Similar to the windows and tabs above, JupyterLab allows users to move cells in a notebook by dragging and dropping them. JupyterLab also supports dragging cells from one notebook to another notebook. Simply click the area to the left of the cell you want to move, and drag it wherever:\n",
    "\n",
    "-----\n",
    "\n",
    "![](../../static/img/jlab_cell_utilities_1.gif)\n",
    "\n",
    "-----\n",
    "\n",
    "JupyterLab also lets you select multiple cells by holding the _Shift_ key. You can move these cells as mentioned before, or right click and select 'Copy Cells' to copy them. JupyterLab has many options in their right click context menu worth exploring, including the 'Create New View For Output' option. This allows you to take __any__ cell output and duplicate it in a new window, allowing you to stack it, view it side-by-side, etc.\n",
    "\n",
    "-----\n",
    "\n",
    "![](../../static/img/jlab_cell_utilities_2.gif)\n",
    "\n",
    "------\n",
    "\n",
    "There are other cool things you can do with cells in JupyterLab not described in this guide, keep on exploring!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Integration with the Map Widget\n",
    "\n",
    "v1.5.0 of the ArcGIS API for Python introduces many new exciting features for the Map Widget, including 2D rotation, 3D mode, 3D renderer support, and more. You can read [this guide page](../advanced-map-widget-useage) for more information about these other features of the new widget: this guide will highlight the map widget's seamless JupyterLab integration.\n",
    "\n",
    "-----\n",
    "\n",
    "![](../../static/img/jlab_widget_1.gif)\n",
    "\n",
    "----\n",
    "\n",
    "\n",
    "The `MapView` class's default view behavior is the same as in the classic Jupyter Notebook environment: the widget is displayed it in a cell's output area. However, you may notice a new UI button that is only visible in a JupyterLab environment:\n",
    "\n",
    "<img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gcUAAIIxu7mQQAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAABI0lEQVRYw+1Wy3GDMBTch3JLBanA+TQR0gDz4JB0Y1xISkBAA4EqHOeYU6qAzYVkPAyWYSLii/Ymzb63q89qBAQEXBgyNamquYhs5zSw1v72SNOUp3gkd2VZ5uP5K1dzkrslqxnzRWQD4MVV4zQw5XguP8uyDckGwBeAm1M10Rrnqqq3fd+3JEVEYhc3WkMcQDMM46IoPv7NQJIkdyLS/oiXZXk4VxP5FDfGNEvEz17Cuciy7J7kGwB0XRfXdX0Yp+NoZ/waGMQbABzE35ekKfIkDhF5mhJf7Q6o6sOReFwUxd7BzdM0ffR5BALglaQAiK21eydZZEsSAFpfBkjy2Rhz7Vr5qimoqurTR4JWeYqDgWDAWwpUNb+ogbn/woCAgL/gG9knfWwKBGcvAAAAAElFTkSuQmC\"> \n",
    "\n",
    "By pressing this button, your widget will move from your cell's output area into a new window. This window can be tabbed, split, etc. like all other windows. If you want to restore the widget to the notebook it originated from, press this button:\n",
    "\n",
    "<img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gcUAAYsnoHHlAAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAABG0lEQVRYw+2WMVLDMBBF/9q+BBUlAS5hn8BeqQk1B8HcBgpLowtgnyJwGWtTkFAEOzIgkmHQLzXjeW9nV2sBKSn/PTR1yMwtET3EBInIo7W2PTwvQh9FqfJIMUcFpoy/E6XUrEB27hlIAkngxwJa65umaS7PIsDMt977gYie55ZaKMXM4hhEJFi5iLy87yu5ByDRBIwxA4AhAO93spUxZnOyFtR1fb2rHERUdV23iT6ESqmSmdspeJ7nfSz4rICIlIc/EGZe7eHjOEaBL24BM68AfMCdc6+x9kDxFbiIlM65t5MtIq311R4OoLLWRoUHBUSkJyLJsqz8DfiSFlwAePLe3zHz5ENl6rZEnQEAa6JPW7Zd8txKSfkT2QKASXQbvOVu9AAAAABJRU5ErkJggg==\">\n",
    "\n",
    "Try this for yourself! If you're reading this guide in a JupyterLab setting, run the below cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from arcgis.gis import GIS\n",
    "\n",
    "#Create a map widget like you have done many times before\n",
    "gis = GIS()\n",
    "map = gis.map()\n",
    "map"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### WebMaps and WebScenes\n",
    "\n",
    "WebMap and WebScene Objects include this same UI button: run the two below cells to try for yourself!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from arcgis.mapping import WebMap\n",
    "webmap_item = gis.content.get(\"ab42b088573d4253a22a8b38ee698ccd\")\n",
    "webmap = WebMap(webmap_item)\n",
    "webmap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from arcgis.mapping import WebScene\n",
    "webscene_item = gis.content.get(\"421433baeb8d487b903d4a89df79149b\")\n",
    "webscene = WebScene(webscene_item)\n",
    "webscene"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Controlling New Windows Programatically\n",
    "\n",
    "Although you just drove this cool new window functionality with your mouse, you still are using __Python__: what sort of Python API would this be if we didn't provide you the option to control this functionality programmatically?!\n",
    "\n",
    "Each instances of a `MapView` widget has a `tab_mode` property and a `toggle_window_view()` method. Setting `tab_mode` will change how the map widget goes into a new window. Try running the below cells to experiment with this behavior:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#First, draw a map\n",
    "map = gis.map()\n",
    "map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Set the tab mode to one of the below options, run the cell, then press the 'new window' button\n",
    "#map.tab_mode = \"split-bottom\"\n",
    "#map.tab_mode = \"split-right\"\n",
    "#map.tab_mode = \"auto\"\n",
    "#map.tab_mode = \"tab-after\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After a map is displayed, you can call the `toggle_window_view()` method to move the map to a new window. You can then call this method while the widget is already in a new window to restore the widget to the original notebook. (i.e., each call to this method is the functional equivalent of pressing the button). Try running the below cells:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from arcgis.widgets import MapView\n",
    "#First, draw a map\n",
    "map = MapView(gis=gis)\n",
    "map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Run this cell a few times in a row\n",
    "map.toggle_window_view()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also programatically specify the `title` (text displayed on the tab) and `tab_mode` in each method call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#First, draw a map\n",
    "map = gis.map(mode=\"3D\")\n",
    "map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Run this cell to move it in a new window\n",
    "map.toggle_window_view(title=\"My 3D Map\", tab_mode=\"split-top\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Then, run this cell to move it back to the notebook\n",
    "map.toggle_window_view()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Run this cell to cycle through all tab_modes\n",
    "tab_modes = ['auto', 'split-top' 'split-bottom', 'split-left',\n",
    "             'split-right', 'tab-before', 'tab-after']\n",
    "for tab_mode in tab_modes:\n",
    "    #to new window\n",
    "    map.toggle_window_view(title=tab_mode, tab_mode=tab_mode)\n",
    "    time.sleep(4)\n",
    "    #to original notebook\n",
    "    map.toggle_window_view()\n",
    "    time.sleep(4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This functionality can be very powerful in many ways: Say you have a list of 3 or more WebScene items, and you want to display them all in new tabs in 1 cell call. You would write something like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Run this cell, it works!\n",
    "from arcgis.gis import GIS\n",
    "from arcgis.widgets import MapView\n",
    "gis = GIS()\n",
    "for webscene_id in ['31874da8a16d45bfbc1273422f772270',\n",
    "                    '91b46c2b162c48dba264b2190e1dbcff',\n",
    "                    '46c47340708f446ba7f112f139e8ae5e']:\n",
    "    webscene_item = gis.content.get(webscene_id)\n",
    "    map = MapView(gis=gis, item=webscene_item, mode=\"3D\") \n",
    "    map.toggle_window_view(title=webscene_item.title, tab_mode='tab-after')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "See [the API reference](https://esri.github.io/arcgis-python-api/apidoc/html/arcgis.widgets.html#arcgis.widgets.MapView.toggle_window_view) for more information on programatic control of the Map Widget."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Conclusion\n",
    "\n",
    "JupyterLab implements many features you can leverage right now to make the most of your experience with the ArcGIS API for Python. Try it out, and please [leave us a comment, suggest a feature, or report a bug](https://github.com/Esri/arcgis-python-api/issues/new)! We look forward to seeing what you will create in JupyterLab!"
   ]
  }
 ],
 "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.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}