# Cordage: Computational Research Data Management
[](https://github.com/plonerma/cordage/actions)
[](https://pypi.org/project/cordage/)
[](https://pypi.org/project/cordage/)
[](https://github.com/plonerma/cordage/blob/main/LICENSE)
[](https://github.com/psf/black)
Parameterize experiments using dataclasses and use cordage to easily parse configuration files and command line
options.
> [!IMPORTANT]
> Cordage is in a very early stage. Currently, it lacks a lot of documentation and wider range
> of features. If you think it could be useful for you, try it out and leave suggestions, complains, and improvemnt ideas
> as [github issues](https://github.com/plonerma/cordage/issues).
## Motivation
In many cases, we want to execute and parameterize a main function.
Since experiments can quickly become more complex and may use an increasing number of parameters,
it often makes sense to store these parameters in a `dataclass`.
Cordage makes it easy to load configuration files or configure the experiment via the commandline.
## Quick Start
### Installation
In an environment of your choice (python>=3.8), run:
```bash
pip install cordage
```
#### Example
```python
from dataclasses import dataclass
import cordage
@dataclass
class Config:
lr: float = 5e-5
name: str = "MNIST"
def train(config: Config):
"""Help text which will be shown."""
print(config)
if __name__ == "__main__":
cordage.run(train)
```
To use cordage, you need a main function (e.g. `func`) which takes a dataclass configuration object as an argument.
Use `cordage.run(func)` to execute this function with arguments passed via the command line. Cordage parses the
configuration and creates an output directory (if the function accepts `output_dir`, it will be passed as such).
See the examples in the examples directory for more details.
## Features
The main puprose of cordage is to manage configurations to make configuring reproducible experiments easy.
Cordage automatically generates a commandline interface which can be used to parse configuration files and/or
set specific configuration fields via CLI options (run the experiment with the `--help option` to get an overview
over the available configuration fields).
By using the `__series__` key, it is possible ot invoke multiple repetitions of an experiment using the same
base configuration but varying some of the configuration fields. The resulting trial runs are (by default)
saved in a common series-level directory.
Additionally, cordage can provide an output directory (via the `output_dir`) where cordage will store the used configuration
as well as some experimental metadata.
Raw data
{
"_id": null,
"home_page": null,
"name": "cordage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Max Ploner <cordage@maxploner.de>",
"download_url": "https://files.pythonhosted.org/packages/0e/54/a333f1e8168fe445d3eb5b2b20c003217df2f11cbc6dd26f239a4523b099/cordage-0.0.4.post3.tar.gz",
"platform": null,
"description": "\n\n\n# Cordage: Computational Research Data Management\n\n\n[](https://github.com/plonerma/cordage/actions)\n[](https://pypi.org/project/cordage/)\n[](https://pypi.org/project/cordage/)\n[](https://github.com/plonerma/cordage/blob/main/LICENSE)\n[](https://github.com/psf/black)\n\nParameterize experiments using dataclasses and use cordage to easily parse configuration files and command line\noptions.\n\n> [!IMPORTANT] \n> Cordage is in a very early stage. Currently, it lacks a lot of documentation and wider range\n> of features. If you think it could be useful for you, try it out and leave suggestions, complains, and improvemnt ideas\n> as [github issues](https://github.com/plonerma/cordage/issues).\n\n\n## Motivation\n\nIn many cases, we want to execute and parameterize a main function.\nSince experiments can quickly become more complex and may use an increasing number of parameters,\nit often makes sense to store these parameters in a `dataclass`.\n\nCordage makes it easy to load configuration files or configure the experiment via the commandline.\n\n\n## Quick Start\n### Installation\n\nIn an environment of your choice (python>=3.8), run:\n\n```bash\npip install cordage\n```\n\n#### Example\n\n```python\nfrom dataclasses import dataclass\nimport cordage\n\n\n@dataclass\nclass Config:\n lr: float = 5e-5\n name: str = \"MNIST\"\n\n\ndef train(config: Config):\n \"\"\"Help text which will be shown.\"\"\"\n print(config)\n\n\nif __name__ == \"__main__\":\n cordage.run(train)\n```\n\n\nTo use cordage, you need a main function (e.g. `func`) which takes a dataclass configuration object as an argument.\nUse `cordage.run(func)` to execute this function with arguments passed via the command line. Cordage parses the\nconfiguration and creates an output directory (if the function accepts `output_dir`, it will be passed as such).\n\nSee the examples in the examples directory for more details.\n\n\n## Features\n\nThe main puprose of cordage is to manage configurations to make configuring reproducible experiments easy.\nCordage automatically generates a commandline interface which can be used to parse configuration files and/or\nset specific configuration fields via CLI options (run the experiment with the `--help option` to get an overview\nover the available configuration fields).\n\nBy using the `__series__` key, it is possible ot invoke multiple repetitions of an experiment using the same\nbase configuration but varying some of the configuration fields. The resulting trial runs are (by default) \nsaved in a common series-level directory.\n\nAdditionally, cordage can provide an output directory (via the `output_dir`) where cordage will store the used configuration\nas well as some experimental metadata.\n",
"bugtrack_url": null,
"license": null,
"summary": "Small framework for computational research data management",
"version": "0.0.4.post3",
"project_urls": {
"Documentation": "https://github.com/plonerma/cordage#readme",
"Issues": "https://github.com/plonerma/cordage/issues",
"Source": "https://github.com/plonerma/cordage"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f72e57000bd9cdbf1d4bfe4375e0c659b634c2f92f49118e61857dc0a85b70e5",
"md5": "5baeef6c99b504c55fd25f8ae1297306",
"sha256": "14345d7c6219a2d61f45e7dd42d71fc69b068a60c55a7d5f110ec7d2211b1dac"
},
"downloads": -1,
"filename": "cordage-0.0.4.post3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5baeef6c99b504c55fd25f8ae1297306",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18120,
"upload_time": "2023-11-23T18:19:09",
"upload_time_iso_8601": "2023-11-23T18:19:09.799857Z",
"url": "https://files.pythonhosted.org/packages/f7/2e/57000bd9cdbf1d4bfe4375e0c659b634c2f92f49118e61857dc0a85b70e5/cordage-0.0.4.post3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0e54a333f1e8168fe445d3eb5b2b20c003217df2f11cbc6dd26f239a4523b099",
"md5": "618a6f4ac2691e6960c3c9d8f9c83dd1",
"sha256": "9409076b7e8185b7f5299012537cebf2e2fc7bcb65469ee61e17a64188274068"
},
"downloads": -1,
"filename": "cordage-0.0.4.post3.tar.gz",
"has_sig": false,
"md5_digest": "618a6f4ac2691e6960c3c9d8f9c83dd1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33676,
"upload_time": "2023-11-23T18:19:08",
"upload_time_iso_8601": "2023-11-23T18:19:08.106356Z",
"url": "https://files.pythonhosted.org/packages/0e/54/a333f1e8168fe445d3eb5b2b20c003217df2f11cbc6dd26f239a4523b099/cordage-0.0.4.post3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-23 18:19:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plonerma",
"github_project": "cordage#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "docstring_parser",
"specs": []
},
{
"name": "colorlog",
"specs": []
},
{
"name": "dacite",
"specs": []
}
],
"lcname": "cordage"
}
JSON
