🚲 From 0 to EOmaps - a quickstart guide

The following section is intended to provide a quick overview on how to get started using EOmaps.

The guide is intended to be concise and covers only the most important information to get things running. Links to websites that provide additional information are provided throughout the text.

Note

This tutorial is intended to get you up and running from scratch as fast as possible using 100% free and open-source tools. It does not cover alternative ways on how to setup python or how to use alternative editors etc.

Feel free to start a discussion of open an issue if you have additional questions or suggestions!

Prerequisites:

  • A computer (Windows / MacOS / Linux) - no root access required

  • basics on how to work with a terminal

  • basic python knowledge

Getting started - set up a python environment

There are of course many ways to set up a python environment… in the following, we will use the (free and open-source) conda package manager which greatly simplifies the creation of environments that depend on both python and c++ libraries (A lot of python-packages for geo-libraries are just bindings to c++ libraries such as GDAL or PyProj).

conda is available for MacOS, Windows and Linux. For more details, see conda-docs .

The fastest way to get started is to use miniconda, a minimalistic installer that includes only conda, python and a minimal set of additional packages.

TODO (~10 min)

Download and install the latest version of miniconda from:

https://docs.conda.io/en/latest/miniconda.html

After the installation is finished, open a Anaconda Prompt terminal (if you need help, see “starting conda” ).

By default, the terminal starts in the conda-environment base (you should see the name in brackets on the left).

Before creating a new dedicated python-environment, we’ll first install mamba into the base environment to speedup the installation process. (for details on mamba, have a look at the mamba-docs !)

  • NOTE: The use of mamba is optional (but highly recommended)! If you don’t want to use it, just replace the term mamba with conda in all subsequent commands.

TODO (~1 min) install mamba:

Install mamba from the conda-forge channel with the following command (in the Anaconda Prompt terminal):

conda install -c conda-forge mamba

Now that mamba is installed, we can use it to create a new python environment, and install the following packages:

  • As editor to write and execute python-code we will use the awesome (free and open-source) spyder-IDE

  • in addition, we install eomaps and matplotlib (the latter is only required to make sure matplotlib backends such as Qt5Agg are installed)

    • all required dependencies will be automatically determined and installed during the process

TODO (~15 min, ~500mb) setup environment:

Setup a new python environment named eomaps and install EOmaps and the spyder IDE.

mamba create -n eomaps -c conda-forge spyder eomaps matplotlib

Once the list of required packages is determined, confirm the installation with y and wait until it is completed.

Finally, all that’s left to do is to activate the environment and start the editor!

TODO (~1 min) activate environment, start and setup the spyder IDE:

To activate the environment, use:

conda activate eomaps

After activating the environment, we can start the spyder IDE with:

spyder

As a last step, we need to adjust the default plot-settings of the spyder IDE to make sure that matplotlib plots are generated as interactive widgets

  • By default, plots are rendered as static images into the “plots-pane”… to avoid this and create interactive matplotlib widgets instead, go to the preferences, select the IPython console section and set the Graphics backend to Automatic :

_images/spyder_preferences.png

Now you’re ready for your first map! -> head over to 🗺 EOmaps examples and run one of the example-codes!

A few quick spyder IDE tips:

In spyder you will work with an interactive IPython console. This allows you to dynamically execute parts of a script and immediately see the outcome.

  • use F9 to execute the selected code (or the current line if nothing is selected)

  • use F5 to execute the current script (e.g. the whole file)

  • use shift + enter to execute the currently selected code-block (code-blocks are separated by # %%)