Logo
pymatviz

A toolkit for visualizations in materials informatics.

Tests This project supports Python 3.10+ PyPI PyPI Downloads Zenodo

If you use pymatviz in your research, see how to cite.

Installation

pip install pymatviz

API Docs

See the /api page.

Usage

See the Jupyter notebooks under examples/ for how to use pymatviz. PRs with additional examples are welcome! 🙏

mlff_phonons.ipynbOpen in Google ColabLaunch Codespace
matbench_dielectric_eda.ipynbOpen in Google ColabLaunch Codespace
mp_bimodal_e_form.ipynbOpen in Google ColabLaunch Codespace
matbench_perovskites_eda.ipynbOpen in Google ColabLaunch Codespace
mprester_ptable.ipynbOpen in Google ColabLaunch Codespace

Periodic Table

See pymatviz/ptable/ptable_matplotlib.py and pymatviz/ptable/ptable_plotly.py. matplotlib supports heatmaps, heatmap ratios, heatmap splits (multiple values per element), histograms, scatter plots and line plots. plotly currently only supports heatmaps (PRs to port over other matplotlib ptable variants to plotly are very welcome!). The plotly heatmap supports displaying additional data on hover or full interactivity through Dash.

ptable_heatmap(compositions, log=True)ptable_heatmap_ratio(comps_a, comps_b)
ptable-heatmapptable-heatmap-ratio
ptable_heatmap_plotly(atomic_masses)ptable_heatmap_plotly(compositions, log=True)
ptable-heatmap-plotly-more-hover-dataptable-heatmap-plotly-log
ptable_hists(data, colormap="coolwarm")ptable_hists_plotly(data)
ptable-histsptable-hists-plotly
ptable_scatters(data, colormap="coolwarm")ptable_lines(data)
ptable-scatters-parityptable-lines
ptable_heatmap_splits(2_vals_per_elem, colormap="coolwarm", start_angle=135)ptable_heatmap_splits(3_vals_per_elem, colormap="coolwarm", start_angle=90)
ptable-heatmap-splits-2ptable-heatmap-splits-3
ptable_heatmap_splits_plotly(2_vals_per_elem)ptable_heatmap_splits_plotly(3_vals_per_elem)
ptable-heatmap-splits-plotly-2ptable-heatmap-splits-plotly-3

Dash app using ptable_heatmap_plotly()

See examples/mprester_ptable.ipynb.

https://user-images.githubusercontent.com/30958850/181644052-b330f0a2-70fc-451c-8230-20d45d3af72f.mp4

Phonons

See examples/mlff_phonons.ipynb for usage example.

phonon_bands(bands_dict)phonon_dos(doses_dict)
phonon-bandsphonon-dos
phonon_bands_and_dos(bands_dict, doses_dict)phonon_bands_and_dos(single_bands, single_dos)
phonon-bands-and-dos-mp-2758phonon-bands-and-dos-mp-23907

Structure

See pymatviz/structure_viz/(mpl|plotly).py. Currently structure plotting is only supported with matplotlib in 2d. 3d interactive plots (probably with plotly) are on the road map.

structure_2d(mp_19017)structure_2d(mp_12712)
struct-2d-mp-19017-Li4Mn0.8Fe1.6P4C1.6O16-disorderedstruct-2d-mp-12712-Hf9Zr9Pd24-disordered
structure_2d_plotly(six_structs)structure_3d_plotly(six_structs)
matbench-phonons-structures-2d-plotlymatbench-phonons-structures-3d-plotly

Brillouin Zone

See pymatviz/brillouin.py.

brillouin_zone_3d(cubic_struct)brillouin_zone_3d(hexagonal_struct)
brillouin-cubic-mp-10018brillouin-hexagonal-mp-862690
brillouin_zone_3d(monoclinic_struct)brillouin_zone_3d(orthorhombic_struct)
brillouin-monoclinic-mp-1183089brillouin-orthorhombic-mp-1183085

X-Ray Diffraction

See pymatviz/xrd.py.

xrd_pattern(pattern)xrd_pattern({key1: patt1, key2: patt2})
xrd-patternxrd-pattern-multiple
xrd_pattern(struct_dict, stack="horizontal")xrd_pattern(struct_dict, stack="vertical", title="Custom Title")
xrd-pattern-horizontal-stackxrd-pattern-vertical-stack

