{"id":13737931,"url":"https://github.com/nmichlo/disent","last_synced_at":"2025-10-09T10:09:35.706Z","repository":{"id":44590582,"uuid":"256271496","full_name":"nmichlo/disent","owner":"nmichlo","description":"🧶 Modular VAE disentanglement framework for python built with PyTorch Lightning ▸ Including metrics and datasets ▸ With strongly supervised, weakly supervised and unsupervised methods ▸ Easily configured and run with Hydra config ▸ Inspired by disentanglement_lib","archived":false,"fork":false,"pushed_at":"2023-03-21T18:06:09.000Z","size":19671,"stargazers_count":128,"open_issues_count":13,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-22T05:26:40.367Z","etag":null,"topics":["autoencoders","configurable","datasets","disentangled-representations","disentanglement","metric-learning","metrics","python","python3","pytorch","pytorch-lightning","representation-learning","vae"],"latest_commit_sha":null,"homepage":"https://disent.michlo.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmichlo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-04-16T16:34:17.000Z","updated_at":"2025-08-27T13:01:15.000Z","dependencies_parsed_at":"2024-01-07T17:11:22.244Z","dependency_job_id":"2c638a7c-b951-4d1a-8f01-3a542151dbde","html_url":"https://github.com/nmichlo/disent","commit_stats":{"total_commits":1334,"total_committers":3,"mean_commits":444.6666666666667,"dds":0.008245877061469287,"last_synced_commit":"ff462ba567a734041874cc584b97695a81729498"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/nmichlo/disent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmichlo%2Fdisent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmichlo%2Fdisent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmichlo%2Fdisent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmichlo%2Fdisent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmichlo","download_url":"https://codeload.github.com/nmichlo/disent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmichlo%2Fdisent/sbom","scorecard":{"id":690927,"data":{"date":"2025-08-11","repo":{"name":"github.com/nmichlo/disent","commit":"8f061a87076adeae8d6e5b0fa984b660cd40e026"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.9,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":1,"reason":"Found 3/30 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/python-lint.yml:1","Warn: no topLevel permission defined: .github/workflows/python-publish.yml:1","Warn: no topLevel permission defined: .github/workflows/python-tests.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-lint.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-lint.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/python-lint.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-lint.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-lint.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-lint.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/python-lint.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-lint.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-tests.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-tests.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-tests.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-tests.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/python-tests.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/nmichlo/disent/python-tests.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:26","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:27","Warn: pipCommand not pinned by hash: .github/workflows/python-tests.yml:31","Warn: pipCommand not pinned by hash: .github/workflows/python-tests.yml:32","Warn: pipCommand not pinned by hash: .github/workflows/python-tests.yml:33","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   5 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 8 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"42 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-4 / GHSA-2mqj-m65w-jghx","Warn: Project is vulnerable to: PYSEC-2023-165 / GHSA-cwvm-v4w8-q58c","Warn: Project is vulnerable to: PYSEC-2022-42992 / GHSA-hcpj-qp55-gfph","Warn: Project is vulnerable to: PYSEC-2023-137 / GHSA-pr76-5cm5-w9cj","Warn: Project is vulnerable to: PYSEC-2023-161 / GHSA-wfm5-v35h-vwf4","Warn: Project is vulnerable to: GHSA-cgwc-qvrx-rf7f","Warn: Project is vulnerable to: GHSA-mr7h-w2qc-ffc2","Warn: Project is vulnerable to: GHSA-6p56-wp2h-9hxr","Warn: Project is vulnerable to: GHSA-fpfv-jqm9-f5jm","Warn: Project is vulnerable to: PYSEC-2021-856","Warn: Project is vulnerable to: GHSA-3f63-hfp8-52jq","Warn: Project is vulnerable to: GHSA-44wm-f244-xhp3","Warn: Project is vulnerable to: GHSA-4fx9-vc88-q2xc","Warn: Project is vulnerable to: PYSEC-2021-331 / GHSA-7534-mm45-c74v","Warn: Project is vulnerable to: PYSEC-2023-227 / GHSA-8ghj-p4vj-mr35","Warn: Project is vulnerable to: PYSEC-2022-10 / GHSA-8vj2-vxx3-667w","Warn: Project is vulnerable to: PYSEC-2021-317 / GHSA-98vv-pw6r-q6q4","Warn: Project is vulnerable to: PYSEC-2022-168 / GHSA-9j59-75qj-795w","Warn: Project is vulnerable to: GHSA-j7hp-h8jx-5ppr","Warn: Project is vulnerable to: PYSEC-2022-42979 / GHSA-m2vv-5vj5-2hm7","Warn: Project is vulnerable to: PYSEC-2022-8 / GHSA-pw3c-h7wp-cvhx","Warn: Project is vulnerable to: PYSEC-2022-9 / GHSA-xrcv-f9gm-v42c","Warn: Project is vulnerable to: PYSEC-2023-175","Warn: Project is vulnerable to: PYSEC-2021-437 / GHSA-5xp3-jfq3-5q8x","Warn: Project is vulnerable to: PYSEC-2023-228 / GHSA-mq26-g339-26xf","Warn: Project is vulnerable to: PYSEC-2014-14 / GHSA-652x-xj99-gmcc","Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-9wx4-h78v-vm56","Warn: Project is vulnerable to: PYSEC-2014-13 / GHSA-cfj3-7x9c-4p3h","Warn: Project is vulnerable to: PYSEC-2018-28 / GHSA-x84v-xcm2-53pg","Warn: Project is vulnerable to: PYSEC-2024-110 / GHSA-jw8x-6495-233v","Warn: Project is vulnerable to: GHSA-jxfp-4rvq-9h9m","Warn: Project is vulnerable to: PYSEC-2023-102","Warn: Project is vulnerable to: PYSEC-2023-114","Warn: Project is vulnerable to: GHSA-3749-ghw9-m3mg","Warn: Project is vulnerable to: PYSEC-2025-41 / GHSA-53q9-r3pm-6pq6","Warn: Project is vulnerable to: PYSEC-2024-252 / GHSA-5pcm-hx3q-hm94","Warn: Project is vulnerable to: GHSA-887c-mr87-cxwp","Warn: Project is vulnerable to: PYSEC-2024-251 / GHSA-pg7h-5qx3-wjr3","Warn: Project is vulnerable to: PYSEC-2024-250","Warn: Project is vulnerable to: PYSEC-2024-259","Warn: Project is vulnerable to: GHSA-g7vv-2v7x-gj9p"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-22T02:16:57.683Z","repository_id":44590582,"created_at":"2025-08-22T02:16:57.684Z","updated_at":"2025-08-22T02:16:57.684Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001323,"owners_count":26083040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"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":["autoencoders","configurable","datasets","disentangled-representations","disentanglement","metric-learning","metrics","python","python3","pytorch","pytorch-lightning","representation-learning","vae"],"created_at":"2024-08-03T03:02:06.290Z","updated_at":"2025-10-09T10:09:35.689Z","avatar_url":"https://github.com/nmichlo.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n    \u003ch1 align=\"center\"\u003e🧶 Disent\u003c/h1\u003e\n    \u003cp align=\"center\"\u003e\n        \u003ci\u003eA modular disentangled representation learning framework built with PyTorch Lightning\u003c/i\u003e\n    \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://choosealicense.com/licenses/mit/\" target=\"_blank\"\u003e\n        \u003cimg alt=\"license\" src=\"https://img.shields.io/github/license/nmichlo/disent?style=flat-square\u0026color=lightgrey\"/\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/disent\" target=\"_blank\"\u003e\n        \u003cimg alt=\"python versions\" src=\"https://img.shields.io/pypi/pyversions/disent?style=flat-square\"/\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/disent\" target=\"_blank\"\u003e\n        \u003cimg alt=\"pypi version\" src=\"https://img.shields.io/pypi/v/disent?style=flat-square\u0026color=blue\"/\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/nmichlo/disent/actions?query=workflow%3Atests\"\u003e\n        \u003cimg alt=\"tests status\" src=\"https://github.com/nmichlo/disent/actions/workflows/python-tests.yml/badge.svg\"/\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/psf/black\" target=\"_blank\"\u003e\n        \u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"/\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pycqa.github.io/isort\" target=\"_blank\"\u003e\n        \u003cimg alt=\"Imports: isort\" src=\"https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336\"/\u003e\n    \u003c/a\u003e\n\u003c!--     \u003ca href=\"https://codecov.io/gh/nmichlo/disent/\"\u003e --\u003e\n\u003c!--         \u003cimg alt=\"code coverage\" src=\"https://img.shields.io/codecov/c/gh/nmichlo/disent?token=86IZK3J038\u0026style=flat-square\"/\u003e --\u003e\n\u003c!--     \u003c/a\u003e --\u003e\n\u003c!--     \u003ca href=\"https://github.com/nmichlo/disent\"\u003e --\u003e\n\u003c!--         \u003cimg alt=\"last commit\" src=\"https://img.shields.io/github/last-commit/nmichlo/disent?style=flat-square\u0026color=lightgrey\"/\u003e --\u003e\n\u003c!--     \u003c/a\u003e --\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cp align=\"center\"\u003e\n        Visit the \u003ca href=\"https://disent.michlo.dev/\" target=\"_blank\"\u003edocs\u003c/a\u003e for more info, or browse the  \u003ca href=\"https://github.com/nmichlo/disent/releases\"\u003ereleases\u003c/a\u003e.\n    \u003c/p\u003e\n    \u003cp align=\"center\"\u003e\n        \u003ca href=\"https://github.com/nmichlo/disent/issues/new/choose\"\u003eContributions\u003c/a\u003e are welcome!\n    \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    ────────────────\n    \u003cbr/\u003e\n    \u003ci\u003e\u003cb\u003e NOTE:\u003c/b\u003e My MSc. research has moved \u003ca href=\"https://github.com/nmichlo/msc-research\"\u003ehere\u003c/a\u003e\u003c/i\u003e\n    \u003cbr/\u003e\n    \u003ci\u003eSome of the contributions have been incorporated directly into disent\u003c/i\u003e\n    \u003cbr/\u003e\n    ────────────────\n\u003c/p\u003e\n\n----------------------\n\n## Table Of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n    * [Datasets](#datasets)\n    * [Frameworks](#frameworks)\n    * [Metrics](#metrics)\n    * [Schedules \u0026 Annealing](#schedules--annealing)\n- [Architecture](#architecture)\n- [Examples](#examples)\n    * [Python Example](#python-example)\n    * [Hydra Config Example](#hydra-config-example)\n- [Install](#install)\n- [Development](#development)\n- [Why?](#why)\n\n----------------------\n\n## Overview\n\nDisent is a modular disentangled representation learning framework for auto-encoders,\nbuilt upon PyTorch-Lightning. This framework consists of various composable components\nthat can be used to build and benchmark various disentanglement vision tasks.\n\n\u003e The name of the framework is derived from both **disent**anglement and scientific **dissent**.\n\nGet started with disent by installing it with $`pip install disent` or cloning this repository.\n\n### Goals\n\nDisent aims to fill the following criteria:\n1. Provide **high quality**, **readable**, **consistent** and **easily comparable** implementations of frameworks\n2. **Highlight difference** between framework implementations by overriding **hooks** and minimising duplicate code \n3. Use **best practice** eg. `torch.distributions`\n4. Be extremely **flexible** \u0026 configurable\n5. Support low memory systems\n\n### Citing Disent\n\nPlease use the following citation if you use Disent in your own research:\n\n```bibtex\n@Misc{Michlo2021Disent,\n  author =       {Nathan Juraj Michlo},\n  title =        {Disent - A modular disentangled representation learning framework for pytorch},\n  howpublished = {Github},\n  year =         {2021},\n  url =          {https://github.com/nmichlo/disent}\n}\n```\n\n----------------------\n\n## Features\n\nDisent includes implementations of modules, metrics and\ndatasets from various papers.\n\n_Note that \"🧵\" means that the dataset, framework or metric was introduced by disent!_\n\n### Datasets\n\nVarious common datasets used in disentanglement research are included with disent. The dataset loaders provide various features including:\n- automatic downloads \u0026 preperation `prepare=True`\n- automatic hash verification\n- automatic optimization of underlying hdf5 formats for\nlow-memory disk-based access.\n\nData input and target dataset augmentations and transforms are supported, as well as augmentations\non the GPU or CPU at different points in the pipeline.\n\n- **Ground Truth**:\n  + \u003cdetails\u003e\n    \u003csummary\u003e🚗 \u003ca href=\"https://papers.nips.cc/paper/5845-deep-visual-analogy-making\" target=\"_blank\"\u003eCars3D\u003c/a\u003e\u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__cars3d.jpg\" alt=\"Cars3D Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails\u003e\n    \u003csummary\u003e◻️ \u003ca href=\"https://github.com/deepmind/dsprites-dataset\" target=\"_blank\"\u003edSprites\u003c/a\u003e\u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__dsprites.jpg\" alt=\"dSprites Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails\u003e\n    \u003csummary\u003e🔺 \u003ca href=\"https://arxiv.org/abs/1906.03292\" target=\"_blank\"\u003eMPI3D\u003c/a\u003e\u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__mpi3d-real.jpg\" alt=\"MPI3D-Real Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails\u003e\n    \u003csummary\u003e🐘 \u003ca href=\"https://cs.nyu.edu/~ylclab/data/norb-v1.0-small/\" target=\"_blank\"\u003eSmallNORB\u003c/a\u003e\u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__smallnorb.jpg\" alt=\"Small Norb Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails\u003e\n    \u003csummary\u003e🌈 \u003ca href=\"https://github.com/deepmind/3d-shapes\" target=\"_blank\"\u003eShapes3D\u003c/a\u003e\u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__shapes3d.jpg\" alt=\"Shapes3D Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails\u003e\n    \u003csummary\u003e🏹 \u003ca href=\"https://github.com/YingzhenLi/Sprites\" target=\"_blank\"\u003eSprites (custom)\u003c/a\u003e\u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__sprites.jpg\" alt=\"Sprites (Custom) Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails open\u003e\n    \u003csummary\u003e\n      🧵 \u003cu\u003edSpritesImagenet\u003c/u\u003e:\n      \u003ci\u003eVersion of DSprite with foreground or background deterministically masked out with tiny-imagenet data.\u003c/i\u003e\n    \u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__dsprites-imagenet-bg-100.jpg\" alt=\"dSpritesImagenet Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n- **Ground Truth Synthetic**:\n  + \u003cdetails open\u003e\n    \u003csummary\u003e\n      🧵 \u003cu\u003eXYSquares\u003c/u\u003e:\n      \u003ci\u003eThree non-overlapping squares that can move around a grid. This dataset is adversarial to VAEs that use pixel-wise reconstruction losses.\u003c/i\u003e\n    \u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__xy-squares__spacing8.jpg\" alt=\"XYSquares Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails\u003e\n    \u003csummary\u003e\n      🧵 \u003cu\u003eXYObject\u003c/u\u003e:\n      \u003ci\u003eA simplistic version of dSprites with a single square.\u003c/i\u003e\n    \u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__xy-object.jpg\" alt=\"XYObject Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n  + \u003cdetails open\u003e\n    \u003csummary\u003e\n      🧵 \u003cu\u003eXYObjectShaded\u003c/u\u003e:\n      \u003ci\u003eExact same dataset as XYObject, but ground truth factors have a different representation.\u003c/i\u003e\n    \u003c/summary\u003e\n    \u003cp align=\"center\"\u003e\u003cimg height=\"192\" src=\"docs/img/traversals/traversal-transpose__xy-object-shaded.jpg\" alt=\"XYObjectShaded Dataset Factor Traversals\"\u003e\u003c/p\u003e\n  \u003c/details\u003e\n\n### Frameworks\n\nDisent provides the following Auto-Encoders and Variational Auto-Encoders!\n\n- **Unsupervised**:\n  + \u003cu\u003eAE\u003c/u\u003e: _Auto-Encoder_\n  + [VAE](https://arxiv.org/abs/1312.6114): Variational Auto-Encoder\n  + [Beta-VAE](https://openreview.net/forum?id=Sy2fzU9gl): VAE with Scaled Loss\n  + [DFC-VAE](https://arxiv.org/abs/1610.00291): Deep Feature Consistent VAE\n  + [DIP-VAE](https://arxiv.org/abs/1711.00848): Disentangled Inferred Prior VAE\n  + [InfoVAE](https://arxiv.org/abs/1706.02262): Information Maximizing VAE\n  + [BetaTCVAE](https://arxiv.org/abs/1802.04942): Total Correlation VAE\n- **Weakly Supervised**:\n  + [Ada-GVAE](https://arxiv.org/abs/2002.02886): Adaptive GVAE, *`AdaVae.cfg(average_mode='gvae')`*, usually better than below!\n  + [Ada-ML-VAE](https://arxiv.org/abs/2002.02886): Adaptive ML-VAE, *`AdaVae.cfg(average_mode='ml-vae')`*\n- **Supervised**:\n  + \u003cu\u003eTAE\u003c/u\u003e: _Triplet Auto-Encoder_\n  + [TVAE](https://arxiv.org/abs/1802.04403): Triplet Variational Auto-Encoder\n\nIntroduced in Disent\n\n- **Unsupervised**:\n  + 🧵 \u003cu\u003eAda-TVAE-D\u003c/u\u003e: Adaptive Triplet VAE that uses data distances instead of ground-truth distances as the supervision signal.\n  + 🧵 \u003cu\u003eAda-TAE-D\u003c/u\u003e:  Adaptive Triplet AE that uses data distances instead of ground-truth distances as the supervision signal.\n- **Weakly Supervised**:\n  + 🧵 \u003cu\u003eAda-AE\u003c/u\u003e: Adaptive AE, the auto-encoder version of the Ada-GVAE\n- **Supervised**:\n  + 🧵 \u003cu\u003eAda-TVAE\u003c/u\u003e: Adaptive Triplet VAE, disentangled version of the TVAE\n  + 🧵 \u003cu\u003eAda-TAE\u003c/u\u003e:  Adaptive Triplet AE, disentangled version of the TAE\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e🏗 Todo\u003c/b\u003e: \u003ci\u003eMany popular disentanglement frameworks still need to be added, please\nsubmit an issue if you have a request for an additional framework.\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n+ FactorVAE\n+ GroupVAE\n+ MLVAE\n\n\u003c/p\u003e\u003c/details\u003e\n\n### Metrics\nVarious metrics are provided by disent that can be used to evaluate the\nlearnt representations of models that have been trained on ground-truth data. \n\n- **Disentanglement**:\n  + [FactorVAE Score](https://arxiv.org/abs/1802.05983)\n  + [DCI](https://openreview.net/forum?id=By-7dz-AZ)\n  + [MIG](https://arxiv.org/abs/1802.04942)\n  + [SAP](https://arxiv.org/abs/1711.00848)\n  + [Unsupervised Scores](https://github.com/google-research/disentanglement_lib)\n  + 🧵 \u003cu\u003eFlatness Components\u003c/u\u003e: _Measures of the three components needed to learn factored representations from distances. VAEs often learn the first two (correlation \u0026 linearity), and the can happen accidentally (axis-alignment)!_\n    - 🪡 \u003cu\u003eGround-Truth Correlation\u003c/u\u003e - _The spearman rank correlation between latent distances and ground-truth distances._\n    - 🪡 \u003cu\u003eLinearity Ratio\u003c/u\u003e - _How well factor traversals lie along an n-dimensional arbitrarily rotated line in the latent space_\n    - 🪡 \u003cu\u003eAxis-Alignment Ratio\u003c/u\u003e - _How well factor traversals are represented by a single latent variable, ie. an n-dimensional line that is axis-aligned._\n  + 🧵 \u003cu\u003eFlatness Score\u003c/u\u003e - _Measuring the max distance between factor traversal embeddings and the path length of their embeddings._\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e🏗 Todo\u003c/b\u003e: \u003ci\u003eSome popular metrics still need to be added, please submit an issue if you wish to\nadd your own, or you have a request.\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\n+ [DCIMIG](https://arxiv.org/abs/1910.05587)\n+ [Modularity and Explicitness](https://arxiv.org/abs/1802.05312)\n\n\u003c/p\u003e\u003c/details\u003e\n\n### Schedules \u0026 Annealing\n\nHyper-parameter annealing is supported through the use of schedules.\nThe currently implemented schedules include:\n\n- Linear Schedule\n- [Cyclic](https://arxiv.org/abs/1903.10145) Schedule\n- Cosine Wave Schedule\n- *Various other wrapper schedules*\n\n----------------------\n\n## Architecture\n\nThe disent module structure:\n\n- `disent.dataset`: dataset wrappers, datasets \u0026 sampling strategies\n    + `disent.dataset.data`: raw datasets\n    + `disent.dataset.sampling`: sampling strategies for `DisentDataset` when multiple elements are required by frameworks, eg. for triplet loss\n    + `disent.dataset.transform`: common data transforms and augmentations\n    + `disent.dataset.wrapper`: wrapped datasets are no longer ground-truth datasets, these may have some elements masked out. We can still unwrap these classes to obtain the original datasets for benchmarking.\n- `disent.frameworks`: frameworks, including Auto-Encoders and VAEs\n    + `disent.frameworks.ae`: Auto-Encoder based frameworks\n    + `disent.frameworks.vae`: Variational Auto-Encoder based frameworks\n- `disent.metrics`: metrics for evaluating disentanglement using ground truth datasets\n- `disent.model`: common encoder and decoder models used for VAE research\n- `disent.nn`: torch components for building models including layers, transforms, losses and general maths\n- `disent.schedule`: annealing schedules that can be registered to a framework\n- `disent.util`: helper classes, functions, callbacks, anything unrelated to a pytorch system/model/framework.\n\n**⚠️ The API Is _Mostly_ Stable ⚠️**\n\nDisent is still under development. Features and APIs are subject to change!\nHowever, I will try and minimise the impact of these.\n\nA small suite of tests currently exist which will be expanded upon in time.\n\n**Hydra Experiment Directories**\n\nEasily run experiments with hydra config, these files\nare not available from `pip install`.\n\n- `experiment/run.py`: entrypoint for running basic experiments with [hydra](https://github.com/facebookresearch/hydra) config\n- `experiment/config/config.yaml`: main configuration file, this is probably what you want to edit!\n- `experiment/config`: root folder for [hydra](https://github.com/facebookresearch/hydra) config files\n- `experiment/util`: various helper code for experiments\n\n**Extending The Default Configs**\n\nAll configs in `experiment/config` can easily be extended or overridden\nwithout modifying any files. We can add a new config folder to the hydra search path\nby setting the environment variable `DISENT_CONFIGS_PREPEND` to point to a config folder\nthat should take priority over those contained in the default folder.\n\nThe advantage of this is that new frameworks and datasets can be used with experiments without cloning or modifying\ndisent itself. You can separate your research code from the library!\n- See the examples in the docs for more information!\n\n----------------------\n\n## Examples\n\n### Python Example\n\nThe following is a basic working example of disent that trains a BetaVAE with a cyclic\nbeta schedule and evaluates the trained model with various metrics.\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e💾 Basic Example\u003c/b\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```python3\nimport lightning as L\nimport torch\nfrom torch.utils.data import DataLoader\n\nfrom disent.dataset import DisentDataset\nfrom disent.dataset.data import XYObjectData\nfrom disent.dataset.sampling import SingleSampler\nfrom disent.dataset.transform import ToImgTensorF32\nfrom disent.frameworks.vae import BetaVae\nfrom disent.metrics import metric_dci\nfrom disent.metrics import metric_mig\nfrom disent.model import AutoEncoder\nfrom disent.model.ae import DecoderConv64\nfrom disent.model.ae import EncoderConv64\nfrom disent.schedule import CyclicSchedule\n\n# create the dataset \u0026 dataloaders\n# - ToImgTensorF32 transforms images from numpy arrays to tensors and performs checks\n# - if you use `num_workers != 0` in the DataLoader, the make sure to\n#   wrap `trainer.fit` with `if __name__ == '__main__': ...`\ndata = XYObjectData()\ndataset = DisentDataset(dataset=data, sampler=SingleSampler(), transform=ToImgTensorF32())\ndataloader = DataLoader(dataset=dataset, batch_size=128, shuffle=True, num_workers=0)\n\n# create the BetaVAE model\n# - adjusting the beta, learning rate, and representation size.\nmodule = BetaVae(\n    model=AutoEncoder(\n        # z_multiplier is needed to output mu \u0026 logvar when parameterising normal distribution\n        encoder=EncoderConv64(x_shape=data.x_shape, z_size=10, z_multiplier=2),\n        decoder=DecoderConv64(x_shape=data.x_shape, z_size=10),\n    ),\n    cfg=BetaVae.cfg(\n        optimizer='adam',\n        optimizer_kwargs=dict(lr=1e-3),\n        loss_reduction='mean_sum',\n        beta=4,\n    )\n)\n\n# cyclic schedule for target 'beta' in the config/cfg. The initial value from the\n# config is saved and multiplied by the ratio from the schedule on each step.\n# - based on: https://arxiv.org/abs/1903.10145\nmodule.register_schedule(\n    'beta', CyclicSchedule(\n        period=1024,  # repeat every: trainer.global_step % period\n    )\n)\n\n# train model\n# - for 2048 batches/steps\ntrainer = L.Trainer(\n    max_steps=2048, gpus=1 if torch.cuda.is_available() else None, logger=False, enable_checkpointing=False\n)\ntrainer.fit(module, dataloader)\n\n# compute disentanglement metrics\n# - we cannot guarantee which device the representation is on\n# - this will take a while to run\nget_repr = lambda x: module.encode(x.to(module.device))\n\nmetrics = {\n    **metric_dci(dataset, get_repr, num_train=1000, num_test=500, show_progress=True),\n    **metric_mig(dataset, get_repr, num_train=2000),\n}\n\n# evaluate\nprint('metrics:', metrics)\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\nVisit the [docs](https://disent.michlo.dev) for more examples!\n\n\n### Hydra Config Example\n\nThe entrypoint for basic experiments is `experiment/run.py`.\n\nSome configuration will be required, but basic experiments can\nbe adjusted by modifying the [Hydra Config 1.1](https://github.com/facebookresearch/hydra)\nfiles in `experiment/config`.\n\nModifying the main `experiment/config/config.yaml` is all you\nneed for most basic experiments. The main config file contains\na defaults list with entries corresponding to yaml configuration\nfiles (config options) in the subfolders (config groups) in\n`experiment/config/\u003cconfig_group\u003e/\u003coption\u003e.yaml`.\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e💾 Config Defaults Example\u003c/b\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```yaml\ndefaults:\n  # data\n  - sampling: default__bb\n  - dataset: xyobject\n  - augment: none\n  # system\n  - framework: adavae_os\n  - model: vae_conv64\n  # training\n  - optimizer: adam\n  - schedule: beta_cyclic\n  - metrics: fast\n  - run_length: short\n  # logs\n  - run_callbacks: vis\n  - run_logging: wandb\n  # runtime\n  - run_location: local\n  - run_launcher: local\n  - run_action: train\n\n# \u003crest of config.yaml left out\u003e\n...\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\nEasily modify  any of these values to adjust how the basic experiment\nwill be run. For example, change `framework: adavae` to `framework: betavae`, or\nchange the dataset from `xyobject` to `shapes3d`. Add new options by adding new\nyaml files in the config group folders.\n\n[Weights and Biases](https://docs.wandb.ai/quickstart) is supported by changing `run_logging: none` to\n`run_logging: wandb`. However, you will need to login from the command line. W\u0026B logging supports\nvisualisations of latent traversals.\n\n\n----------------------\n\n### Install\n\n```bash\npip install disent\n```\n\nOtherwise, to install from source we recommend using a conda virtual environment.\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e⤵️ Install from Source\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# clone the repo\ngit clone https://github.com/nmichlo/disent\ncd disent\n\n# create and activate the conda environment [py38,py39,py310]\nconda create -n disent-py310 python=3.10\nconda activate disent-py310\n\n# check that the correct python version is used\nwhich python\nwhich pip\n\n# make sure to upgrade pip\npip install --upgrade pip\n\n# install minimal requirements\npip install -r requirements.txt\n\n# (optional) install extra requirements\n# - first do the above because torch is required to compile torchsort while installing\npip install -r requirements-extra.txt\n\n# (optional) install test requirements\npip install -r requirements-test.txt\n```\n\n\u003c/details\u003e\n\n----------------------\n\n### Development\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)](https://pycqa.github.io/isort/)\n\nMake sure to install `pre-commit` hooks to ensure code is automatically formatted\ncorrectly when committing or pushing changes to `disent`.\n\n```bash\n# install git hooks\npip install pre-commit\npre-commit install\n\n# manually trigger all pre-commit hooks\npre-commit run --all-files\n```\n\nTo run tests locally, make sure to install all the test and extra dependencies in your\nenvironment.\n\n```bash\npip install -r requirements.txt\n# torchsort first requires torch to be installed\npip install -r requirements-extra.txt -r requirements-test.txt\n```\n\n----------------------\n\n### Why?\n  \n- Created as part of my Computer Science MSc which ended early 2022.\n- I needed custom high quality implementations of various VAE's.\n- A pytorch version of [disentanglement_lib](https://github.com/google-research/disentanglement_lib).\n- I didn't have time to wait for [Weakly-Supervised Disentanglement Without Compromises](https://arxiv.org/abs/2002.02886) to release\n  their code as part of disentanglement_lib. (As of September 2020 it has been released, but has unresolved [discrepencies](https://github.com/google-research/disentanglement_lib/issues/31)).\n- disentanglement_lib still uses outdated Tensorflow 1.0, and the flow of data is unintuitive because of its use of [Gin Config](https://github.com/google/gin-config).\n\n----------------------\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmichlo%2Fdisent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmichlo%2Fdisent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmichlo%2Fdisent/lists"}