{"id":50148755,"url":"https://github.com/zeiss/things_eeg2_dataset","last_synced_at":"2026-05-24T07:02:51.325Z","repository":{"id":328140697,"uuid":"1104423945","full_name":"ZEISS/things_eeg2_dataset","owner":"ZEISS","description":"🧠⚡A CLI to access and process the THINGS-EEG2 dataset by Gifford et al. (2022)","archived":false,"fork":false,"pushed_at":"2026-03-07T15:02:10.000Z","size":14846,"stargazers_count":8,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T17:44:03.632Z","etag":null,"topics":["cli","eeg","electroencephalography","mne","neuroscience"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZEISS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-26T07:38:43.000Z","updated_at":"2026-03-07T14:56:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ZEISS/things_eeg2_dataset","commit_stats":null,"previous_names":["zeiss/things_eeg2_dataset"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ZEISS/things_eeg2_dataset","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fthings_eeg2_dataset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fthings_eeg2_dataset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fthings_eeg2_dataset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fthings_eeg2_dataset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZEISS","download_url":"https://codeload.github.com/ZEISS/things_eeg2_dataset/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fthings_eeg2_dataset/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33424573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","eeg","electroencephalography","mne","neuroscience"],"created_at":"2026-05-24T07:02:38.126Z","updated_at":"2026-05-24T07:02:51.320Z","avatar_url":"https://github.com/ZEISS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/ZEISS/things_eeg2_dataset/refs/heads/main/.github/assets/things_eeg2_dataset-banner-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/ZEISS/things_eeg2_dataset/refs/heads/main/.github/assets/things_eeg2_dataset-banner-light.png\"\u003e\n  \u003cimg alt=\"things_eeg2_dataset\" src=\"https://raw.githubusercontent.com/ZEISS/things_eeg2_dataset/refs/heads/main/.github/assets/things_eeg2_dataset-banner-light.png\"\u003e\n\u003c/picture\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI][pypi-badge]][pypi]\n[![Conda Platform][conda-badge]][conda-url]\n[![License][license-badge]][license-url]\n[![CI Status][ci-badge]][ci-url]\n\n[pypi-badge]: https://img.shields.io/pypi/v/things_eeg2_dataset?style=flat-square\u0026label=PyPI\n[pypi]: https://pypi.org/project/things-eeg2-dataset/\n\n[license-badge]: https://img.shields.io/badge/License-CC%20BY--NC%204.0-yellow.svg?style=flat-square\n[license-url]: LICENSE\n\n[ci-badge]: https://img.shields.io/github/actions/workflow/status/zeiss/things_eeg2_dataset/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\n[ci-url]: https://github.com/zeiss/things_eeg2_dataset/actions/workflows/ci.yml\n\n[conda-badge]: https://img.shields.io/conda/vn/conda-forge/things_eeg2_dataset?style=flat-square\n[conda-url]: https://prefix.dev/channels/conda-forge/packages/things_eeg2_dataset\n\n\u003c/div\u003e\n\n# Introduction\n\nThis package provides tools for downloading, preprocessing the raw THINGS-EEG2 data, and generating image embeddings using various vision models.\n\n\u003e [!WARNING]\n\u003e This repository builds upon the original data processing by [Gifford et al (2022)](https://github.com/gifale95/eeg_encoding).\n\u003e Please check out their original code and the [corresponding paper](https://www.sciencedirect.com/science/article/pii/S1053811922008758?via%3Dihub).\n\u003e\n\u003e We are in no way associated with the authors.\n\u003e Nonetheless we hope, that this makes things easier (pun intended) to use.\n\n## Installation\n\n### CLI-only\n\nIf you only need the CLI functionality, you can run it using one line of code:\n\n#### Using the PyPI package (with uv)\n\n```bash\nuvx run --from things_eeg2_dataset things-eeg2\n```\n\n#### Using the conda package (with pixi)\n\n```bash\npixi exec --with things_eeg2_dataset things-eeg2\n```\n\n### From GitHub\n\n```bash\ngit clone git@github.com:ZEISS/things_eeg2_dataset.git\ncd things_eeg2_dataset\n\nuv sync\nuv pip install --editable .\nsource .venv/bin/activate\n\nthings-eeg2 --help\nthings-eeg2 --install-completion\n\n# Then restart your shell\n# Example for zsh:\nsource ~/.zshrc\n```\n\n### From PyPI\n\n```bash\n# Using UV\nuv init\nuv add things_eeg2_dataset\nsource .venv/bin/activate\n\nthings-eeg2 --help\nthings-eeg2 --install-completion\n\n# Then restart your shell\n# Example for zsh:\nsource ~/.zshrc\n```\n\n### Using the conda package\n\n```bash\n# Using pixi  \npixi init\npixi add things_eeg2_dataset\npixi shell\n\nthings-eeg2 --help\nthings-eeg2 --install-completion\n\n# Then restart your shell\n# Example for zsh:\nsource ~/.zshrc\n```\n\n## Usage\n\n![things_eeg2_dataset demo](https://raw.githubusercontent.com/ZEISS/things_eeg2_dataset/refs/heads/main/.github/assets/demo/demo-light.gif#gh-light-mode-only)\n![things_eeg2_dataset demo](https://raw.githubusercontent.com/ZEISS/things_eeg2_dataset/refs/heads/main/.github/assets/demo/demo-dark.gif#gh-dark-mode-only)\n\n## Data Structure\n\nYou can understand the data structure that is created by the CLI by referring to [paths.py](src/things_eeg2_dataset//paths.py).\nIt contains the ground truth data structure used throughout the project.\n\n### Embedding Generation (`embedding_processing/`)\n\nThe package supports multiple state-of-the-art vision models for generating image embeddings:\n\n| Model | Embedder Class | Description |\n|-------|----------------|-------------|\n| `open-clip-vit-h-14` | `OpenClipViTH14Embedder` | OpenCLIP ViT-H/14 (SDXL image encoder) |\n| `openai-clip-vit-l-14` | `OpenAIClipVitL14Embedder` | OpenAI CLIP ViT-L/14 |\n| `dinov2` | `DinoV2Embedder` | DINOv2 with registers (self-supervised) |\n| `ip-adapter` | `IPAdapterEmbedder` | IP-Adapter Plus projections |\n\nEach embedder generates:\n\n- **Pooled embeddings**: Single vector per image (e.g., `(1024,)` for ViT-H-14)\n- **Full sequence embeddings**: All tokens (e.g., `(257, 1280)` for ViT-H-14)\n- **Text embeddings**: Corresponding text features from image captions\n\n**Output Files:**\n\n```bash\nembeddings/\n├── ViT-H-14_features_training.safetensors           # Pooled embeddings\n├── ViT-H-14_features_training_full.safetensors      # Full token sequences\n├── ViT-H-14_features_test.safetensors\n└── ViT-H-14_features_test_full.safetensors\n```\n\n### Using the dataloader\n\n```python\nfrom things_eeg2_dataset.dataloader import ThingsEEGDataset\n\ndataset = ThingsEEGDataset(\n    image_model=\"ViT-H-14\",\n    data_path=\"/path/to/processed_data\",\n    img_directory_training=\"/path/to/images/train\",\n    img_directory_test=\"/path/to/images/test\",\n    embeddings_dir=\"/path/to/embeddings\",\n    train=True,\n    time_window=(0.0, 1.0),\n)\n```\n\nSee `things_eeg2_dataloader/README.md` for detailed usage.\n\n## References \u0026 Citation\n\nWe are happy users of the [THINGS-EEG2 dataset](https://things-initiative.org/), but not associated with the original authors.\nIf you use this code, please cite the [THINGS-EEG2 paper](https://www.sciencedirect.com/science/article/pii/S1053811922008758?via%3Dihub):\n\u003e Gifford, A. T., Lahner, B., Saba-Sadiya, S., Vilas, M. G., Lascelles, A., Oliva, A., ... \u0026 Cichy, R. M. (2022). The THINGS-EEG2 dataset. Scientific Data.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeiss%2Fthings_eeg2_dataset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeiss%2Fthings_eeg2_dataset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeiss%2Fthings_eeg2_dataset/lists"}