{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "This guide is intended for those who are using CARTOframes for the first time and provides the steps to install it **locally**, in a **Jupyter Notebook**, or using a **Virtual Environment**. You need **Python 3** to use CARTOframes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install CARTOframes using `pip`\n",
    "\n",
    "CARTOframes can be installed with [`pip`](https://pypi.org/project/pip/) by simply typing one of the following commands to do a system install:\n",
    "\n",
    "To install the package:\n",
    "\n",
    "```bash\n",
    "pip install cartoframes\n",
    "```\n",
    "\n",
    "To upgrade the package to the latest version:\n",
    "\n",
    "```bash\n",
    "pip install --upgrade cartoframes\n",
    "```\n",
    "\n",
    "To install a specific version:\n",
    "\n",
    "```bash\n",
    "pip install cartoframes==1.x.y\n",
    "```\n",
    "\n",
    "#### Optional dependencies\n",
    "\n",
    "- [RTree](https://github.com/Toblerity/rtree) is a spatial index package to improve performance and required for overlay operations. It provides an interface to [libspatialindex](https://github.com/libspatialindex/libspatialindex)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use a Jupyter Notebook\n",
    "\n",
    "In the CARTOframes Developer Center, all of the examples are created with [Jupyter Notebooks](https://jupyter.org/). If you aren't familiar with Jupyter Notebooks, we recommend reading the [beginner documentation](https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html) to get familiar with the environment.\n",
    "\n",
    "To install CARTOframes through a Jupyter Notebook, run this command:\n",
    "\n",
    "```bash\n",
    "pip install cartoframes\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use a Virtual Environment\n",
    "\n",
    "We recommend installing CARTOframes in a [Virtual Environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/), since they are very useful when working with Python locally. This section provides the necessary information to create a simple Virtual Environment and install CARTOframes inside of it:\n",
    "\n",
    "```bash\n",
    "$ virtualenv cartoframes_env\n",
    "$ source cartoframes_env/bin/activate\n",
    "(cartoframes_env) $ pip install cartoframes\n",
    "```\n",
    "\n",
    "When the virtual environment is activated, it is visible in the command line prompt, in this case: `(cartoframes_env)`. It can be deactivated by typing `deactivate` to exit the virtualenv:\n",
    "\n",
    "```bash\n",
    "(cartoframes_env) $ deactivate\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use Jupyter Lab\n",
    "\n",
    "Jupyter Lab does not install by default some requirements we need in this version of CARTOframes, so it requires to run also:\n",
    "\n",
    "```bash\n",
    "pip install ipywidgets\n",
    "jupyter labextension install @jupyter-widgets/jupyterlab-manager\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Metrics\n",
    "\n",
    "We collect data on your usage of CARTOframes to understand how you use it and use this information to improve the product. Usage data includes information like \"map_created,\" which tells us the date and time you created a map. The usage data we collect is anonymous, does not allow us to see the contents of what you're working on, and is handled in accordance with our Privacy Notice <https://carto.com/privacy/> .\n",
    "You may choose to opt out by calling `cartoframes.utils.setup_metrics(False)`."
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}