CLN: rename/refactor recursive_stem and add clearer error message
#525
Comments
NickleDave
added
the
CLN: clean / refactor
|
Looking at this more.
What's confusing is when the latter case causes an error because the user doesn't know about that convention. We need to specifically capture that case and provide an informative error with a link to the docs explaining the convention. |
|
Here is the whole traceback for an instance of when this happens (that I got by naming files without following the convention, to raise the error intentionally) Key point is it's happening when |
|
Ok so this is more nuanced... but the 'simple' format assumes that the name of the annotated file is "name of annotation file, minus the .csv extension" This means if you name the annotation file without following the "includes audio filename" convention, you will end up with an So it's not crashing because we try to find a stem from the annotation filenames themselves, it's crashing because we try to find a stem from the This matters because I was expecting to wrap some code that tries to get stems from the annotation files themselves in a try/except block. I can't just say "this audio file could not be stemmed" since a user won't know where the "audio file" is coming from (it's a filename made up by Simplest thing to do is catch any ValueError inside |
|
Also: rename
|
Adds a page on file naming conventions to the reference section of the docs, that we can link to from other pages (as in #524) and from error messages (see #525). Also adds a page with Frequently Asked Questions, with information on how to annotate data for use with `vak` and links to other how-tos. Fixes #424. Squashed commits: - Add target to howto_user_annot.md Add target to header "spectrogram file naming conventions" so we can reference it from a separate page on file naming conventions. - Add doc/reference/filenames.md that explicitly documents naming conventions, so that we can reference this elsewhere, as described in #524. - Add doc/faq.md, fixes #424 - Add "getting help" to doc/index.md with link to just-added FAQ, as well as links to forum and issue tracker. - Update 'support/contributing' section of README to match the "Getting Help" section on the index of the docs, with links to FAQ, forum, issue tracker, and additionally the contributing docs. - Add faq to toctree in doc/index.md - Add link to naming conventions in howto_user_annot callout
- Rename `vak.annotation.recursive_stem` -> `audio_stem_from_path` Trying to convey that we are specifically looking for an audio filename, and then returning only its stem, while keeping function name concise. - Rename `annotation.source_annot_map` -> `map_annotated_to_annot`
- Add custom exception `AudioFilenameNotFound` - Have `audio_stem_from_path` raise this exception when it fails to find a valid audio format extension and then runs out of extensions to remove. The error clearly states that an audio filename was not found in the path, instead of short cryptic "unable to stem". - Have `map_annoted_to_annot` look for this custom exception in a try-except block when it first creates the keys for the map. If we catch an AudioFilenameNotFound exception, then we raise a verbose ValueError explaining what happened, including both `audio_path` and the path to the annotation itself, and a link to the file naming convention page added in #564 and to the how-to-user-annotation-format page.
Moving from #524 to a separate issue here since this is not really a documentation thing, but it's a fix I've been meaning to make anyway
See #524 and #523 for context
recursive_stemfunction is cryptically named. Renamefind_notated_extor something like that?recursive_stemrefer to naming convention in error message. Ideally link directly to the docsThe text was updated successfully, but these errors were encountered: