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 

The most recent version of MapReader supports python versions 3.9+.

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 use mapreader):
```
conda create -n mapreader
```
This will create a conda enviroment for you to install MapReader and its dependencies into.
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.9, 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 use mapreader):
```
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 .
```

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

Installation Instructions

Method 1: Install from PyPI

Method 1: Install from PyPI 