Improving SmartFigure indexing

[Oddball777]

Hey everyone,

I've been thinking about the SmartFigure quite a bit, especially the indexing API. This a great shortcut to organize and access sub figures and Plottables. And while I think the idea is great, I do think there are some things that could benefit from a bit of polishing or rethinking. This relates in part to the following issue in @mamar828 's fork:

• Add elements with +=

This issue is one symptom of a larger problem, which, if I had to summarize it in one sentence, would be that the indexing with SmartFigures can lead to unintuitive behaviour. See the following example which I adapted from the docs:

# Create curves
curve1 = gl.Curve.from_function(lambda x: np.sin(x), x_min=0, x_max=2*np.pi)
curve2 = gl.Curve.from_function(lambda x: np.cos(x), x_min=0, x_max=2*np.pi)
curve3 = gl.Curve.from_function(lambda x: np.sin(2*x), x_min=0, x_max=2*np.pi)
curve4 = gl.Curve.from_function(lambda x: np.cos(2*x), x_min=0, x_max=2*np.pi)
curve5 = gl.Curve.from_function(lambda x: np.sin(3*x), x_min=0, x_max=2*np.pi)

# Create top left figure
fig_top_left = gl.SmartFigure(
    elements=[curve1, curve2]
)

# Create bottom spanning figure
fig_bottom = gl.SmartFigure(
    elements=[curve1, curve2, curve3, curve4]
)

# Combine into parent figure
parent = gl.SmartFigure(
    num_rows=2,
    num_cols=2,
    size=(10, 6),
)

# Add elements with spanning
parent.elements = [fig_top_left, [curve3, curve4]]
parent[1, :] = fig_bottom  # Spans both columns

print(parent[0, 0])  # Returns <graphinglib.smart_figure.SmartFigure object at 0x10cb556a0>
print(parent[0, 1])  # Returns [Curve(), Curve()]
print(parent[1, 0])  # Returns []
print(parent[1, 1])  # Returns []
print(parent[1, :])  # Returns <graphinglib.smart_figure.SmartFigure object at 0x10d3116a0>

Here, we have a pretty simple layout with 2 figures in the top row and one wide figure in the bottom row. However, the indexing returns a wide range of things depending on how elements were inserting. This is something which I find a bit annoying. I view the different ways of setting up a SmartFigure and of adding elements as just that: different ways of doing the same thing, to accommodate different workflows. But here, clearly, these different ways don't really end up doing the same thing. Adding a sub figure via parent.elements = [subfigure, None] vs via parent.elements = [[curve1, curve2], None] leads to different behaviours of the indexing calls (even though the figures produced look and are the same).

Criterion A: Different APIs to accomplish the same thing should lead to indistinguishable results.

Another angle from which to view this issue is type checking. We haven't put much emphasis on types as of now (just try running ty check on the repo to see how much work there is to do in that department). But ideally, I think it should probably be the case that all first level indexing of a SmartFigure should return the same type. That type could be a Plottable if the SmartFigure is not nested (contains only Plottables), or a SmartFigure, if's a parent SmartFigure. But for a given SmartFigure, type(fig[0, 0]) == type(fig[0, 1] == type(fig[1, 0]) ... should be true. This would make things more uniform. Maybe one solution which would solve both this issue and the previous one is to dynamically create a sub figure when users pass in a list of Plottables? This would make passing in a list of Plottables just a shortcut when you're too lazy to create a whole sub figure yourself (but it actually is created for you behind the scenes, and you can access it using indexing).

Criterion B: Indexing one level deep should return same type across all indices (whether that's Plottables or SmartFigures)

There's another issue which is that we're using a tool (indexing) that's too powerful and flexible for what we need (ex: I could index a completely nonsensical slice which intersects through multiple figures and doesn't include any complete figure). More generally, the question we need to answer is this: What does indexing on a SmartFigure mean? I think we can view it as either a "select" tool or a "pointer" tool, and both have different implications, both for assignment (parent[0, 1] = fig) and for accessing (parent[0, 1].set_grid(...)).

All a pointer tool can do is click. This would mean no slices, only put in the coordinates of the cell you want to access/assign to. For accessing, this would mean that if a sub figure spans the two bottom rows of a 2x2 grid, both parent[1,0] and parent[1,1] will return that sub figure. Clicking on a cell returns whatever figure happens to be on that cell, even if the figure is bigger than just that cell. For assignment, we'd need another way to specify the span of the sub figure we're adding. You'd call parent[1,0] = new_sub_fig.set_cols_in_parent(2) or something like that (might be a better way to do it, considering that this won't work with parent[1,0] = [my_curve]). In any case, you'd "click" on the top left cell of the span you want your sub figure to occupy, and specify the span some other way.

