adibvafa / cyclops

Toolkit for healthcare ML implementation

---

cyclops is a toolkit for facilitating research and deployment of ML models for healthcare. It provides a few high-level APIs namely:

• query - Query EHR databases (such as MIMIC-IV)
• data - Create datasets for training, inference and evaluation. We use the popular 🤗 datasets to efficiently load and slice different modalities of data.
• models - Use common model implementations using scikit-learn and PyTorch.
• tasks - Use canonical Healthcare ML tasks such as
  • Mortality prediction
  • Chest X-ray classification
• evaluate - Evaluate models on clinical prediction tasks
• monitor - Detect dataset shift relevant for clinical use cases
• report - Create model report cards for clinical ML models

cyclops also provides a library of end-to-end use cases on clinical datasets such as

• MIMIC-III
• MIMIC-IV
• eICU-CRD

🐣 Getting Started

Installing cyclops using pip

python3 -m pip install pycyclops

The base package installation supports the use of the data and process APIs to load and transform clinical data, for downstream tasks.

To install additional functionality from the other APIs, they can be installed as extras.

To install with query API support,

python3 -m pip install 'pycyclops[query]'

To install with models, tasks, evaluate and monitor API support,

python3 -m pip install 'pycyclops[models]'

To install with report API support,

python3 -m pip install 'pycyclops[report]'

Multiple extras could also be combined, for example to install with both query and models support:

python3 -m pip install 'pycyclops[query,models]'

🧑🏿‍💻 Developing

Using poetry

The development environment can be set up using poetry. Hence, make sure it is installed and then run:

python3 -m poetry install
source $(poetry env info --path)/bin/activate

Using Conda

The development environment can also be set up using conda. Hence, make sure it is installed and then run:

conda env create
conda install conda-build
conda develop .

API documentation is built using Sphinx and can be locally built by:

cd docs
make html SPHINXOPTS="-D nbsphinx_allow_errors=True"

Contributing

Contributing to cyclops is welcomed. See Contributing for guidelines.

📚 Documentation

📓 Notebooks

To use jupyter notebooks, the python virtual environment can be installed and used inside an IPython kernel. After activating the virtual environment, run:

python3 -m ipykernel install --user --name <name_of_kernel>

Now, you can navigate to the notebook's Kernel tab and set it as <name_of_kernel>.

🎓 Citation

Reference to cite when you use CyclOps in a project or a research paper:

@article {Krishnan2022.12.02.22283021,
	author = {Krishnan, Amrit and Subasri, Vallijah and McKeen, Kaden and Kore, Ali and Ogidi, Franklin and Alinoori, Mahshid and Lalani, Nadim and Dhalla, Azra and Verma, Amol and Razak, Fahad and Pandya, Deval and Dolatabadi, Elham},
	title = {CyclOps: Cyclical development towards operationalizing ML models for health},
	elocation-id = {2022.12.02.22283021},
	year = {2022},
	doi = {10.1101/2022.12.02.22283021},
	publisher = {Cold Spring Harbor Laboratory Press},
	URL = {https://www.medrxiv.org/content/early/2022/12/08/2022.12.02.22283021},
	journal = {medRxiv}
}