Metadata-Version: 2.1
Name: pix2py
Version: 0.2.0
Summary: A python package to plot pixelmaps generated by Domino.
License: GPL-3.0
Author: Philip Hartmeier
Author-email: philip.hartmeier@hotmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: ipykernel (>=6.29.0,<7.0.0)
Requires-Dist: matplotlib (>=3.8.2,<4.0.0)
Requires-Dist: numpy (>=1.26.3,<2.0.0)
Requires-Dist: pandas (>=2.2.0,<3.0.0)
Description-Content-Type: text/markdown

# pix2py

[![Tests](https://github.com/Philipsite/pix2py/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/Philipsite/pix2py/actions/workflows/CI.yml)
[![PyPI](https://img.shields.io/pypi/v/pix2py.svg?style=flat)](https://pypi.python.org/pypi/pix2py)
[![Compatible Python Versions](https://img.shields.io/pypi/pyversions/pix2py.svg?style=flat)](https://pypi.python.org/pypi/pix2py/)

A python package to plot pixelmaps generated by [Theriak-Domino](https://github.com/Theriak-Domino) using [matplotlib](https://matplotlib.org/).

## Installation

The latest version of pix2py can be installed using pip:

```bash
pip install pix2py
```

## Quickstart

In your Python script or notebook you must first import ```PixelMap``` from ```pix2py```.

```python
from pix2py import PixelMap
```

To use pix2py, you need to have a pixelmap folder called ```_pixelmaps``` generated by [Domino](https://github.com/Theriak-Domino) in your working directory. Or you can specify the path to the pixelmap folder:

```python
from pathlib import Path

pixelmap_dir = Path("{INSERT PATH HERE}", "_pixelmaps")
```

Since the individual pixelmaps for solid solution phases are named after the dominant endmember, you need to provide a dictionary to map a phase name to all endmember names for that phase in the thermodynamic database used to generate the pixelmaps.\
This dictionary has the general form:
```ENDMEMBER_DICT = {"phase_name": "endmember1, endmember2, ...", ...}```. Create a local dictionary for the project by:

```python
LOCAL_ENDMEMBER_DICT = {}
LOCAL_ENDMEMBER_DICT["biotite"] = "phl", "annm", "obi", "east", "tbi", "fbi", "mnbi"
```
Additonal phases can be added to the dictionary as needed:

```python
LOCAL_ENDMEMBER_DICT["LIQtc6"] = "q4L", "abL", "kspL", "anL", "slL", "fo2L", "fa2L", "h2oL"
```

Next, set up a pixelmap object by passing the path to the pixelmap folder and the endmember dictionary.

```python
pixmap = PixelMap(pixelmap_dir, LOCAL_ENDMEMBER_DICT)
```

To plot a pixelmap, use the ```plot_pixelmap``` method of the pixelmap object. The method takes a variable to plot (```variable```) the phase name (```mineral```) as input arguments and returns a matplotlib figure object and ax object.

```python
pixmap.plot_pixelmap("vol", mineral="LIQtc6")
```
![Pixelmap of melt (LIQtc6) volume fraction](assets/LIQtc6_vol.png "Pixelmap of melt (LIQtc6) volume fraction")

To plot isolines, use the ```plot_isolines``` method of the pixelmap object. The method takes a variable to plot (```variable```) and the phase name (```mineral```) as input arguments and returns a matplotlib figure object and ax object.

```python
pixmap.plot_isolines("vol", mineral="LIQtc6")
```

![Isolines of melt (LIQtc6) volume fraction](assets/LIQtc6_vol_isolines.png "Isolines of melt (LIQtc6) volume fraction")

Capture the figure and ax objects to save or further customise the plotted pixelmap.

```python
fig, ax = pixmap.plot_pixelmap("vol", mineral="LIQtc6")
fig.savefig("LIQtc6_vol.png", dpi=300)
```
You can use matplotlib's functions to further customise the plotted pixelmap.

```python
fig, ax = pixmap.plot_pixelmap("vol", mineral="LIQtc6")
ax.set_title("LIQtc6 Volume Fraction")
```

### Full Example

```python
from pix2py import PixelMap
from pathlib import Path

pixelmap_dir = Path("{path_to_pixelmap_folder}", "_pixelmaps")

LOCAL_ENDMEMBER_DICT = {}
LOCAL_ENDMEMBER_DICT["biotite"] = "phl", "annm", "obi", "east", "tbi", "fbi", "mnbi"

pixmap = PixelMap(pixelmap_dir, LOCAL_ENDMEMBER_DICT)

fig, ax = pixmap.plot_pixelmap("#Mg", mineral="biotite")
fig.savefig("Biotite_Mg.png", dpi=300)
```