A select tool only works with ranges. This is the current way things work. Assign with the exact range where you want the sub figure to be, access with the exact range where the sub figure is. It's consistent. But it comes with the following downsides: additional complexity (understanding ranges/slices), needing to know the exact slice of the figure you're looking for, and ambiguity in the case of nonsensical slices (what if a slice contains only part of a subfigure? two whole figures? one and a half figures?).

In Rust, there's this common saying: “Make invalid states unrepresentable”. This means designing your API so users can’t even construct a value that breaks your rules, instead of allowing it and checking later. For example, use two types like UnpaidPayment(amount) and PaidPayment(amount, paid_at) rather than one Payment(status, paid_at) where status="paid" but paid_at=None is possible in the database but impossible in reality. The pointer option seems to me like it's closer to this ideal than the select option, but it still has the issue of how to specify spans.

I'm legitimately unsure what the solution is here, or if there even is any. There may be a clever way to combine the two approaches and get the best of both worlds? But then again, we'd lose the clear intuition of click vs select.

Criterion C: Make slices make more sense? Somehow??? Idk

---

I think at least part of the solution to all this is:

1. Indexing on a SubFigure which is a parent should return a SubFigure, no matter how the user created the parent and sub figures.

parent[0,0] = fig_top_left
accessed_fig = parent[0,0]

2. Indexing on a SubFigure which is a standalone figure should either (not sure which is best) return Plottables:

   a_curve = standalone_fig[0]
   a_scatter = standalone_fig[1]

   Or return an error, and require the explicit .elements or something similar:

   a_curve = standalone_fig[0] # Error
   a_curve = standalone_fig.elements[0] # works

3. Define += on the SmartFigure as a shortcut to add elements (or on an internal object which is returned when .elements is called).

This would solve the @mamar828's += issue. You can call standalone_figure += my_curve or standalone_figure.elements += my_curve. For a parent figure, you can call parent[0,1] += my_curve because the left side evaluates to a SmartFigure object. It would also solve Criterion A and Criterion B. It still leaves open the question of what to do about Criterion C.

This is all extremely untested and brainstormy, so if you disagree with anything, have other justifications for why things are the way they currently are, or have any other ideas, please comment them! I specifically started a discussion on this topic because my confidence in everything I wrote above is rather weak and I want other people's impressions.

[Oddball777]

@mamar828 @charlesantoineparent3 @Mykola-P I'd love your input on this if/when you have the time! Sorry for the ridiculously long text haha

[mamar828]

Yeah, you're kind of converging towards an idea I started to have more and more haha. I was also thinking that it could be useful to always create nested SmartFigures whenever the user creates a SmartFigure with multiple subplots. This then makes it very easy to modify specific subplots (e.g. setting ticks) without having to tediously create another SmartFigure just for that, and it uniformises the API as you point out.

However, I didn't implement it that way because I felt it would kind of complicate default attributes. Say you create a 2x2 SmartFigure and you want to remove_x_ticks of all subplots. This would mean that changing this property in the parent SmartFigure should also affect all nested SmartFigures. But then how do you differentiate from a nested SmartFigure that has automatically been created from one that has been given by the user? In other words, how do you keep track of which values were specified by the user and which are the default ones that should get overridden by the parent SmartFigure? With the current logic of: each SmartFigure controls their own parameter, and use nested SmartFigures to change them, I'm not sure it would actually simplify the API.

Another example would be: you create a 2x2 SmartFigure and you make the axes blue. Then you change the 0,0 SmartFigure's axes to red, and the 0,1 SmartFigure's axes to None. After that you modify the parent SmartFigure's axes to green. What then should get modified? Should you like "untie" SmartFigures once you modify them? "Untie" just the attributes you modified? I feel like it would introduce more randomness and complexity unfortunately, and I really wish there was a smart way to do this...

At least maybe something that could help would be to implement a helper method that converts a subplot to a SmartFigure. That way the user knows they changed it and that it's going to have its own parameters from this point on, and they don't have to create their own nested SmartFigure.

