[](https://mitosis.readthedocs.io/en/latest/?badge=latest)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/mitosis)
[](https://pepy.tech/project/mitosis)
[](https://github.com/psf/black)
# Overview
Mitosis is an experiment _runner_.
It handles administrative tasks to decrease the mental overhead of collaboration:
* Creating a CLI for your experiment
* Recording commit information
* Tracking parameterization, as well as parameter names (e.g. "low-noise")
* Storing logs
* Generating HTML visuals
* Pickling result data
The virtuous consequence of these checks and organization
is a faster workflow,
a more rigorous scientific method,
and reduced mental overhead of collaboration.
## Trivial Example
Hypothesis: the maximum value of a sine wave is equal to its amplitude.
*sine_experiment/\_\_init\_\_.py*
import numpy as np
import matplotlib.pyplot as plt
name = "sine-exp"
lookup_dict = {"frequency": {"fast": 10, "slow": 1}}
def run(amplitude, frequency):
"""Deterimne if the maximum value of the sine function equals ``amplitude``"""
x = np.arange(0, 10, .05)
y = amplitude * np.sin(frequency * x)
err = np.abs(max(y) - amplitude)
plt.title("What's the maximum value of a sine wave?")
plt.plot(x, y, label="trial data")
plt.plot(x, amplitude * np.ones_like(x), label="expected")
plt.legend()
return {"main": err, "data": y}
*pyproject.toml*
[tool.mitosis.steps]
my_exp = ["sine_experiment:run", "sine_experiment:lookup_dict"]
Commit these changes to a repository. After installing sine_experiment as a python package, in CLI, run:
mitosis my_exp --param my_exp.frequency=slow --eval-param my_exp.amplitude=4
Mitosis will run `sin_experiment.run()`, saving
all output as an html file in a subdirectory. It will also
track the parameters and results.
If you later change the variant named "slow" to set frequency=2, mitosis will
raise a `RuntimeError`, preventing you from running a trial. If you want to run
`sine_experiment` with a different parameter value, you need to name that variant
something new. Eval parameters, like "amplitude" in the example, behave differently.
Rather than being specified by `lookup_dict`, they are evaluated directly.
# Use
Philosophically, an experiment is any time we run code with an aim to convince someone
of something.
As code, mitosis takes the approach that an experiment is a callable
(or a sequence of callables).
Using mitosis involves
registering experiments in pyproject.toml,
naming interesting parameters,
running experiments on the command line,
and browsing results.
## Registration
mitosis uses the `tool.mitosis.steps` table of pyproject.toml to learn
what python callables are experiment steps
and where to lookup named parameter values.
It uses a syntax evocative of entry points:
[tool.mitosis.steps]
my_exp = ["sine_experiment:run", "sine_experiment:lookup_dict"]
Experiment steps must be callables with a dictionary return type. The returned
dictionary is required to have a key "main". All but the final step in an experiment
must also have a key "data" that gets passed to the first argument of the subsequent
step. If the key "metrics" is present, it will display prominently in the HTML output
_Developer note: Building an experiment step static type at_ `mitosis._typing.ExpRun`
## CLI
The basic invocation lists the steps along with the values of any parameters for each
step.
mitosis [OPTION...] step [steps...] [[-p step.lookup_param=key...]
[-e step.eval_param=val...]]...
Some nuance:
* `--debug` can be used to waive a lot of the reproducibility checks mitosis does.
This arg allows you to run experiments in a dirty git repository (or no repository)
and will neither save results in the experimental database, nor increment the trials
counter, nor verify/lock in the definitions of any variants. It will, however,
create the output notebook. It also changes the experiment log level from INFO
to DEBUG.
* lookup parameters can be nearly any python object that is pickleable. Tracking
parameter values can be turned off for parameters either for something that isn't
pickleable (e.g. a lambda function) or isn't important to track
(e.g. which GPU to run on). This can be done with eval or lookup parameters
by adding a `+` to the parameter, e.g. `-e +jax_playground.gpu_id=1`.
* Eval parameters which are strings will need quotation marks that escape the shell
(e.g. `-e smoothing.kernel=\"rbf\"`)
* `-e` and `-p` are short form for `--eval-param` and `--param` (lookup param).
## Results
Trials are saved in `trials/` (or whatever is passed after `-F`). Each trial has a
pseudorandom bytes key, postpended to a metadata folder and an html output filename.
There are two obviously useful things to do after an experiment:
* view the html file. `python -m http.server` is helpful to browse results
* load the data with `mitosis.load_trial_data()`
Beyond this, the metadata mitosis keeps to disk is useful for troubleshooting or reproducing experiments, but no facility yet exists to browse or compare experiments.
## API
Mitosis is primarily intended as a command line program, so `mitosis --help` has the syntax documentation.
There is only one intentionally public part of the api: `mitosis.load_trial_data()`.
Raw data
{
"_id": null,
"home_page": null,
"name": "mitosis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Machine Learning, Science, Mathematics, Experiments",
"author": null,
"author_email": "Jake Stevens-Haas <jacob.stevens.haas@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bc/c1/a08d02798091e33ee1d8b8a640220b4ea73b446d0a6cdfca95c051547eeb/mitosis-0.6.1.tar.gz",
"platform": null,
"description": "[](https://mitosis.readthedocs.io/en/latest/?badge=latest)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/mitosis)\n[](https://pepy.tech/project/mitosis)\n[](https://github.com/psf/black)\n\n\n# Overview\nMitosis is an experiment _runner_.\nIt handles administrative tasks to decrease the mental overhead of collaboration:\n* Creating a CLI for your experiment\n* Recording commit information\n* Tracking parameterization, as well as parameter names (e.g. \"low-noise\")\n* Storing logs\n* Generating HTML visuals\n* Pickling result data\n\nThe virtuous consequence of these checks and organization\n is a faster workflow,\n a more rigorous scientific method,\n and reduced mental overhead of collaboration.\n\n## Trivial Example\n\nHypothesis: the maximum value of a sine wave is equal to its amplitude.\n\n*sine_experiment/\\_\\_init\\_\\_.py*\n\n\n import numpy as np\n import matplotlib.pyplot as plt\n\n name = \"sine-exp\"\n lookup_dict = {\"frequency\": {\"fast\": 10, \"slow\": 1}}\n\n def run(amplitude, frequency):\n \"\"\"Deterimne if the maximum value of the sine function equals ``amplitude``\"\"\"\n x = np.arange(0, 10, .05)\n y = amplitude * np.sin(frequency * x)\n err = np.abs(max(y) - amplitude)\n plt.title(\"What's the maximum value of a sine wave?\")\n plt.plot(x, y, label=\"trial data\")\n plt.plot(x, amplitude * np.ones_like(x), label=\"expected\")\n plt.legend()\n return {\"main\": err, \"data\": y}\n\n\n*pyproject.toml*\n\n [tool.mitosis.steps]\n my_exp = [\"sine_experiment:run\", \"sine_experiment:lookup_dict\"]\n\n\nCommit these changes to a repository. After installing sine_experiment as a python package, in CLI, run:\n\n mitosis my_exp --param my_exp.frequency=slow --eval-param my_exp.amplitude=4\n\nMitosis will run `sin_experiment.run()`, saving\nall output as an html file in a subdirectory. It will also\ntrack the parameters and results.\nIf you later change the variant named \"slow\" to set frequency=2, mitosis will\nraise a `RuntimeError`, preventing you from running a trial. If you want to run\n`sine_experiment` with a different parameter value, you need to name that variant\nsomething new. Eval parameters, like \"amplitude\" in the example, behave differently.\nRather than being specified by `lookup_dict`, they are evaluated directly.\n\n\n# Use\n\nPhilosophically, an experiment is any time we run code with an aim to convince someone\n of something.\nAs code, mitosis takes the approach that an experiment is a callable\n (or a sequence of callables).\n\nUsing mitosis involves\n registering experiments in pyproject.toml,\n naming interesting parameters,\n running experiments on the command line,\n and browsing results.\n\n## Registration\n\nmitosis uses the `tool.mitosis.steps` table of pyproject.toml to learn\n what python callables are experiment steps\n and where to lookup named parameter values.\nIt uses a syntax evocative of entry points:\n\n [tool.mitosis.steps]\n my_exp = [\"sine_experiment:run\", \"sine_experiment:lookup_dict\"]\n\nExperiment steps must be callables with a dictionary return type. The returned\ndictionary is required to have a key \"main\". All but the final step in an experiment\nmust also have a key \"data\" that gets passed to the first argument of the subsequent\nstep. If the key \"metrics\" is present, it will display prominently in the HTML output\n\n_Developer note: Building an experiment step static type at_ `mitosis._typing.ExpRun`\n\n## CLI\n\nThe basic invocation lists the steps along with the values of any parameters for each\nstep.\n\n mitosis [OPTION...] step [steps...] [[-p step.lookup_param=key...]\n [-e step.eval_param=val...]]...\n\nSome nuance:\n* `--debug` can be used to waive a lot of the reproducibility checks mitosis does.\n This arg allows you to run experiments in a dirty git repository (or no repository)\n and will neither save results in the experimental database, nor increment the trials\n counter, nor verify/lock in the definitions of any variants. It will, however,\n create the output notebook. It also changes the experiment log level from INFO\n to DEBUG.\n* lookup parameters can be nearly any python object that is pickleable. Tracking\n parameter values can be turned off for parameters either for something that isn't\n pickleable (e.g. a lambda function) or isn't important to track\n (e.g. which GPU to run on). This can be done with eval or lookup parameters\n by adding a `+` to the parameter, e.g. `-e +jax_playground.gpu_id=1`.\n* Eval parameters which are strings will need quotation marks that escape the shell\n (e.g. `-e smoothing.kernel=\\\"rbf\\\"`)\n* `-e` and `-p` are short form for `--eval-param` and `--param` (lookup param).\n\n## Results\n\nTrials are saved in `trials/` (or whatever is passed after `-F`). Each trial has a\npseudorandom bytes key, postpended to a metadata folder and an html output filename.\n\nThere are two obviously useful things to do after an experiment:\n* view the html file. `python -m http.server` is helpful to browse results\n* load the data with `mitosis.load_trial_data()`\n\nBeyond this, the metadata mitosis keeps to disk is useful for troubleshooting or reproducing experiments, but no facility yet exists to browse or compare experiments.\n\n## API\n\nMitosis is primarily intended as a command line program, so `mitosis --help` has the syntax documentation.\nThere is only one intentionally public part of the api: `mitosis.load_trial_data()`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Reproduce Machine Learning experiments easily",
"version": "0.6.1",
"project_urls": {
"homepage": "https://github.com/Jacob-Stevens-Haas/mitosis"
},
"split_keywords": [
"machine learning",
" science",
" mathematics",
" experiments"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "489feabc19bdf2774d1255869e115ae929e344a0b257b20eadc51ce64ab36237",
"md5": "b0b29a16f64752aefeb3df7205531d3f",
"sha256": "2db9e12d80789c06e69cb898615cb5896c5f88690a03afb47c09ff319ae88d22"
},
"downloads": -1,
"filename": "mitosis-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0b29a16f64752aefeb3df7205531d3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25318,
"upload_time": "2025-07-28T21:46:09",
"upload_time_iso_8601": "2025-07-28T21:46:09.325788Z",
"url": "https://files.pythonhosted.org/packages/48/9f/eabc19bdf2774d1255869e115ae929e344a0b257b20eadc51ce64ab36237/mitosis-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bcc1a08d02798091e33ee1d8b8a640220b4ea73b446d0a6cdfca95c051547eeb",
"md5": "932644508fd462acc372b83a6c159a8a",
"sha256": "94f368faa215cc807ff094fcc5f783d786b1c3cdb8045044201137d0e94ea9e4"
},
"downloads": -1,
"filename": "mitosis-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "932644508fd462acc372b83a6c159a8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27779,
"upload_time": "2025-07-28T21:46:10",
"upload_time_iso_8601": "2025-07-28T21:46:10.890155Z",
"url": "https://files.pythonhosted.org/packages/bc/c1/a08d02798091e33ee1d8b8a640220b4ea73b446d0a6cdfca95c051547eeb/mitosis-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 21:46:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jacob-Stevens-Haas",
"github_project": "mitosis",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mitosis"
}
JSON
