pyranges · marco-mariotti · May 31, 2026 · May 25, 2026 · May 26, 2026 · May 26, 2026
diff --git a/README.md b/README.md
@@ -55,6 +55,14 @@ Note that the minimal installation by `pip install pyrangeyes` is not able to pr
 since the graphical dependencies are not installed.
 
 
+## Shared assets
+
+The PyRanges cheat sheet image is kept in this repository for downstream use by the PyRanges 1.x documentation:
+
+- [PyRanges cheat sheet](images/pyranges_cheatsheet.png)
+
+Do not remove this image as an unreferenced local asset; it is intentionally shared across repositories.
+
 ## Documentation
 Pyrangeyes documentation and tutorial can be found at https://pyrangeyes.readthedocs.io/.
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,7 +12,6 @@
 #
 from docutils import nodes
 import doctest
-import sphinx_rtd_theme
 import os
 import sys
 
@@ -36,7 +35,6 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.napoleon",
-    "sphinx_rtd_theme",
 ]
 autosummary_generate = True  # Enable summary table generation
 
@@ -98,7 +96,11 @@ def _doctest_plot(*args, **kwargs):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "show_toc_level": 2,
+    "navigation_with_keys": False,
+}
 
 
 def monospaced_link(name, rawtext, text, lineno, inliner, options={}, content=[]):

