{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Installation\n", "\n", "This guide is intended for those who are using CARTOframes for the first time. It covers:\n", "- The **Python version** required\n", "- How to install it using **pip**\n", "- How to install it in a **Jupyter Notebook**\n", "- How to install it in **Windows**\n", "- How to create a **Virtual Enviroment**\n", "- Considerations in **Jupyter Lab**\n", "- Metrics\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.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Python version required\n", "\n", "CARTOframes needs Python 3 to work properly. You can check your version by running:\n", "\n", "```\n", "python --version\n", "```\n", "\n", "You should get some output like Python 3.6.3. If you do not have Python, please install the latest 3.x version from [python.org](https://python.org/) or refer to the [Installing Python](http://docs.python-guide.org/en/latest/starting/installation/) section of the Hitchhiker’s Guide to Python." ] }, { "cell_type": "markdown", "metadata": { "heading_collapsed": true }, "source": [ "### Install it 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 dependency\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": [ "### Install it in 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": [ "### Install it in Windows\n", "\n", "In order to work properly, CARTOframes needs that [Shapely](https://github.com/Toblerity/Shapely) and [Fiona](https://github.com/Toblerity/Fiona) libraries are already installed in your system. Execute these commands to install CARTOframes correctly:\n", "\n", "```bash\n", "pip install shapely\n", "conda install -c conda-forge fiona\n", "pip install cartoframes\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Use a Virtual Environment\n", "\n", "This section provides the necessary information to create a simple Virtual Environment with virtualenv and conda and also how to 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", "\n", "#### Conda users\n", "\n", "Let's see how to achieve it with conda.\n", "\n", "```bash\n", "$ conda create --name cartoframes_env\n", "$ conda activate cartoframes_env\n", "(cartoframes_env) $ pip install shapely\n", "(cartoframes_env) $ conda install -c conda-forge fiona\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) $ conda deactivate\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 .\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 }