Need to clarify the scope of `axes.number`

[Hem-W]

I guess the meaning of axes.number is not clear or confined now. Some internal functions rely on this property to count the sequence of axes, but fig.add_subplot allows user to specify number on their own. However, this may lead to a bit of confusion, especially for abc format, after the fix #167 .

fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2, abc=True)
ax2 = fig.add_subplot(132, number=4, abc=True)
ax3 = fig.add_subplot(133, number=6, abc=True)

fig.show()

fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2)
ax2 = fig.add_subplot(132, number=4)
ax3 = fig.add_subplot(133, number=6)

axes = fig.subplotgrid
axes.format(abc=True)
fig.show()

This fix comes with an assumption that a subplots always starts with axes.number=1. Before this fix, for uplt.subplots, I can change the starting number to have a different starting letter of abc.

[cvanelteren]

Ah I see. I was not aware people manually numbered them. The use case you are describing is valid. Will have to add some logic to allow for the custom numbering. Thanks for bringing this to my attention and clear description!

[Hem-W]

Thank you for follow-up. I guess the fundamental issue here is what we are expecting from axes.number. Do we always expect axes.number from 1 to the number of axes? Part of the reason for the bug #166 is because when slicing axes, we cannot expect axes.number to start from 1.

Do we expect the user to arbitrarily assign this value? Is it in the scope of ultraplot to allow user to do a partial figure (which does not start from sub-figure A)?

[cvanelteren]

Yeah I was thinking about this too.

I wrongly assumed that the format is always intended to be used in a sequential order, and we can fool the formatting if we don't provide all the inputs by either resetting the number of imputing values to none or empty strings. However, this approach would fail for abc as it specifically uses the axis number to index into the alphabet.

As you pointed out this can be considered as a bug or a feature -- leaning more towards a bug. I am just not too sure how often one constructs figures in the manner your provided. I heavily lean on subplots and never manually label the axes, but that does not mean that others expect this feature. I will need to do some thinking about whether to revert the fix for #166 or there is a way to have both. Slicing the axes in a way would perhaps be better than what I introduced in by fixing #166.

[Hem-W]

I agree that this issue is linked to one’s coding style. If we assume that `abc` only occurs during the final production stage, then there are large chances that users use a chain of code from subplot A to N one by one. However, figures are becoming complicated. It is common now that subplots are combined from multiple sources, which means subplots may rely on different datasets. If in this case users wish to plot everything in one figure with ultraplot, then they need to load all relevant data in one script. I guess sometimes we may just wish to plot several separate panels of subplots and manually combine them later. I am not sure whether this is a reasonable demand...? I feel treating "manual manipulation abc label” as a feature would be easier. Maybe.

[cvanelteren]

There are a few options I see

• use slicing as a replacement for the current lazy evaluation where the ordering is assumed. This would replace the current lazy evaluation
• allow dicts to be passed to only update certain numbers
• add keyword to set abc offset

For the last one it could be an offset, i.e. you want to plot specifically from "D" or from "Z" or whatever. All three would potentially be the most flexible, but necessitates a partial reversal.

[cvanelteren]

Actually the fourth would just be to pass options, but then the difference with mere titles is not that much

[Hem-W]

For the offset one, there will be an assumption that user always want a sequence of abc with an increment of 1. If users should be allowed to arbitrarily set abc label, then this is just a partial implementation instead of a full solution. One possible scenario is to just plot the rightmost column in a 2x3 figure, which has labels of "C" "F".

Is it a good thing to decouple abc label with axes.number?

• When not specified, infer abc labels from axes.number.
• If users give sequence, then map the sequence like what title do in Error when setting titles for a subset of axes using a list of titles #166;
• if give dicts, then do the replacement.

Also, one related issue: I am also confused on the documentation of abc in API (like this one). It says abc key accepts sequence but not clear on how sequence is interpreted.

[cvanelteren]

Yes, I think we thinking along similar lines. However, the issue is that #166 does this in a particular way by overriding the number property to satisfy the length check. For example the abc parameter is inferred as:

            if self.number > len(abc):
                raise ValueError(
                    f"Invalid abc list length {len(abc)} "
                    f"for axes with number {self.number}."
                )
            else:
                kw["text"] = abc[self._number - 1]

