Metadata-Version: 2.1
Name: pycyclops
Version: 0.2.0.dev0
Summary: Framework for healthcare ML implementation
Home-page: https://github.com/VectorInstitute/cyclops
License: Apache-2.0
Author: Vector AI Engineering
Author-email: cyclops@vectorinstitute.ai
Requires-Python: >=3.9,<3.11
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Provides-Extra: models
Provides-Extra: report
Requires-Dist: alibi-detect[torch] (>=0.11.0,<0.12.0) ; extra == "models"
Requires-Dist: alibi[shap] (>=0.9.4,<0.10.0) ; extra == "models"
Requires-Dist: datasets (>=2.10.1,<3.0.0)
Requires-Dist: hydra-core (>=1.2.0,<2.0.0) ; extra == "models"
Requires-Dist: kaleido (==0.2.1) ; extra == "report"
Requires-Dist: llvmlite (>=0.40.0,<0.41.0) ; extra == "models"
Requires-Dist: monai[itk] (>=1.1.0,<2.0.0)
Requires-Dist: numpy (>=1.23.0,<2.0.0)
Requires-Dist: pandas (>=2.0,<3.0)
Requires-Dist: pillow (>=9.5.0,<10.0.0) ; extra == "report"
Requires-Dist: plotly (>=5.7.0,<6.0.0) ; extra == "report"
Requires-Dist: psutil (>=5.9.4,<6.0.0)
Requires-Dist: pyarrow (>=11.0.0,<12.0.0)
Requires-Dist: pybtex (>=0.24.0,<0.25.0) ; extra == "report"
Requires-Dist: pydantic (>=1.10.11,<2.0.0) ; extra == "report"
Requires-Dist: scikit-learn (>=1.2.2,<2.0.0) ; extra == "models"
Requires-Dist: scour (>=0.38.2,<0.39.0) ; extra == "report"
Requires-Dist: spdx-tools (>=0.8.1,<0.9.0) ; extra == "report"
Requires-Dist: torch (>=1.11.0,<2.0.0) ; extra == "models"
Requires-Dist: torchxrayvision (>=1.2.0,<2.0.0) ; extra == "models"
Requires-Dist: xgboost (>=1.5.2,<2.0.0) ; extra == "models"
Project-URL: Documentation, https://vectorinstitute.github.io/cyclops/
Project-URL: Repository, https://github.com/VectorInstitute/cyclops
Description-Content-Type: text/markdown

![cyclops Logo](https://github.com/VectorInstitute/cyclops/blob/main/docs/source/theme/static/cyclops_logo-dark.png?raw=true)

--------------------------------------------------------------------------------

[![PyPI](https://img.shields.io/pypi/v/pycyclops)](https://pypi.org/project/pycyclops)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycyclops)
[![code checks](https://github.com/VectorInstitute/cyclops/actions/workflows/code_checks.yml/badge.svg)](https://github.com/VectorInstitute/cyclops/actions/workflows/code_checks.yml)
[![integration tests](https://github.com/VectorInstitute/cyclops/actions/workflows/integration_tests.yml/badge.svg)](https://github.com/VectorInstitute/cyclops/actions/workflows/integration_tests.yml)
[![docs](https://github.com/VectorInstitute/cyclops/actions/workflows/docs_deploy.yml/badge.svg)](https://github.com/VectorInstitute/cyclops/actions/workflows/docs_deploy.yml)
[![codecov](https://codecov.io/gh/VectorInstitute/cyclops/branch/main/graph/badge.svg)](https://codecov.io/gh/VectorInstitute/cyclops)
[![docker](https://github.com/VectorInstitute/cyclops/actions/workflows/docker.yml/badge.svg)](https://hub.docker.com/r/vectorinstitute/cyclops)
[![license](https://img.shields.io/github/license/VectorInstitute/cyclops.svg)](https://github.com/VectorInstitute/cyclops/blob/main/LICENSE)

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

* `data` - Create datasets for training, inference and evaluation. We use the popular 🤗 [datasets](https://github.com/huggingface/datasets) to efficiently load and slice different modalities of data.
* `models` - Use common model implementations using [scikit-learn](https://scikit-learn.org/stable/) and [PyTorch](https://pytorch.org/).
* `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](https://vectorinstitute.github.io/cyclops/api/tutorials/nihcxr/nihcxr_report_periodic.html) for clinical ML models

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

* [MIMIC-III](https://physionet.org/content/mimiciii/1.4/)
* [MIMIC-IV](https://physionet.org/content/mimiciv/2.0/)
* [eICU-CRD](https://eicu-crd.mit.edu/about/eicu/)


## 🐣 Getting Started

### Installing cyclops using pip

```bash
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 `models`, `tasks`, `evaluate` and `monitor` API support,

```bash
python3 -m pip install 'pycyclops[models]'
```

To install with `report` API support,

```bash
python3 -m pip install 'pycyclops[report]'
```

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

```bash
python3 -m pip install 'pycyclops[report,models]'
```


## 🧑🏿‍💻 Developing

### Using poetry

The development environment can be set up using
[poetry](https://python-poetry.org/docs/#installation). Hence, make sure it is
installed and then run:

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

In order to install dependencies for testing (codestyle, unit tests, integration tests),
run:

```bash
python3 -m poetry install --with test
```

API documentation is built using [Sphinx](https://www.sphinx-doc.org/en/master/) and
can be locally built by:

```bash
python3 -m poetry install --with docs
cd docs
make html SPHINXOPTS="-D nbsphinx_allow_errors=True"
```

### Contributing

Contributing to cyclops is welcomed.
See [Contributing](https://vectorinstitute.github.io/cyclops/api/intro.html) for
guidelines.


## 📚 [Documentation](https://vectorinstitute.github.io/cyclops/)


## 📓 Notebooks

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

```bash
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}
}
```