As for the indexing, I understand your points about being able to slice incoherently and then having to know the exact layout of the SmartFigure to access elements from it. I really like the simplicity of the [] operator though... I agree that it is maybe too flexible, but since it feels very intuitive, I didn't think it was that much of a problem. We could however also implement some checks and maybe methods to ease the setting/getting of elements.

I also agree with your suggestion of being able to "click" in a specific subplot even though it spans multiple rows/columns. This could be implemented by tweaking the way elements are added and removed from the SmartFigure.elements dictionary and then being able to access and modify elements that span multiple rows/columns by accessing any of these rows/columns.

Thank you for starting this discussion: I was probably going to start one about this very subject one day!

[Oddball777]

I think replacing all the "default" strings by a Default type is a good idea which we should do even if it ends up being just a marker type with no additional functionality (because strings are icky).

But using it for fetching defaults interactively could lead to certain problems. For example, the default line_style of a Curve depends on the figure style chosen for the Figure that it is added to. Sometimes even that is not enough, if for example the user decides to override the default curve line_style by calling SmartFigure.set_rc_params. So what should Curve.line_style return instead of "default"? There's no way for the Curve to know ahead of time which figure it will be placed in and therefore which style it will have.

There's a case to be made for just returning the default style's values. When installing GL, the default style is plain, but there are a few different ways the user can change this. So if I decide I want my default style to be horrible for some reason, calling Curve.line_style would return horrible's default Curve line_style.

Pro: Some of MPL's units are really confusing (ex: marker sizes and line widths are not the same units) and so having a point of reference could make it useful when trying to adjust these things. For example, if I want my marker size a tiny bit bigger than the default, right now I don't have a way to easily get the current size, nor even any idea of the order of magnitude of a typical marker size.

Con: This could be misleading and hard to interpret though. I could imagine a user wondering why the their Curve has a dashed line_style in the figure and yet printing Curve.line_style returns dotted.

Another option could be to write an order of magnitude reference point in the docstrings for each parameter. Most sensible value to put there would probably be the plain style values. For example:

"""
...
line_width : float
            Width of the curve.
            Default depends on the ``figure_style`` configuration. In 'plain' style: 3.
...
"""

Not sure what the best option is here either 🤷‍♂️

[mamar828]

The way this used to work with MultiFigure was using a combination of two things. For rc params, we separated the figure style and inherited params from the user specified ones using self._user_rc_dict and self._rc_dict (see this example in the handbook). For non rc params (things set either with methods, properties, or in the init), we heavily used "default" as a placeholder.

In your first example then, if SmartFigure's init had remove_x_ticks: SomeType = "default" as a default, then you could easily tell whether or not the user had touched this parameter. If it's "default", it means "replace me with whatever my parent/style says I should be". If it's anything else, leave it as is since the user manually changed it. So if you want to remove_x_ticks everywhere, specify that parameter for the parent, and leave it as "default" for the children (so just don't touch it) and you're good. This also comes with the advantage that if you want to define a style where x ticks are absent by default for some reason, you can. Though it comes with the significant downside that basically everything is "default" and you can't really know what the default behaviour of a parameter is unless you try it, or unless you read the style file.

In your second example, I'm not sure what you mean. Isn't this already handled by the self._user_rc_dict behaviour? I tried your example and I got pretty much what I expected:

# Create the curves
sine = gl.Curve.from_function(lambda x: np.sin(x), 0, 2 * np.pi, label="sine")
cosine = gl.Curve.from_function(lambda x: np.cos(x), 0, 2 * np.pi, label="cosine")
positive = gl.Curve.from_function(lambda x : 3*x + 4, 0, 2*np.pi, label="+ slope")
negative = gl.Curve.from_function(lambda x : -3*x + 4, 0, 2*np.pi, label="- slope")

# Create the figures and add the elements
figure1 = gl.SmartFigure(elements=[sine])
figure2 = gl.SmartFigure(elements=[cosine])
figure3 = gl.SmartFigure(elements=[positive])
figure4 = gl.SmartFigure(elements=[negative])

parent_figure = gl.SmartFigure(num_cols=2, num_rows=2, size=(10, 4), elements=[figure1, figure2, figure3, figure4])

parent_figure.set_visual_params(axes_edge_color="blue")
parent_figure[0,0].set_visual_params(axes_edge_color="red")
parent_figure[0,1].remove_axes = True
parent_figure.set_visual_params(axes_edge_color="green")

parent_figure.show()

