Add metadata and improve discoverability

README.md

@@ -1,10 +1,20 @@
+---
+license: apache-2.0
+pipeline_tag: video-classification
+tags:
+- concept-bottleneck
+- interpretability
+- video-understanding
+arxiv: 2509.20899
+---
+
 # MoTIF — Concepts in Motion
 
-[**Read the Paper (arXiv)**](https://arxiv.org/pdf/2509.20899)
+[**Read the Paper (arXiv)**](https://arxiv.org/pdf/2509.20899) | [**GitHub Repository**](https://github.com/patrick-knab/MoTIF)
 
 ## Abstract
 
-Conceptual models such as Concept Bottleneck Models (CBMs) have driven substantial progress in improving interpretability for image classification by leveraging human‑interpretable concepts. However, extending these models from static images to sequences of images, such as video data, introduces a significant challenge due to the temporal dependencies inherent in videos, which are essential for capturing actions and events. In this work, we introduce MoTIF (Moving Temporal Interpretable Framework), an architectural design inspired by a transformer that adapts the concept bottleneck framework for video classification and handles sequences of arbitrary length. Within the video domain, concepts refer to semantic entities such as objects, attributes, or higher‑level components (e.g., "bow", "mount", "shoot") that reoccur across time—forming motifs collectively describing and explaining actions. Our design explicitly enables three complementary perspectives: global concept importance across the entire video, local concept relevance within specific windows, and temporal dependencies of a concept over time. Our results demonstrate that the concept‑based modeling paradigm can be effectively transferred to video data, enabling a better understanding of concept contributions in temporal contexts while maintaining competitive performance. 
+Conceptual models such as Concept Bottleneck Models (CBMs) have driven substantial progress in improving interpretability for image classification by leveraging human‑interpretable concepts. However, extending these models from static images to sequences of images, such as video data, introduces a significant challenge due to the temporal dependencies inherent in videos, which are essential for capturing actions and events. In this work, we introduce MoTIF (Moving Temporal Interpretable Framework), an architectural design inspired by a transformer that adapts the concept bottleneck framework for video classification and handles sequences of arbitrary length. Within the video domain, concepts refer to semantic entities such as objects, attributes, or higher‑level components (e.g., "bow", "mount", "shoot") that reoccur across time—forming motifs collectively describing and explaining actions. Our design explicitly enables three complementary perspectives: global concept importance across the entire video, local concept relevance within specific windows, and temporal dependencies of a concept over time.
 
 ---
 
@@ -33,7 +43,7 @@ pip install -r requirements.txt
 
 ### 2) Data
 
-Place your datasets under `Datasets/` (see the folder structure below). If you want to generate small demo clips or frames, you can use:
+Place your datasets under `Datasets/`. If you want to generate small demo clips or frames, you can use:
 
 ```bash
 python save_videos.py
@@ -67,7 +77,7 @@ Adjust hyperparameters in the script or via CLI flags (if exposed).
 
 ## Pretrained Checkpoints
 
-Pre-trained MoTIF checkpoints for all model variants are available on [Hugging Face](https://huggingface.co/P4ddyki/MoTIF/tree/main). The checkpoints include models trained on Breakfast, HMDB-51, and UCF-101 datasets with PE-L/14 backbone. We will upload soon additional checkpoints.
+Pre-trained MoTIF checkpoints for all model variants are available on [Hugging Face](https://huggingface.co/P4ddyki/MoTIF/tree/main). The checkpoints include models trained on Breakfast, HMDB-51, and UCF-101 datasets with PE-L/14 backbone.
 
 To use a pre-trained checkpoint, download it from the Hugging Face repository and place it in the `Models/` directory. The notebook `MoTIF.ipynb` will automatically load the appropriate checkpoint based on the dataset and backbone you specify.
 
@@ -88,31 +98,6 @@ To use a pre-trained checkpoint, download it from the Hugging Face repository an
 - Something‑Something v2 — [20BN dataset page](https://www.qualcomm.com/developer/software/something-something-v-2-dataset)
 - Breakfast Actions — [Dataset page](https://serre-lab.clps.brown.edu/resource/breakfast-actions-dataset/)
 
-Please follow each dataset’s license and terms of use.
-
-Note: If you use other datasets, you will need to adapt the dataset logic in the code (e.g., train/val/test splits, preprocessing, and loaders). Relevant places include `utils/core/data/` (e.g., `data.py`, `preprocessor.py`, `dataloader.py`) and any dataset‑specific handling in `embedding.py` and `train_MoTIF.py`.
-
----
-
-## Folder Structure
-
-- `Datasets/` — dataset placeholders
-- `Embeddings/` — generated embeddings (created by scripts)
-- `Models/` — trained model checkpoints
-- `Videos/` — example videos used in the paper/one‑pager
-- `utils/` — library code (vision encoder, projector, dataloaders, transforms, etc.)
-- `index.html` — minimal one‑pager describing MoTIF (open locally in a browser)
-- `embedding.py`, `save_videos.py`, `train_MoTIF.py` — main scripts
-- `MoTIF.ipynb` — notebook for inspection and visualization
-
----
-
-## Quick Tips
-
-- If you change the dataset or backbone, regenerate embeddings before training.
-- The attention visualizations are concept‑wise and time‑wise; they should not mix information across concepts.
-- GPU memory usage depends on the number of concepts and the temporal window length.
-
 ---
 
 ## Citation
@@ -136,10 +121,4 @@ If you use MoTIF in your research, please consider citing:
 ## Acknowledgements
 
 - Parts of the `utils/core` codebase are adapted from the Perception Encoder framework.
-- Thanks to the CORE research group at TU Clausthal and Ramblr.ai Research for support.
-
----
-
-## Contact
-
-For questions and discussion, please open an issue or contact the authors.
+- Thanks to the CORE research group at TU Clausthal and Ramblr.ai Research for support.