Metadata-Version: 2.4
Name: deepSSF
Version: 0.2.3
Summary: Deep learning step selection functions for predicting animal movement.
Project-URL: Homepage, https://swforrest.github.io/deepSSF/
Project-URL: Repository, https://github.com/swforrest/deepssf
Project-URL: Paper, https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.70136
Author-email: Scott Forrest <scottwforrest@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: animal-movement,deep-learning,ecology,ssf,step-selection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: imageio>=2.28
Requires-Dist: ipykernel>=6.0
Requires-Dist: jupyterlab>=4.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: rasterio>=1.3
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: ipykernel>=6.0; extra == 'examples'
Requires-Dist: jupyterlab>=4.0; extra == 'examples'
Description-Content-Type: text/markdown

# 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](https://swforrest.github.io/deepSSF/). 

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](https://github.com/swforrest/deepSSF_package/tree/main/examples) directory. The example script will not download with the package installation, but the GPS and spatial datasets will.

![](icons/both_icons.png)

The Python package can be viewed on [PyPi](https://pypi.org/project/deepSSF/).

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](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:

```bash
pip install deepssf
```

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

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

## Quick start

```python
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](https://docs.anaconda.com/miniconda/).

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/](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:

```bash
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:

```bash
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:

```bash
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](LICENSE).