Radial Distribution Functions

See pymatviz/rdf/plotly.py.

rdf_plot(rdf)rdf_plot(rdf, rdf2)
element-pair-rdfs-Na8Nb8O24element-pair-rdfs-crystal-vs-amorphous

Coordination

See pymatviz/coordination/plotly.py.

coordination_hist(struct_dict)coordination_hist(struct_dict, by_element=True)
coordination-hist-singlecoordination-hist-by-structure-and-element
coordination_vs_cutoff_line(struct_dict, strategy=None)coordination_vs_cutoff_line(struct_dict, strategy=None)
coordination-vs-cutoff-singlecoordination-vs-cutoff-multiple

Sunburst

See pymatviz/sunburst.py.

spacegroup_sunburst([65, 134, 225, ...])spacegroup_sunburst(["C2/m", "P-43m", "Fm-3m", ...])
spg-num-sunburstspg-symbol-sunburst

Rainclouds

See pymatviz/rainclouds.py.

rainclouds(two_key_dict)rainclouds(three_key_dict)
rainclouds-bimodalrainclouds-trimodal

Sankey

See pymatviz/sankey.py.

sankey_from_2_df_cols(df_perovskites)sankey_from_2_df_cols(df_space_groups)
sankey-spglib-vs-aflow-spacegroupssankey-crystal-sys-to-spg-symbol

Histograms

See pymatviz/histogram.py.

spacegroup_bar([65, 134, 225, ...], backend="matplotlib")spacegroup_bar(["C2/m", "P-43m", "Fm-3m", ...], backend="matplotlib")
spg-num-hist-matplotlibspg-symbol-hist-matplotlib
spacegroup_bar([65, 134, 225, ...], backend="plotly")spacegroup_bar(["C2/m", "P-43m", "Fm-3m", ...], backend="plotly")
spg-num-hist-plotlyspg-symbol-hist-plotly
elements_hist(compositions, log=True, bar_values='count')histogram({'key1': values1, 'key2': values2})
elements-histhistogram-ecdf

Scatter Plots

See pymatviz/scatter.py.

density_scatter_plotly(df, x=x_col, y=y_col, ...)density_scatter_plotly(df, x=x_col, y=y_col, ...)
density-scatter-plotlydensity-scatter-plotly-blobs
density_scatter(xs, ys, ...)density_scatter_with_hist(xs, ys, ...)
density-scatterdensity-scatter-with-hist
density_hexbin(xs, ys, ...)density_hexbin_with_hist(xs, ys, ...)
density-hexbindensity-hexbin-with-hist

Uncertainty

See pymatviz/uncertainty.py.

qq_gaussian(y_true, y_pred, y_std)qq_gaussian(y_true, y_pred, y_std: dict)
normal-prob-plotnormal-prob-plot-multiple
error_decay_with_uncert(y_true, y_pred, y_std)error_decay_with_uncert(y_true, y_pred, y_std: dict)
error-decay-with-uncerterror-decay-with-uncert-multiple

Cumulative Metrics

See pymatviz/cumulative.py.

cumulative_error(preds, targets)cumulative_residual(preds, targets)
cumulative-errorcumulative-residual

Classification

See pymatviz/classify/confusion_matrix.py.

confusion_matrix(conf_mat, ...)confusion_matrix(y_true, y_pred, ...)
stability-confusion-matrixcrystal-system-confusion-matrix

See pymatviz/classify/curves.py.

roc_curve_plotly(targets, probs_positive)precision_recall_curve_plotly(targets, probs_positive)
roc-curve-plotly-multipleprecision-recall-curve-plotly-multiple

How to cite pymatviz

See citation.cff or cite the Zenodo record using the following BibTeX entry:

@software{riebesell_pymatviz_2022,
  title = {Pymatviz: visualization toolkit for materials informatics},
  author = {Riebesell, Janosh and Yang, Haoyu and Goodall, Rhys and Baird, Sterling G.},
  date = {2022-10-01},
  year = {2022},
  doi = {10.5281/zenodo.7486816},
  url = {https://github.com/janosh/pymatviz},
  note = {10.5281/zenodo.7486816 - https://github.com/janosh/pymatviz},
  urldate = {2023-01-01}, % optional, replace with your date of access
  version = {0.8.2}, % replace with the version you use
}