API: should ``Layer()`` not derive from ``BaseObject``?

[jakevdp]

Since Layer is the main interface, it would be nice if tab completion on the object only listed relevant pieces of the API so that you can quickly find what plot types are available (e.g. point(), bar(), text(), etc.)

Currently, since it derives from BaseObject the namespace is polluted with all sorts of traitlet stuff that the user probably doesn't care about.

I'd propose something like this:

class LayerObject(BaseObject):
    # traitlet-related stuff goes here
    def __init__(self, *args, **kwargs):
        super(LayerObject, self).__init__(**kwargs)

    # etc.

class Layer(object):
    # non-traitlet-related Layer methods here
    def __init__(self, *args, **kwargs):
        if len(args)==1:
            self.data = args[0]
        self._layerobject = LayerObject(**kwargs)

    def point(self):
        self.mark = 'point'
        return self

    # etc.

The only problem would be if we ever want to pass Layer to some other class this would complicate things. What do you think?

[ellisonbg]

What about defining a dir

Method?

Sent from my iPhone

On May 18, 2016, at 10:08 PM, Jake Vanderplas notifications@github.com wrote:

Since Layer is the main interface, it would be nice if tab completion on the object only listed relevant pieces of the API so that you can quickly find what plot types are available (e.g. point(), bar(), text(), etc.)

Currently, since it derives from BaseObject the namespace is polluted with all sorts of traitlet stuff that the user probably doesn't care about.

I'd propose something like this:

class LayerObject(BaseObject):
# traitlet-related stuff goes here
def init(self, _args, *_kwargs):
super(LayerObject, self).init(**kwargs)

# etc.

class Layer(object):
# non-traitlet-related Layer methods here
def init(self, _args, *_kwargs):
if len(args)==1:
self.data = args[0]
self._layerobject = LayerObject(**kwargs)

def point(self):
    self.mark = 'point'
    return self

# etc.

The only problem would be if we ever want to pass Layer to some other class this would complicate things. What do you think?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub

[jakevdp]

Ah – that's a good idea! I'll try that.

[ellisonbg]

Traitlets even offers a method for getting a list of all the traitlets attributes - we could combine that with a list of the public methods

Sent from my iPhone

On May 19, 2016, at 9:22 AM, Jake Vanderplas notifications@github.com wrote:

Ah – that's a good idea! I'll try that.

—
You are receiving this because you commented.
Reply to this email directly or view it on GitHub

[jakevdp]

Another option: what if we change point(), bar(), etc. to draw_point(), draw_bar(), etc. Then users could tab-complete draw_<TAB> to see all the mark methods available.

[ellisonbg]

Or maybe mark_* to be consistent with the VL naming of things ?

Sent from my iPhone

On May 19, 2016, at 9:30 AM, Jake Vanderplas notifications@github.com wrote:

Another option: what if we change point(), bar(), etc. to draw_point(), draw_circle(), draw_bar(), etc. Then users could tab-complete draw to see all the mark methods available.

—
You are receiving this because you commented.
Reply to this email directly or view it on GitHub

[kanitw]

I have alternative syntax to propose here. I'm not married to this idea yet, but think it's worth considering.

Currently Altair rely on method chaining to describe mark.

.encode(x=X('Horsepower'), y=Y('Miles_per_Gallon')).point()

What if we make mark first parameter of .encode()?

.encode('point', X('Horsepower'), Y('Miles_per_Gallon'))
// or 
.encode(point(), x=X('Horsepower'), y=Y('Miles_per_Gallon'))

Especially if we call the top-level object a View

View(data).encode('point', X('Horsepower'), Y('Miles_per_Gallon'))

I feel like this seems more natural, in a sense that we encode points by mapping Horsepower to X and Miles per Gallon to Y. (Not sure how much work would this introduce though.)

[ellisonbg]

