Add keyword hide_f_block: bool = None (La and Ac series) to ptable plotters

examples/_generate_assets.py

@@ -232,6 +232,7 @@
     colormap="coolwarm",
     start_angle=135,
     cbar_title="Periodic Table Evenly-Split Heatmap Plots",
+    hide_f_block=True,
 )
 save_and_compress_svg(fig, "ptable-heatmap-splits")
 

pymatviz/ptable.py

@@ -318,9 +318,11 @@ class PTableProjector:
 
     def __init__(
         self,
+        *,
         data: SupportedDataType,
         colormap: str | Colormap | None,
         plot_kwargs: dict[str, Any] | None = None,
+        hide_f_block: bool = False,
     ) -> None:
         """Initialize a ptable projector.
 
@@ -332,17 +334,23 @@ def __init__(
             colormap (str | Colormap | None): The colormap to use.
             plot_kwargs (dict): Additional keyword arguments to
                 pass to the plt.subplots function call.
+            hide_f_block: Hide f-block (Lanthanum and Actinium series).
         """
         # Get colormap
         self.cmap: Colormap = colormap
 
+        self.hide_f_block = hide_f_block
+
         # Preprocess data
         self.data: pd.DataFrame = data
 
         # Initialize periodic table canvas
         n_periods = df_ptable.row.max()
         n_groups = df_ptable.column.max()
 
+        if self.hide_f_block:
+            n_periods -= 3
+
         # Set figure size
         plot_kwargs = plot_kwargs or {}
         plot_kwargs.setdefault("figsize", (0.75 * n_groups, 0.75 * n_periods))
@@ -404,6 +412,7 @@ def add_child_plots(
         self,
         child_plotter: Callable[[plt.axes, Any], None],
         child_args: dict[str, Any],
+        *,
         ax_kwargs: dict[str, Any],
         on_empty: Literal["hide", "show"] = "hide",
     ) -> None:
@@ -416,6 +425,10 @@ def add_child_plots(
             on_empty: Whether to "show" or "hide" tiles for elements without data.
         """
         for element in Element:
+            # Hide f-block
+            if self.hide_f_block and (element.is_lanthanoid or element.is_actinoid):
+                continue
+
             # Get axis index by element symbol
             symbol: str = element.symbol
             row, column = df_ptable.loc[symbol, ["row", "column"]]
@@ -459,6 +472,10 @@ def add_ele_symbols(
 
         # Add symbol for each element
         for element in Element:
+            # Hide f-block
+            if self.hide_f_block and (element.is_lanthanoid or element.is_actinoid):
+                continue
+
             # Get axis index by element symbol
             symbol: str = element.symbol
             row, column = df_ptable.loc[symbol, ["row", "column"]]
@@ -473,6 +490,7 @@ def add_colorbar(
         self,
         title: str,
         coords: tuple[float, float, float, float] = (0.18, 0.8, 0.42, 0.02),
+        *,
         cbar_kwargs: dict[str, Any] | None = None,
         title_kwargs: dict[str, Any] | None = None,
     ) -> None:
@@ -635,7 +653,8 @@ def ptable_heatmap(
     label_font_size: int = 16,
     value_font_size: int = 12,
     tile_size: float | tuple[float, float] = 0.9,
-    rare_earth_voffset: float = 0.5,
+    f_block_voffset: float = 0.5,
+    hide_f_block: bool = False,
     **kwargs: Any,
 ) -> plt.Axes:
     """Plot a heatmap across the periodic table of elements.
@@ -702,8 +721,10 @@ def ptable_heatmap(
         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.18, 0.8, 0.42, 0.05).
-        rare_earth_voffset (float): Vertical offset for lanthanides and actinides
+        f_block_voffset (float): Vertical offset for lanthanides and actinides
             (row 6 and 7) from the rest of the periodic table. Defaults to 0.5.
+        hide_f_block (bool): Whether to hide the f-block (lanthanides and actinides).
+            Defaults to False.
         **kwargs: Additional keyword arguments passed to plt.figure().
 
     Returns:
@@ -778,6 +799,9 @@ def tick_fmt(val: float, _pos: int) -> str:
     ) | (text_style or {})
 
     for symbol, row, column, *_ in df_ptable.itertuples():
+        if hide_f_block and (row in (6, 7)):
+            continue
+
         period = n_rows - row  # invert row count to make periodic table right side up
         tile_value = values.get(symbol)
 
