API for using Otava as a library

[radove]

I recently utilized Otava by calling the functions directly instead of using an importer. This is useful if you have data received by Python in some custom way and want to programmically utilize Otava on the data. There isn't a lot of documentation on this so it was sort of like looking at unit tests and guessing at it. I figured it out, but I am not sure if I am doing it entirely correctly. It would be useful if this was documented officially as an option, unless for some reason you rather people be limited to using an existing importer?

Here is my potentially bad attempt at an example of this

from otava.analysis import compute_change_points, ChangePoint

def _compute_change_points(p, m=0.0, w=30, series=[], new_data=None):
    return compute_change_points(series, window_len=w, max_pvalue=p, min_magnitude=m, new_data=new_data)

#Bring in your data from another source, and set y_list to the data...
y_list = []

#Tweak the parameters to appropriate max_pvalue and min_magnitude options, as these may differ depending on dataset and sensitivity desired


math_results,old_math_results = _compute_change_points(0.005, m=0.003, w=100, series=y_list, new_data=None)
index_list = []

c: ChangePoint
for c in math_results:
    index_list.append(c.index)

for index, y in enumerate(y_list):
    if index in index_list:
        print("This Y should be marked!")

[henrikingo]

Hi @radove

That's a good observation and in fact I also use otava as an imported python module, I never used the CLI myself.

Nyrkiö is a bit behind on versions and in fact I've been waiting to get to the post 0.7.x world which is today! So with that caveat, let me link to how I've used Otava the past 2 years:
https://github.com/nyrkio/nyrkio/blob/ecc4b6f5f8c6369f900fafbbfc5533220888eefc/backend/core/core.py#L12-L18
https://github.com/nyrkio/nyrkio/blob/ecc4b6f5f8c6369f900fafbbfc5533220888eefc/backend/api/changes.py#L4

Notably:

• In the Nyrkiö code, Otava (née Hunter) is not connected to any database, I feed it Series() objects from the outside.
• For incremental otava, I also store and return the (weak) change points.

Wishlist:

• Currently the input data is well defined, we have our own PerformanceTestResultSeries that generates the Otava Series() class. But AnalyzedSeries() is more hacky and in the end we descned into just holding the change points in a large dict.
• Would like to better define a structure/schema for the input and output data. It's timeseries data with SI units, everyone ends up doing roughly the same thing.
• Adopting Pydantic on Nyrkio side is a step in that direction.
• Probably should merge the Slack/Github/Email reporting between Nyrkio and Otava.

We could define a proper API in the init.py file, or some other similar mechanism

(Sorry for expanding your ticket, but wanted to share relevant context. Most of what I write here should be new tickets of their own.))

[Gerrrr]

Hey @radove!

It is nice to discover new usage patterns via issues like this! Please beware that, as Otava does not expose a public API yet, it may (i.e., likely will) break in the future minor/patch releases.

I love the idea of adding a public programmatic API and would approach this in a way, similar to what @henrikingo wrote in the wish list - first define public API (probably via init.py), then officially document it.

[radove]

I'm not the best programmer in the world, but if you need help I could take a stab at the public API to get something started on this subject. I recently implemented Otava as an experiment to detect change at the energy company I work for. The squares in this screenshot represent the change point detections.

We have our own data feed coming from MySQL currently, but the data is manipulated quite a bit. After that, we put it into Apache Otava Series like this:

                    time = list(range(len(y_list)))
                    data_series = Series(
                        "data",
                        branch=None,
                        time=time,
                        metrics={"series1": Metric(1, 1.0)},
                        data={"series1": y_list},
                        attributes={},
                    )
                    
                    # Our Default Options
                    options = AnalysisOptions()
                    options.window_len = 125
                    options.max_pvalue = 0.005
                    options.min_magnitude = 0.10
                    options.orig_edivisive = False

                    change_point_groups = data_series.analyze(options).change_points_by_time

[henrikingo]

Hey thanks for sharing! I always had various ideas about using e-divisive/otava beyond just performance testing. This is very exciting to see. Thanks!

I suggest you should start by suggesting an API that would work for you. Don't limit yourself to anything that otava is today, just think of it as a clean slate and start from your own needs. (If you are following the other pull requests, where we're for example replacing Series and AnalyzedSeries with pydantic classes - #93 - you'll see that we're here to do a proper refresh and modernization.

Whether you are the best programmer in the world or not is not important. I am also not, but we will review your submission thoroughly. (And add my and hopefully others input as well.)

That said, I disagree with @Gerrrr on the point of documentation: If you prefer to just write in english what you hope a future API would do, that's also welcome. (I call it documentation driven development :- ) But bear in mind that API docs can often be generated from code, so in the end not much might survive from your original writeup.