To get around the first check, I merely overrode the number property temporarily. For abc this is not an issue issue. For title this happens in a similar fashion. For example, the code you provided would fail for setting title if we remove the overwriting of the number because it will attempt to look up based on the index. The relevant code for update is

            if self.number is None:
                pass
            elif self.number > len(title):
                raise ValueError(
                    f"Invalid title list length {len(title)} "
                    f"for axes with number {self.number}."
                )
            else:
                kw["text"] = title[self.number - 1]

The codebase, therefore, assumes that the arrays that are being set are linear, and the user does not have custom numbers. But that doesn't solve your issue. You could provide a sequence like this

fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2, abc=True)
ax2 = fig.add_subplot(132, number=4, abc=True)
ax3 = fig.add_subplot(133, number=6, abc=True)

axs = fig.subplotgrid
axs.format(abc=["d", "e", "f"])

which would generate

An abc offset would allow you to do this in an "automatic" fashion without having to specify this -- but as you said then it would still be linear.

[Hem-W]

Yes. This is really nice. It is like treating abc just like title and many other properties. If users wanna change specific parts, they can do something like #166 (axs[1:].format(abc=["X", "Y"]). In this case, no need to implement the dicts for replacements on specific axes.

import ultraplot as uplt
fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2)
ax2 = fig.add_subplot(132, number=4)
ax3 = fig.add_subplot(133, number=6)

axs = fig.subplotgrid
axs.format(abc=True)
axs[1:].format(abc=["X", "Y"])

However, we still have some confusing cases. For example, in one CartesianAxes, we can use a single string to do title placement, but cannot for abc as without a list, it is used for automatic formatting.

fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2)
ax2 = fig.add_subplot(132, number=4)
ax3 = fig.add_subplot(133, number=6)

axs = fig.subplotgrid
axs.format(abc=True)
axs[1].format(title="title")
axs[1].format(abc="X")

This leads to

and error

File ~/.conda/envs/ultraplot_127/lib/python3.13/site-packages/ultraplot/axes/cartesian.py:1060, in CartesianAxes.format(self, aspect, xloc, yloc, xspineloc, yspineloc, xoffsetloc, yoffsetloc, xwraprange, ywraprange, xreverse, yreverse, xlim, ylim, xmin, ymin, xmax, ymax, xscale, yscale, xbounds, ybounds, xmargin, ymargin, xrotation, yrotation, xformatter, yformatter, xticklabels, yticklabels, xticks, yticks, xlocator, ylocator, xminorticks, yminorticks, xminorlocator, yminorlocator, xcolor, ycolor, xlinewidth, ylinewidth, xtickloc, ytickloc, fixticks, xtickdir, ytickdir, xtickminor, ytickminor, xtickrange, ytickrange, xtickcolor, ytickcolor, xticklen, yticklen, xticklenratio, yticklenratio, xtickwidth, ytickwidth, xtickwidthratio, ytickwidthratio, xticklabelloc, yticklabelloc, xticklabeldir, yticklabeldir, xticklabelpad, yticklabelpad, xticklabelcolor, yticklabelcolor, xticklabelsize, yticklabelsize, xticklabelweight, yticklabelweight, xlabel, ylabel, xlabelloc, ylabelloc, xlabelpad, ylabelpad, xlabelcolor, ylabelcolor, xlabelsize, ylabelsize, xlabelweight, ylabelweight, xgrid, ygrid, xgridminor, ygridminor, xgridcolor, ygridcolor, xlabel_kw, ylabel_kw, xscale_kw, yscale_kw, xlocator_kw, ylocator_kw, xformatter_kw, yformatter_kw, xminorlocator_kw, yminorlocator_kw, **kwargs)
   1031 """
   1032 Modify axes limits, axis scales, axis labels, spine locations,
   1033 tick locations, tick labels, and more.
   (...)   1057 and tick labels will be automatically formatted as dates.
   1058 """
   1059 rc_kw, rc_mode = _pop_rc(kwargs)
