pymatviz

A toolkit for visualizations in materials informatics.

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.ipynb		Launch Codespace
matbench_dielectric_eda.ipynb		Launch Codespace
mp_bimodal_e_form.ipynb		Launch Codespace
matbench_perovskites_eda.ipynb		Launch Codespace
mprester_ptable.ipynb		Launch Codespace

Periodic Table

See pymatviz/ptable/ptable_plotly.py. The module supports heatmaps, heatmap splits (multiple values per element), histograms, scatter plots and line plots. All visualizations are interactive through Plotly and support displaying additional data on hover.

Warning

Version 0.16.0 of pymatviz dropped the matplotlib-based functions in ptable_matplotlib.py in #270. Please use the plotly-based functions shown below instead which have feature parity, interactivity and better test coverage.

ptable_heatmap_plotly(atomic_masses)	ptable_heatmap_plotly(compositions, log=True)
ptable_hists_plotly(data)	ptable_scatter_plotly(data, mode="markers")
ptable_heatmap_splits_plotly(2_vals_per_elem)	ptable_heatmap_splits_plotly(3_vals_per_elem)

Dash app using ptable_heatmap_plotly()

See examples/mprester_ptable.ipynb.

2022-07-28-ptable_heatmap_plotly-dash-example.mp4

Phonons

See examples/mlff_phonons.ipynb for usage example.

phonon_bands(bands_dict)	phonon_dos(doses_dict)
phonon_bands_and_dos(bands_dict, doses_dict)	phonon_bands_and_dos(single_bands, single_dos)

Structure

See pymatviz/structure_viz/plotly.py.

structure_3d_plotly(hea_structure)	structure_3d_plotly(lco_supercell)
structure_2d_plotly(six_structs)	structure_3d_plotly(six_structs)

Brillouin Zone

See pymatviz/brillouin.py.

brillouin_zone_3d(cubic_struct)	brillouin_zone_3d(hexagonal_struct)
brillouin_zone_3d(monoclinic_struct)	brillouin_zone_3d(orthorhombic_struct)

X-Ray Diffraction

See pymatviz/xrd.py.

xrd_pattern(pattern)	xrd_pattern({key1: patt1, key2: patt2})
xrd_pattern(struct_dict, stack="horizontal")	xrd_pattern(struct_dict, stack="vertical")

Radial Distribution Functions

See pymatviz/rdf/plotly.py.

element_pair_rdfs(pmg_struct)	element_pair_rdfs({"A": struct1, "B": struct2})

Coordination

See pymatviz/coordination/plotly.py.

coordination_hist(struct_dict)	coordination_hist(struct_dict, by_element=True)
coordination_vs_cutoff_line(struct_dict, strategy=None)	coordination_vs_cutoff_line(struct_dict, strategy=None)

Sunburst

See pymatviz/sunburst.py.

spacegroup_sunburst([65, 134, 225, ...])	chem_sys_sunburst(["FeO", "Fe2O3", "LiPO4", ...])

Treemap

See pymatviz/treemap.py.

chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...])	chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...], group_by="formula")

Rainclouds

See pymatviz/rainclouds.py.

rainclouds(two_key_dict)	rainclouds(three_key_dict)

Sankey

See pymatviz/sankey.py.

sankey_from_2_df_cols(df_perovskites)	sankey_from_2_df_cols(df_space_groups)

Bar Plots

See pymatviz/bar.py.

spacegroup_bar([65, 134, 225, ...], backend="plotly")	spacegroup_bar(["C2/m", "P-43m", "Fm-3m", ...], backend="plotly")

Histograms

See pymatviz/histogram.py.

elements_hist(compositions, log=True, bar_values='count')	histogram({'key1': values1, 'key2': values2})

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(xs, ys, ...)	density_scatter_with_hist(xs, ys, ...)
density_hexbin(xs, ys, ...)	density_hexbin_with_hist(xs, ys, ...)

Uncertainty

See pymatviz/uncertainty.py.

qq_gaussian(y_true, y_pred, y_std)	qq_gaussian(y_true, y_pred, y_std: dict)
error_decay_with_uncert(y_true, y_pred, y_std)	error_decay_with_uncert(y_true, y_pred, y_std: dict)

Classification

See pymatviz/classify/confusion_matrix.py.

confusion_matrix(conf_mat, ...)	confusion_matrix(y_true, y_pred, ...)

See pymatviz/classify/curves.py.

roc_curve_plotly(targets, probs_positive)	precision_recall_curve_plotly(targets, probs_positive)

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
}

Papers using pymatviz

Sorted by number of citations. Last updated 2025-03-03. Auto-generated from Google Scholar. Manual additions via PR welcome.

1. C Zeni, R Pinsler, D Zügner et al. (2023). Mattergen: a generative model for inorganic materials design (cited by 116)
2. J Riebesell, REA Goodall, P Benner et al. (2023). Matbench Discovery--A framework to evaluate machine learning crystal stability predictions (cited by 38)
3. C Chen, DT Nguyen, SJ Lee et al. (2024). Accelerating computational materials discovery with machine learning and cloud high-performance computing: from large-scale screening to experimental validation (cited by 34)
4. L Barroso-Luque, M Shuaibi, X Fu et al. (2024). Open materials 2024 (omat24) inorganic materials dataset and models (cited by 21)
5. M Giantomassi, G Materzanini (2024). Systematic assessment of various universal machine‐learning interatomic potentials (cited by 12)
6. AA Naik, C Ertural, P Benner et al. (2023). A quantum-chemical bonding database for solid-state materials (cited by 11)
7. K Li, AN Rubungo, X Lei et al. (2025). Probing out-of-distribution generalization in machine learning for materials (cited by 6)
8. N Tuchinda, CA Schuh (2025). Grain Boundary Segregation and Embrittlement of Aluminum Binary Alloys from First Principles (cited by 2)
9. A Onwuli, KT Butler, A Walsh (2024). Ionic species representations for materials informatics (cited by 1)
10. A Peng, MY Guo (2025). The OpenLAM Challenges
11. F Therrien, JA Haibeh (2025). OBELiX: A Curated Dataset of Crystal Structures and Experimentally Measured Ionic Conductivities for Lithium Solid-State Electrolytes
12. HH Li, Q Chen, G Ceder (2024). Voltage Mining for (De) lithiation-Stabilized Cathodes and a Machine Learning Model for Li-Ion Cathode Voltage
13. RA Mayo (2025). MOSAEC-DB: a comprehensive database of experimental metal–organic frameworks with verified chemical accuracy suitable for molecular simulations
14. N Tuchinda, CA Schuh (2025). A Grain Boundary Embrittlement Genome for Substitutional Cubic Alloys
15. Daniel W. Davies, Keith T. Butler, Adam J. Jackson et al. (2024). SMACT: Semiconducting Materials by Analogy and Chemical Theory
16. Hui Zheng, Eric Sivonxay, Rasmus Christensen et al. (2024). The ab initio non-crystalline structure database: empowering machine learning to decode diffusivity