README.md

ARCHIVED: This repo will not be updated with new changes to the MapReader code.

Spatial Humanities Mapreader Workshop 2024

This repo contains a worked example of running MapReader, designed for the Spatial Humanities conference 2024.

Follow the instructions below to set up the notebook on Google Colab (recommended), in Docker or locally.

Table of contents

• Set up - Google Colab (short version)
• Detailed instructions for setting up on Google Colab
  • Optional: Change the runtime type
• Set up - Docker
  • Creating the Docker image
  • Running the Docker container
• Set up - Local

Set up - Google Colab (short version)

If you are familiar with Google Colab, you can set up the notebook by following these steps. If you are new to Google Colab, please refer to the detailed instructions below.

• Open Google Colab
• In the "Open notebook" window, click the "GitHub" option
• Paste the URL of this repository into the search bar and press Enter
• Open mapreader-spatial-humanities-workshop.ipynb

Detailed instructions for setting up on Google Colab

1. In your browser, navigate to Google Colab.

   An "Open notebook" window should appear automatically. If it doesn't, click File > Open notebook....

   

2. In the "Open notebook" window, click the "GitHub" option:

   

3. Paste the URL of this repository into the search bar and press Enter.

   

4. After pressing Enter, a list of notebooks in the repository should appear. Click on mapreader-spatial-humanities-workshop.ipynb to open it.

   

5. The notebook should now be opened and look like this:

   

   Note that Google may display a warning that the notebook is not authored by Google. You can ignore this warning.

   

6. You can now run the notebook by clicking the play button on the left of each cell.

   Note that the first cell will install all requirements for the notebook to run. It will take some time, and will display some warnings. Those can be ignored. At the bottom, you will see a message that the installation was successful.

   

Optional: Change the runtime type

By default, Google Colab uses a CPU runtime. If you want to use a GPU runtime, you can change this by clicking Runtime > Change runtime type and selecting GPU from the Hardware accelerator dropdown.

1. Click Runtime > Change runtime type.

   

2. In the "Change runtime type" window, select GPU from the Hardware accelerator dropdown. Click Save to apply the changes.

   

   After you save the changes, the runtime will be changed to GPU and the core needs to be restarted. Click OK to restart the runtime.

   

3. The runtime type should now be changed to GPU.

   

Set up - Docker

Creating the Docker image

Clone the repository and navigate to the root directory of the repository.

git clone https://github.com/maps-as-data/spatial-humanities-mapreader-workshop
cd spatial-humanities-mapreader-workshop

To create the Docker image, run the following command:

docker build -t mapreader-workshop .

Running the Docker container

To run the Docker container, run the following command:

docker run -p 8888:8888 --mount source=workshop_outputs,target=/app mapreader-workshop

Click the link that appears in the terminal to open the notebook in your browser.

Set up - Local

To run the notebook locally, follow the instructions here to set up your MapReader python environment.

You can then install the required packages for this notebook by running:

pip install -r requirements.txt

You can then run the notebook by running:

jupyter notebook mapreader-spatial-humanities-workshop.ipynb