Introduction

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.

Caution!

The current code is still in a development state. Please report any bugs, but do not be surprised if — while using the early releases — TweetyPy “fall down and go BOOM!”2

Bug reports can be directed to the bug tracker3. Any other questions or comments can be sent via email4.

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.

  1. 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)
  2. Clip from “Tale of Two Kitties” (video)
  3. Bugs are tracked via Fossil VCS tickets (link)
  4. Mail to code@jessemcclure.org
  5. Unladen Swallow and Dead Parrot just didn't seem to work
  6. Tweety Bird

Table Of Contents

  1. General Introduction
    2.
  2. Table Of Contents
    3.
  3. Installation
    4.
    1. Mac OSX
      2.
    2. Windows
      3.
    3. Linux
      4.
  4. Basic Configuration
    5.
  5. Step-By-Step Usage
    6.
    1. Frequency Excursion
      2.
  6. Advanced Configuration
    7.
    1. Icons
      2.
    2. Actions
      3.
    3. Menus
      4.
    4. Toolbars
      5.
  7. Scripting Interface
    8.
  8. Development Roadmap
    9.

Installation

TweetyPy will run on any system with Python 3.6 or newer1 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

In either case setuptools should install the remaining depdendencies numpy5, scipy6, and PyYAML7. If not, these may need to be installed separately.

Mac OSX

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

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.

Linux

A 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.

  1. Install Python 3.6 or higher via your package / software manager or from the Python website.
  2. Install Qt5 via your package / software manager or from the Qt5 Website.
  3. TweetyPy on PyPi (link)
  4. Fossil VCS repository (link)
  5. Numpy
  6. SciPy
  7. PyYAML

Basic Configuration

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 $XDG_CONFIG_HOME/tweetypy/ or $HOME/.config/tweetypy/ if XDG_CONFIG_HOME is not set and on Windows %APPDATA%\tweetypy\ or %USERPROFILE%\AppData\tweetypy\ 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.

  1. Wikipedia has a good introduction to YAML.

Step-By-Step Usage

Frequency Excursion

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.

  1. 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.
  2. Add songs via the File -> Add Songs menu or the Add Songs toolbar button. Future versions will also allow dropping files into the main window.
  3. Move and resize the spectrogram for a song by dragging with the left an right mouse buttons.
  4. Select Tools -> Eraser or the Eraser toolbar button to enter erasing mode to remove unwanted points from the highlighted frequency excursion path.
  5. 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).
  6. When the signal has been appropriately cleaned up, select the Songs -> Next Song menu or Next Song toolbar button. Future versions will allow navigating back to previous songs to repeat or revise scores.
  7. After the last song has been scored, a save-file dialog will be presented. Select a location for the output data file.

Advanced Configuration

Coming soon to upcoming releases.

Scripting API

Scripting ability will come with version 3.X releases.

Development Roadmap

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)

  1. complete documentation (configuration)

Version 1.1 release (All a Bir-r-r-rd)

  1. fix ugly toolbar icons on mac
  2. app icon
  3. adjustable eraser size
  4. toolbar position configuration
  5. add save button and remember filename (use as default for next save)

Version 1.2 release (Bad Ol' Putty Tat)

  1. possible eraser shapes/rotations
  2. drag and drop adding of files
  3. 'back' navigation (and save/commit options for repeats)
  4. trim with cursor

Version 1.3 release (Bird In A Guilty Cage)

  1. add notes / comments to each song
  2. data table view / editting

Version 2.x releases

  1. power spectra
  2. bandwidth calculation
  3. trill-rate calculation
  4. automated trill-rate x bandwidth scoring

Version 3.x releases

  1. multi-song analyses: e.g., cross correlation, dynamic time warping
  2. scripting API (public module)