deepSSF

Predicting animal movement with a deep learning step-selection framework.

This package provides the installable implementation of the deepSSF approach in Python. Accompanying tutorials and example code live at the deepSSF project site.

There is a package walkthrough script that outlines an implementation of the functions with some example GPS tracking data (a single water buffalo) and two spatial covariates (NDVI and slope). You can access the script as a Jupyter notebook or as a knitted html in the examples directory. The example script will not download with the package installation, but the GPS and spatial datasets will.

The Python package can be viewed on PyPi.

The paper can be found at:

Forrest, S. W., Pagendam, D., Hassan, C., Potts, J. R., Drovandi, C., Bode, M., & Hoskins, A. J. (2026). Predicting animal movement with deepSSF : A deep learning step selection framework. Methods in Ecology and Evolution, 17(2), 371–391. https://doi.org/10.1111/2041-210x.70136.

Installation (pip only)

If you already have a Python environment that you want to install the package into, install deepSSF with:

pip install deepssf

Development install (editable, with linting and testing tools):

git clone https://github.com/swforrest/deepssf
cd deepssf
pip install -e ".[dev]"

Quick start

import deepssf
print(deepssf.__version__)

Setting up (for users new to Python)

1. Install Miniconda (once, system-wide)

Download and run the installer from the official Miniconda page.

If you click 'Download' towards the top right, the links to download Miniconda are towards the bottom of the page - the links at the top are for the Anaconda Distribution, which has thousands of pacakges and is not necessary to get things up and running initially.

1b. (Optional) Install an IDE (such as VSCode)

Once you have Python and Miniconda installed, you will likely want an interface (‘Integrated Development Environment’, an IDE) to code in (such as RStudio for R users). I use Visual Studio Code, or ‘VS Code’ as I find the functionality similar to RStudio (and as I have become familiar with VS Code I prefer it to RStudio in some ways).

You can download VSCode from here: https://code.visualstudio.com/.

For the commands below, you can use the Terminal directly in VScode (Terminal > New Terminal), or the Terminal/Command Line in Windows or macOS.

2. Create the environment

Think of a conda environment the way you think of an renv project library — it is a self-contained Python installation that keeps this project's packages separate from everything else on your computer. The steps below create one for deepSSF.

Using the Terminal (which can be in VScode), you can clone the package repository with:

git clone https://github.com/swforrest/deepssf_package
cd deepssf
conda env create -f environment.yml

This installs Python 3.11, the geospatial libraries (rasterio / GDAL / PROJ), Jupyter Lab, and the deepSSF package itself with all of its dependencies. PyTorch is installed via pip with no extra flags — pip automatically picks the right build for your hardware: MPS on Apple Silicon, CUDA on NVIDIA GPUs, CPU everywhere else. No configuration is needed; the package selects the correct backend at runtime.

3. Activate the environment

Also in the Terminal:

conda activate deepssf

You will need to run this once per terminal session before using deepSSF.

4. (Optional) Register the Jupyter kernel

If you use VS Code or another editor that manages its own Jupyter kernel list, register the environment so it appears as a kernel option:

python -m ipykernel install --user --name deepssf --display-name "Python (deepssf)"

Then you can open examples/deepssf_train_validate_example.ipynb in VSCode to get started. You can also view the knitted deepssf_train_validate_example.html script, which you should be able to open in a browser such as Chrome.

Documentation

There are additional tutorials and walkthroughs to help understand deep learning concepts and the deepSSF approach, model and functions at: https://swforrest.github.io/deepSSF/

Citation

If you use deepSSF in your research, please cite the paper. See CITATION.cff or use the citation and link to paper below.

Forrest, S. W., Pagendam, D., Hassan, C., Potts, J. R., Drovandi, C., Bode, M., & Hoskins, A. J. (2026). Predicting animal movement with deepSSF : A deep learning step selection framework. Methods in Ecology and Evolution, 17(2), 371–391. https://doi.org/10.1111/2041-210x.70136

License

MIT — see LICENSE.