GeezerVison is showing github.com — API things, names, consistency, etc. · Issue #68 · fastplotlib/fastplotlib
API things, names, consistency, etc. #68Descriptioncurrently the simple Plot API attaches methods like plot.image, plot.line etc which adds a graphic to the plot. This is kinda matplotlib inspired but could quickly get polluted (i.e. matlab inspired) . What if we prefix these methods with "add", so it becomes plot.add_image, plot.add_line etc. Because then I could also add add this behavior to the GridPlot API to remove the add_graphic step which is just boilerplate, while keeping the api clean. All add_ methods must add something to the plot or Subplot.
@EricThomson thoughts? ActivityEricThomson commented on Dec 14, 2022 I definitely think it's a good idea to stick with one api either way. One of the most annoying things about matplotlib is the plt.title() vs ax.set_title() for pyplot vs object-oriented api (I realize not quite the same, but you know what I mean: it is basically an unnecessary barrier to entry).
Not sure about which is the right move: I tend to want to type fewer words and stick with what people will tend to naturally just try, so like things like .scatter() over .add_scatter(), but honestly both would be good as long as consistent. kushalkolar commented on Dec 15, 2022 yes consistency between the Plot API and GridPlot API would be nice and reduce boilerplate for using the GridPlot which could be a barrier to entry.
For example now we have:
from fastplotlib.layouts import GridPlot
from fastplotlib.graphics import ImageGraphic, LineGraphic
gp = GridPlot((2, 3))
img_graphic = ImageGraphic(data=....)
gp[0, 0].add_graphic(img_graphic)
line = LineGraphic(data=....)
gp[0, 0].add_Graphic(line) This could be reduced to:
from fastplotlib.layouts import GridPlot
gp = GridPlot((2, 3))
gp[0, 0].add_image(data=...)
gp[0, 0].add_line(data=...) People can worry less about using Graphics objects directly unless they're doing something more complex.
A Subplot in a GridPlot is almost the same as Plot. Plot is actually just a subclass of Subplot with a show() method so it can be shown by itself, and the graphic methods attached to it. https://github.com/kushalkolar/fastplotlib/blob/master/fastplotlib/plot.py#L10 EricThomson commented on Dec 15, 2022 Yes, that would be nice, I recently did the two-line approach when drawing contours on an image, and it seemed like too much. I was wondering why not gp[n,m].line()? Why is there the intermediate step of creating the line object and then adding it? kushalkolar commented on Dec 15, 2022
Why is there the intermediate step of creating the line object and then adding it?
No reason really. Before I make this change we will just have to make sure it doesn't introduce annoying namespace pollution. For example we soon want to add Selector objects #59 , I can imagine the API for that being something like gp[m, n].add_selector_linear, add_selector_rectangle etc. I think it shouldn't get out of hand, I'm very much in favor of making this change. kushalkolar commented on Dec 15, 2022 I think this is what I'm going to do:
Subplot gets all the add_<graphic>, add_selector_<type> methods attached to it, this allows them to be used without boilerplate in Plot and GridPlot.
All other types of PlotArea, such as docked-subplots (see this: #30 (comment)), do not get these methods appended to them and must use the full API to add things to them for more complex plots. kushalkolar commented on Dec 17, 2022 so it's simplified now, leaving this open until we make the selectors kushalkolar commented on Dec 17, 2022 For z position, I think it'd useful to set the z position automatically if not provided so that whenever a new graphic is added it is by default above all existing graphics. EricThomson commented on Dec 20, 2022 Note I've been working with this new api for a little bit now and really like it. I like not having to do this:
Simply running add_line() is more intuitive and Pythonic in the long-run I think. changed the title [-]simple Plot API[/-] [+]API things, names, consistency, etc. [/+] on Dec 30, 2022kushalkolar commented on Dec 30, 2022 The way that graphics are stored across objects in fastplotlib is inconsistent. For example in subplots/plots we have:
but in graphic collections we have:
Maybe we should make it consistent, anywhere that an iterable of graphics is "stored" we just use a graphics read-only property? that would result in:
plot.graphics # gives tuples of graphics in the plot/subplot
line_collection.graphics # also gives tuple of graphics in the collection EricThomson commented on Jan 8, 2023 I like the idea of making it consistent. I personally like things like .get_graphics()
but consistency either way is good I think (I know in Python naming getters and setters as such is often frowned upon :) ). kushalkolar commented on Apr 18, 2023 Now that fully fledged selectors are coming in I think we've come to a good system. Selectors are added onto a graphic using graphic.add_<selector_name>. If users want to add more general selectors without a "parent" Graphic and get full control they can do that too by instantiating a Selector themselves and adding it to a PlotArea kushalkolar commented on Jun 22, 2023 We've been using this API for ~6 months now so I think we're pretty comfortable with it now. Whenever we have a hierarchy of objects, we just use Parent.add_<child_name>(). parent can be a PlotArea or Graphic, and children can be a Graphic or Selector
I think we can discuss further API naming, consistencies etc. in future issues.
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|