Curifactory
Curifactory: A research experiment manager - Published in JOSS (2023)
Science Score: 98.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
✓DOI references
Found 4 DOI reference(s) in README and JOSS metadata -
✓Academic publication links
Links to: joss.theoj.org -
✓Committers with academic emails
3 of 4 committers (75.0%) from academic institutions -
✓Institutional organization owner
Organization ornl has institutional domain (software.ornl.gov) -
✓JOSS paper metadata
Published in Journal of Open Source Software
Repository
An experiment workflow and organization tool.
Basic Info
- Host: GitHub
- Owner: ORNL
- License: bsd-3-clause
- Language: Python
- Default Branch: main
- Homepage: https://ornl.github.io/curifactory/stable/index.html
- Size: 6 MB
Statistics
- Stars: 18
- Watchers: 4
- Forks: 0
- Open Issues: 57
- Releases: 33
Metadata Files
README.md
Curifactory
Curifactory is a library and CLI tool designed to help organize and manage research experiments in python.
Experiment management must fulfill several tasks, including experiment orchestration, parameterization, caching, reproducibility, reporting, and parallelization. Existing projects such as MLFlow, MetaFlow, Luigi, and Pachyderm support these tasks in several different ways and to various degrees. Curifactory provides a different opinion, with a heavier focus on supporting general research experiment workflows for individuals or small teams working primarily in python.
You can read more about these design principles in our paper in the SciPy 2022 proceedings.
Features
- Adds a CLI layer on top of your codebase, a single entrypoint for running experiments
- Automatic caching of intermediate data and lazy loading of stored objects
- Jupyter notebook output for further exploration of an experiment run
- Docker container output with copy of codebase, conda environment, full experiment run cache, and jupyter run notebook
- HTML report output from each run with graphviz-rendered diagram of experiment
- Easily report plots and values to HTML report
- Configuration files are python scripts, allowing programmatic definition, parameter composition, and parameter inheritance
- Output logs from every run
- Run experiments directly from CLI or other python code, notebooks, etc.
Installation
python
pip install curifactory
Graphviz is required for certain features and can be installed through conda via:
python
conda install python-graphviz
Tab completion
For tab-completion in bash/zsh, install the argcomplete package (if using curifactory inside
a conda environment, you'll need to install this in your system python.)
python
pip install argcomplete
To enable, you can either use argcomplete's global hook activate-global-python-argcomplete, which
will enable tab complete on all argcomplete-enabled python packages (e.g. pytest), or you can add
eval "$(register-python-argcomplete experiment)" to your shell's rc file. Curifactory can add
this line for you automatically with:
bash
curifactory completion [--bash|--zsh] # use the shell flag appropriate
Once enabled, the experiment command will provide tab complete for experiment names, parameter names, and flags.
Requirements
OS: We primarily develop and test Curifactory on Linux, but it runs on Windows and MacOS as well.
Python: 3.9-3.11
Optional:
- Conda/Mamba
- Graphviz
- Docker
- Jupyter notebook/lab
Documentation
The documentation for the latest version of Curifactory can be found at: https://ornl.github.io/curifactory/stable/index.html.
Examples
Several small example can be found in the examples folder.
examples/notebooks includes walkthroughs demonstrating usage of curifactory
solely in Jupyter.
Citation
Please use the following BibTeX if citing this project:
bibtex
@article{Martindale2023,
doi = {10.21105/joss.05793},
url = {https://doi.org/10.21105/joss.05793},
year = {2023},
publisher = {The Open Journal},
volume = {8},
number = {90},
pages = {5793},
author = {Nathan Martindale and Scott L. Stewart and Jason Hite and Mark B. Adams},
title = {Curifactory: A research experiment manager},
journal = {Journal of Open Source Software}
}
Similar Projects
Curifactory is one tool and one opinion among many, other projects that have similar goals and/or approaches:
Owner
- Name: Oak Ridge National Laboratory
- Login: ORNL
- Kind: organization
- Email: software@ornl.gov
- Location: Oak Ridge TN
- Website: http://software.ornl.gov
- Repositories: 99
- Profile: https://github.com/ORNL
Software repositories from Oak Ridge National Laboratory
JOSS Publication
Curifactory: A research experiment manager
Authors
Oak Ridge National Laboratory, USA
Oak Ridge National Laboratory, USA
Oak Ridge National Laboratory, USA
Oak Ridge National Laboratory, USA
Editor
Kelly Rowland
Tags
data analysis management analysis orchestration analysis reporting research experiment managementGitHub Events
Total
- Issues event: 4
- Watch event: 1
- Issue comment event: 1
- Push event: 2
- Create event: 1
Last Year
- Issues event: 4
- Watch event: 1
- Issue comment event: 1
- Push event: 2
- Create event: 1
Committers
Last synced: 7 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| Martindale, Nathan | m****a@o****v | 380 |
| Scott Stewart | 1****l | 8 |
| Mark Adams | a****b@o****v | 4 |
| Daniel S. Katz | d****z@i****g | 2 |
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 121
- Total pull requests: 11
- Average time to close issues: about 2 months
- Average time to close pull requests: 17 days
- Total issue authors: 4
- Total pull request authors: 4
- Average comments per issue: 0.68
- Average comments per pull request: 0.91
- Merged pull requests: 9
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 5
- Pull requests: 2
- Average time to close issues: 1 day
- Average time to close pull requests: about 12 hours
- Issue authors: 1
- Pull request authors: 1
- Average comments per issue: 0.0
- Average comments per pull request: 0.0
- Merged pull requests: 2
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- WildfireXIII (89)
- WarmCyan (8)
- deniederhut (8)
- stewartsl (7)
Pull Request Authors
- WildfireXIII (7)
- WarmCyan (3)
- mbadams5 (1)
- danielskatz (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
-
Total downloads:
- pypi 38 last-month
- Total dependent packages: 0
- Total dependent repositories: 1
- Total versions: 33
- Total maintainers: 2
pypi.org: curifactory
An experiment workflow and organization tool
- Homepage: https://github.com/ORNL/curifactory
- Documentation: https://ornl.github.io/curifactory/stable/index.html
- License: BSD License
-
Latest release: 0.19.0
published 7 months ago
Rankings
Maintainers (2)
Dependencies
- actions/checkout v2 composite
- actions/setup-python v2 composite
- actions/checkout v3 composite
- actions/setup-python v2 composite
- pre-commit/action v3.0.0 composite