{"id":28636036,"url":"https://github.com/ramppdev/ablate","last_synced_at":"2025-06-12T17:36:49.092Z","repository":{"id":297267585,"uuid":"981497050","full_name":"ramppdev/ablate","owner":"ramppdev","description":"ablate turns deep learning experiments into structured, human-readable reports.","archived":false,"fork":false,"pushed_at":"2025-06-04T17:33:15.000Z","size":2842,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-04T22:39:42.091Z","etag":null,"topics":["autrainer","clearml","deep-learning","experiment-tracking","mlflow","notes","tensorboard","weights-and-biases"],"latest_commit_sha":null,"homepage":"https://ramppdev.github.io/ablate/","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/ramppdev.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-11T08:42:38.000Z","updated_at":"2025-06-04T17:31:53.000Z","dependencies_parsed_at":"2025-06-04T22:39:49.013Z","dependency_job_id":"390c0b47-5983-4731-abc8-3b3ab8d409dd","html_url":"https://github.com/ramppdev/ablate","commit_stats":null,"previous_names":["ramppdev/ablate"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ramppdev/ablate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramppdev%2Fablate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramppdev%2Fablate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramppdev%2Fablate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramppdev%2Fablate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramppdev","download_url":"https://codeload.github.com/ramppdev/ablate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramppdev%2Fablate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259513158,"owners_count":22869565,"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","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":["autrainer","clearml","deep-learning","experiment-tracking","mlflow","notes","tensorboard","weights-and-biases"],"created_at":"2025-06-12T17:36:44.773Z","updated_at":"2025-06-12T17:36:49.075Z","avatar_url":"https://github.com/ramppdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://ramppdev.github.io/ablate/_images/logo_banner.png\" alt=\"ablate turns deep learning experiments into structured, human-readable reports.\"\u003e\n\u003c/div\u003e\n\n# ablate\n\n[![ablate PyPI Version](https://img.shields.io/pypi/v/ablate?logo=pypi\u0026logoColor=b4befe\u0026color=b4befe)](https://pypi.org/project/ablate/)\n[![ablate Python Versions](https://img.shields.io/pypi/pyversions/ablate?logo=python\u0026logoColor=b4befe\u0026color=b4befe)](https://pypi.org/project/ablate/)\n[![ablate GitHub License](https://img.shields.io/badge/license-MIT-b4befe?logo=c)](https://github.com/ramppdev/ablate/blob/main/LICENSE)\n\n_ablate_ turns deep learning experiments into structured, human-readable reports. It is built around five principles:\n\n- **composability**: sources, queries, blocks, and exporters can be freely combined\n- **immutability**: query operations never mutate runs in-place, enabling safe reuse and functional-style chaining\n- **extensibility**: sources, blocks, and exporters are designed to be easily extended with custom implementations\n- **readability**: reports are generated with humans in mind: shareable, inspectable, and format-agnostic\n- **minimal friction**: no servers, no databases, no heavy integrations: just Python and your existing logs\n\nCurrently, _ablate_ supports the following [sources](https://ramppdev.github.io/ablate/modules/sources.html)\nand [exporters](https://ramppdev.github.io/ablate/modules/exporters.html):\n\n- sources:\n  [autrainer](https://github.com/autrainer/autrainer),\n  [ClearML](https://clear.ml/),\n  [MLflow](https://mlflow.org/),\n  [TensorBoard](https://www.tensorflow.org/tensorboard),\n  and [WandB](https://www.wandb.ai/)\n- exporters: [Markdown](https://www.markdownguide.org) and [Jupyter](https://jupyter.org/)\n\n## Installation\n\nInstall _ablate_ using _pip_:\n\n```bash\npip install ablate\n```\n\nThe following optional dependencies can be installed to enable additional features:\n\n- `ablate[clearml]` to use [ClearML](https://clear.ml/) as an experiment source\n- `ablate[mlflow]` to use [MLflow](https://mlflow.org/) as an experiment source\n- `ablate[tensorboard]` to use [TensorBoard](https://www.tensorflow.org/tensorboard) as an experiment source\n- `ablate[wandb]` to use [WandB](https://www.wandb.ai/) as an experiment source\n- `ablate[jupyter]` to use _ablate_ in a [Jupyter](https://jupyter.org/) notebook\n\n## Quickstart\n\n_ablate_ is built around five composable modules:\n\n- [ablate.sources](https://ramppdev.github.io/ablate/modules/sources.html): load experiment runs from various sources\n- [ablate.queries](https://ramppdev.github.io/ablate/modules/queries.html): apply queries and transformations to the runs\n- [ablate.blocks](https://ramppdev.github.io/ablate/modules/blocks.html): structure content as tables, text, figures, and other blocks\n- [ablate.Report](https://ramppdev.github.io/ablate/modules/report.html): create a report from the runs and blocks\n- [ablate.exporters](https://ramppdev.github.io/ablate/modules/exporters.html): export a report to various formats\n\n### Creating a Report\n\nTo create your first [Report](https://ramppdev.github.io/ablate/modules/report.html), define one or more experiment sources.\nFor example, the built in [Mock](https://ramppdev.github.io/ablate/modules/sources.html#mock-source) can be used to simulate runs:\n\n```python\nimport ablate\n\nsource = ablate.sources.Mock(\n  grid={\"model\": [\"vgg\", \"resnet\"], \"lr\": [0.01, 0.001]},\n  num_seeds=2,\n)\n```\n\nEach run in the mock source has _accuracy_, _f1_, and _loss_ metrics, along with a _seed_ parameter\nas well as the manually defined parameters _model_ and _lr_.\nNext, the runs can be loaded and processed using functional-style queries to e.g., sort by accuracy,\ngroup by seed, aggregate the results by mean, and finally collect all results into a single list:\n\n```python\nruns = (\n    ablate.queries.Query(source.load())\n    .sort(ablate.queries.Metric(\"accuracy\", direction=\"max\"))\n    .groupdiff(ablate.queries.Param(\"seed\"))\n    .aggregate(\"mean\")\n    .all()\n)\n\n```\n\nNow that the runs are loaded and processed, a [Report](https://ramppdev.github.io/ablate/modules/report.html)\ncomprising multiple blocks can be created to structure the content:\n\n```python\nreport = ablate.Report(runs)\nreport.add(ablate.blocks.H1(\"Model Performance\"))\nreport.add(\n    ablate.blocks.Table(\n        columns=[\n            ablate.queries.Param(\"model\", label=\"Model\"),\n            ablate.queries.Param(\"lr\", label=\"Learning Rate\"),\n            ablate.queries.Metric(\"accuracy\", direction=\"max\", label=\"Accuracy\"),\n            ablate.queries.Metric(\"f1\", direction=\"max\", label=\"F1 Score\"),\n            ablate.queries.Metric(\"loss\", direction=\"min\", label=\"Loss\"),\n        ]\n    )\n)\n```\n\nFinally, the report can be exported to a desired format such as [Markdown](https://ramppdev.github.io/ablate/modules/exporters.html#ablate.exporters.Markdown):\n\n```python\nablate.exporters.Markdown().export(report)\n```\n\nThis will produce a `report.md` file with the following content:\n\n```markdown\n# Model Performance\n\n| Model  | Learning Rate | Accuracy | F1 Score |    Loss |\n| :----- | ------------: | -------: | -------: | ------: |\n| resnet |          0.01 |  0.94285 |  0.90655 |  0.0847 |\n| vgg    |          0.01 |  0.92435 |   0.8813 |  0.0895 |\n| resnet |         0.001 |   0.9262 |   0.8849 |  0.0743 |\n| vgg    |         0.001 |  0.92745 |  0.90875 | 0.08115 |\n```\n\n### Combining Sources\n\nTo compose multiple sources, they can be added together using the `+` operator\nas they represent lists of [Run](https://ramppdev.github.io/ablate/modules/core.html#ablate.core.types.Run) objects:\n\n```python\nruns1 = ablate.sources.Mock(...).load()\nruns2 = ablate.sources.Mock(...).load()\n\nall_runs = runs1 + runs2 # combines both sources into a single list of runs\n```\n\n### Functional Queries\n\n_ablate_ queries are functionally pure such that intermediate results are not modified and can be reused:\n\n```python\nruns = ablate.sources.Mock(...).load()\n\nsorted_runs = Query(runs).sort(ablate.queries.Metric(\"accuracy\", direction=\"max\"))\n\nfiltered_runs = sorted_runs.filter(\n    ablate.queries.Metric(\"accuracy\", direction=\"max\") \u003e 0.9\n)\n\nsorted_runs.all() # still contains all runs sorted by accuracy\nfiltered_runs.all() # only contains runs with accuracy \u003e 0.9\n```\n\n### Composing Reports\n\nBy default, _ablate_ reports populate blocks based on the global list of runs passed to the report during initialization.\nTo create more complex reports, blocks can be populated with a custom list of runs using the _runs_ parameter:\n\n```python\nreport = ablate.Report(sorted_runs.all())\nreport.add(ablate.blocks.H1(\"Report with Sorted Runs and Filtered Runs\"))\nreport.add(ablate.blocks.H2(\"Sorted Runs\"))\nreport.add(\n    ablate.blocks.Table(\n        columns=[\n            ablate.queries.Param(\"model\", label=\"Model\"),\n            ablate.queries.Param(\"lr\", label=\"Learning Rate\"),\n            ablate.queries.Metric(\"accuracy\", direction=\"max\", label=\"Accuracy\"),\n        ]\n    )\n)\nreport.add(ablate.blocks.H2(\"Filtered Runs\"))\nreport.add(\n    ablate.blocks.Table(\n        runs = filtered_runs.all(), # use filtered runs only for this block\n        columns=[\n            ablate.queries.Param(\"model\", label=\"Model\"),\n            ablate.queries.Param(\"lr\", label=\"Learning Rate\"),\n            ablate.queries.Metric(\"accuracy\", direction=\"max\", label=\"Accuracy\"),\n        ]\n    )\n)\n```\n\n## Extending _ablate_\n\n_ablate_ is designed to be extensible, allowing you to create custom [sources](https://ramppdev.github.io/ablate/modules/sources.html),\n[blocks](https://ramppdev.github.io/ablate/modules/blocks.html),\nand [exporters](https://ramppdev.github.io/ablate/modules/exporters.html) by implementing their respective abstract classes.\n\nTo contribute to _ablate_, please refer to the [contribution guide](https://ramppdev.github.io/ablate/development/contributing.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framppdev%2Fablate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framppdev%2Fablate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framppdev%2Fablate/lists"}