-> 1060 with rc.context(rc_kw, mode=rc_mode):
   1061     # No mutable default args
   1062     xlabel_kw = xlabel_kw or {}
   1063     ylabel_kw = ylabel_kw or {}

File ~/.conda/envs/ultraplot_127/lib/python3.13/site-packages/ultraplot/config.py:829, in Configurator.__enter__(self)
    827 except Exception as e:
    828     self.__exit__()
--> 829     raise e
    831 for rc_dict, kw_new in zip(
    832     (rc_ultraplot, rc_matplotlib),
    833     (kw_ultraplot, kw_matplotlib),
    834 ):
    835     for key, value in kw_new.items():

File ~/.conda/envs/ultraplot_127/lib/python3.13/site-packages/ultraplot/config.py:826, in Configurator.__enter__(self)
...
--> 238 raise ValueError(
    239     "A-b-c setting must be string containing 'a' or 'A' or sequence of strings."
    240 )

ValueError: A-b-c setting must be string containing 'a' or 'A' or sequence of strings.

[Hem-W]

Also, I wish to note that the list of strings can not be used in formatting single CartesianAxes.

import ultraplot as uplt
fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2)
ax2 = fig.add_subplot(132, number=4)
ax3 = fig.add_subplot(133, number=6)

axs = fig.subplotgrid
axs.format(abc=True)
axs[2:].format(title=["title"])
axs[2].format(title=["title"]) # This leads to error relevant to axes.number

The error:

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[22], line 10
      8 axs.format(abc=True)
      9 axs[2:].format(title=["title"])
---> 10 axs[2].format(title=["title"])

File ~/.conda/envs/ultraplot_127/lib/python3.13/site-packages/ultraplot/axes/cartesian.py:1350, in CartesianAxes.format(self, aspect, xloc, yloc, xspineloc, yspineloc, xoffsetloc, yoffsetloc, xwraprange, ywraprange, xreverse, yreverse, xlim, ylim, xmin, ymin, xmax, ymax, xscale, yscale, xbounds, ybounds, xmargin, ymargin, xrotation, yrotation, xformatter, yformatter, xticklabels, yticklabels, xticks, yticks, xlocator, ylocator, xminorticks, yminorticks, xminorlocator, yminorlocator, xcolor, ycolor, xlinewidth, ylinewidth, xtickloc, ytickloc, fixticks, xtickdir, ytickdir, xtickminor, ytickminor, xtickrange, ytickrange, xtickcolor, ytickcolor, xticklen, yticklen, xticklenratio, yticklenratio, xtickwidth, ytickwidth, xtickwidthratio, ytickwidthratio, xticklabelloc, yticklabelloc, xticklabeldir, yticklabeldir, xticklabelpad, yticklabelpad, xticklabelcolor, yticklabelcolor, xticklabelsize, yticklabelsize, xticklabelweight, yticklabelweight, xlabel, ylabel, xlabelloc, ylabelloc, xlabelpad, ylabelpad, xlabelcolor, ylabelcolor, xlabelsize, ylabelsize, xlabelweight, ylabelweight, xgrid, ygrid, xgridminor, ygridminor, xgridcolor, ygridcolor, xlabel_kw, ylabel_kw, xscale_kw, yscale_kw, xlocator_kw, ylocator_kw, xformatter_kw, yformatter_kw, xminorlocator_kw, yminorlocator_kw, **kwargs)
   1348 if aspect is not None:
   1349     self.set_aspect(aspect)
-> 1350 super().format(rc_kw=rc_kw, rc_mode=rc_mode, **kwargs)

File ~/.conda/envs/ultraplot_127/lib/python3.13/site-packages/ultraplot/axes/base.py:3050, in Axes.format(self, title, title_kw, abc_kw, ltitle, lefttitle, ctitle, centertitle, rtitle, righttitle, ultitle, upperlefttitle, uctitle, uppercentertitle, urtitle, upperrighttitle, lltitle, lowerlefttitle, lctitle, lowercentertitle, lrtitle, lowerrighttitle, share_xlabels, share_ylabels, **kwargs)
   3048     self._abc_pad = units(pad)
   3049 self._update_abc(**abc_kw)
