Metadata-Version: 2.4
Name: deepSSF
Version: 0.2.1
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 manage your own Python environment, 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)

If you are coming from R, 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 and should take about five minutes.

### 1. Install Miniconda (once, system-wide)

Download and run the installer from the
[official Miniconda page](https://docs.anaconda.com/miniconda/).

- **Windows**: use the **Anaconda Prompt** for all subsequent commands, and
  choose an install path that contains **no spaces** (e.g. `C:\miniconda3`).
- **macOS / Linux**: a normal terminal works fine.

> **Miniforge alternative**: if you prefer to avoid Anaconda's default channel
> entirely, [Miniforge](https://github.com/conda-forge/miniforge) is a
> drop-in replacement that ships with `conda-forge` as the only channel.

### 2. Create the environment

```bash
git clone https://github.com/swforrest/deepssf
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

```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)"
```

### 5. Launch Jupyter Lab

```bash
jupyter lab
```

Then open `examples/deepssf_train_validate_example.ipynb` to get started.

---

## Documentation

Tutorials and walkthroughs: 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).
