New plot type: ptable_scatter

[janosh]

Add ptable_scatter equivalent to ptable_hists. Function signature can be largely identical except each element data must specify both x and y data. Could potentially have a single function that toggles between hist and scatter depending on presence of y data.

pymatviz/pymatviz/ptable.py

Lines 745 to 795 in 882a6ca

	def ptable_hists(
	data: pd.DataFrame | pd.Series | dict[str, list[float]],
	bins: int = 20,
	colormap: str | None = None,
	hist_kwds: dict[str, Any]
	| Callable[[Sequence[float]], dict[str, Any]]
	| None = None,
	cbar_coords: tuple[float, float, float, float] = (0.18, 0.8, 0.42, 0.02),
	x_range: tuple[float | None, float | None] | None = None,
	symbol_kwargs: Any = None,
	symbol_text: str | Callable[[Element], str] = lambda elem: elem.symbol,
	cbar_title: str = "Values",
	cbar_title_kwds: dict[str, Any] | None = None,
	cbar_kwds: dict[str, Any] | None = None,
	symbol_pos: tuple[float, float] = (0.5, 0.8),
	log: bool = False,
	anno_kwds: dict[str, Any] | None = None,
	return_axes: bool = False,
	**kwargs: Any,
	) -> plt.Figure:
	"""Plot histograms of values across the periodic table of elements.
	Args:
	data (pd.DataFrame | pd.Series | dict[str, list[float]]): Map from element
	symbols to histogram values. E.g. if dict, {"Fe": [1, 2, 3], "O": [4, 5]}.
	If pd.Series, index is element symbols and values lists. If pd.DataFrame,
	column names are element symbols histograms are plotted from each column.
	bins (int): Number of bins for the histograms. Defaults to 20.
	colormap (str): Matplotlib colormap name to use. Defaults to None. See options
	at https://matplotlib.org/stable/users/explain/colors/colormaps.
	hist_kwds (dict | Callable): Keywords passed to ax.hist() for each histogram.
	If callable, it is called with the histogram values for each element and
	should return a dict of keyword arguments. Defaults to None.
	cbar_coords (tuple[float, float, float, float]): Color bar position and size:
	[x, y, width, height] anchored at lower left corner of the bar. Defaults to
	(0.25, 0.77, 0.35, 0.02).
	x_range (tuple[float | None, float | None]): x-axis range for all histograms.
	Defaults to None.
	symbol_text (str | Callable[[Element], str]): Text to display for each element
	symbol. Defaults to lambda elem: elem.symbol.
	symbol_kwargs (dict): Keyword arguments passed to plt.text() for element
	symbols. Defaults to None.
	cbar_title (str): Color bar title. Defaults to "Histogram Value".
	cbar_title_kwds (dict): Keyword arguments passed to cbar.ax.set_title().
	Defaults to dict(fontsize=12, pad=10).
	cbar_kwds (dict): Keyword arguments passed to fig.colorbar().
	symbol_pos (tuple[float, float]): Position of element symbols relative to the
	lower left corner of each tile. Defaults to (0.5, 0.8). (1, 1) is the upper
	right corner.
	log (bool): Whether to log scale y-axis of each histogram. Defaults to False.
	anno_kwds (dict): Keyword arguments passed to plt.annotate() for element

[DanielYang59]

I would be working on this. Thanks @janosh!

[janosh]

Thanks, that would be much appreciated! It can be very close in implementation to the existing ptable_hists

[DanielYang59]

I'm thinking a dedicated data type for periodic table might be justified. I'm currently unaware of any existing package (closest is periodictable but doesn't seem to be designed for parsing custom datasheet).

It would be very similar to a Python dictionary, but with the keys predefined as elements (The atomic numbers should be used internally and auxiliarily for ordering) and missing values imputated.

Having this, we would be able to unify handling and parsing of multiple periodic table based plots, data for ptable_heatmap and ptable_hists would be simplified to element: float pairs. Then we could make fancy scatter plots easy to handle and scale up to multi-dimensional data, ptable_scatter_2D would be element: [float, float] pairs, and we could also include a 3rd dimension (either the size of the scatter or colormap) by using element: [float, float, float]. And this would also make 3D scatters easy to plot.

What do you think?

[janosh]

not sure we need a data type to represent PeriodicTable. even if, i think pymatgen rather than pymatviz would be the place for it. i would prefer a helper function that converts input data in different formats (e.g. using atomic numbers vs element symbols as keys, or dictionaries vs pd.Series) to a consistent internal format. that helper can be called inside each plotting function before the actual plotting code.

for the use case you outline of having additional dimensions for color or marker size, a pd.DataFrame already seems like the optimal format. you simply pass around dataframes to plotting functions along with column names to use for x/y/color/marker size. works great for plotly.

[DanielYang59]

Thanks for sharing your thoughts @janosh. It make sense, as pd.DataFrame should be able to do what I wish to do and I would use it for the time being until perhaps put a periodic table data parser to either pymatgen or others.

[janosh]

closed in #122