{"id":46260323,"url":"https://github.com/dynamical-inference/ituna","last_synced_at":"2026-03-04T01:29:09.936Z","repository":{"id":336884605,"uuid":"1151092132","full_name":"dynamical-inference/ituna","owner":"dynamical-inference","description":"🐟 ituna – tune machine learning models for empirical identifiability and consistency","archived":false,"fork":false,"pushed_at":"2026-02-06T19:29:36.000Z","size":1875,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T23:30:12.389Z","etag":null,"topics":["hyperparameter-optimization","hyperparameter-tuning","identifiability","pytorch","sklearn"],"latest_commit_sha":null,"homepage":"https://dynamical-inference.github.io/ituna/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dynamical-inference.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2026-02-06T03:30:29.000Z","updated_at":"2026-02-06T19:31:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dynamical-inference/ituna","commit_stats":null,"previous_names":["dynamical-inference/ituna"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dynamical-inference/ituna","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamical-inference%2Fituna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamical-inference%2Fituna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamical-inference%2Fituna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamical-inference%2Fituna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dynamical-inference","download_url":"https://codeload.github.com/dynamical-inference/ituna/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamical-inference%2Fituna/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30068395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T01:03:42.280Z","status":"ssl_error","status_checked_at":"2026-03-04T01:03:23.410Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["hyperparameter-optimization","hyperparameter-tuning","identifiability","pytorch","sklearn"],"created_at":"2026-03-04T01:29:04.740Z","updated_at":"2026-03-04T01:29:09.928Z","avatar_url":"https://github.com/dynamical-inference.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐟\u003cb\u003ei\u003c/b\u003e\u003cspan style=\"color: #3C92ED;\"\u003eTuna\u003c/span\u003e\n\n[![iTuna](https://img.shields.io/badge/repo-🐟_iTuna-3C92ED?logo=github\u0026logoColor=white)](https://github.com/dynamical-inference/ituna)\n[![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://dynamical-inference.github.io/ituna/)\n[![PyPI version](https://img.shields.io/pypi/v/ituna.svg?cacheSeconds=3600)](https://pypi.org/project/ituna/)\n[![Python versions](https://img.shields.io/pypi/pyversions/ituna.svg?cacheSeconds=3600)](https://pypi.org/project/ituna/)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Build](https://github.com/dynamical-inference/ituna/actions/workflows/build.yml/badge.svg)](https://github.com/dynamical-inference/ituna/actions/workflows/build.yml)\n\n**Tune machine learning models for empirical identifiability and consistency**\n\n## Why 🐟i\u003cspan style=\"color: #4D94E8;\"\u003eTuna\u003c/span\u003e?\n\nApplying machine learning to scientific data analysis often suffers from an **identifiability gap**: many models along the data-to-analysis pipeline lack statistical guarantees about the uniqueness of their learned representations. This means that re-running the same algorithm can yield different embeddings, making downstream interpretation unreliable without manual verification.\n\nIdentifiable representation learning addresses this by ensuring models recover representations that are unique up to a known class of transformations (permutation, linear, affine, etc.). However, even theoretically identifiable models need **empirical validation** to confirm they behave consistently in practice.\n\n🐟i\u003cspan style=\"color: #4D94E8;\"\u003eTuna\u003c/span\u003e closes this gap by providing a lightweight, model-agnostic framework to:\n\n1. Train multiple instances of a model with different random seeds\n2. Align their embeddings under the appropriate indeterminacy class\n3. Measure how consistent the learned representations are\n\nThink of it as a **unit test for reproducibility** of learned embeddings.\n\n## Features\n\n- **sklearn-compatible**: Works with any transformer implementing `fit`, `transform`, and standard sklearn conventions\n- **Built-in indeterminacy classes**:\n  - `Identity` - no transformation needed (model is already fully identifiable)\n  - `Permutation` - handles sign flips and component reordering (e.g., FastICA)\n  - `Linear` - linear transformation alignment (e.g., PCA)\n  - `Affine` - linear transformation with intercept (e.g., CEBRA)\n- **Consistency scoring**: Quantifies how stable embeddings are across runs\n- **Embedding alignment**: Returns aligned embeddings for downstream analysis\n- **Flexible backends**: In-memory, disk caching, distributed execution, and DataJoint support\n\n## Installation\n\n```bash\npip install ituna\n```\n\nor alternative install from source\n```bash\npip install git+https://github.com/dynamical-inference/ituna.git\n```\n\nOptional extras:\n\n```bash\npip install \"git+https://github.com/dynamical-inference/ituna.git#egg=ituna[datajoint]\"  # DataJoint backend for database-backed caching\npip install \"git+https://github.com/dynamical-inference/ituna.git#egg=ituna[dev]\"        # Development dependencies (pytest, etc.)\n```\n\n## Quickstart\n\n```python\nimport numpy as np\nfrom sklearn.decomposition import FastICA\n\nfrom ituna import ConsistencyEnsemble, metrics\n\n# Generate sample data\nX = np.random.randn(1000, 64)\n\n# Create a consistency ensemble\nensemble = ConsistencyEnsemble(\n    estimator=FastICA(n_components=16, max_iter=500),\n    consistency_transform=metrics.PairwiseConsistency(\n        indeterminacy=metrics.Permutation(),  # FastICA is identifiable up to permutation\n        symmetric=False,\n        include_diagonal=True,\n    ),\n    random_states=5,  # Train 5 instances with different seeds\n)\n\n# Fit and evaluate\nensemble.fit(X)\nprint(\"Consistency score:\", ensemble.score(X))\n\n# Get aligned embeddings\nemb = ensemble.transform(X)\nprint(\"Embedding shape:\", emb.shape)\n```\n\n## Documentation\n\nFull documentation is available at **[dynamical-inference.github.io/ituna](https://dynamical-inference.github.io/ituna/)**.\n\n- **Quickstart notebook**: [`docs/tutorials/quickstart.ipynb`](docs/tutorials/quickstart.ipynb) - minimal working example\n- **Core concepts**: [`docs/tutorials/core.ipynb`](docs/tutorials/core.ipynb) - in-depth walkthrough\n- **Backends**: [`docs/tutorials/backends.ipynb`](docs/tutorials/backends.ipynb) - caching and distributed execution\n\n## Backends\n\n🐟i\u003cspan style=\"color: #4D94E8;\"\u003eTuna\u003c/span\u003e supports different backends for caching and distributed computation:\n\n```python\nfrom ituna import ConsistencyEnsemble, config, metrics\nfrom sklearn.decomposition import FastICA\n\nensemble = ConsistencyEnsemble(\n    estimator=FastICA(n_components=16, max_iter=500),\n    consistency_transform=metrics.PairwiseConsistency(\n        indeterminacy=metrics.Permutation(),\n    ),\n    random_states=10,\n)\n\n# Enable disk caching (avoids re-fitting identical models)\nwith config.config_context(DEFAULT_BACKEND=\"disk_cache\"):\n    ensemble.fit(X)\n\n# Distributed execution with multiple workers\nwith config.config_context(\n    DEFAULT_BACKEND=\"disk_cache_distributed\",\n    BACKEND_KWARGS={\"trigger_type\": \"auto\", \"num_workers\": 4},\n):\n    ensemble.fit(X)\n```\n\n### CLI Commands\n\nFor large-scale experiments, use the command-line tools:\n\n```bash\n# Local distributed backend\nituna-fit-distributed --sweep-name \u003csweep-uuid\u003e --cache-dir ./cache\n\n# DataJoint backend\nituna-fit-distributed-datajoint --sweep-name \u003csweep-uuid\u003e --schema-name myschema\n```\n\n## Development\n\n```bash\n# Clone and install in development mode\ngit clone https://github.com/dynamical-inference/ituna.git\ncd ituna\npip install -e .[dev]\n\n# Run tests\npytest tests -v\n\n# Setup pre-commit hooks\npre-commit install\n```\n\nFor the full development guide — branching conventions, code style, building docs, and the release process — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Citation\n\nIf you use 🐟i\u003cspan style=\"color: #4D94E8;\"\u003eTuna\u003c/span\u003e in your research, please cite:\n\n```bibtex\n@software{ituna,\n  author = {Schmidt, Tobias and Schneider, Steffen},\n  title = {iTuna: Tune machine learning models for empirical identifiability and consistency},\n  url = {https://github.com/dynamical-inference/ituna},\n  version = {0.1.0},\n}\n```\n\n## License\n\n🐟i\u003cspan style=\"color: #4D94E8;\"\u003eTuna\u003c/span\u003e is released under the [MIT License](./LICENSE). If you re-use parts of the iTuna code in your own package, please make sure to copy \u0026 paste the contents of the `LICENSE` file into a `NOTICE` in your repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynamical-inference%2Fituna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdynamical-inference%2Fituna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynamical-inference%2Fituna/lists"}