Installation

It is strongly recommended to install and use conda for environment management, as some of MGSurvE’s dependencies might clash with specific packages versions. These installation instructions assume conda is already installed in the target system.

Local Installation

MGSurvE makes use of some external dependencies to make the most of its capabilities. Some of these, such as DEAP, are strict requirements but others are optional, such as:

cartopy: needed for geographical landscapes plots and manipulations (not needed if we will be working with Euclidean landscapes but highly recommended nevertheless)
libpysal: not strictly required by MGSurvE but useful if we wanted to do more complex point-sampling operations
osmnx: not required but pretty useful for interacting with OpenStreetMap data

Taking this into account, we provide some alternatives we have tested to get MGSurvE setup. The core software is installed by following the Uneventful Base Installation, whereas installing the package with all the dependencies is achieved through the Additional Dependencies and Installation Mishaps or Bulletproof Installation Method, as described in this webpage. Finally, if everything described before fails, we can download a Docker Image following the docker set of instructions.

Uneventful Base Installation

Create a clean python=3.9 environment:

conda create -n MGSurvE python="3.9" -y

Activate the environment, and install MGSurvE using pip:

conda activate MGSurvE
pip install MGSurvE

If this ran correctly, try importing the package from the terminal with:

python
import MGSurvE as srv

If cartopy or libpysal are not currently installed, we will get a warning that we can safely ignore (see the next section for more info); but if any of these steps resulted in an error, let’s have a look at the next section in this installation guide.

Additional Dependencies, and Installation Mishaps

Sometimes, either DEAP, libpysal, or cartopy decide not to play nicely. For these cases, the following procedure might help.

In a fresh environment on python=3.9 (or one in which the installation of MGSurvE failed), run the following commands to install DEAP:

conda install deap -y

Now, let’s install cartopy (for geo-features plotting), and libpysal (to generate poisson-distributed pointsets). The easiest way to install these dependencies is through anaconda:

conda install cartopy -y
conda install libpysal -y

With these packages installed, we can proceed and install MGSurvE:

pip install MGSurvE

which should be enough to get us started. If this installation fails, or if import MGSurvE fails on python, we might need to have a look at the next section.

Bulletproof Installation Method

If either of these approaches is failing, try the following chain of commands:

conda create -n MGSurvE python="3.10"
conda activate MGSurvE
conda update -n base -c defaults conda
conda config --add channels conda-forge
conda config --add channels bioconda
conda install gdal fiona pyproj cartopy libpysal -y
conda install -c conda-forge deap nodejs osmnx basemap-data-hires -y
pip install MGSurvE

In case this method still fails, please have a look at the installation instructions on: DEAP, cartopy, and libpysal; before installing MGSurvE.

Docker

An alternative way to get MGSurvE running is to download the latest Docker image.

To get started with this approach, install Docker on your system. Then, go to our Docker image hub and get the latest tag to pull from it. For example:

docker pull chipdelmal/mgsurve

And then run it in interactive mode:

docker run -it chipdelmal/mgsurve bash

We can check that MGSurvE is correctly installed with its dependencies by running:

python
import MGSurvE

Which should run without any error or warnings. To quit our python session, we simply type exit() into the interpreter, and we exit the docker promt by typing exit.