Even if the sub figures had been created internally by the parent figure instead of being passed manually, I'm pretty sure we'd get the same result. Isn't this what we should expect? The parent figure passes on its properties to the sub figures, unless these parameters have already been manually specified by the user in the sub figures. This works on a "per parameter" basis, meaning that it checks "did the user make a more specific request" independently for each rc param. If I had also changed the `axes_face_color` but on the parent only, all the children would have inherited that param since I didn't specify the children face colors for any of them. And since all of this is evaluated only upon calling `fig.show()`, the blue edge color call is completely overwritten by the green one, so the blue line could be deleted entirely.

For the indexing, I agree that it's less of a priority. I think we could probably just make "clicking" behaviour work for figures that span multiple cells and keep the rest of the existing behaviour. And also, maybe add a method to SmartFigure to add multicell sub figures without using indexing. The only way to do this right now is to use indexing/slicing right? That's really intuitive for people who are familiar with numpy, but I think adding a method which asks for top left coordinate, col span and row span would be good for beginners. That would be good enough for 1.6.0, what do you think?

Also, while writing this I noticed that matplotlib styles seem to work inconsistently with SmartFigures, is that something you looked into? I tried this example from the gallery (adapted to use SmartFigure):

import graphinglib as gl

# Generating data for a 2D plot of the Lorenz attractor
def lorenz_attractor(sigma, beta, rho, initial_state, num_steps, dt):
    x, y, z = initial_state
    xs, ys, zs = [], [], []

    for _ in range(num_steps):
        dx = sigma * (y - x)
        dy = x * (rho - z) - y
        dz = x * y - beta * z

        x += dx * dt
        y += dy * dt
        z += dz * dt

        xs.append(x)
        ys.append(y)
        zs.append(z)

    return xs, ys, zs


# Parameters for the Lorenz attractor
sigma = 10.0
beta = 8.0 / 3.0
rho = 28.0
initial_state = (0.0, 1.0, 1.05)
num_steps = 5000
dt = 0.01

# Generating the Lorenz attractor data
xs, ys, zs = lorenz_attractor(sigma, beta, rho, initial_state, num_steps, dt)

# 2D plot of the Lorenz attractor
curve = gl.Curve(x_data=xs, y_data=zs, line_width=1)

# Choosing a style from the matplotlib library
fig = gl.SmartFigure(x_label="x", y_label="z", figure_style="Solarize_Light2")
fig.add_elements(curve)

fig_big = gl.SmartFigure(num_cols=2, elements=[fig, None])
fig_big.show()

Right, I didn't think that we would want "default" to reference the parent SmartFigure's parameters rather than the figure style. This would make it work, but would change the current philosophy of "nested SmartFigures keep their own properties untouched". So if by laziness you left a parameter as "default" since the style gives the desired value, but then you placed that figure into a parent SmartFigure that makes this parameter another value (e.g. to modify other subplots), you would have to go back and manually modify the original nested SmartFigure to change this parameter back. I'm not saying that we should not implement it because of this, but more like something we should keep in mind.

As for my second example, I should have used a parameter in the __init__/property as an example rather than one in set_visual_params, because I agree with you that children inheriting the parent figure's visual params is the intended behaviour. However, properties are currently coded such as None doesn't mean "replace me by the parent" but rather "don't use this parameter". So if we didn't use the "default" you suggest, this would lead to the ambiguous behaviour I was discussing earlier (i.e. not being able to track whether None properties should be replaced by the parent's values or left as is).

For indexing, I agree with your suggestions and I think it would be fair for 1.6.0. Just a quick question:

• Regarding the "clicking" behaviour, do you think that once a multicell subplot is created, you should also be able to add Plottables by indexing any of these cells? And that setting any of these cells to None should erase the entire cell across all subplots?

As for the matplotlib styles, just like MultiFigure, only the parent SmartFigure style is used even when there are nested SmartFigures with different styles. In your code snippet, you should either specify a figure_style for fig_big, or directly show fig to get the intended style. Let me know if I understood your issue well!

[mamar828]

Though it comes with the significant downside that basically everything is "default" and you can't really know what the default behaviour of a parameter is unless you try it, or unless you read the style file.

Couldn't this be fixed (or improved) by defining a Default type which could maybe fetch the value from the style file at the time of its instantiation? We could then make it print the value from the style file if the user tries to print the value of a parameter.

