geocompy

Geocomputation with Python is an open source book project that will be
published as a physical book. We are developing it in the open and
publishing an up-to-date online version at https://py.geocompx.org.

Dependencies

Running the code that is part of Geocomputation with Python (geocompy
for short) requires the following dependencies to be installed:

1. Python dependencies, which can be installed with
   pip, a package manager or a
   Docker container (see below)
2. An integrated development environment (IDE) such as VS
   Code (running locally or on
   Codespaces/other
   host) or Jupyter
   Notebook for
   running and exploring the Python code interactively
3. Quarto, which is used to
   generate the book

Reproduce the book with GitHub Codespaces

GitHub Codespaces minimise
set-up costs by providing access to a modern IDE (VS Code) plus
dependencies in your browser. This can save time on package
installation. Codespaces allow you to make and commit changes, providing
a way to test changes and contribute fixes in an instant.

To run the book in Codespaces, click on the link below.

You should see
something like this, the result of running all the code in the book by
opening the terminal (e.g. with the command Ctrl+J) and entering the
following command:

quarto preview

Reproduce the book with Docker (devcontainer)

If you can install Docker
this is likely to be the quickest way to reproduce the contents of this
book. To do this from within VS Code:

1. Install Microsoft’s official Dev
   Container
   extension
2. Open the folder containing the repo in VS Code and click on the
   ‘Reopen in container’ button that should appear, as shown below (you
   need to have Docker installed on your computer for this to work)

Edit the code in the containerised instance of VS Code that will appear
🎉

See details below for other ways to get the dependencies and reproduce
the book.

Install dependencies with pip

Use pip to install the dependencies as follows, after cloning the repo
and opening a terminal in the root folder of the repo.

First we’ll set-up a virtual environment to install the dependencies in:

# Create a virtual environment called geocompy
python -m venv geocompy
# Activate the virtual environment
source geocompy/bin/activate

Then install the dependencies (with the optional
python -m
prefix specifying the Python version):

# Install dependencies from the requirements.txt file
python -m pip install -r requirements.txt

You can also install packages individually, e.g.:

pip install jupyter-book

Deactivate the virtual environment when you’re done:

deactivate

Install dependencies with a package manager

The environment.yml file contains a list of
dependencies that can be installed with a package manager such as
conda, mamba or micromamba. The instructions below are for
micromamba
but should work for any package manager.

# For Linux, the default shell is bash:
curl -L micro.mamba.pm/install.sh | bash
# For macOS, the default shell is zsh:
curl -L micro.mamba.pm/install.sh | zsh

After answering the questions, install dependencies with the following
command:

micromamba env create -f environment.yml

Activate the environment as follows:

micromamba activate geocompy

Install kernel, this will allow you to select the environment in vscode
or IPython as follows:

python -m ipykernel install --user

You can now reproduce the book (requires quarto to be installed):

micromamba run -n geocompy quarto preview

Reproduce chapters with jupyter

VS Code’s quarto.quarto plugin can Python code in the chunks in the
.qmd files in this book interactively.

However, you can also run any of the chapters in a Jupyter Notebook,
e.g. as follows:

cd ipynb
# jupyter notebook . # open a notebook showing all chapters
jupyter notebook 02-spatial-data.ipynb

You should see something like this:

See documentation on running and developing Python code in a Jupyter
notebook at docs.jupyter.org.

Additional information

If you’re interested in how to auto-generate and run the .py and .ipynb
files from the .qmd files, see below.

Updating the .py and .ipynb files

The Python scripts and IPython notebook files stored in the code
and ipynb folders are generated from the .qmd files. To
regenerate them, you can use the following commands, to generate .ipynb
and .py files for local versions of Chapter 2, for example:

quarto convert 02-spatial-data.qmd # generate .ipynb file
jupytext --to py *.ipynb # generate .py files .ipynb files

Do this for all chapters with the following bash script in the repo:

./convert.sh

Updating .py and .ipynb files with GitHub Actions

We have set-up a GitHub Action to do this automatically: every commit
message that contains the text string ‘convert’ will create and push
updated .ipynb and .py files.

Executing the .py and .ipynb files

Running the code chunks in the .qmd files in an IDE such as VSCode or
directly with quarto is the main way code in this book is designed to be
run interactively, but you can also execute the .py and .ipynb files
directly. To run the code for chapter 2, for example, you can run one of
the following commands from your system shell:

python code/chapters/02-spatial-data.py # currently requires manual intervention to complete, see #71
ipython ipynb/02-spatial-data.ipynb # currently requires manual intervention to complete, see #71
bash ./run-code.sh # run all .python files

Updating packages

We pin package versions in the environment.yml and
requirements.txt files to ensure reproducibility.

To update the requirements.txt run the following:

python -m pip install pur
pur -r requirements.txt
python -m pip install -r requirements.txt

To update the environment.yml file in the same way based on your newly
installed packages, run the following:

micromamba list export > environment.yml