pix2py

A python package to plot pixelmaps generated by Theriak-Domino using matplotlib.

The pix2py package is registered on Zenodo. If you use pix2py to generate pixelmaps for your research, please cite it. This DOI will resolve to the latest version of pix2py.

Installation

The latest version of pix2py can be installed using pip:

pip install pix2py

Quickstart

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

from pix2py import PixelMap

To use pix2py, you need to have a pixelmap folder called _pixelmaps generated by Domino in your working directory. Or you can specify the path to the pixelmap folder:

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:

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

Additonal phases can be added to the dictionary as needed:

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.

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.

pixmap.plot_pixelmap("vol", mineral="LIQtc6")

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.

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

Customising the plots

If you want to customise the plots, you can pass additional arguments to the plot_pixelmap and plot_isolines methods. For example, you can set the colormap, the number of contour levels, and the contour levels to plot.

To change the colormap, pass the name of the colormap to the colormap argument. The default colormap is "viridis". You can use any of the colormaps available in matplotlib.

pixmap.plot_pixelmap("vol", mineral="LIQtc6", colormap="plasma")

If you plot isolines, you can set the number of contour levels or specify the contour levels to plot using the isolines argument. The default number of isolines is 5. Pass an integer to the isolines argument to set the number of contour levels.

pixmap.plot_isolines("vol", mineral="LIQtc6", isolines=10)

You can also explicitly set the contour levels to plot by passing a list of values to the isolines argument.

pixmap.plot_isolines("vol", mineral="LIQtc6", isolines=[0.1, 0.2, 0.3, 0.4, 0.5])

Save the pixelmap

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

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.

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

Full Example

To run an example look into the folder example, where a runable python script is provided along a _pixelmaps directory containing the data generate by Domino.

from pix2py import PixelMap
from pathlib import Path

pixelmap_dir = Path("example", "_pixelmaps")

LOCAL_ENDMEMBER_DICT = {}
LOCAL_ENDMEMBER_DICT["biotite"] = "phl", "annm", "obi", "east", "tbi", "fbi", "mnbi"
LOCAL_ENDMEMBER_DICT["LIQtc6"] = "q4L", "abL", "kspL", "anL", "slL", "fo2L", "fa2L", "h2oL"

pixmap = PixelMap(pixelmap_dir, LOCAL_ENDMEMBER_DICT)

fig, ax = pixmap.plot_pixelmap("vol", mineral="LIQtc6")
fig.savefig("LIQtc6_vol.png", dpi=300)

fig, ax = pixmap.plot_isolines("vol", mineral="LIQtc6")
fig.savefig("LIQtc6_vol_isolines.png", dpi=300)

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