If we wanted to include this, it would mean that the figure_style should become immutable, i.e. it could only be specified at creation time since otherwise, we wouldn't be able to know which parameters to modify if the figure_style was changed after the Default type fetched the values.

[mamar828]

I think replacing all the "default" strings by a Default type is a good idea which we should do even if it ends up being just a marker type with no additional functionality (because strings are icky).

But using it for fetching defaults interactively could lead to certain problems. For example, the default line_style of a Curve depends on the figure style chosen for the Figure that it is added to. Sometimes even that is not enough, if for example the user decides to override the default curve line_style by calling SmartFigure.set_rc_params. So what should Curve.line_style return instead of "default"? There's no way for the Curve to know ahead of time which figure it will be placed in and therefore which style it will have.

There's a case to be made for just returning the default style's values. When installing GL, the default style is plain, but there are a few different ways the user can change this. So if I decide I want my default style to be horrible for some reason, calling Curve.line_style would return horrible's default Curve line_style.

Pro: Some of MPL's units are really confusing (ex: marker sizes and line widths are not the same units) and so having a point of reference could make it useful when trying to adjust these things. For example, if I want my marker size a tiny bit bigger than the default, right now I don't have a way to easily get the current size, nor even any idea of the order of magnitude of a typical marker size.

Con: This could be misleading and hard to interpret though. I could imagine a user wondering why the their Curve has a dashed line_style in the figure and yet printing Curve.line_style returns dotted.

Another option could be to write an order of magnitude reference point in the docstrings for each parameter. Most sensible value to put there would probably be the plain style values. For example:

"""
...
line_width : float
            Width of the curve.
            Default depends on the ``figure_style`` configuration. In 'plain' style: 3.
...
"""

Not sure what the best option is here either 🤷‍♂️

Yeah I agree that it's sometimes tedious to guess the order of magnitude of certain parameters, and that returning the default style would be useful but could be unintuitive. In my opinion, I think documentation would be the way to go here. Although this would come with the cost of having to make sure to modify the docstrings if the plain figure style was ever modified.

[Oddball777]

In order to declutter this discussion, I created issue #649 to implement clicking behaviour and issue #650 for the MPL style bug (I made a mistake in the code I showed in the comment above, the correct code is in the issue). I think these are both specific and focused enough that discussion about these can be moved to those issues.

What should "default" mean?

Right, I didn't think that we would want "default" to reference the parent SmartFigure's parameters rather than the figure style. This would make it work, but would change the current philosophy of "nested SmartFigures keep their own properties untouched". So if by laziness you left a parameter as "default" since the style gives the desired value, but then you placed that figure into a parent SmartFigure that makes this parameter another value (e.g. to modify other subplots), you would have to go back and manually modify the original nested SmartFigure to change this parameter back. I'm not saying that we should not implement it because of this, but more like something we should keep in mind.
As for my second example, I should have used a parameter in the init/property as an example rather than one in set_visual_params, because I agree with you that children inheriting the parent figure's visual params is the intended behaviour. However, properties are currently coded such as None doesn't mean "replace me by the parent" but rather "don't use this parameter". So if we didn't use the "default" you suggest, this would lead to the ambiguous behaviour I was discussing earlier (i.e. not being able to track whether None properties should be replaced by the parent's values or left as is).

