Dictionary interface for quick access to annotations

[bmcfee]

I was chatting with Peter today about some of the more annoying aspects of using jams for simple tasks. For example, to get a single onsets annotation out of the jams object, one has to do something like the following:

>>> anns = jam.search(namespace='onsets')
>>> onset = anns[0]
...

which is rather cumbersome.

I think we can shortcut this a little by providing a read-only dictionary interface to the jams object:

>>> onset = jam['onset'][0]

where the JAMS object under the hood just short-circuits the search for us:

def __getitem__(self, query):
    return self.search(namespace=query)

Would this level of syntactic sugar be helpful?

[justinsalamon]

Yes

[ejhumphrey]

wholly agree!

I'd challenge us to take it one step further. I find it really unnerving that annotations are order sensitive. If I interact with a jam the right way (intentionally or otherwise), I can end up with annotations taking on new index values (e.g. shuffling, slicing, etc).

What if we adopted the pandas conventions of .loc and .iloc (or different names, I don't feel strongly), so that you can specify an index for annotations in the whole of a jam (I realize this might involve a schema change, but hang with me for a second). For example:

>>> ann1 = jams.Annotation('beat', data=[dict(time=0.2)])
>>> ann2 = jams.Annotation('onset', data=[dict(time=2.5)])
>>> jam = JAMS([ann1], index=['foo'])
>>> jam.append(ann2, index='bar')
>>> jam.loc['foo'].data
             time  duration  value  confidence
0 00:00:00.200000       NaT    NaN         NaN

>>> jam.iloc['onsets', 0].data
             time  duration  value  confidence
0 00:00:02.500000       NaT    NaN         NaN

not a fully formed idea, but curious to field thoughts.

[bmcfee]

I find it really unnerving that annotations are order sensitive.

Agreed. I blame javascript for not having a set primitive data structure.

The obvious way around this is to provide each annotation with a key / index, like you describe. This could be done by replacing AnnotationArray with an AnnotationDict (and the corresponding schema change). The downside to this is the index would be part of the annotation dict object, and not the annotation itself; this means it will be harder to separate annotations from jams as described in #92 .

If we put index into the Annotation object, then we will need an accessor to get at it. This could be pretty easily done by extending the __getitem__ interface to take a tuple, where the second element is an index. This would expand to the query:

def __getitem__(self, query):
    kwargs = {}
    if isinstance(query, tuple):
        kwargs['namespace'], kwargs['Annotation.index'] = query
    elif isinstance(query, six.string_types):
        kwargs['namespace'] = query
    else: raise KeyError('Invalid query: {}'.format(query))

    return self.search(**kwargs)

Of course, the tricky thing here is knowing when to return a list vs when to return a single object. If we don't enforce uniqueness among Annotations -- which will be difficult if they're self-identified -- then the best we can do is always return a list. I'd really like to avoid having multiple return types for the same syntax.

Anyone else have thoughts about how this should look?

PS: I took a hack at this last night, and realized that clobbering __getitem__ in the JAMS object might break serialization. All the tests seemed to pass when I tried it, so maybe it's okay, but thoughts from @ejhumphrey on this would be welcome.

[ejhumphrey]

I've still got my eye on the future when Annotations live in the cloud and JAMS are response containers. I think GUIDs are inevitable, but happy to run with the key / index language for now.

I'd really like to avoid having multiple return types for the same syntax.

Perhaps this is where pandas has done some of the hard design work ... imagine the following analogy where JAMS -> DataFrame (table) as Annotation -> Series (row). Depending on how you talk to a DF, you'll get back either a series or another DF. Anything that slice-like (search) could return another dataframe (JAMS container), and anything that's index-based would return a series (annotation).

Again, I realize whole-heartedly I might be speaking to the next major version of the API (the schema wouldn't have to change much). But, Serieseses are nameed (indexed), so it seems like that data would go in the Annotation (annotation array is left alone).

[ejhumphrey]

oh, also ... I don't know that I like having search under the hood of an item / attribute accessor, but I don't have any constructive thoughts on that topic. Don't want my silence to pass for approval just yet. :o)

[bmcfee]

I think GUIDs are inevitable, but happy to run with the key / index language for now.

Yeah, agreed.

Depending on how you talk to a DF, you'll get back either a series or another DF.

And this is one of the things I've always hated about pandas, but I guess it's somewhat inevitable with heterogeneous data structures (DF vs Series).

Anything that slice-like (search) could return another dataframe (JAMS container), and anything that's index-based would return a series (annotation).

Yup. Consolidating the proposals above, my first version would look like:

>>> ann = jam['beat'][0]

and a tuple-index would look like

>>> ann = jam['beat', 0]

which is a little cleaner. I see no harm in supporting both: the semantics of tuple-based indexing are such that the two should be equivalent anyway.

In the future, the 0 index could be replaced with a key to the same effect -- if multiple annotations match, I think it would be reasonable to throw an exception. What do you think about adding the key-based indexer to the AnnotationArray object? That way, the jams object can be agnostic as to the second index, and everything should work smoothly.

I don't know that I like having search under the hood of an item / attribute accessor,

I tend to agree, but I think it's probably the best option. It prevents us from having to maintain another index structure, and implies consistency between search and [] behavior. At the end of the day, these structures are small anyway, so it's not going to be a serious overhead hit.

[bmcfee]

Circling back to this:

JObject defines a __getitem__ interface (but no setitem or getslice etc) which simply wraps the op inside a call to self.__dict__. Do we ever actually use this interface?

Similarly, JObject.keys() returns self.__dict__.keys(); this would mess up the proposed dictionary interface, since these keys are not valid indices into the annotation array.

TLDR: I don't think we can implement this as described above without breaking backwards compatibility.

HOWEVER

If we implement it at the level of AnnotationArray, then everything can be made to work, with a slightly more explicit syntax:

# Returns an AnnotationArray
all_beat_anns = jam.annotations['beat']

# Returns the first beat or an index error
one_beat_ann = jam.annotations['beat', 0] 

# Returns an AnnotationArray of up to 3 beat annotations
slice_beat_ann = jam.annotations['beat', :3] 

# Get the first annotation, as per current spec
some_ann = jam.annotations[0] 

This works because AnnotationArray is not a JObject.

@ejhumphrey what you say?

[ejhumphrey]

I love it when a plan comes together :bites-cigar-with-satisfaction:
On Jul 9, 2016 16:35, "Brian McFee" notifications@github.com wrote:

Circling back to this:

JObject defines a getitem interface (but no setitem or getslice etc)
which simply wraps the op inside a call to self.dict. Do we ever
actually use this interface?

Similarly, JObject.keys() returns self.dict.keys(); this would mess
up the proposed dictionary interface, since these keys are not valid
indices into the annotation array.

TLDR: I don't think we can implement this as described above without
breaking backwards compatibility.

HOWEVER

If we implement it at the level of AnnotationArray, then everything can be
made to work, with a slightly more explicit syntax:

Returns an AnnotationArray

all_beat_anns = jam.annotations['beat']

Returns the first beat or an index error

one_beat_ann = jam.annotations['beat', 0]

Returns an AnnotationArray of up to 3 beat annotations

slice_beat_ann = jam.annotations['beat', :3]

Get the first annotation, as per current spec

some_ann = jam.annotations[0]

This works because AnnotationArray is not a JObject.

@ejhumphrey https://github.com/ejhumphrey what you say?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#112 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/AA4iq2UH9cfifZZB3cxngk0yhAdenO_Dks5qUAYjgaJpZM4IYgfY
.

[bmcfee]

This was fixed in #120