@@ -814,7 +838,7 @@ def tick_fmt(val: float, _pos: int) -> str:
             # replace shortens scientific notation 1e+01 to 1e1 so it fits inside cells
             label = label.replace("e+0", "e")
         if period < 3:  # vertical offset for lanthanides + actinides
-            period += rare_earth_voffset
+            period += f_block_voffset
         rect = Rectangle(
             (column, period), tile_width, tile_height, edgecolor="gray", facecolor=color
         )
@@ -900,6 +924,7 @@ def ptable_heatmap_splits(
     cbar_coords: tuple[float, float, float, float] = (0.18, 0.8, 0.42, 0.02),
     cbar_title: str = "Values",
     on_empty: Literal["hide", "show"] = "hide",
+    hide_f_block: bool = False,
     ax_kwargs: dict[str, Any] | None = None,
     symbol_kwargs: dict[str, Any] | None = None,
     plot_kwargs: dict[str, Any]
@@ -943,6 +968,7 @@ def ptable_heatmap_splits(
         cbar_kwargs (dict): Keyword arguments passed to fig.colorbar().
         on_empty ('hide' | 'show'): Whether to show or hide tiles for elements without
             data. Defaults to "hide".
+        hide_f_block (bool): Hide f-block (Lanthanum and Actinium series).
         plot_kwargs (dict): Additional keyword arguments to
                 pass to the plt.subplots function call.
 
@@ -964,6 +990,7 @@ def ptable_heatmap_splits(
         data=data,
         colormap=colormap,
         plot_kwargs=plot_kwargs,  # type: ignore[arg-type]
+        hide_f_block=hide_f_block,
     )
 
     # Call child plotter: evenly split rectangle
@@ -1548,6 +1575,7 @@ def ptable_scatters(
     symbol_text: str | Callable[[Element], str] = lambda elem: elem.symbol,
     symbol_pos: tuple[float, float] = (0.5, 0.8),
     on_empty: Literal["hide", "show"] = "hide",
+    hide_f_block: bool = False,
     plot_kwargs: dict[str, Any]
     | Callable[[Sequence[float]], dict[str, Any]]
     | None = None,
@@ -1579,6 +1607,7 @@ def ptable_scatters(
             Defaults to (0.5, 0.5). (1, 1) is the upper right corner.
         on_empty ('hide' | 'show'): Whether to show or hide tiles for elements without
             data. Defaults to "hide".
+        hide_f_block (bool): Hide f-block (Lanthanum and Actinium series).
         child_args: Arguments to pass to the child plotter call.
         plot_kwargs (dict): Additional keyword arguments to
                 pass to the plt.subplots function call.
@@ -1595,7 +1624,12 @@ def ptable_scatters(
     symbol_kwargs.setdefault("fontsize", 12)
 
     # Initialize periodic table plotter
-    plotter = PTableProjector(data=data, colormap=None, plot_kwargs=plot_kwargs)  # type: ignore[arg-type]
+    plotter = PTableProjector(
+        data=data,
+        colormap=None,
+        plot_kwargs=plot_kwargs,  # type: ignore[arg-type]
+        hide_f_block=hide_f_block,
+    )
 
     # Call child plotter: Scatter
     plotter.add_child_plots(
@@ -1620,6 +1654,7 @@ def ptable_lines(
     symbol_text: str | Callable[[Element], str] = lambda elem: elem.symbol,
     symbol_pos: tuple[float, float] = (0.5, 0.8),
     on_empty: Literal["hide", "show"] = "hide",
+    hide_f_block: bool = False,
     plot_kwargs: dict[str, Any]
     | Callable[[Sequence[float]], dict[str, Any]]
     | None = None,
@@ -1651,6 +1686,7 @@ def ptable_lines(
             Defaults to (0.5, 0.5). (1, 1) is the upper right corner.
         on_empty ('hide' | 'show'): Whether to show or hide tiles for elements without
             data. Defaults to "hide".
+        hide_f_block (bool): Hide f-block (Lanthanum and Actinium series).
         child_args: Arguments to pass to the child plotter call.
         plot_kwargs (dict): Additional keyword arguments to
                 pass to the plt.subplots function call.
@@ -1669,6 +1705,7 @@ def ptable_lines(
         data=data,
         colormap=None,
         plot_kwargs=plot_kwargs,  # type: ignore[arg-type]
+        hide_f_block=hide_f_block,
     )
 
     # Call child plotter: line

readme.md

@@ -53,15 +53,15 @@ See the Jupyter notebooks under [`examples/`](examples) for how to use `pymatviz
 
 See [`pymatviz/ptable.py`](pymatviz/ptable.py). Heatmaps of the periodic table can be plotted both with `matplotlib` and `plotly`. `plotly` supports displaying additional data on hover or full interactivity through [Dash](https://plotly.com/dash).
 
-|              [`ptable_heatmap(compositions, log=True)`](pymatviz/ptable.py)               |    [`ptable_heatmap_ratio(comps_a, comps_b)`](pymatviz/ptable.py)     |
-| :---------------------------------------------------------------------------------------: | :-------------------------------------------------------------------: |
-|                                     ![ptable-heatmap]                                     |                        ![ptable-heatmap-ratio]                        |
-|               [`ptable_heatmap_plotly(atomic_masses)`](pymatviz/ptable.py)                | [`ptable_heatmap_plotly(compositions, log=True)`](pymatviz/ptable.py) |
-|                         ![ptable-heatmap-plotly-more-hover-data]                          |                     ![ptable-heatmap-plotly-log]                      |
-|              [`ptable_hists(data, colormap="coolwarm")`](pymatviz/ptable.py)              |              [`ptable_lines(data)`](pymatviz/ptable.py)               |
-|                                      ![ptable-hists]                                      |                            ![ptable-lines]                            |
-| [`ptable_heatmap_splits(data, colormap="coolwarm", start_angle=135)`](pymatviz/ptable.py) |
-|                                 ![ptable-heatmap-splits]                                  |
+|                        [`ptable_heatmap(compositions, log=True)`](pymatviz/ptable.py)                        |    [`ptable_heatmap_ratio(comps_a, comps_b)`](pymatviz/ptable.py)     |
+| :----------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------: |
+|                                              ![ptable-heatmap]                                               |                        ![ptable-heatmap-ratio]                        |
+|                         [`ptable_heatmap_plotly(atomic_masses)`](pymatviz/ptable.py)                         | [`ptable_heatmap_plotly(compositions, log=True)`](pymatviz/ptable.py) |
+|                                   ![ptable-heatmap-plotly-more-hover-data]                                   |                     ![ptable-heatmap-plotly-log]                      |
+|                       [`ptable_hists(data, colormap="coolwarm")`](pymatviz/ptable.py)                        |              [`ptable_lines(data)`](pymatviz/ptable.py)               |
+|                                               ![ptable-hists]                                                |                            ![ptable-lines]                            |
+| [`ptable_heatmap_splits(data, colormap="coolwarm", start_angle=135, hide_f_block=True)`](pymatviz/ptable.py) |
+|                                           ![ptable-heatmap-splits]                                           |
 
 [ptable-hists]: https://github.com/janosh/pymatviz/raw/main/assets/ptable-hists.svg
 [ptable-lines]: https://github.com/janosh/pymatviz/raw/main/examples/diatomics/homo-nuclear-mace-medium.svg

tests/test_ptable.py

@@ -177,6 +177,11 @@ def test_ptable_heatmap(
 ) -> None:
     ax = ptable_heatmap(glass_formulas)
     assert isinstance(ax, plt.Axes)
+    assert len(ax.texts) == 236
+    # ensure only 118 elements are labeled
+    labels = {txt.get_text() for txt in ax.texts}
+    allowed_labels = {*df_ptable.index} | {*map(str, range(182))} | {"-"}
+    assert labels <= allowed_labels, f"{labels - allowed_labels=}"
 
     ptable_heatmap(glass_formulas, log=True)
 
@@ -282,6 +287,28 @@ def test_ptable_heatmap_splits() -> None:
     assert cbar_ax.get_title() == cbar_title
 
 
+def test_ptable_heatmap_splits_hide_f_block() -> None:
+    """Test ptable_heatmap_splits f block hidden."""
+    data_dict = {
+        elem.symbol: [
+            random.randint(0, 10)  # random heat value for each split
+            for _ in range(2)
+        ]
+        for elem in Element
+    }
+
+    cbar_title = "Periodic Table with f-block hidden"
+    fig = ptable_heatmap_splits(
+        data_dict,
+        colormap="coolwarm",
+        start_angle=135,
+        cbar_title=cbar_title,
+        hide_f_block=True,
+    )
+    assert isinstance(fig, plt.Figure)
+    assert len(fig.axes) == 127
+
+
 def test_ptable_heatmap_ratio(
     steel_formulas: list[str],
     glass_formulas: list[str],