diff --git a/docs/images/my_plot.png b/docs/images/my_plot.png
diff --git a/docs/images/options_fig_wm.png b/docs/images/options_fig_wm.png
diff --git a/docs/images/prp_rtd_01.png b/docs/images/prp_rtd_01.png
diff --git a/docs/images/prp_rtd_01_mpl.png b/docs/images/prp_rtd_01_mpl.png
diff --git a/docs/images/prp_rtd_02.png b/docs/images/prp_rtd_02.png
diff --git a/docs/images/prp_rtd_02_mpl.png b/docs/images/prp_rtd_02_mpl.png
diff --git a/docs/images/prp_rtd_03.png b/docs/images/prp_rtd_03.png
diff --git a/docs/images/prp_rtd_04.png b/docs/images/prp_rtd_04.png
diff --git a/docs/images/prp_rtd_04_mpl.png b/docs/images/prp_rtd_04_mpl.png
diff --git a/docs/images/prp_rtd_05.png b/docs/images/prp_rtd_05.png
diff --git a/docs/images/prp_rtd_05_mpl.png b/docs/images/prp_rtd_05_mpl.png
diff --git a/docs/images/prp_rtd_06.png b/docs/images/prp_rtd_06.png
diff --git a/docs/images/prp_rtd_06_mpl.png b/docs/images/prp_rtd_06_mpl.png
diff --git a/docs/images/prp_rtd_07.png b/docs/images/prp_rtd_07.png
diff --git a/docs/images/prp_rtd_07_mpl.png b/docs/images/prp_rtd_07_mpl.png
diff --git a/docs/images/prp_rtd_08.png b/docs/images/prp_rtd_08.png
diff --git a/docs/images/prp_rtd_08_mpl.png b/docs/images/prp_rtd_08_mpl.png
diff --git a/docs/images/prp_rtd_09.png b/docs/images/prp_rtd_09.png
diff --git a/docs/images/prp_rtd_09_mpl.png b/docs/images/prp_rtd_09_mpl.png
diff --git a/docs/images/prp_rtd_10.png b/docs/images/prp_rtd_10.png
diff --git a/docs/images/prp_rtd_10_mpl.png b/docs/images/prp_rtd_10_mpl.png
diff --git a/docs/images/prp_rtd_11.png b/docs/images/prp_rtd_11.png
diff --git a/docs/images/prp_rtd_12.png b/docs/images/prp_rtd_12.png
diff --git a/docs/images/prp_rtd_13.png b/docs/images/prp_rtd_13.png
diff --git a/docs/images/prp_rtd_13_mpl.png b/docs/images/prp_rtd_13_mpl.png
diff --git a/docs/images/prp_rtd_14.png b/docs/images/prp_rtd_14.png
diff --git a/docs/images/prp_rtd_14_mpl.png b/docs/images/prp_rtd_14_mpl.png
diff --git a/docs/images/prp_rtd_15.png b/docs/images/prp_rtd_15.png
diff --git a/docs/images/prp_rtd_15_mpl.png b/docs/images/prp_rtd_15_mpl.png
diff --git a/docs/images/prp_rtd_16.png b/docs/images/prp_rtd_16.png
diff --git a/docs/images/prp_rtd_16_mpl.png b/docs/images/prp_rtd_16_mpl.png
diff --git a/docs/images/prp_rtd_17.png b/docs/images/prp_rtd_17.png
diff --git a/docs/images/prp_rtd_17_mpl.png b/docs/images/prp_rtd_17_mpl.png
diff --git a/docs/images/prp_rtd_18.png b/docs/images/prp_rtd_18.png
diff --git a/docs/images/prp_rtd_18_mpl.png b/docs/images/prp_rtd_18_mpl.png
diff --git a/docs/images/prp_rtd_19.png b/docs/images/prp_rtd_19.png
diff --git a/docs/images/prp_rtd_20.png b/docs/images/prp_rtd_20.png
diff --git a/docs/images/prp_rtd_21.png b/docs/images/prp_rtd_21.png
diff --git a/docs/images/prp_rtd_21_mpl.png b/docs/images/prp_rtd_21_mpl.png
diff --git a/docs/images/prp_rtd_22.png b/docs/images/prp_rtd_22.png
diff --git a/docs/images/prp_rtd_23.png b/docs/images/prp_rtd_23.png
diff --git a/docs/images/prp_rtd_24.png b/docs/images/prp_rtd_24.png
diff --git a/docs/images/prp_rtd_25.png b/docs/images/prp_rtd_25.png
diff --git a/docs/images/prp_rtd_26.png b/docs/images/prp_rtd_26.png
diff --git a/docs/images/prp_rtd_28.png b/docs/images/prp_rtd_28.png
diff --git a/docs/images/prp_rtd_29.png b/docs/images/prp_rtd_29.png
diff --git a/docs/images/prp_rtd_29_mpl.png b/docs/images/prp_rtd_29_mpl.png
diff --git a/docs/images/prp_rtd_30.png b/docs/images/prp_rtd_30.png
diff --git a/docs/images/prp_rtd_30_mpl.png b/docs/images/prp_rtd_30_mpl.png
diff --git a/docs/images/prp_rtd_31.png b/docs/images/prp_rtd_31.png
diff --git a/docs/images/prp_rtd_31_mpl.png b/docs/images/prp_rtd_31_mpl.png
diff --git a/docs/images/prp_rtd_32.png b/docs/images/prp_rtd_32.png
diff --git a/docs/images/prp_rtd_32_mpl.png b/docs/images/prp_rtd_32_mpl.png
diff --git a/docs/images/prp_rtd_33.png b/docs/images/prp_rtd_33.png
diff --git a/docs/images/prp_rtd_33_mpl.png b/docs/images/prp_rtd_33_mpl.png
diff --git a/docs/images/prp_rtd_34.png b/docs/images/prp_rtd_34.png
diff --git a/docs/images/prp_rtd_34_mpl.png b/docs/images/prp_rtd_34_mpl.png
diff --git a/docs/images/prp_rtd_35.png b/docs/images/prp_rtd_35.png
diff --git a/docs/images/prp_rtd_35_mpl.png b/docs/images/prp_rtd_35_mpl.png
diff --git a/docs/images/prp_rtd_36.png b/docs/images/prp_rtd_36.png
diff --git a/docs/images/prp_rtd_37.png b/docs/images/prp_rtd_37.png
diff --git a/docs/images/prp_rtd_38.png b/docs/images/prp_rtd_38.png
diff --git a/docs/images/prp_rtd_38_mpl.png b/docs/images/prp_rtd_38_mpl.png
diff --git a/docs/images/prp_rtd_39.png b/docs/images/prp_rtd_39.png
diff --git a/docs/images/prp_rtd_39_mpl.png b/docs/images/prp_rtd_39_mpl.png
diff --git a/docs/images/prp_rtd_40.png b/docs/images/prp_rtd_40.png
diff --git a/docs/images/prp_rtd_40_mpl.png b/docs/images/prp_rtd_40_mpl.png
diff --git a/docs/images/prp_rtd_41.png b/docs/images/prp_rtd_41.png
diff --git a/docs/images/prp_rtd_43_mpl.png b/docs/images/prp_rtd_43_mpl.png
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
diff --git a/examples/fig_1a.png b/examples/fig_1a.png
diff --git a/setup.cfg b/setup.cfg
@@ -41,7 +41,7 @@ plotly =
     dash_bootstrap_components >= 1.5.0
 docs =
     sphinx >= 7.3.7
