# experiments_csv - experiment tracking via CSV files
[](https://badge.fury.io/py/experiments_csv)
## Motivation
You run an experiments with various input parameters. You check various input combinations and run the experiment on each combination.
Suddenly, during one of the runs, the program crashes. You have to restart the experiment for the current and future inputs, but you do not want to repeat it for all previous inputs.
## Solution
`experiments_csv` saves all the experiment input and output data into a CSV file. When you restart the experiment, it reads the CSV file and notes all the input combinations for which the experiment already completed. It then automatically skips these input combinations.
## Installation
Basic installation:
```
pip install experiments-csv
```
Installation with plotting ability:
```
pip install experiments-csv[plotting]
```
## Usage
See the demo programs in the [examples](examples/) folder for usage examples. In detail, you should:
1. Write a function for running a single instance of the experiment.
The function may take any number of arguments as inputs.
It should return a dict with any number of arguments as outputs.
For example:
```
def fair_division_algorithm(num_of_agents:int, num_of_items:int, threshold:float, criterion:str):
# ...
# Run the fair division algorithm with the given parameters
# ...
return {
"runtime": runtime,
"max_value": max(values),
"min_value": min(values)
}
```
2. Decide what ranges you want for your input parameters, for example:
```
input_ranges = {
"num_of_agents": [2, 3, 4],
"num_of_items": range(2,10),
"threshold": [0.5],
"criterion": ["proportionality", "envy-freeness"]
}
```
3. Create an Experiment object. It takes as arguments the folder for the experiment results, the experiment file name, and the folder for backups:
```
import experiments_csv
ex = experiments_csv.Experiment("results/", "results.csv", "results/backups")
```
4. Run the experiment:
```
ex.run(fair_division_algorithm, input_ranges)
```
This loops over all combinations of inputs in the ranges you passed (the Cartesian product of the ranges in input_ranges), calls the single-instance function, and records the results in the given CSV file. The CSV file will have a column for every input and output (in the example: num_of_agents, num_of_items, threshold, criterion, runtime, min_value, max_value), and a single row for every run.
If the experiment stops abruptly due to an error, you can re-run the same code, and it will not repeat the experiments with the combinations of arguments it already completed - it will only run the experiments for the combinations not done yet.
If you do want to restart the experiment from scratch, either manually delete the CSV file, or use a new CSV file with a different name, or do
```
ex.clear_previous_results()
```
To log the inputs and outputs during run, you can do:
```
ex.logger.setLevel(logging.INFO)
```
## Plotting
To plot the results, you can use the `plot_results` function, for example:
```
from matplotlib import pyplot as plt
experiments_csv.plot_results(plt, "results.csv", filter={"algorithm": "abc"}, xcolumn="size", ycolumn="runtime", zcolumn="bits")
```
See the [demo programs](demo/) for usage examples.
Raw data
{
"_id": null,
"home_page": "https://github.com/erelsgl/experiments_csv",
"name": "experiments-csv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "experiments",
"author": "Erel Segal-Halevi",
"author_email": "erelsgl@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/36/37/d236965a96918ffa044eb719e9fc448b1a8543db55da496c7e78ba083c27/experiments_csv-0.5.5.tar.gz",
"platform": null,
"description": "# experiments_csv - experiment tracking via CSV files\r\n[](https://badge.fury.io/py/experiments_csv)\r\n\r\n## Motivation\r\nYou run an experiments with various input parameters. You check various input combinations and run the experiment on each combination.\r\n\r\nSuddenly, during one of the runs, the program crashes. You have to restart the experiment for the current and future inputs, but you do not want to repeat it for all previous inputs.\r\n\r\n## Solution\r\n`experiments_csv` saves all the experiment input and output data into a CSV file. When you restart the experiment, it reads the CSV file and notes all the input combinations for which the experiment already completed. It then automatically skips these input combinations.\r\n\r\n## Installation\r\n\r\nBasic installation:\r\n\r\n```\r\n pip install experiments-csv\r\n```\r\n\r\nInstallation with plotting ability:\r\n\r\n```\r\n pip install experiments-csv[plotting]\r\n```\r\n\r\n\r\n\r\n## Usage\r\nSee the demo programs in the [examples](examples/) folder for usage examples. In detail, you should:\r\n\r\n1. Write a function for running a single instance of the experiment.\r\nThe function may take any number of arguments as inputs.\r\nIt should return a dict with any number of arguments as outputs.\r\nFor example:\r\n\r\n```\r\n def fair_division_algorithm(num_of_agents:int, num_of_items:int, threshold:float, criterion:str):\r\n # ...\r\n # Run the fair division algorithm with the given parameters\r\n # ...\r\n return {\r\n \"runtime\": runtime,\r\n \"max_value\": max(values),\r\n \"min_value\": min(values)\r\n }\r\n```\r\n\r\n2. Decide what ranges you want for your input parameters, for example:\r\n\r\n```\r\n input_ranges = {\r\n \"num_of_agents\": [2, 3, 4],\r\n \"num_of_items\": range(2,10),\r\n \"threshold\": [0.5],\r\n \"criterion\": [\"proportionality\", \"envy-freeness\"]\r\n }\r\n```\r\n\r\n3. Create an Experiment object. It takes as arguments the folder for the experiment results, the experiment file name, and the folder for backups:\r\n\r\n```\r\n import experiments_csv\r\n ex = experiments_csv.Experiment(\"results/\", \"results.csv\", \"results/backups\")\r\n```\r\n\r\n4. Run the experiment:\r\n\r\n```\r\n ex.run(fair_division_algorithm, input_ranges)\r\n```\r\n\r\nThis loops over all combinations of inputs in the ranges you passed (the Cartesian product of the ranges in input_ranges), calls the single-instance function, and records the results in the given CSV file. The CSV file will have a column for every input and output (in the example: num_of_agents, num_of_items, threshold, criterion, runtime, min_value, max_value), and a single row for every run.\r\n\r\nIf the experiment stops abruptly due to an error, you can re-run the same code, and it will not repeat the experiments with the combinations of arguments it already completed - it will only run the experiments for the combinations not done yet.\r\n\r\nIf you do want to restart the experiment from scratch, either manually delete the CSV file, or use a new CSV file with a different name, or do\r\n\r\n```\r\n ex.clear_previous_results()\r\n```\r\n\r\nTo log the inputs and outputs during run, you can do:\r\n```\r\n ex.logger.setLevel(logging.INFO)\r\n```\r\n\r\n## Plotting\r\n\r\nTo plot the results, you can use the `plot_results` function, for example:\r\n\r\n```\r\n from matplotlib import pyplot as plt\r\n experiments_csv.plot_results(plt, \"results.csv\", filter={\"algorithm\": \"abc\"}, xcolumn=\"size\", ycolumn=\"runtime\", zcolumn=\"bits\")\r\n```\r\n\r\nSee the [demo programs](demo/) for usage examples.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple framework for running simulation experiments and recording them in a CSV file",
"version": "0.5.5",
"project_urls": {
"Bug Reports": "https://github.com/erelsgl/experiments_csv/issues",
"Homepage": "https://github.com/erelsgl/experiments_csv",
"Source Code": "https://github.com/erelsgl/experiments_csv"
},
"split_keywords": [
"experiments"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7c21e5e7baf42f19d1d708370d0365aa24286ff273d52a057ef18d6648f6b74c",
"md5": "ac1d94f3bfb17ee37d6ec696961ccc96",
"sha256": "35dd70a1c27b3f8639c4c624aaef23885c2882f370478fcd46950b952915fc0f"
},
"downloads": -1,
"filename": "experiments_csv-0.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac1d94f3bfb17ee37d6ec696961ccc96",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10712,
"upload_time": "2024-06-14T07:34:40",
"upload_time_iso_8601": "2024-06-14T07:34:40.184145Z",
"url": "https://files.pythonhosted.org/packages/7c/21/e5e7baf42f19d1d708370d0365aa24286ff273d52a057ef18d6648f6b74c/experiments_csv-0.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3637d236965a96918ffa044eb719e9fc448b1a8543db55da496c7e78ba083c27",
"md5": "a2e1f0b6ab2dad2d67734878cc0ad0f8",
"sha256": "a283686de85285f5e631ab7c175abf69147a0baa4d4ba22f2888d7b951c6e769"
},
"downloads": -1,
"filename": "experiments_csv-0.5.5.tar.gz",
"has_sig": false,
"md5_digest": "a2e1f0b6ab2dad2d67734878cc0ad0f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11430,
"upload_time": "2024-06-14T07:34:41",
"upload_time_iso_8601": "2024-06-14T07:34:41.587689Z",
"url": "https://files.pythonhosted.org/packages/36/37/d236965a96918ffa044eb719e9fc448b1a8543db55da496c7e78ba083c27/experiments_csv-0.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-14 07:34:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "erelsgl",
"github_project": "experiments_csv",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pandas",
"specs": [
[
">=",
"2.2.2"
]
]
}
],
"lcname": "experiments-csv"
}
JSON