-> 3050 self._update_title(None, title, **title_kw)
   3051 self._update_title(
   3052     "left",
   3053     _not_none(ltitle=ltitle, lefttitle=lefttitle),
   3054     **title_kw,
   3055 )
   3056 self._update_title(
   3057     "center",
   3058     _not_none(ctitle=ctitle, centertitle=centertitle),
   3059     **title_kw,
   3060 )

File ~/.conda/envs/ultraplot_127/lib/python3.13/site-packages/ultraplot/axes/base.py:2772, in Axes._update_title(self, loc, title, **kwargs)
   2770     pass
   2771 elif self.number > len(title):
-> 2772     raise ValueError(
   2773         f"Invalid title list length {len(title)} "
   2774         f"for axes with number {self.number}."
   2775     )
   2776 else:
   2777     kw["text"] = title[self.number - 1]

ValueError: Invalid title list length 1 for axes with number 6.

[cvanelteren]

The first error you describe is to be expected. The docs read as:

abc (bool or str or sequence, default: rc.abc = False) – The “a-b-c” subplot label style. Must contain the character a or A, for example 'a.', or 'A'. If True then the default style of 'a' is used. The a or A is replaced with the alphabetic character matching the number. If number is greater than 26, the characters loop around to a, …, z, aa, …, zz, aaa, …, zzz, etc. Can also be a sequence of strings, in which case the “a-b-c” label will simply be selected from the sequence according to number.

that is we can either provide a sequence of strings or a singular character that will format it, e.g. we could have "[A]" or "a." or "A." indicating how the abc label will look like using the letter A as a placeholder. The axes will then be numbered according to the index into abc but linearly from 1. Before it used the index directly but then title would fail for example as the numbers did not match the length of those arrays.

The second case you describe two issues. Let's go through it one by one. In the first case you are getting a subplotgrid as you are slicing into axes which is a subplotgrid (and thus getting a subplot grid). Format will then go through figure.format. This will create a linear index temporarily which is why you can format with this list.

In the second case, you are passing a list to a singular axis, which will then retrieve it based on the axis number as it did not pass through figure.format but you are addressing a Cartesian axis directly. This behavior is, I must admit, rather confusing but is a weird edge case that I think should never occur as you are telling a singular axis to use a list. I do think the error message needs to change as it is confusing getting that message if you do encounter it when you are trying to infer how the arguments could be passed.

Note that

fig = uplt.figure(figwidth=3, figheight=2)
ax1 = fig.add_subplot(131, number=2)
ax2 = fig.add_subplot(132, number=4)
ax3 = fig.add_subplot(133, number=6)

axs = fig.subplotgrid
axs.format(abc=True)
axs[2:].format(title=["title"])
axs[2].format(title="title")

works as intended

[cvanelteren]

I think the concerns you raised are valid as the docs are not updated to reflect the change from #166. I should adjust the text to state that when a list is parsed it assumes we are updating the plot linearly from the axes passed in the subplotgrid. Furthermore, the error in singular index should reflect a more generic message rather than referring to the actual number.

[Hem-W]

The first error you describe is to be expected. The docs read as:

abc (bool or str or sequence, default: rc.abc = False) – The “a-b-c” subplot label style. Must contain the character a or A, for example 'a.', or 'A'. If True then the default style of 'a' is used. The a or A is replaced with the alphabetic character matching the number. If number is greater than 26, the characters loop around to a, …, z, aa, …, zz, aaa, …, zzz, etc. Can also be a sequence of strings, in which case the “a-b-c” label will simply be selected from the sequence according to number.

Thank you. Yes, I can understand where this error comes from. My idea of raising this issue is to highlight that "abc" cannot be transited to allow free manipulation like "title" among many others. For "title" of a single axes, we can simply change it using ax[2].format(title="title"), but this is not applicable for "abc". We cannot use ax[2].format(abc="X") but can use ax[2:].format(abc=["X"]). This may be a little bit confusing to the user, I guess. The auto infer from "A" would clash with the user's intention to change abc on only one axis.