One of the core abstractions in altair is that everything is a strongly
typed attribute and that we only add extra methods that provide a
convenience layer on top one attribute at a time.

Thus, the Layer.encoding attribute has a encode method. The
Layer.config has a configure method. Putting the mark type into the
encoding confuses that model and also forces us to do more complex parsing
or positional args.

Lastly, tab completion of the API is pretty important as in the notebook it
is one of the main ways that users discover APIs. Thus, we are looking at
renaming the current mark methods to things like mark_line and
mark_point to allow users to type l.mark_<tab> to see all of the mark
types. Putting the mark as a positional inside the encode method makes
that entire part of the API much less discoverable.

On Thu, May 19, 2016 at 5:32 PM, Kanit Wongsuphasawat <
notifications@github.com> wrote:

I have alternative syntax to propose here. I'm not married to this idea
yet, but think it's worth considering.

Currently Altair rely on method chaining to describe mark.

.encode(x=X('Horsepower'), y=Y('Miles_per_Gallon')).point()

What if we make mark first parameter of .encode()?

.encode('point', X('Horsepower'), Y('Miles_per_Gallon'))
// or
.encode(point(), x=X('Horsepower'), y=Y('Miles_per_Gallon'))

Especially if we call the top-level object a View

View(data).encode('point', X('Horsepower'), Y('Miles_per_Gallon'))

I feel like this seems more natural, in a sense that we encode points by
mapping Horsepower to X and Miles per Gallon to Y. (Not sure how much
work would this introduce though.)

—
You are receiving this because you commented.
Reply to this email directly or view it on GitHub
https://github.com/ellisonbg/altair/issues/93#issuecomment-220488589

Brian E. Granger
Associate Professor of Physics and Data Science
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

[jakevdp]

I make the mark_point change in ellisonbg@8a593b5

[jakevdp]

On the tab-completion question – is there a way to make the traitlets keyword arguments show up in tab completion? That would be extremely helpful!

[kanitw]

Lastly, tab completion of the API is pretty important as in the notebook it
is one of the main ways that users discover APIs. Thus, we are looking at
renaming the current mark methods to things like mark_line and
mark_point to allow users to type l.mark_<tab> to see all of the mark types.

I like the tab idea. So please ignore my comment above. :)

That said, I wonder why you have to put mark after encode in the examples?

For example,
View/Layer(data).encode(x=X('Horsepower'), y=Y('Miles_per_Gallon')).mark_point()

Why not:
View/Layer(data).mark_point().encode(x=X('Horsepower'), y=Y('Miles_per_Gallon'))

I think the latter is more consistent with how we write specs in Vega-Lite.

[jakevdp]

To be clear, either order works currently.

[kanitw]

To be clear, either order works currently.

Yep. I mean, unless you have strong preference, can we put mark_point() before encode() in the all the example so we can establish convention? (For the same reason, in all VL examples, we put mark before encoding although order does not really matter in JSON. :) )

[ellisonbg]

I don't feel too strongly about the ordering but like the idea of being consistent with the vegalite examples. So +1 to marking first

Sent from my iPhone

On May 20, 2016, at 9:44 AM, Kanit Wongsuphasawat notifications@github.com wrote:

To be clear, either order works currently.

Yep. I mean, unless you have strong preference, can we put mark_point() before encode() in the all the example so we can establish convention? (For the same reason, in all VL examples, we put mark before encoding although order does not really matter in JSON. :) )

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub

[jakevdp]

Somewhat related: how would you feel about the mark_*() methods take optional arguments that pass to MarkConfig?

For example, here's the current API for creating a red scatterplot:

Layer(data, config=Config(mark=MarkConfig(color='red'))).mark_circle(
).encode(
          x='Horsepower',
          y='Miles_per_Gallon',
)

Here's how we might do the same thing with mark keywords:

Layer(data).mark_circle(
         color='red'
).encode(
          x='Horsepower',
          y='Miles_per_Gallon',
)