Skip to content

Latest commit

 

History

History
181 lines (104 loc) · 7 KB

Install.rst

File metadata and controls

181 lines (104 loc) · 7 KB
Raw

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.

Table of Contents

.. todo:: Add comments about how to get to conda in Windows

Step 1: Set up a virtual python environment

MapReader supports python versions 3.8 to 3.10.

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 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 use mapreader):

    python3 -m venv mapreader

  • Activate your virtual environment:

    source mapreader/bin/activate

Step 2: 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 required dependancy.

If you would like to use MapReader's plotting functions, you will need to ensure you have installed the required dependencies for cartopy.

Then, to install cartopy with your mapreader installation, you should install mapreader with the geo optional dependencies (see notes below).

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

Note

Replace pip install mapreader with pip install "mapreader[geo]" if you would like to install cartopy with your mapreader installation.

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 .

Note

Replace pip install -v -e . with pip install -v -e ".[geo]" if you would like to install cartopy with your mapreader installation.

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