Metadata-Version: 2.1
Name: oximachinerunner
Version: 1.4.0
Summary: Run the oximachine
Home-page: https://github.com/kjappelbaum/oximachinerunner
Author: Kevin M. Jablonka, Daniele Ongari, Mohamad Moosavi, Berend Smit
Author-email: kevin.jablonka@epfl.ch
License: MIT
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.7,<3.9
Description-Content-Type: text/markdown
Requires-Dist: oximachine-featurizer (>=0.3.1)
Requires-Dist: xgboost (~=1.3.3)
Provides-Extra: dev
Requires-Dist: pre-commit (~=2.6.0) ; extra == 'dev'
Requires-Dist: pylint (~=2.5.3) ; extra == 'dev'
Requires-Dist: pytest (~=6.0.1) ; extra == 'dev'
Requires-Dist: versioneer (~=0.18) ; extra == 'dev'
Requires-Dist: isort (~=4.3.21) ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx (~=3.3.1) ; extra == 'docs'
Requires-Dist: sphinx-book-theme (~=0.0.39) ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints (~=1.11.1) ; extra == 'docs'
Requires-Dist: sphinx-copybutton (~=0.3.1) ; extra == 'docs'


# oximachinerunner

[![Actions Status](https://github.com/kjappelbaum/oximachinerunner/workflows/Python%20package/badge.svg)](https://github.com/kjappelbaum/oximachinerunner/actions)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/kjappelbaum/oximachinerunner/master?filepath=examples%2Fexample.ipynb)
[![Documentation Status](https://readthedocs.org/projects/oximachinerunner/badge/?version=latest)](https://oximachinerunner.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/kjappelbaum/pyepal/branch/master/graph/badge.svg?token=BL2CF4HQ06)](https://codecov.io/gh/kjappelbaum/oximachinerunner)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oximachinerunner)

## Installation

On macOS you need to run `brew install libomp` first to enable multithreading for the `XGBoost` library.

Ideally, you install everything in a clean environment, e.g., using conda

```bash
conda create -n test_oximachine_runner python=3.7 -y
```

Then activate with `conda activate test_oximachine_runner`.

### Latest stable release

```bash
pip install oximachinerunner
```

Note that the installation requires significant (>500 MB) storage space since the ensembles use k-nearest neighbors models.

### Development version

```bash
pip install git+https://github.com/kjappelbaum/oximachinerunner.git
```

## Usage

#### Loading the model

```python
from oximachinerunner import OximachineRunner
runner = OximachineRunner()
```

The `OximachineRunner` can be initialized with a modelname from `runner.available_models`.

By default, models will be automatically downloaded (upon first use) if there are not yet in the correct folder:

```
/Users/kevinmaikjablonka/opt/miniconda3/envs/test_oximachine_runner/lib/python3.7/site-packages/oximachinerunner/assets/all_202000830/classifier.joblib are not exist or md5 is wrong.
Download file from https://www.dropbox.com/s/lc2z4abaycjbbe1/classifier.joblib?dl=1
2.9% of 527.44M
```

To disable this behavior of, set `OximachineRunner(automatic_download=False)` and manually download your model, e.g. using a function from the `utils` module.

#### Predicting oxidation states

The `run_oximachine` function accepts `pymatgen.Structure`, `ase.Atoms` and `str` as well as `os.PathLike`.
The latter two are expected to be paths to a file that is then parsed with `pymatgen`.

```python
runner.run_oximachine('oximachinerunner/assets/ACODAA.cif')
```

The function prints for how many sites it will run the model.

```
featurize.py: iterating over 6 metal sites
```

It returns an `OrderedDict` with the fields:

- `metal_indices`: A list of indices of the metal sites
- `metal_symbols`: A list of symbols of the metal atoms
- `prediction`: A list of oxidation state predictions
- `max_probabs`: For each metal site the maximum confidence of all 4 models.
- `base_predictions`: For each metal site a list of the oxidation state predictions for each of the 4 models.

### Development setup

```
git clone https://github.com/kjappelbaum/oximachinerunner
pip install -e .[dev]
```

## Reference

Jablonka, Kevin Maik; Ongari, Daniele; Moosavi, Seyed Mohamad; Smit, Berend (2020): Using Collective Knowledge to Assign Oxidation States. ChemRxiv. Preprint. https://doi.org/10.26434/chemrxiv.11604129.v1


