vocalpy / crowsetta Goto Github PK

Inspiration, from Kyles and Kylers:
https://github.com/kylebgorman/textgrid
https://github.com/kylerbrown/textgrid

should link to overall vocalpy/contributing.md

so that user can avoid writing their own format2csv function

The argument will be a function such as notmat2seq, and if not None then seq2csv will take the seq argument and run it through this format2seq_func like so:

def seq2csv(seq, ..., format2seq_func=None):
     if format2seq_func is not None:
        seq = format2seq_func(seq)

because a user can have .not.mat files but not have .rec files, e.g. song was acquired with software that is not evTAF but they still used evsonganaly to annotate

so if user has a csv with header different from segment fields, can just provide mapping (i.e. a dict) that specifies which header fields (csv columns) correspond to Segment attributes

so with this header
Onsets, Offsets, Filename, SegmentLabel
you'd use

header_segment_map = {
    'Onsets': 'onsets_s',
    'Offsets': 'offsets_s',
    'Filename': 'file',
    'SegmentLabel': 'label'
    }
crowsetta.csv.csv2seq(csv_filename='my.csv', header_segment_map=header_segment_map)

• because 'path' is more specific + accurate than 'file'
• for consistency with vak

mainly as easier way to get stuff out of SAP?
Would be a convenience wrapper around csv2seq that knows to use Excel dialect and look for SAP field names

that can have a Stack attribute or a Sequence attribute

mainly because it feels weird and counterintuitive to write

annot : crowsetta.Sequence

in docstrings. No-one will get why an annotation is a Sequence.

should have a mandatory annot_file attribute
and optional audio_file' and spect_file` attributes

Seems like __repr__ should be something like

Sequence(segments=15)

and then a pretty_print method would give something like

Sequence with 15 segments:
    Segment 1: label='a', onset_Hz=16000, offset_Hz=17500, onset_s=None, offset_s=None, file='0.wav'
    Segment 2: label='b', onset_Hz=18000, offset_Hz=19500, onset_s=None, offset_s=None, file='0.wav'
   ...

because it's not really an "annotation"

it's the high-level abstract object that lets us associate an annotation file with the sequence of annotated segments within that file, and the file that the annotation annotates, e.g. an audio file

so it should be something like:
Vocalization, with attributes 'sequence', 'annot_pathand (optionally)source_path`

Praat allows for multiple user-defined tiers per segment, e.g. "phoneme", "syllable", "word", "sentence".

http://www.fon.hum.uva.nl/praat/manual/Intro_7__Annotation.html

Not sure if that would be easy to add for Crowsetta.
I was thinking it would require the ability to dynamically add attributes to the Segment class, but I guess there could be an optional tiers attribute that's a dict mapping an annotation to each tier for any instance of a Segment.
But even then seq2csv would have to be able to handle mapping these extra tiers. I guess that's not too painful though if we're iterating over Segments anyway. Just would have to make sure all Segments have the same tiers.

and converting e.g. from Textgrid to Audacity, then using TIMIT

Later talk about code stuff. Like, buried deep in the docs later

override __repr__ to say Sequence with x segments: Segment(info), Segment(info), ...
(actually showing ellipsis in __repr__)
and then change repr of segment list, maybe using UserList from collections?

• "crowsetta stone" image?
  • in doc/index.rst & README.md
• maybe also image showing GUI with labeling | Filenames | Sequence objects | csv output

programatically instantiated attrs class where each attribute is a Sequence.
A Stack is made up of 2 or more Sequences

Make should remove the raw cells with .rst directives that are just used in the .doc files

Is there some way to get more control flow with nbconvert, i.e. "use these cells for the notebook --> notebook conversion and use these other cells for the notebook --> rst"?

causing vak to crash because the default is written relative to the current working directory, ./Wave

This only works if user is in the right place

Instead default should be written relative to the Annotation.xml path, which will always be in the parent directory of the Wave directory, unless someone was actually using the same format somewhere outside this dataset. In which case they could specify the correct location with the non-default Wave argument