-    sphinx_rtd_theme >= 2.0.0
+    pydata-sphinx-theme >= 0.16.0
     sphinx-autoapi >= 3.1.1
     sphinxcontrib-napoleon >= 0.7
     memory-profiler >= 0.61.0
@@ -53,7 +53,7 @@ all =
     dash >= 2.14.0
     dash_bootstrap_components >= 1.5.0
     sphinx >= 7.3.7
-    sphinx_rtd_theme >= 2.0.0
+    pydata-sphinx-theme >= 0.16.0
     sphinx-autoapi >= 3.1.1
     sphinxcontrib-napoleon >= 0.7
     memory-profiler >= 0.61.0

diff --git a/src/pyrangeyes/data_preparation.py b/src/pyrangeyes/data_preparation.py
@@ -1035,6 +1035,7 @@ def assign_label_rows(
     track_scales=None,
     pack_by_track=None,
     text_position_by_track=None,
+    text_avoid_by_track=None,
     label_size=None,
 ):
     """
@@ -1109,7 +1110,12 @@ def assign_label_rows(
                 if text_position_by_track is None
                 else text_position_by_track.get(pr_val, "left")
             )
-            effective_text_avoid = text_avoid and track_scale >= 1
+            track_text_avoid = (
+                text_avoid
+                if text_avoid_by_track is None
+                else bool(text_avoid_by_track.get(pr_val, text_avoid))
+            )
+            effective_text_avoid = track_text_avoid and track_scale >= 1
             # Font size is specified in points by the rendering engines, while
             # layout is expressed in pyrangeyes' row units. Reserve a modest
             # vertical text band for above/below labels: enough to prevent
@@ -1118,7 +1124,7 @@ def assign_label_rows(
             text_extra_y = (
                 0.0
                 if not (effective_text_avoid and text_position in {"above", "below"})
-                else float(label_size or 12) / 40.0
+                else float(label_size or 12) / 26.0
             )
             track_height = interval_height * track_scale
             track_gap = v_spacer * track_scale

diff --git a/src/pyrangeyes/matplotlib_base/fig_axes.py b/src/pyrangeyes/matplotlib_base/fig_axes.py
@@ -2,7 +2,6 @@
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import matplotlib.colors as mcolors
-import matplotlib.gridspec as gridspec
 from matplotlib.ticker import ScalarFormatter
 from matplotlib.ticker import MaxNLocator
 from matplotlib.patches import Rectangle
@@ -30,7 +29,7 @@ def ax_display(ax, title, t_dict, plot_back, plot_border):
     """
 
     if title:
-        ax.set_title(title, fontdict=t_dict)
+        ax.set_title(title, fontdict=t_dict, pad=8)
 
     ax.set_facecolor(plot_back)
     plt.setp(ax.spines.values(), color=plot_border)
@@ -184,22 +183,53 @@ def _fmt_title(row, fallback_chrom):
     num_additional_rows = len(additional_plots) if add_aligned_plots else 0
     total_rows = num_main_rows + num_additional_rows
     row_heights_additional = [height] * num_additional_rows
