Add Named Attributes to Matrix Profile

[seanlaw]

Matrix profiles that are generated from functions like stump returns a 4 column output (or more for kNN) that represents the matrix profile, the nearest neighbor index, the left index, and the right index. However, this may seem unintuitive. Instead, it may make sense to subclass the numpy ndarray and add additional attributes (or properties) that can return the right column so that you can do something like:

mp = stumpy.stump(T, m)
print(mp.p, mp.idx, mp.left_idx, mp.right_idx)

or

motif_idx = np.argsort(mp.p)[0]

This code example or this one might help. So, we simply compute matrix profile, push it into our subclassed Class, and return it at the end of the function.

[seanlaw]

A little bit more experimentation shows that this works:

import stumpy
import numpy as np

class mparray(np.ndarray):

    def __new__(cls, input_array, m=None, k=1):        
        obj = np.asarray(input_array).view(cls)
        obj.m = m
        obj.k = k
        return obj

    def __array_finalize__(self, obj):
        if obj is None: return
        self.your_new_attr = getattr(obj, 'm', None)

    def _idx(self):
        return self[:, 1]

    @property
    def p(self):
        return self[:, 0]

    @property
    def idx(self):
        return self._idx()

Then we can do:

T = np.random.rand(1000)
m = 50
mp = stumpy.stump(T, m)

mp = mparray(mp, m=m)  # This will be done at the END of the, say, `stump` function

and be able to do things like:

mp.m
# 50

or

mp.idx
# mparray([197, 110, 369, 112, 620, 114, 403, 404, 405, 69, 407, 408, 409, ..., 628, 629, 151, 152], dtype=object)

Notice that the object class is now mparray rather than array but our object (instance) inherits ALL of the attributes/methods from a traditional numpy array and there would be minimal code change in our codebase while retaining backwards compatibility. I'm not sure if there are any side effects though...

Being able to do mp.p and mp.idx feels more natural/explicit and less clunky than typing mp[:, 0] or mp[:, 1] and then we can handle the kNN case immediately since we have all of the information at run time.

Of course, we should update all of our docstrings/docs/tutorials to use these new properties

[andersooi]

Hello! I just chanced upon the repository and saw this issue and am interested in contributing. However, I see that a pull request has already been opened. Safe to say the issue is more or less resolved?

[seanlaw]

@andersooi Thank you for your interest in helping us!

Safe to say the issue is more or less resolved?

Yes, I think it is mostly completed now as I had some time to tinker with it yesterday (what's left are unit tests). However, we welcome you to check out our other open issues and your help is greatly appreciated!

[seanlaw]

Thanks @NimaSarajpoor and congratulations on your first merge in this repo! 🎉