with utility functions for labels and annotations
for labels just steal from vak
annotations utilities would be e.g. duration of all annotations

pros: on PyPI, citable
(possible) cons: Python 3? Maintained? Some issues -- does it work with as many diff't versions?
https://github.com/hbuschme/TextGridTools
https://pub.uni-bielefeld.de/download/2561620/2563287

Need to have to_csv insert something (NaN or None?) when value of Segment field is None for on/offsets_s/Hz

see https://github.com/kylerbrown/bark

with poetry or setup.py

• first-order, add _static/spectrogram for use with tutorial.rst + tutorial.ipynb
• and/or add librosa as docs dependency, create spects when building docs
• later, use vocalpy for this

in spirit of DRY, instead of having a separate dict in the data module,
the top-level docstring for each format's module should have this metadata,
and there should be a formats module that knows how to parse this

Better if this could be linked with the internal config.ini somehow.

Maybe a Makefile that generates the config.ini?

Or ... each formats module has its own config_dict at the top, and then that gets used through an entry point maybe?

e.g. in README with info on how to contribute:
https://github.com/NickleDave/vocal-annotation-formats

to not get

TypeError: ("'annot_file' must be <class 'str'> (got PosixPath('/home/ildefonso/Documents/repos/coding/birdsong/tweetynet/tests/test_data/mat/llb3_annot_subset.mat') that is a <class 'pathlib.PosixPath'>).", Attribute(name='annot_file', default=NOTHING, validator=<instance_of validator for type <class 'str'>>, repr=True, eq=True, order=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'str'>, PosixPath('/home/ildefonso/Documents/repos/coding/birdsong/tweetynet/tests/test_data/mat/llb3_annot_subset.mat'))

• should import within function show() when called
• have a similar function load() that does this and then show() calls load() if formats not loaded
• and then build these function calls into Transcriber
• how to test?

This will get used when one annotation file contains multiple sequences, and/or each sequence does not correspond to one audio file.
E.g., in the Koumura data set there are multiple sequences per audio file.
Similarly, canary song can be annotated by phrase and the user might want to preserve this annotation.

i.e. notmat_list_to_csv should be renamed to notmat2csv and accept either a list or a single .not.mat file, and notmat2seq should also accept either a list or a single .not.mat file

since .not.mat files have onsets and offsets in seconds

this makes it possible to "round trip" from .not.mat to Annotation and back without anything besides the .not.mat file (e.g. without getting sampling frequency from the associated audio file)

Otherwise the features section feels like I'm repeating myself after I just said all those things with nice lil' examples

i.e. have a 'default' 2csv function that gets used if none (or None, or 'default') specified, and only replace if user needs some extra functionality?

so user of e.g. vak can specify 'csv' as format

this would be a place where the 'to_annot` would have to return a list of annotations, though (see #54 )

• less testing required for different returned types
• clearer what expected type returned is for downstream user -- won't have to test all their code for e.g. Annot + list of Annots

users will be able to e.g. write a list comprehension so it's not actually that useful to include this extra functionality

• why:

  • club project for ppl studying vocalizations
  • tool for munging datasets of vocalizations that have annotated segments
    • so that when working with the dataset, there is no need to be aware of where different files are,
      e.g., the annotation file or files, the audio files, etc.
  • assumes you care about the "segments" part
    • need to include illustration of annotated segments right at top of docs

• how:

  • Python classes that faciliate representing these datasets
    • a Vocalization that consists of its annotation and the files associated with it
  • end product: a .csv / DataFrame where each row is an annotated segment

module crashes with a relative path like ./mymodule.py

to_csv and to_format have to be 'None' (if not using), not

None

which is annoying to type

Stack module was added but yes, looks like we're not using it?

Not sure now if we should be. Leaving this open

so user doesn't have to do something like

seq_dict = seq.to_dict()
file = seq_dict['file']

just to get the audio filename