chicolucio/ph-diagrams

A Python package to plot fractional composition diagrams and pH-log c diagrams

pH diagrams

A Python package to plot fractional composition diagrams and pH-log c diagrams

Interactive web app:

Installation

pip install pH-diagrams

Usage

The class Acid must be imported from ph_diagrams. To create diagrams for the acetic acid:

>>> from ph_diagrams import Acid
>>> import matplotlib.pyplot as plt
>>> fig, axs = plt.subplots(nrows=1, ncols=2)
>>> acetic_acid = Acid(pKa=(4.76,), acid_concentration=0.1)
>>> acetic_acid.plot(plot_type='distribution', backend='matplotlib',
                     title='Acetic acid - Distribution diagram',
                     ax=axs[0], legend=False)
>>> acetic_acid.plot(plot_type='pC', backend='matplotlib',
                     title='Acetic acid - pH-log c diagram', ax=axs[1])
>>> plt.show()

As can be seen, the parameter pKa must be a tuple even if there is only one value. The above example generates the following plot, with both diagrams side by side:

The plots above were made with Matplotlib, the default backend.

Changing the backend parameter to plotly, and removing the ax parameter (it works only with Matplotlib), will open a browser window for each plot. Since Plotly is interactive, the user can zoom, pan, and see values on hover.

Full documentation is hosted on Read the Docs.

A live interactive version of this project can be seen clicking in the following badge:

The web app was made with Streamlit and hosted on Heroku.

A brief explanation on the chemical theory behind each diagram can be seen here.

Local Streamlit app and Jupyter notebooks

This repo has Jupyter Notebooks and scripts for a fully functional Streamlit app. First, create a virtual environment, clone the repo and install dependencies:

python -m venv .venv
source .venv/bin/activate
git clone [email protected]:chicolucio/pH-diagrams.git
cd pH-diagrams
pip install -r requirements.txt

This considers that you have Jupyter Notebook installed. If not, install it with pip install notebook.

For more basic usage examples, see the tutorial.ipynb notebook on notebooks folder. In the same folder, the tutorial_interactive_ipywidgets.ipynb file shows how to use ipywidgets to create interactive diagrams. Just run jupyter notebook on a terminal from the repo root folder and select the files.

A local version of the Streamlit app can be used running, from the repo root folder, streamlit run Home.py on a terminal. A browser window will open (if not, follow the instructions shown on the terminal output).

Contributing

All contributions are welcome.

Issues

Feel free to submit issues regarding:

• recommendations
• more examples for the tutorial
• enhancement requests and new useful features
• code bugs

Pull requests

• before starting to work on your pull request, please submit an issue first
• fork the repo
• clone the project to your own machine
• commit changes to your own branch
• push your work back up to your fork
• submit a pull request so that your changes can be reviewed

For full contribution guidelines and details check out our contributing guide.

Citing

If you use this project in a scientific publication or in classes, please consider citing as

F. L. S. Bustamante & H. B. Soares & N. O. Souza, pH diagrams, 2021. Available at: https://github.com/chicolucio/pH-diagrams

ph-diagrams's Issues

Arquivo de dependências para facilitar reprodução do repositório

Disponibilizar arquivos de dependências para reprodução do projeto:

• requirements.txt
• environment.yml

Talvez seja melhor criar após #4 e #5 quando as dependências chave do projeto devem ser consolidadas. E aí atualizar os arquivos aos poucos a medida que novas dependências surjam.

Resolver questão das fórmulas

• O Matplotlib reconhece código LaTeX sem maiores problemas para as legendas
• O Plotly possui diversos problemas de interação com LaTeX
  • necessidade de ter o MathJax local ou via CDN
  • não tem comportamento muito previsível em hover ou em labels (ver refs abaixo)

Possíveis soluções:

• função usando LaTeX para uso com Matplotlib e função usando HTML para Plotly conforme #4
  • 👎 repetição de lógica/código
  • 👎 não lida bem com cargas
• delegar criação das fórmulas para a classe Substance do chempy
  • 👍 pode usar os métodos latex_name e html_name
  • 👎 mais uma dependência...
  • 👍 lida com a questão da representação correta das cargas: - ao invés de -1; 2- ao invés de -2
  • 👎 não lida bem índices 0 e 1: H_0A^- ao invés de A^- e H_1A ao invés de HA
    • pode ser contornado da mesma forma que é contornado nas funções atuais
  • 👍 pode ser uma única função, com um argumento onde se diz qual tipo de retorno é desejado

from chempy import Substance
...

def formulas(output='latex'):
    ...
    if output == 'latex':
         ...
    if output == 'html':
         ...
    ...

Tendo, no momento, a considerar a solução com o chempy melhor.

Referências para problemas do Plotly com LaTeX:

• https://togithub.com/plotly/plotly.js/issues/559
• https://community.plotly.com/t/hovertemplate-does-not-show-name-property/36139
• https://stackoverflow.com/questions/64718655/plotly-fails-to-show-text-in-latex-labels-in-python
• https://community.plotly.com/t/latex-text-does-not-work-at-all-in-plotly-offline/13800
• https://togithub.com/plotly/plotly.py/issues/515
• https://community.plotly.com/t/latex-in-layout-title-does-not-work-properly/21585

[BUG] `streamlit-ph` does not work

Describe the bug

streamlit-ph script does not work.

To Reproduce
Steps to reproduce the behavior:

1. install the package
2. run streamlit-ph on terminal
3. message: Error: Invalid value: File does not exist: Home.py

Expected behavior
Browser window opens with Streamlit app

Screenshots
NA

Specification

• pH-diagrams version: 0.3.2
• Python version: 3.10
• platform: Linux (but will happen in all platforms)

Additional context
The file is not part of the package. Maybe the project should be restructured in a way that the Streamlit app becomes a module.

Adicionar colaborador no README e em LICENSE

Adicionar @natashaosouza na citação do README e no LICENSE após merge de #4

gif no README

gif mostrando gráfico interativo

Gráficos interativos com Matplotlib

• possibilidade de mudar valores de pKa e verificar atualizações dos gráficos em tempo real
  • sliders do ipywidget para cada pKa: de 0 a 14, com step 0.5
  • quantos sliders?
  • condições de contorno de cada de slider
    • pKa2 mínimo tem que ser igual ou maior que o pKa1

links dos tutoriais no README

• arquivos notebook no repositório
• links para o colab no README

[BUG] Notebooks do not work on Google Colab

Describe the bug
Python version of Google Colab is too old (3.7) and the package requires >=3.8

To Reproduce
Steps to reproduce the behavior:

1. open notebooks with Colab link
2. uncomment the lines at the first as request
3. Does not work (should add src before ph_diagrams)
4. Try install the package with pip install pH-diagrams
5. Does not work

Expected behavior
Just works...

Screenshots
NA

Specification

• pH-diagrams: 0.3.2
• Python version: 3.7
• platform: Google Colab

Additional context

And that is how Google deals with it: googlecolab/colabtools#2165 I'm considering drop Colab links...

All notebooks work in a local environment with Python >= 3.8.

Deepnote can be an alternative. But it has issues with ipywidgets:

• https://community.deepnote.com/c/ask-anything/ipywidgets
• https://community.deepnote.com/c/ask-anything/when-will-ipywidgets-support-be-added

Adicionar tags em momentos importantes do projeto

Adicionar tags em commits que marcam momentos importantes do projeto:

• tag 0.1 no commit 7668876 com mensagem "versão 0.1 - gráficos com matplotlib"
• tag 0.2 no commit ef14534 com mensagem "versão 0.2 - gráficos com matplotlib e plotly"