Up until now, "default" has always had the purpose of inheriting from the parent, going up the chain all the way to the style file. Maybe when we turn this into a marker class, we could rename it to Inherit, or maybe have both Inherit and FromStyle to distinguish between an inheritance chain and a strict "use the value from the style file". More on this below, but as of now, using "default" is the repo-wide method to inherit from both parents and styles. There is currently no way to have a parameter which inherits only from the style and not the parent (and I'm not actually sure how useful this be). The way things currently work is described in the MultiFigure section of the handbook (which I think has only been slightly changed for the SmartFigure handbook):

The figure_style chosen in the MultiFigure constructor is applied to every Figure in the MultiFigure. Any figure_style specified in the individual Figure objects is ignored when displaying or saving the MultiFigure.
On the other hand, though applying style customizations to the MultiFigure object will apply them to every Figure in the MultiFigure, customizations specified in the individual Figure objects is prioritized over the MultiFigure’s customizations. This means that turning the grid on in the MultiFigure will turn it on for every Figure in the MultiFigure, but turning it off in an individual Figure will override the MultiFigure’s setting and turn it off for that Figure only.

I think this logic should apply to all parameters and properties which have "default", regardless of whether they're in the init or not. This could be made clearer in the docs, but what's implied here is a CSS-type (Cascading Style Sheets) style inheritance structure, where some properties naturally flow from a parent element down to its children unless a child sets its own value. If a child sets its value, it overrides whatever values its ancestors may have. If it doesn't, it inherits the value of its parent (and the parent may also have inherited its value from its own parents, etc etc until you reach the master style file at the top, e.g. plain). Having a parameter which ignores its ancestors and only looks at the style file would go against this intuition. So there would need to be a significant gain in order to implement this. Here is an example which compares what the code would look like in both cases.

CSS-like inheritance

Here, we use CSS-like inheritance for remove_x_ticks (I picked a random parameter for this example):

def random_fig() -> gl.SmartFigure:
    curve = gl.Curve.from_function(
    lambda x: np.sin(x + np.random.rand()), 0, 2*np.pi
    )
    return gl.SmartFigure(elements=[curve])

# Here, all remove_x_ticks are still "default"
elems = [random_fig() for _ in range(4)]
# Change the first subfigure's remove_x_ticks from "default" to True
elems[0].remove_x_ticks = False

# Create the parent and set the parent's remove_x_ticks to True
parent = gl.SmartFigure(2, 2, elements=elems, remove_x_ticks=True)

# This step resolves all params. The three subfigures which still have "default"
# are changed to True by inheritance. Subfigure 1 does not have "default" so
# it's value is not changed.
parent.show()

Since remove_x_ticks is a "default" parameter, all subfigures inherit True from the parent except for the subfigure at [0, 0] which we had previously manually changed from "default" to False. To have the opposite behaviour (where [0,0] is the only one without x ticks), we could simply swap the True <-> False values in the example above. In fact, since the plain style would probably have remove_x_ticks = False as a default, you could just omit that parameter in the parent. Parent would inherit False from the style, and all subfigures would inherit False from the parent except for the one at [0,0] which is manually set to True. You have to remember here that all remaining "default" parameters are only "baked in" when parent.show() is called. So setting the parameter on the parent and on the child can be done in any order. Also, notice how you have to use the parameter remove_x_ticks at most twice to get the intended behaviour. This stays true for any number of figures where you want only one to have a different behaviour than the parent.

Style-only "default"

If, instead, remove_x_ticks inherited only from the style, and not the parent, then setting the parent's remove_x_ticks=True becomes useless. The parent container has no x ticks to remove, the only place it can remove them is from its children, but the children don't inherit that parameter. So now you have to set subfig.remove_x_ticks = True on all 3 of the subfigures individually, or use the parent's remove_x_ticks with a list of bools [True, False, False, False] (which doesn't seem to work currently? But anyways, passing a list of values can be done with both the style-only and the css-like models, so it doesn't differentiate them). Both of these become more clunky as the number of children increases.

Conclusion: I think CSS-like inheritance is better, than style-only, both because the code ends up being simpler in most cases and because it's consistent and in this case, there is no real distinction between inheriting from the parent or inheriting from the style files; they're all part of the same inheritance tree, same logic.

Again, if you disagree, please don't hesitate to mention it!

One caveat: parameter lists

One thing that fits less clearly in the inheritance/css model is when you do something like:

sub_fig_at_0_1.remove_x_ticks = True # change from "default" to True
parent = gl.SmartFigure(2, 2, elements=elems, remove_x_ticks=[True, False, False, True])

If the subfigure at [0,1] already has a value of True, should the second line override it? According to the inheritance model, parameters of the parent should only affect the child if the child's parameter is "default". But the second line isn't really setting the remove_x_ticks parameter of the parent, it's more so just enumerating what the parameters of the children should be. So what should we do?

I still think that if we go with the inheritance model, we have to go all the way. Why would the user manually set subfigure [0,1]'s param to True if they intended to override it with the parent anyway? That would be a useless line of code. With the inheritance model, setting remove_x_ticks=[True, False, False, True] on the parent means that you can substitute in different subfigures, shuffle them around all you like, but the subfigures at [0,0] and [1,1] will by default have their x ticks removed. If you want to change this behaviour, you can either change the values in the list to change the parent's behaviour, or you can override this behaviour on the subfigures directly as above. When changing a parameter on something high up the inheritance tree from "default" to something else, you should always remember that you are setting the children's default behaviour, not determining a hard set rule for them. It can always for overridden on the children themselves. Thinking about it in terms of inheritance also maintains the GL principle that the order in which you make your calls doesn't matter, since everything is always evaluated on .show() anyway.

To inherit or not to inherit?

Assuming we go with the inheritance-like model, I think the real question we have to answer, for each param in the init, is the following: does it make sense for param x to use inheritance or not? Choosing "yes" means that the param will inherit both from the parent and the style according to the inheritance tree.

For example, num_rows and x_lim are things which I think makes no sense to have inheritance for. They're so specific to an individual plot that it doesn't make much sense to let the user set this for all subfigures. I think at some point, if the user really wants that, they can just __iter__ over the plots and set it themselves. It makes no sense to use "default" for those. What would we even put in the style files?

There are other init params for which it would make a lot of sense to have inheritance behaviour. I think remove_axes is style-related enough that some users might like having this option in the style files, and similarly might like being able to just set it once on the parent and have it be applied to all subfigures automatically, regardless of what's in the styles. Might be worth having "default" for those. There are also things like size which are only applied to the parent-most figure, so even if it's inherited, it doesn't have any effect on the subfigures so using "default" is a good option here too, just so that the user doesn't have to set it every time on the top level parent.

Then there are the in-between cases, where I could see an argument being made either way. Does it make sense for log_scale_x to have "default"? Well, most of the time no. But maybe some user out there use GL only for log based stuff in a log based context and would really like being able to just create a style where plots are log in x by default. But that's probably a very niche use case, and it's probably not crazy to ask users to simply set log scale x on the specific subfigures where they want it. Should remove_x_ticks have "default"? Eh. Idk. Maybe? Could go either way. I think that for these, the best thing to do would probably be to put "default" unless there's a good reason not too. Is there a downside I'm not seeing here?

[mamar828]

I agree with your assessment that it would be better to use "default" for both inheritance and style management. Using types like Inherit and FromStyle would probably be way too complicated for the benefits they would provide, and I think they would be used only in very niche situations.

As for the parameter lists, their goal is to allow to modify parameters for individual subplots without having to create a SmartFigure for each. That means that currently the parameter lists are not applied on subplots where a SmartFigure was placed as an element, but by implementing the "default" properties, we could definitely apply the ListOrItem value to a subplot when the nested SmartFigure has this property as "default". So ListOrItem values could basically give the default of each nested SmartFigure, in the event that they don't specify their own value.

For the other parameters, I think we could use a "default" value anywhere unless we have a good reason not to. So I think that parameters such as remove_axes or remove_x_ticks would perfectly make sense to have "default", since some users may want to create a style for inserting images for example, in which they wouldn't want x or y ticks. But for other parameters you were mentioning like num_rows, x_lim and log_scale_x, they seem to be very situation-dependent, so probably no "default".

[Oddball777]

Yes, I agree. Awesome, things are starting to come together. Alright, here's a proposal (I think this covers everything we mentioned, if I forgot anything or you think something wouldn't work here, please point it out):

