Blame for README.md

---
language: en
license: other
license_name: deepethogram-academic-noncommercial
license_link: LICENSE
library_name: deepethogram
tags:
- deepethogram
- pytorch
- optical-flow
- animal-behavior
- kinetics
- pretrained
- legacy-archive
---

# DeepEthogram pretrained models — legacy archive

For new projects, use the **[individual model repositories in the DeepEthogram collection](https://huggingface.co/collections/jbohnslav/deepethogram-pretrained-models-6ad61e8af1ac368c56d8deec)**.
Each usable model has its own card, architecture/task tags, checkpoint and checksum manifest.
This repository preserves the historical bundle for compatibility and archival use.

Archived pretrained weights for [DeepEthogram](https://github.com/jbohnslav/deepethogram),
a pipeline for supervised behavior classification from raw video pixels.
These weights initialize optical-flow and feature-extractor training on your own behavior dataset.
They are not ready-to-use classifiers for your behavior labels. No videos, datasets, or trained
sequence classifiers are included.

## Download

Install the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/guides/cli), then download
into an existing DeepEthogram project's `models` directory:

```bash
hf download jbohnslav/deepethogram-pretrained --revision v1.0 --local-dir /path/to/your_project/models
```

The resulting layout must be `your_project/models/pretrained_models/<run>/...`.
Preserve the run names and nested `flow`/`spatial` directories. Downloading the full repository also
includes this card, the license, and `SHA256SUMS` in the destination directory.
For reproducible downloads, pass `--revision` with a release tag or commit ID.

Verify the model files from that directory:

```bash
cd /path/to/your_project/models
shasum -a 256 -c SHA256SUMS
```

Use the DeepEthogram GUI or training commands to select the pretrained weights. Models retain
the original PyTorch checkpoint format; use DeepEthogram rather than Transformers to load them.

## Contents

The archive contains 30 files (2,058,618,150 bytes). `SHA256SUMS` records the SHA-256 checksum of every archived file. Original checkpoints, YAML hyperparameters, model
definitions, HDF5 metrics, and TIFF training plots are retained without conversion.

| Run | Component | Architecture | Status |
| --- | --- | --- | --- |
| `200221_115158_TinyMotionNet` | Flow generator | TinyMotionNet | Checkpoint present |
| `200310_174416_MotionNet_kinetics` | Flow generator | MotionNet | Checkpoint present |
| `200313_125331_TinyMotionNet3D_kinetics` | Flow generator | TinyMotionNet3D | Checkpoint present |
| `200409_101808_hidden_two_stream_kinetics_degs` | DEG-s feature extractor | ResNet3D-34 | Flow-classifier checkpoint only; incomplete |
| `200410_142156_hidden_two_stream_kinetics_degm` | DEG-m feature extractor | ResNet50 | Full and separate stream checkpoints present |
| `200415_125824_hidden_two_stream_kinetics_degf` | DEG-f feature extractor | ResNet18 | Full and separate stream checkpoints present |

## Training and intended use

The historical configuration files identify Kinetics700 as the pretraining dataset and specify
700 classes for feature extractors. The three flow models provide motion estimates; feature
extractors combine appearance and motion. Fine-tune on your own labeled videos, then train a
sequence model to classify your behaviors. Keep training, validation, and test videos separate.

Historical hyperparameters describe the original training environment and contain old filesystem
paths and YAML serialization tags. They are provenance records, not portable project configs.
The archived `.pt` files use legacy PyTorch serialization.

## Validation

Using PyTorch 2.4.1 and DeepEthogram source revision
`1541eec6958f90673b79c402e10b434c8cb7c868`, all five discoverable models loaded with strict
state-dict matching and produced finite outputs on synthetic CPU inputs. The two feature
extractors returned 700-class outputs. All five nested flow/spatial classifier checkpoints
were readable and contained finite tensors. These checks verify file and architecture
compatibility, not behavior-classification accuracy.

## Known limitations

- The DEG-s folder has `flow/checkpoint.pt` but no top-level checkpoint or spatial checkpoint.
  DeepEthogram's current model discovery skips this incomplete feature extractor. This release
  provides three discoverable flow generators and the DEG-m/DEG-f feature extractors.
  The [individual DEG-s release](https://huggingface.co/jbohnslav/deepethogram-deg-s)
  provides a complete checkpoint.
- DEG-f has no `classification_metrics.h5`; the legacy folders use `hyperparameters.yaml`,
  rather than `config.yaml`. Some inference helpers require newer run files. Use this bundle
  for pretraining initialization and use the new run produced by fine-tuning for inference.
- No task-specific behavior class names, thresholds, or sequence model are supplied.
- The publication's behavior-classification results describe trained pipelines and datasets;
  they are not benchmark scores for this archive alone.

## License and citation

The accompanying [LICENSE](LICENSE) reproduces the DeepEthogram repository's Harvard
Academic and Non-Commercial Research Use Software License and Terms of Use unchanged.
It restricts commercial use and end-user redistribution. This mirror does not grant additional
permissions or relicense the original assets. Commercial licensing inquiries should go to the
Harvard Office of Technology Development as described in that license.

Please cite:

Bohnslav et al. (2021). *DeepEthogram, a machine learning pipeline for supervised behavior
classification from raw pixels*. eLife 10:e63377.
[doi:10.7554/eLife.63377](https://doi.org/10.7554/eLife.63377).