+    row_heights = chrmd_df_grouped["y_height"].to_list() + row_heights_additional
 
     # Start figure
     fig = plt.figure(figsize=(x, y), facecolor=figure_bg)
-
-    gs = gridspec.GridSpec(
-        total_rows,
-        1,
-        height_ratios=chrmd_df_grouped["y_height"].to_list() + row_heights_additional,
-    )  # size of chromosome subplot according to number of gene rows
+    fig_w_px = fig.get_figwidth() * fig.dpi
+    fig_h_px = fig.get_figheight() * fig.dpi
+    left_px = 96
+    right_px = 24
+    top_px = 18
+    bottom_px = 28
+    title_px = max(34, int(title_dict_plt.get("size", 18) * 1.9))
+    xaxis_px = 46
+    panel_gap_px = 6
+    # Figure-level legends live in a reserved bottom strip. Keeping this out of
+    # the axes placement means legends do not shrink or overlap plot panels.
+    if legend:
+        bottom_px += 80
+
+    non_data_px = (
+        top_px
+        + bottom_px
+        + total_rows * (title_px + xaxis_px)
+        + max(0, total_rows - 1) * panel_gap_px
+    )
+    available_data_px = max(1, fig_h_px - non_data_px)
+    row_sum = sum(row_heights) or 1
+    row_data_px = [available_data_px * h / row_sum for h in row_heights]
+
+    left = left_px / fig_w_px
+    width = max(0.1, (fig_w_px - left_px - right_px) / fig_w_px)
+    y_cursor = fig_h_px - top_px
+
+    def _add_layout_axis(row_index):
+        nonlocal y_cursor
+        y_cursor -= title_px
+        axis_h = row_data_px[row_index]
+        bottom = y_cursor - axis_h
+        ax = fig.add_axes([left, bottom / fig_h_px, width, axis_h / fig_h_px])
+        y_cursor = bottom - xaxis_px - panel_gap_px
+        return ax
 
     # one plot per chromosome
     axes = []
     for i in range(total_rows):
         if i < num_main_rows:
             chrom = chrmd_df_grouped.index[i]
-            axes.append(plt.subplot(gs[i]))
+            axes.append(_add_layout_axis(i))
             ax = axes[i]
             # Adjust plot display
             ax_display(ax, titles[i], title_dict_plt, plot_background, plot_border)
@@ -418,7 +448,7 @@ def _fmt_title(row, fallback_chrom):
             ax.set_yticklabels(list(y_ticks_name))
         else:
             # Adding the added plot
-            axes.append(plt.subplot(gs[i]))
+            axes.append(_add_layout_axis(i))
             ax = axes[i]
             aligned_idx = i - num_main_rows
             original_ax = additional_plots[aligned_idx]
@@ -445,7 +475,4 @@ def _fmt_title(row, fallback_chrom):
                     fontsize=custom_dict.get("title_size", 14),  # Setting the size
                     color=custom_dict.get("title_color", "black"),  # Setting the color
                 )
-
-    plt.subplots_adjust(hspace=vertical_spacing)
-
     return fig, axes
diff --git a/src/pyrangeyes/plot_features.py b/src/pyrangeyes/plot_features.py
@@ -42,6 +42,11 @@
         "Default (and maximum) height of rendered interval blocks.",
         " ",
     ),
+    "auto_height_px_per_unit": (
+        80,
+        "Pixels assigned to one vertical layout unit when pyrangeyes infers figure height automatically.",
+        " ",
+    ),
     "figure_bg": ("white", "Bakground color of the whole figure.", " "),
     "grid_color": ("lightgrey", "Color of x coordinates grid lines.", " "),
     "intron_color": (
@@ -124,6 +129,7 @@
             "shrink_threshold",
             "v_spacer",
             "x_ticks",
+            "auto_height_px_per_unit",
             "title_color",
             "title_size",
             "title_font",