documentation: unknown behavior for week parameter greater than 48 and unknown valid parameters in python api

[yblacky]

Title: Unknown behavior for week parameter greater than 48 and valid parameters when directly used analyze() via python

Description:

The CLI documentation for birdnet_analyzer.analyze is solid, but when calling analyze() directly as a Python function there is no equivalent documentation.

Example:
the CLI docs state that --week accepts values from 1 to 48 (4 weeks per month).
There is no equivalent note for direct called analyze() via python. External integrations that get the week from a standard ISO calendar (week 1 to 52/53) will pass values above 48. Its unclear for me what happens in that case.
Is the value getting ignored, extrapolated or used by the geo model as the maximum (48)?. I didnt get an error or a warning if i use a week parameter greater than 48.

Questions:

• What is the actual behavior when week is greater than 48, if called via analyze()?
• Should out-of-range values raise an error?

Excpected:
Any of that (or all of them) would resolve that:

• A AnalyzeConfig dataclass or TypedDict for constructing valid calls
• Good documentation of direct usage of analyzing functions and their valid parameters
• Validation inside analyze() for out-of-range values

Context:
I'm building a local web UI on top of a local installation of BirdNET-Analyzer wrapped in a FastAPI. The week range is the most concrete example, but in general the lack of a python api affects any programmatic integration.

[MacJudge]

My comment is not meant as an answer, but merely illustrates my approach.

I had a similar question regarding the behavior of the week parameter some time ago and I just tried it out. I've been using directly the geo model, so I was able to see the model output without additional abstraction layers. I just tested the model with week inputs in a range from -10 to 60 and compared all the output vectors just by printing them to the console.

The results answered my question as the model had unique output vectors for weeks in a range from 1 to 48. All other week inputs yielded the same output vector, which is meant to be used for the whole year instead of a special week.

As my input is a Unix timestamp, which has to be mapped to weeks in a range from 1 to 48, I came up with the following formula:

week = int(float(time.strftime('%j', time.gmtime(timestamp))) / 7.63) + 1

This derives the day of the year from the Unix timestamp and divides it by 7.63, as 366 / 48 = 7.625, so I get a value in a range from 0 to 47 and simply add 1 at the end.

[MacJudge]

After having written all these things, I just tried it out again and discovered, that the week parameter may be a floating point number. Valid week values have to be bigger than 0.0 and smaller than 49.0, so I can just calculate them like

week = ((timestamp % 31557600) + 1) / 644033

as a year has 31,557,600 seconds in average and 31,557,601 / 49 is a bit less than 644,033 and I add 1 second to avoid getting exactly 0.

Of course, this may not be as intended and I have to check, whether this output vectors from below 1 and above 48 are still valid, but they don’t look strange and at the end it shouldn’t make a big difference.

There is also a new geo model available, which hasn’t yet been implemented in the BirdNET Analyzer, and I have to check, how the valid input range looks like. I already know, that the new geo model doesn’t have the overall year probabilities implemented, so you would have to calculate it by your own from multiple week inputs.

[yblacky]

Thank you, this is very helpful!

So...:

• any week value outside the range of 0 to 49 silently falls back to the annual output vector and no warning is raised.
• The fact that week also accepts float values isn't documented anywhere.

The core issue remains: none of this behavior is documented in the analyze() docstring or anywhere in the docs.
A developer integrating the analyzer programmatically has no way to know the valid range without either reading this thread or reverse-engineering the geo model like you did.

The note about the new geo model is quite interesting. If it removes the unfiltered output vector entirely, the current -1 will break silently for any programmatic integration. That seems worth addressing in the docs before the new model is published or integrated into the analyzer.

[MacJudge]

I did some more tests and got some new insights into the two models.

The currently implemented geo model "BirdNET_GLOBAL_6K_V2.4_MData_Model_V2" accepts floating point values in range (0.0 .. 49.0), but the values in range (0.0 .. 1.0) equal the values in range (48.0 .. 49.0). So we shouldn't use both parts and I decided to use just the lower part and limited my week values to (0.0 .. 48.0] by changing my week calculation to

week = ((timestamp % 31557600) + 1) / 657450

as 31,557,600 / 48 = 657,450.

I also tested the new geo model "BirdNET+_Geomodel_V3.0.1_Global_12K", which accepts floating point values, too.
As already stated, there is no overall year probability, so we have to calculate it on our own, in case we need it. I did some tests with the old model "BirdNET_GLOBAL_6K_V2.4_MData_Model_V2" and compared the minimum, average and maximum values of individual values of all full weeks and found that the maximum is closest to the overall year probability provided by the model in about 93 percent in my test case. So taking the maximum of weekly probabilities might also be a good idea for the new geo model.
As there is no limit to the provided week values in the new geo model, we could provide anything and won't find out, that we do something wrong. So -5.0, 43.0 and 91.0 are all valid week values and they all mean the same thing, as the model just maps everything to range of (0.0 .. 48.0] or [0.0 .. 48.0) as 0.0 == 48.0, which is fine for me, as I can just use the same formula I created for the old geo model.

BUT, and I have to stress this, this is just the usage of the raw geo models. I used TFLite for the V2.4 geo model and ONNX for the V3.0 geo model (as the new TFLite model contains operations which are unsupported by my AI-Edge-LiteRT interpreter). In case there is anything built around these raw models, things may change considerable. For example, one could easily create an API, which just accepts integer values in range [1 .. 48] (like I did, before I discovered that floating point values are possible).

So you are right, without a good documentation we can't know, how to use a certain API. The only thing we can do for now, is to read the code and try to understand how to use it.