TweetyPy is a direct descendant of the FEX frequency excursion calculator1. Frequency excursion is the first (and only in version 1) analysis that TweetyPy is capable of, but there are plans for adding several additional calculations starting with trill rate and bandwidth followed by multi-song comparisons for similarity and eventually clustering and categorization of songs.
The current code is still in a development state and may not be ready for large-scale analyses just yet. Please report any bugs, but do not be surprised if — while using the early releases — TweetyPy “fall down and go BOOM!”2
What's In A Name?
As it became clear that this program, formerly known as Fex, would be useful for doing more than just frequency excursion calculations it became worth considering new names. The goal was for a fun name that would be immediately recognizable as a bird while also potentially referencing the heritage of the Python language in which the software was written5. This lead to Tweety Bird6 also known as Tweety Pie. Hence the name TweetyPy. Each minor-version release of TweetyPy will have a codename from the title of a Tweety Bird short.
- Podos J, Moseley DL, Goodwin SE, McClure J, Taft BN, Strauss AV, Rega-Brodsky C, Lahti DC. A fine-scale, broadly applicable index of vocal performance: frequency excursion. Animal Behaviour. 2016 Jun 30;116:203-12. (link)
- Clip from “Tale of Two Kitties” (video)
- Bugs are tracked via Fossil VCS tickets (link)
- Mail to firstname.lastname@example.org
- Unladen Swallow and Dead Parrot just didn't seem to work
- Tweety Bird
Table Of Contents
TweetyPy will run on any system with Python 3.61 and Qt52. TweetyPy is available from the PyPi “Cheese Shop”3 which will be updated with each minor-version release. These releases — as well as the most recent development code — can also be obtained directly from the Fossil VCS source4. Once Python 3.6 is on your system, TweetyPy can be installed directly from PyPi via pip:
pip install tweetypy
Alternatively, TweetyPy can be installed from sources retrieved from PyPi or Fossil with the following command from within the top-level directory of the source files:
python setup.py install
Mac OSX typically comes with python preinstalled, however it is an older version of python. You will need python 3.6 or later1. Python 3.6 will be installed along-side the existing python2 installation, however the default python and pip commands will still use the python2 versions so you will need to use the -3 suffix for pip. Once python 3.6 is installed, the following command in a terminal should suffice to complete the installation of tweetypy:
pip3 install tweetypy
This should install all the dependencies followed by tweetypy itself. Preliminary testing on a mac resulted in a successful installation and minimal test of a working tweetypy install.
Windows may come with python preinstalled, however it is likely an older version of python. You will need python 3.6 or later1. Python 3.6 will be installed along-side any existing python2 installation, however the default python and pip commands will still use the python2 versions so you will need to use the -3 suffix for pip. Once python 3.6 is installed, the following command in a console / power-shell session should suffice to complete the installation of tweetypy:
pip3 install tweetypy
This should install all the dependencies followed by tweetypy itself. Preliminary testing on windows 10 resulted in a successful installation and minimal test of a working tweetypy install.
PKGBUILD is provided in the source repository for ArchLinux.
Other distros may use
python setup.py install from the root of
the source repository. If you are able to help package TweetyPy for your
distro, please feel free to open a feature request on the ticket tracker.
Alternatively, tweetypy can be installed directly from PyPi via pip.
Configuration files are provided with reasonable defaults that should work ‘out-of-the-box’ for many analyses. Configuration files are written in the YAML markup language1 which for general use can be viewed as simple key-value pairs. To customize your configuration, copy config.yaml from the python site-packages directory where it was installed to your user's configuration directory.
TweetyPy reads configuration from any
config.yaml files in
order from the site-packages directory, platform-specific configuration
directories, and the present working directory with settings in each file
taking precedence over previous settings. On Mac-OSX and Linux, the
configuration directories are
$HOME/.config/tweetypy/ if XDG_CONFIG_HOME is not set and on Windows
if APPDATA is not set.
Details of the configurable settings will be coming soon. For now, feel free to review the configuration files as many settings may be self-explanatory.
- Wikipedia has a good introduction to YAML.
Version 1.0.0 has a minimal set of features for taking measures of frequency excursion. Below is an example sequence for analyzing a single song or set of songs. Future versions of TweetyPy will allow for numerous modifications to this workflow including dynamically raising or lowering the threshold for inclusion in the calculation, changing the shape and/or orientation of the eraser tool, moving back through the sequence of songs to repeat measures, cropping of songs, and entering notes to be saved with each song's data.
- Start TweetyPy. Currently a list of wave files can be passed on the command line. Dropping files on any desktop icon shoul also work but has not yet been tested.
- Add songs via the
File -> Add Songsmenu or the
Add Songstoolbar button. Future versions will also allow dropping files into the main window.
- Move and resize the spectrogram for a song by dragging with the left an right mouse buttons.
Tools -> Eraseror the
Erasertoolbar button to enter erasing mode to remove unwanted points from the highlighted frequency excursion path.
- In eraser mode, erase by clicking and dragging in the spectrogram window. If you erase too much, there is an undo option (only one level of undo is available).
- When the signal has been appropriately cleaned up, select the
Songs -> Next Songmenu or
Next Songtoolbar button. Future versions will allow navigating back to previous songs to repeat or revise scores.
- After the last song has been scored, a save-file dialog will be presented. Select a location for the output data file.
Coming soon to upcoming releases.
Scripting ability will come with version 3.X releases.
Below is the tentative development roadmap. Version 1.0 should be fully functional for frequency excursion calculations. Useful features for frequence excursion use will continue to be added through version 1.3 at which point frequency excursion should be feature-complete. Any remaining version 1.X releases will be for bug fixes or for code-refactoring in preparation of the additional features to come with the 2.X releases.
Version 1.0 release (Ain't She Tweet)
- complete documentation (configuration)
Version 1.1 release (All a Bir-r-r-rd)
- fix ugly toolbar icons on mac
- app icon
- adjustable eraser size
- toolbar position configuration
- add save button and remember filename (use as default for next save)
Version 1.2 release (Bad Ol' Putty Tat)
- possible eraser shapes/rotations
- drag and drop adding of files
- 'back' navigation (and save/commit options for repeats)
- trim with cursor
Version 1.3 release (Bird In A Guilty Cage)
- add notes / comments to each song
- data table view / editting
Version 2.x releases
- power spectra
- bandwidth calculation
- trill-rate calculation
- automated trill-rate x bandwidth scoring
Version 3.x releases
- multi-song analyses: e.g., cross correlation, dynamic time warping
- scripting API (public module)