[BUG]: `vertical_spacing` argument for `make_subplots` should leave space for subplot titles

[emilykl]

Description

Setting the vertical_spacing argument of make_subplots to a small value, while also passing subplot_titles, results in a really ugly chart where the subplot titles overlap the subplots themselves.

Ideally vertical_spacing should take titles into account, and control the spacing between the top of the title and the bottom of the subplot above.

We obviously don't know the exact size of the title text, but something like font size * 1.75 should be approximately the right amount of space for a single-line title.

However we need to see whether this requires changes to Plotly.js, since axis.domain only supports units of plot fraction, not sure if there is a way to shift it by a certain number of pixels.

Screenshots/Video

Steps to reproduce

from plotly.subplots import make_subplots
import plotly.graph_objects as go
import random

fig1 = make_subplots(
        rows=6, cols=1,
        shared_xaxes=True,
        vertical_spacing=0.02,
        row_heights=[0.35, 0.13, 0.13, 0.13, 0.13, 0.13],
        subplot_titles=['Heart Rate Variability', 'Walking', 'Cycling', 'Hiking', 'Other', 'Pilates']
    )
for i in range(6):
    fig1.add_trace(
        go.Scatter(x=[0,1,2], y=[random.randint(0, 10) for _ in range(3)]),
        row=i+1,
        col=1
    )
fig1.show()

[SharadhNaidu]

hey @emilykl, happy to take this if nobody's on it.

had a dig — the titles are just annotations pinned to the top of each subplot domain (yanchor bottom), so they grow upward into the gap above. with vertical_spacing=0.02 that gap is tiny, but a 16px title needs ~0.06 at the default 450px height (your font*1.75), so each one pokes ~0.04 into the plot above it. thats the overlap.

the tricky part is the one you flagged: the gap is a fraction but the title is pixels, and make_subplots doesnt know the final height (people set it later or leave it responsive), so a pixel-exact fix really needs plotly.js. but i can get close from python by shaving font*1.75/height off the top of each titled row's domain — tried it on the repro and the overlap turns into a clean gap.

couple of calls i didnt want to make for you:

1. should the estimate use layout.height when its set and fall back to 450 otherwise?
2. do you want it applied always (moves a bunch of baselines) or only when spacing is too tight for the titles?

whichever you'd prefer and i'll put up a PR.

[emilykl]

@SharadhNaidu You're welcome to take a stab at it if you like, but I don't think the proposed fix will work since plot height can change dynamically if the containing div is resized. I think in order to support this fix, Plotly.js will need to be modified to support pixel offsets for domain, or something along those lines. That's a larger project, but you're welcome to look into it.

Before going too far with a specific implementation, please open an issue in Plotly.js linking to this issue and proposing a change to the API to support this fix.

[SharadhNaidu]

ok , it really looks like a big work but let me try

[SharadhNaidu]

opened the plotly.js issue as you suggested: plotly/plotly.js#7835

laid out the dynamic-height problem and two possible directions (a pixel component on domain spacing, or letting subplot titles reserve space via the existing automargin pass), but left the actual API call to the team. happy to implement once there's a direction.