crowsetta: A Python tool to work with any format for annotating animal vocalizations and bioacoustics data.

[NickleDave]

Submitting Author: David Nicholson (@NickleDave )
All current maintainers: (@NickleDave )
Package Name: crowsetta
One-Line Description of Package: A Python tool to work with any format for annotating animal vocalizations and bioacoustics data.
Repository Link: https://github.com/vocalpy/crowsetta
Version submitted: 4.0.0.post2
Editor: @cmarmo
Reviewer 1: @rhine3
Reviewer 2: @shaupert
Archive:
JOSS:
Version accepted: v 5.0
Date accepted (month/day/year): 03/28/2023

---

Description

• Include a brief paragraph describing what your package does:
  crowsetta provides a Pythonic way to work with annotation formats for animal vocalizations and bioacoustics data. It has has built-in support for many widely used formats such as Audacity label tracks, Praat .TextGrid files, and Raven .txt files. The package focuses on providing interoperability, as well as making it easier to share data in plaintext flat-file formats (csv) and common serialization formats (json). In addition, abstractions in the package are designed to make it easy to use these simplified formats for common downstream tasks. Examples of such tasks are fitting statistical models of vocal behavior, and building datasets to train machine learning models that predict new annotations.

Scope

• Please indicate which category or categories this package falls under:
  • Data retrieval
  • Data extraction
  • Data munging
  • Data deposition
  • Reproducibility
  • Geospatial
  • Education
  • Data visualization*

Please fill out a pre-submission inquiry before submitting a data visualization package. For more info, see notes on categories of our guidebook.

n/a

• For all submissions, explain how the and why the package falls under the categories you indicated above. In your explanation, please address the following points (briefly, 1-2 sentences for each):

  • Who is the target audience and what are scientific applications of this package?

Anyone that works with animal vocalizations or other bioacoustics data that is annotated in some way. Examples (from the landing page of the docs): neuroscientists studying how songbirds learn their song, or why mice emit ultrasonic calls. Ecologists studying dialects of finches distributed across Asia, linguists studying accents in the Caribbean, a speech pathologist looking for phonetic changes that indicate early onset Alzheimer’s disease.

• Are there other Python packages that accomplish the same thing? If so, how does yours differ?

Not to my knowledge.

There are many format-specific packages in various states of maintenance, e.g. a search for the format textgrid used by the application Praat on PyPI currently returns 33 packages (include crowsetta):
https://pypi.org/search/?q=textgrid&o=

There are also several larger packages whose functionality includes the ability to parse specific formats, e.g. Parselmouth wraps all of Praat and thus can load TextGrid files. But the goal of crowsetta is mainly to provide interoperability, and to do so for a wide array of formats, so that other higher-level libraries can leverage its functionality. This emphasis on data extraction + munging, like the possibly destructive transformation to other formats, makes it in scope for pyOpenSci.

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has an OSI approved license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.

Publication options

• Do you wish to automatically submit to the Journal of Open Source Software?

yes

• If so:

JOSS Checks

• The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
• The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
• The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
• The package is deposited in a long-term repository with the DOI:

Note: Do not submit your package separately to JOSS

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

• Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Code of conduct

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

Please fill out our survey

• Last but not least please fill out our pre-review survey. This helps us track
  submission and improve our peer review process. We will also ask our reviewers
  and editors to fill this out.

P.S. *Have feedback/comments about our review process? Leave a comment here

Potential reviewers

As discussed with @lwasser I am tagging some potential reviewers given that pyOpenSci does not currently have anyone that's familiar with this area (besides me)

@rhine3 @shyamblast @YannickJadoul @avakiai @danibene @nilor

edit: just updating here for clarity that I am only suggesting reviewers to help bootstrap the process since we're still a growing org. @lwasser will assign an editor that will then reach out directly to potential reviewers. Sorry for any confusion, and we appreciate interest of people that have replied so far.

Editor and Review Templates

Editor and review templates can be found here

[lwasser]

hi @NickleDave responding here so it's visible that this issue is being worked on! I am looking for an editor for this package now given I can't step in due to COI! :) but please know i've reached out to a few people and am in the process of finding an editor.