Automatic subfigure creation

• Children subfigures that aren't explicitly created by the user (e.g. parent.elements = [[curve1, curve2], [curve3, curve4]]) should be dynamically created internally.

Inherit

• Replace the "default" string with a new marker type called Inherit (is the name ok?). This is more clear (the word "default" doesn't sound like you can inherit from parent figures) and is much better than a string (typing will be more friendly than having Literal["default"] everywhere). No actual functionality has been added here, this is only for clarity and typing.
• Every parameter that can reasonably have an Inherit should have it.

Parameter lists

• gl.SmartFigure(2, 2, elements=elems, remove_x_ticks=[True, False, False, True]) means that the subfigures which still have remove_x_ticks = Inherit will have their values replaced by the corresponding default in the parent. Those which aren't Inherit won't be touched.
• Looking at it from the opposite direction, anytime a subfigure has Inherit for a parameter, it gets replaced by whatever that parameter is in the parent, and if the parent has a list of parameters instead of a single value, the child inherits whatever parameter in that list corresponds to its position when iterating over subfigures.

__getitem__
Parent figure: returns a child figure at the specified location according to the clicking rule.
Standalone figure: raises an Exception.

__setitem__
Parent figure: if RHS is a SmartFigure, set it as a subfigure at the specified location if it doesn't overlap anything. If RHS is a Plottable or a list of Plottables, select an existing subfigure using clicking rules and overwrite that subfigure's Plottables with those given.
Standalone figure: raise an Exception

.elements getter
Parent figure: return a list of subfigures (generated from the internal _elements dictionary)
Standalone figure: return a list of Plottables (generated from the internal _elements dictionary)

.elements setter
Parent figure: RHS must be a list of same length as number of cells or shorter (missing ones at the end are assumed to be None). Each element in list is either a Plottable, a list of Plottables, or a SmartFigure. Overwrites every subfigure with each list element, respectively. Internal _elements dict is regenerated from these new contents. Subfigures are automatically created if values passed aren't already SmartFigures.
Standalone figure: RHS must be either a Plottable or a list of Plottables. Overwrites the figure's contents. Internal _elements dict is regenerated from these new contents.

__add__ and __iadd__
Parent figure: RHS must be a list of same length as number of cells or shorter (missing ones at the end are assumed to be None). Each element in list is either a Plottable or a list of Plottables (notice difference with elements setter here: can't be a SmartFigure). Extends every subfigure with each list element, respectively.
Standalone figure: RHS must be either a Plottable or a list of Plottables. Extends the figure's contents.

__len__
Parent figure: returns number of immediate children subfigures
Standalone figure: returns number of Plottables

__iter__
Parent figure: returns iterator of immediate children subfigures
Standalone figure: returns iterator of Plottables

Examples of what's possible and what should raise exceptions:

standalone = SmartFigure()

x = standalone[0] # raises, use .elements[0] instead
standalone[0] = my_plottable # raises, can't overwrite a specific plottable. Either add it or overwrite elements entirely
plottable_list = standalone.elements
first_plottable = standalone.elements[0]
standalone.elements = my_plottable
standalone.elements = [my_plottable, my_plottable2, my_plottable3]
standalone_plus = standalone + my_plottable
standalone_plus = standalone + [my_plottable, my_plottable2, my_plottable3]
standalone_plus += my_plottable
standalone_plus += [my_plottable, my_plottable2, my_plottable3]
num_plottables = len(standalone)
plottable_iter = iter(standalone)


parent = SmartFigure(2,3)

subfig = parent[0, 0]
subfig = parent[4] # raises in this case because 2D, would work if 1D
parent[1, 2] = new_subfig
parent[0, 0] = my_plottable
parent[0, 1] = [my_plottable2, my_plottable3]
parent[0, 0] += my_plottable
parent[0, 1]  += [my_plottable2, my_plottable3]
x = parent[0,1][0] # raises, use .elements[0] instead
first_plottable_of_subfig = parent[0,1].elements[0] # etc. Since parent[i, j] returns a subfigure, all the things described for standalone will work here

subfigs = parent.elements
parent.elements = [
    my_plottable,                               # cell 0: subfigure overwritten with one plottable
    [my_plottable2, my_plottable3],             # cell 1: overwritten with two plottables
    None,                                       # cell 2: cleared
    new_subfig,                              # cell 3: replaced by new SmartFigure
    my_plottable4,                              # cell 4
] # cell 5 assumed None, cleared
parent_plus = parent + [
    my_plottable,                               # extend cell 0 with one plottable
    [my_plottable2, my_plottable3],             # extend cell 1 with two more plottables
    None,                                       # cell 2 unchanged
    my_plottable4,                              # extend cell 3
    new_subfig,                                  # Raises exception!
] # cell 5 unchanged, assumed None
parent_plus +=  [
    my_plottable,                               # extend cell 0 with one plottable
    [my_plottable2, my_plottable3],             # extend cell 1 with two more plottables
    None,                                       # cell 2 unchanged
    my_plottable4,                              # extend cell 3
    new_subfig,                                  # Raises exception!
] # cell 5 unchanged, assumed None
num_subfigs = len(parent)

subfigure_iter = iter(parent)

Potential downside: these won't work as user might expect, and won't raise an error either:

parent[0,1].elements[0] = my_plottable
parent[0,1].elements += [my_plottable]

Since .elements returns a list derived from the internal dictionary, modifying the list directly won't modify the internal dictionary. This is the only issue I've been able to find, if you find more please comment them.

[mamar828]

That sounds really good, I hope it's really feasible! I don't have any issues with what you mentioned at the moment.

It might be a while until I have time to implement this since I'm super busy with paper writing at the moment. So feel free to begin on your own if you wish! Otherwise I'll be happy to do it/help, but I can't promise anything timing-wise.