volcanic: Automated Generator of Volcano Plots
==============================================
[](https://zenodo.org/badge/latestdoi/381737392)
[](https://badge.fury.io/py/navicat_volcanic)
## Contents
* [About](#about-)
* [Install](#install-)
* [Examples](#examples-)
* [Citation](#citation-)
## About [↑](#about)
The code runs on pure python with the following dependencies:
- `numpy`
- `scipy`
- `matplotlib`
- `pandas`
- `scikit-learn`
- Optionally, `h5py`
## Install [↑](#install)
You can install volcanic using pip:
```python
pip install navicat_volcanic
```
Afterwards, you can call volcanic as:
```python
python -m navicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]
[-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]
```
or simply
```python
navicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]
[-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]
```
Alternatively, you can download the package and execute:
```python
python setup.py install
```
Afterwards, you can call volcanic as:
```python
python -m navicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]
[-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]
```
or
```python
navicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]
[-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]
```
Options can be consulted using the `-h` flag in either case. The help menu is quite detailed.
Note that the volcano plot and activity map functions are directly exposed in `volcanic.py` as `volcanic_2d` and `volcanic_3d` respectively, in case you want to incorporate them in your own code.
## Examples [↑](#examples)
The examples subdirectory contains a copious amount of tests which double as examples. Any of the data files can be run as:
```python
python -m navicat_volcanic -i [FILENAME]
```
This will query the user for options and generate the volcano plots as png images. Options can be consulted with the `-h` flag.
The input of volcanic is a `pandas` compatible dataframe, which includes plain .csv and .xls files.
Regarding format, volcanic expects headers for all columns. The first column must contain names/identifiers. Then, volcanic expects a number of columns with relative free energies for the species in the catalytic cycle (in order of appearance), whose headers must contain "TS" if the species is a transition state, and a final column whose header is "Product" containing the reaction energy. Non-energy descriptors can be input as a separate file using the `-df` flag or as extra columns whose headers contain the word "Descriptor".
High verbosity levels (`-v 1`, `-v 2`, etc.) will print the output as .csv files as well, which can be used to plot your volcano plot or activity map using external tools. An example is found in the `pretty_plotting_example` directory in this repository. Keep increasing the verbosity to get even more detailed output. This can be useful for understanding what the code is doing and what can have possibly gone wrong. To be as automated as possible, reasonable default values are set for most choices. The generated csvs also contain the 95% confidence interval value for the plot in question, which are obtained by propagating the uncertainty of the LSFERs involved in the computation. To simplify the propagation of uncertainties in the TOF computation, the uncertainty is approximated using the energy span in TOF volcano plots.
The plotmode (`-pm 1`, `-pm 2`) option can be used to modify the default look of the generated pngs, including more detail as the plotmode level increases.
## Citation [↑](#citation)
Please cite the accompanying manuscript, which clarifies the details of volcano plot construction. You can find it [here](https://rdcu.be/cT7uu) and in the reference:
```
Laplaza, R., Das, S., Wodrich, M.D. et al. Constructing and interpreting volcano plots and activity maps to navigate homogeneous catalyst landscapes. Nat Protoc (2022). https://doi.org/10.1038/s41596-022-00726-2
```
Kinetic volcano plots were introduced [here](https://doi.org/10.1039/C6SC01660J) and turnover frequency/energy span volcano plots were introduced [here](https://doi.org/10.1021/acscatal.9b00717). The energy span model was introduced by Kozuch and Shaik [here](https://doi.org/10.1021/ar1000956). Please include those citations where relevant. A comprehensive account can be found [here](https://doi.org/10.1021/acs.accounts.0c00857).
---
Raw data
{
"_id": null,
"home_page": "https://github.com/lcmd-epfl/volcanic/",
"name": "navicat-volcanic",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "compchem",
"author": "rlaplaza, lcmd-epfl",
"author_email": "\"R. Laplaza\" <rlaplaza@duck.com>",
"download_url": "https://files.pythonhosted.org/packages/82/89/137512d358773eb2b11be08b0c156043937a117344be459213605f73243a/navicat_volcanic-1.3.3.tar.gz",
"platform": null,
"description": "volcanic: Automated Generator of Volcano Plots\n==============================================\n[](https://zenodo.org/badge/latestdoi/381737392)\n\n\n[](https://badge.fury.io/py/navicat_volcanic)\n\n## Contents\n* [About](#about-)\n* [Install](#install-)\n* [Examples](#examples-)\n* [Citation](#citation-)\n\n## About [\u2191](#about)\n\nThe code runs on pure python with the following dependencies: \n- `numpy`\n- `scipy`\n- `matplotlib`\n- `pandas`\n- `scikit-learn`\n- Optionally, `h5py`\n\n## Install [\u2191](#install)\n\nYou can install volcanic using pip:\n\n```python\npip install navicat_volcanic\n```\n\nAfterwards, you can call volcanic as:\n\n```python\npython -m navicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]\n [-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]\n```\nor simply\n```python\nnavicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]\n [-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]\n```\n\nAlternatively, you can download the package and execute:\n\n```python \npython setup.py install\n```\n\nAfterwards, you can call volcanic as:\n\n```python\npython -m navicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]\n [-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]\n```\nor\n```python\nnavicat_volcanic [-h] [-version] -i [FILENAMES] [-df DFILENAMES] [-nd ND] [-v VERB] [-r RUNMODE] [-lsfer | -thermo | -kinetic | -es | -tof | -all] [-T TEMP] [-pm PLOTMODE] [-ic IC] [-fc FC]\n [-rm RMARGIN] [-lm LMARGIN] [-np NPOINTS] [-d] [-is IMPUTER_STRAT] [-refill]\n```\n\n\nOptions can be consulted using the `-h` flag in either case. The help menu is quite detailed. \n\nNote that the volcano plot and activity map functions are directly exposed in `volcanic.py` as `volcanic_2d` and `volcanic_3d` respectively, in case you want to incorporate them in your own code.\n\n## Examples [\u2191](#examples)\n\nThe examples subdirectory contains a copious amount of tests which double as examples. Any of the data files can be run as:\n\n```python\npython -m navicat_volcanic -i [FILENAME]\n```\n\nThis will query the user for options and generate the volcano plots as png images. Options can be consulted with the `-h` flag.\n\nThe input of volcanic is a `pandas` compatible dataframe, which includes plain .csv and .xls files. \n\nRegarding format, volcanic expects headers for all columns. The first column must contain names/identifiers. Then, volcanic expects a number of columns with relative free energies for the species in the catalytic cycle (in order of appearance), whose headers must contain \"TS\" if the species is a transition state, and a final column whose header is \"Product\" containing the reaction energy. Non-energy descriptors can be input as a separate file using the `-df` flag or as extra columns whose headers contain the word \"Descriptor\".\n\nHigh verbosity levels (`-v 1`, `-v 2`, etc.) will print the output as .csv files as well, which can be used to plot your volcano plot or activity map using external tools. An example is found in the `pretty_plotting_example` directory in this repository. Keep increasing the verbosity to get even more detailed output. This can be useful for understanding what the code is doing and what can have possibly gone wrong. To be as automated as possible, reasonable default values are set for most choices. The generated csvs also contain the 95% confidence interval value for the plot in question, which are obtained by propagating the uncertainty of the LSFERs involved in the computation. To simplify the propagation of uncertainties in the TOF computation, the uncertainty is approximated using the energy span in TOF volcano plots. \n\nThe plotmode (`-pm 1`, `-pm 2`) option can be used to modify the default look of the generated pngs, including more detail as the plotmode level increases. \n\n\n## Citation [\u2191](#citation)\n\nPlease cite the accompanying manuscript, which clarifies the details of volcano plot construction. You can find it [here](https://rdcu.be/cT7uu) and in the reference:\n\n```\nLaplaza, R., Das, S., Wodrich, M.D. et al. Constructing and interpreting volcano plots and activity maps to navigate homogeneous catalyst landscapes. Nat Protoc (2022). https://doi.org/10.1038/s41596-022-00726-2\n```\n\nKinetic volcano plots were introduced [here](https://doi.org/10.1039/C6SC01660J) and turnover frequency/energy span volcano plots were introduced [here](https://doi.org/10.1021/acscatal.9b00717). The energy span model was introduced by Kozuch and Shaik [here](https://doi.org/10.1021/ar1000956). Please include those citations where relevant. A comprehensive account can be found [here](https://doi.org/10.1021/acs.accounts.0c00857).\n\n\n---\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Modular Analysis of Representative Conformers",
"version": "1.3.3",
"project_urls": {
"Homepage": "https://github.com/lcmd-epfl/volcanic/"
},
"split_keywords": [
"compchem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e3305cce639c3035a721f99a56c69576c9e4c178c9fad37b536eeb77a948078",
"md5": "d1243b2c68999b0553bcc21c4355c9a3",
"sha256": "c7b4f8a8482a5e0832fb54a473585f4c2f608a7852325a976009769bb5a88509"
},
"downloads": -1,
"filename": "navicat_volcanic-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d1243b2c68999b0553bcc21c4355c9a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28377,
"upload_time": "2023-12-13T10:21:57",
"upload_time_iso_8601": "2023-12-13T10:21:57.325606Z",
"url": "https://files.pythonhosted.org/packages/9e/33/05cce639c3035a721f99a56c69576c9e4c178c9fad37b536eeb77a948078/navicat_volcanic-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8289137512d358773eb2b11be08b0c156043937a117344be459213605f73243a",
"md5": "624f6477bc85cf0f61b385b4ede223d6",
"sha256": "4a8ac7a78e6a7712fcd69f3cde1d42c0c393a80b762a797846564f6b1291e394"
},
"downloads": -1,
"filename": "navicat_volcanic-1.3.3.tar.gz",
"has_sig": false,
"md5_digest": "624f6477bc85cf0f61b385b4ede223d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24869,
"upload_time": "2023-12-13T10:21:58",
"upload_time_iso_8601": "2023-12-13T10:21:58.455462Z",
"url": "https://files.pythonhosted.org/packages/82/89/137512d358773eb2b11be08b0c156043937a117344be459213605f73243a/navicat_volcanic-1.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-13 10:21:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lcmd-epfl",
"github_project": "volcanic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "navicat-volcanic"
}
JSON