[NickleDave]

Thank you @lwasser, understood

[cmarmo]

Hi @NickleDave , I'm Chiara and I'm going to be the editor for your submission.
I'm sure I'm going to learn a lot in the process. Nice to meet you!
I will perform the editor checks in the next days (no more than a week) and starting to look for reviewers (thanks for your suggestions! 🙏 ).

[NickleDave]

Hi @cmarmo! Nice to meet you as well.

Looking forward to working with you on the review, I am sure I will learn a lot.

A week is perfect, I should have survived a deadline at my day job by then 😆

[cmarmo]

Editor in Chief checks

Hi @NickleDave, below are the basic checks that your package needs to pass
to begin our review.

• Installation The package can be installed from a community repository such as PyPI (preferred), and/or a community channel on conda (e.g. conda-forge, bioconda).
  • The package imports properly into a standard Python environment import package-name.
• Fit The package meets criteria for fit and overlap.
• Documentation The package has sufficient online documentation to allow us to evaluate package function and scope without installing the package. This includes:
  • User-facing documentation that overviews how to install and start using the package.
  • Short tutorials that help a user understand how to use the package and what it can do for them.
  • API documentation (documentation for your code's functions, classes, methods and attributes): this includes clearly written docstrings with variables defined using a standard docstring format. We suggest using the Numpy docstring format.
• Core GitHub repository Files
  • README The package has a README.md file with clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
  • Contributing File The package has a CONTRIBUTING.md file that details how to install and contribute to the package.
    • The contributing.md file is located in the .github/ folder, while pyOpenSci recommends including it in the root repository.
  • Code of Conduct The package has a Code of Conduct file.
  • License The package has an OSI approved license.
    NOTE: We prefer that you have development instructions in your documentation too.
• Issue Submission Documentation All of the information is filled out in the YAML header of the issue (located at the top of the issue template).
• Automated tests Package has a testing suite and is tested via GitHub actions or another Continuous Integration service.
• Repository The repository link resolves correctly.
• Package overlap The package doesn't entirely overlap with the functionality of other packages that have already been submitted to pyOpenSci.
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly.
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

• Initial onboarding survey was filled out
  We appreciate each maintainer of the package filling out this survey individually. 🙌
  Thank you authors in advance for setting aside five to ten minutes to do this. It truly helps our organization. 🙌

---

---

Editor comments

The package is already in a very good shape, thank you for all your work!

I would like to mention that the contributing.md file is located in the .github/ directory and not in the root repository as recommended by the pyOpenSci documentation.
I don't have any strong opinion about that, but I must confess that I had to look for it for a moment before remembering that it could be placed in the .github directory. I guess having it in the root repo will make it more discoverable directly on-line (without downloading the sources).
Feel free to move it or not, depending on your point of view.

I'm going to look for reviewers for your package now.
I hope this will not take too much time... I will let you know anyway by the end of the next week.
Thanks for your patience!

[NickleDave]

🙏 thank you @cmarmo

the contributing.md file is located in the .github/ directory and not in the root repository as recommended by the pyOpenSci documentation.
I guess having it in the root repo will make it more discoverable directly on-line

I can move it to the root, and I agree with you that it's easier to spot that way for someone looking at the repo e.g. on GitHub in the browser.

I think I was basically copying what I saw in numpy--I thought the file had to be there for the link to show up when someone opened an issue.

But now I see the GitHub docs say it can be there, in the root, or docs, as you said. Good to know.

So I'll just move it.

[NickleDave]

Done in vocalpy/crowsetta@9d435f6

edit: also I have now filled out the onboarding survey (sorry, forgot!)

[cmarmo]

So I'll just move it.

Thanks @NickleDave !

[cmarmo]

Dear @NickleDave,
I have been lucky this week and already found the two reviewers for your submission.
I would like to thank @rhine3 and @shaupert for accepting to serve as reviewers.
I'll let them introduce themselves here when ready (you know ... it's almost week-end already.. 🙂)