Add specification for data schemas and/or AOEF format to reference in docs?

[NickleDave]

Hi @mbsantiago, good talking with you today.

As we discussed, I was thinking it might be helpful to add a more formal description of the soundevent schema to the docs, and maybe a schema for the Acoustic Objects Exchange format you mention here

The descriptions you have in the data schemas section and the user guide are very well written, intuitive, and helpful for understanding the package.

But adding a more formal description of the schema would be good as well, to:

• help understand the mapping/hierarchy from pydantic classes to schema (e.g., not clear to me right now if Dataset is the top-level object that I should interact with "first"?)
• open up a broader conversation in the bioacoustics community about what kind of schemas + standards we need so that file formats are more portable and tools are interoperable

If it were me I would put this more formal description in the "Reference" section of the docs, following the Diataxis framework (and maybe move the API docs to their own separate section "API" or a sub-section within "reference")?

Hope that feedback is helpful and that we can keep talking!

[geoffreyliddell]

I'm just dropping a comment here that this repository looks very useful to me, but that the documentation is abstract enough that I think it would have been difficult for me to realise how useful it was (alongside Crowsetta, which I wish I had seen earlier) until it was too late for it to make my life easier!

I've been writing quite similar code, although much less well-structured https://git.soton.ac.uk/gcl1r25/spAEkit. I just wanted to be able to iterate through audio recordings for event detection and annotation and have converged on a similar sort of data structure. I had:

• A recording dict, which holds the recording id file paths, channels and other recording metadata, e.g.

recording_dict_example = {
    'file_id': str,
    'samplerate': int,
    'datetime': datetime,
    'channels': list[int],
    'file_paths': list[str]
}

• A dataset dict, containing recording ids taken from the file name as the keys, and the recording dicts as the values. I was not sensible enough to add whole-dataset level metadata...

dataset_example = {
    'file_id1': recording_dict1,
   'file_id2': recording_dict2,
   ...
}

• an 'events' dict, with structure which I can attach to a recording to save a detection result.

event_dict_example = {
    'start': [start1, start2, ...],
    'end': [end1, end2, ...],
    'property1': [p11, p12, ...], 'propert2': [p21, p22, ...], 
    ...
}

will update with thoughts on the soundevent documentation when I have had a chance to actually write some code with it!