Metadata-Version: 2.4
Name: deepSSF
Version: 0.1.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

Deep learning step selection functions for predicting animal movement.

This package provides the reusable, installable implementation of the deepSSF
method. The accompanying paper, tutorials, and reproducibility code live at the
[deepSSF project site](https://swforrest.github.io/deepSSF/).

## 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).
