Mouse2Vec/README.md

<div align="center">
<h1> Mouse2Vec: Learning Reusable Semantic Representations of Mouse Behaviour </h1>
    
**[Guanhua Zhang][4], &nbsp; [Zhiming Hu][5], &nbsp; [Mihai Bâce][3], &nbsp; [Andreas Bulling][6]** <br>
**ACM CHI 2024**, Honolulu, Hawaii <br>
**[[Project][2]]** **[[Paper][7]]** </div>
----------------

# Setup
We recommend to setup a virtual environment using Anaconda. <br>
1. Create a conda environment and install dependencies
   ```shell
   conda env create --name mouse2vec --file=env.yaml
   conda activate mouse2vec
    ```
2. Clone our repository to download our code and a pretrained model
   ```shell
   git clone this_repo.git
   ```

# Run the code
Our code supports training using GPUs or CPUs. It will prioritise GPUs if available (line 45 in main.py). You can also assign a particular card via CUDA_VISIBLE_DEVICES (e.g., the following commands use GPU card no.3).
## Train Mouse2Vec Autoencoder<br>
Execute
```shell
CUDA_VISIBLE_DEVICES=3 python main.py --ssl True
```
## Use Mouse2Vec for Downstream Tasks

We enable two ways to use Mouse2Vec on your datasets for downstream tasks.
1. Use the (frozen) pretrained model and only train a MLP-based classifier <br>

Execute
```shell
CUDA_VISIBLE_DEVICES=3 python main.py --sl True --load True --stage 0 --testDataset [Your Dataset]
```

2. Finetune both Mouse2Vec and the classifier <br>

Execute
```shell
CUDA_VISIBLE_DEVICES=3 python main.py --sl True --load True --stage 1 --testDataset [Your Dataset]
```

# Citation 
If you find our code useful or use it in your own projects, please cite our paper:
```
@inproceedings{zhang24_chi,
  title = {Mouse2Vec: Learning Reusable Semantic Representations of Mouse Behaviour},
  author = {Zhang, Guanhua and Hu, Zhiming and B{\^a}ce, Mihai and Bulling, Andreas},
  year = {2024},
  pages = {1--17},
  booktitle = {Proc. ACM SIGCHI Conference on Human Factors in Computing Systems (CHI)},
  doi = {10.1145/3613904.3642141}
}
```

# Acknowledgements
Our work relied on the codebase of [Cross Reconstruction Transformer][1]. Thanks to the authors for sharing their code.

[1]: https://github.com/BobZwr/Cross-Reconstruction-Transformer
[2]: https://perceptualui.org/publications/zhang24_chi/
[3]: https://scholar.google.com/citations?user=ku-t0MMAAAAJ&hl=en&oi=ao
[4]: https://scholar.google.com/citations?user=NqkK0GwAAAAJ&hl=en
[5]: https://scholar.google.com/citations?hl=en&user=OLB_xBEAAAAJ
[6]: https://www.perceptualui.org/people/bulling/
[7]: https://perceptualui.org/publications/zhang24_chi.pdf