Installation Instructions
Note
Run these commands from your terminal.
There are three steps to setting up MapReader. You should choose one method within each step and follow the instructions for that method.
Note
You do not need to use the same method between steps. i.e. It is completely fine to follow Method 1 for Step 1 and Method 2 for Step 2.
Step 1: Set up a virtual python environment
MapReader requires python version 3.7+.
Method 1: Using conda (recommended)
We recommend installing MapReader using either Anaconda (installation instructions here) or miniconda (installation instructions here). A discussion of which of these to choose can be found here.
Once you have installed either Ananconda or miniconda, open your terminal and use the following commands to set up your virtual python environment:
Create a new conda environment for
mapreader
(you can call this whatever you like, we usemapreader
):conda create -n mapreader python=3.8
This will create a conda enviroment which uses python version 3.8.
Activate your conda environment:
conda activate mapreader
Method 2: Using venv or other
If you would like not to use conda, you are more than welcome to set up a virtual python environment using other methods.
For example, if you would like to use venv, open your terminal and use the following commands to set up your virtual python environment:
First, importantly, check which version of python your system is using:
python3 --version
If this returns a version below 3.7, you will need download an updated python version. You can do this by downloading from here (make sure you download the right one for your operating system).
You should then run the above command again to check your python version has updated.
Create a new virtual python environment for
mapreader
(you can call this whatever you like, we usemapreader
):python3 -m venv mapreader
Activate your virtual environment:
source mapreader/bin/activate
Step 2: Install MapReader
Method 1: Install from PyPI
If you want to use the latest stable release of MapReader and do not want/need access to the worked examples or MapReader code, we recommend installing from PyPI. This is probably the easiest way to install MapReader.
Install
mapreader
:pip install mapreader
Method 2: Install from source
If you want to keep up with the latest changes to MapReader, or want/need easy access to the worked examples or MapReader code, we reccommend installing from source.
This method will create a MapReader
directory on your machine which will contain all the MapReader code, docs and worked examples.
Note
You will need to have git installed to use this method. If you are using conda, this can be done by running conda install git
. Otherwise, you should install git by following the instructions on their website.
Clone the
mapreader
source code from the MapReader GitHub repository:git clone https://github.com/Living-with-machines/MapReader.git
Install
mapreader
:cd MapReader pip install -v -e .
Method 3: Install via conda (EXPERIMENTAL)
If neither of the above methods work, you can try installing MapReader using conda. This method is still in development so should be avoided for now.
Install MapReader directly from the conda package:
conda install -c anothersmith -c conda-forge -c defaults --override-channels --strict-channel-priority mapreader
Note
The conda package seems to be sensitive to the precise priority of the conda channels, hence the use of the –override-channels –strict-channel-priority switches is required for this to work. Until this is resolve this installation method will be marked “experimental”.
Step 3: Add virtual python environment to notebooks
To allow the newly created python virtual environment to show up in jupyter notebooks, run the following command:
python -m ipykernel install --user --name mapreader --display-name "Python (mr_py)"
Note
if you have used a different name for your python virtual environment replace the mapreader
with whatever name you have used.
Troubleshooting
M1 mac
If you are using an M1 mac and are having issues installing MapReader due to an error when installing numpy or scikit-image:
Try separately installing the problem packages (edit as needed) and then installing MapReader:
pip install numpy==1.21.5 pip install scikit-image==0.18.3 pip install mapreader
Try using conda to install the problem packages (edit as needed) and then pip to install MapReader:
conda install numpy==1.21.5 conda install scikit-image==0.18.3 pip install mapreader
Alternatively, you can try using a different version of openBLAS when installing:
brew install openblas OPENBLAS="$(brew --prefix openblas)" pip install mapreader
Cartopy
Cartopy is used by MapReader’s download subpackage to plot maps and geospatial data. It is not essential to the functioning of MapReader and so is not listed as a dependancy.
If you would like to use MapReader’s plotting functions, you should download cartopy by following the instructions here.
Note
There are some required dependencies which you may need to install first. These are listed here.