{
    "info": {
        "author": "Yarden Cohen, David Nicholson",
        "author_email": "yardenc@bu.edu",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "License :: OSI Approved :: BSD License",
            "Programming Language :: Python",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: Implementation :: CPython"
        ],
        "description": "\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2667812.svg)](https://doi.org/10.5281/zenodo.2667812)\n[![PyPI version](https://badge.fury.io/py/tweetynet.svg)](https://badge.fury.io/py/tweetynet)\n\n# TweetyNet\n<p align=\"center\"><img src=\"./doc/tweetynet.gif\" alt=\"tweetynet image\" width=400></p>\n\n## A hybrid convolutional-recurrent neural network that segments and labels birdsong and other vocalizations.\n\n![sample annotation](doc/sample_phrase_annotation.png)\nCanary song segmented into phrases\n\n## Installation\nTo install, run the following command at the command line:  \n`pip install tweetynet`\n\nBefore you install, you'll want to set up a virtual environment\n(for an explanation of why, see\nhttps://www.geeksforgeeks.org/python-virtual-environment/).\nCreating a virtual environment is not as hard as it might sound;\nhere's a primer: https://realpython.com/python-virtual-environments-a-primer/  \nFor many scientific packages that depend on libraries written in  \nlanguages besides Python, you may find it easier to use \na platform dedicated to managing those dependencies, such as\n[Anaconda](https://www.anaconda.com/download) (which is free).\nYou can use the `conda` command-line tool developed by Anaconda  \nto create environments and install the scientific libraries that this package \ndepends on. In addition, using `conda` to install the dependencies may give you some performance gains \n(see https://www.anaconda.com/blog/developer-blog/tensorflow-in-anaconda/).  \nHere's how you'd set up a `conda` environment:  \n`/home/you/code/ $ conda create -n tweetyenv python=3.6 numpy scipy joblib tensorflow-gpu ipython jupyter`    \n`/home/you/code/ $ source activate tweetyenv`  \n(You don't have to `source` on Windows: `> activate tweetyenv`)  \n\nYou can then use `pip` inside a `conda` environment:  \n`(tweetyenv)/home/you/code/ $ pip install tweetynet`\n\n## Usage\n### Training `tweetynet` models to segment and label birdsong\nYou train `tweetynet` models with the [`vak`](https://github.com/NickleDave/vak) library.\nThe `vak` library is configured with `config.ini` files, using one of a handful of command-line flags.\nAs an example, here's how you'd run `vak` from the command line to train a single `config.ini` file:  \n`(tweetyenv)$ vak train ./configs/config_bird0.ini`  \n\nFor more details, please see the [vak documentation](https://github.com/NickleDave/vak).\n\n### Data and folder structures\nTo train models, you must supply training data in the form of audio files or \nspectrogram files, and annotations for each spectrogram.\n\n#### Spectrograms and labels\nThe package can generate spectrograms from `.wav` or `.cbin` audio files.\nIt can also accept spectrograms in the form of Matlab `.mat` files.\n\n### Important model parameters\n* The following parameters must be correctly defined in the configuration `.ini` [file](doc/README_config.md).\n  * `n_syllables` - Must be the correct number of labels, including a label for silent periods between syllables.\n  * `time_bins` - The number of time bins in each window from the spectrogram shown to the network.\n  During training, the network sees batches of windows grabbed randomly from the data whose width are equal to `time_bins`.\n  Intuitively, the bigger the time steps, the more temporal context the network has, but the longer it will take \n  to train. In practice, for Bengalese finch song, we achieve good accuracy with 88 time bins, and with canary song, \n  we achieve good accuracy with ~250 time bins. \n\n* The following parameters can be changed if needed:\n  * `num_epochs` - Number of times the network should see all the training data.\n  * `batch_size` - The number of snippets in each training batch (currently 11)\n  * `learning_rate` - The training step rate coefficient (currently 0.001)\nOther parameters that specify the network itself can be changed in the code but require knowledge of tensorflow.\n\n## Preparing training files\n\nIt is possible to train on any manually annotated data but there are some useful guidelines:\n* __Use as many examples as possible__ - The results will just be better. Specifically, this code will not label correctly syllables it did not encounter while training and will most probably generalize to the nearest sample or ignore the syllable.\n* __Use noise examples__ - This will make the code very good in ignoring noise.\n* __Examples of syllables on noise are important__ - It is a good practice to start with clean recordings. The code will not perform miracles and is most likely to fail if the audio is too corrupt or masked by noise. Still, training with examples of syllables on the background of cage noises will be beneficial.\n\n### Results of running the code\n\n__It is recommended to apply post processing when extracting the actual syllable tag and onset and offset timesfrom the estimates.__\n\n## Predicting new labels\n\nYou can predict new labels by adding a [PREDICT] section to the `config.ini` file, and \nthen running the command-line interface with the `predict` command, like so:  \n`(tweetyenv)$ vak predict ./configs/config_bird0.ini`\nAn example of what a `config.ini` file with a [PREDICT] section is \nin the doc folder [here](./doc/template_predict.ini).\n\nFor users with some scripting / Tensorflow experience, you can\nreload a saved model using a checkpoint file saved by the\nTensorflow checkpoint saver. Here's an example of how to do this, taken \nfrom the `vak.train_utils.learn_curve` function:\n```Python\nmeta_file = glob(os.path.join(training_records_dir, 'checkpoint*meta*'))[0]\ndata_file = glob(os.path.join(training_records_dir, 'checkpoint*data*'))[0]\n\nmodel = TweetyNet(n_syllables=n_syllables,\n                  input_vec_size=input_vec_size,\n                  batch_size=batch_size)\n\nwith tf.Session(graph=model.graph) as sess:\n    model.restore(sess=sess,\n                  meta_file=meta_file,\n                  data_file=data_file)\n```\n\n## Model architecture\nThe architecture of this deep neural network is based on these papers:\n* S. B\u00f6ck and M. Schedl, \"Polyphonic piano note transcription with recurrent neural networks,\" 2012 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP), Kyoto, 2012, pp. 121-124.\ndoi: 10.1109/ICASSP.2012.6287832 (http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=6287832&isnumber=6287775)\n* Parascandolo, Huttunen, and Virtanen, \u201cRecurrent Neural Networks for Polyphonic Sound Event Detection in Real Life Recordings.\u201d (https://arxiv.org/abs/1604.00861)\n\nThe deep net. structure, used in this code, contains 3 elements:\n* 2 convolutional and max pooling layers - A convolutional layer convolves the spectrogram with a set of tunable features and the max pooling is used to limit the number of parameters. These layers allow extracting local spectral and temporal features of syllables and noise.\n* A long-short-term-memory recurrent layer (LSTM) - This layer allows the model to incorporate the temporal dependencies in the signal, such as canary trills and the duration of various syllables. The code contains an option to adding more LSTM layers but, since it isn't needed, those are not used.\n* A projection layer - For each time bin, this layer projects the previous layer's output on the set of possible syllables. \n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/yardencsGitHub/tweetynet",
        "keywords": "",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "tweetynet",
        "package_url": "https://pypi.org/project/tweetynet/",
        "platform": "",
        "project_url": "https://pypi.org/project/tweetynet/",
        "project_urls": {
            "Homepage": "https://github.com/yardencsGitHub/tweetynet"
        },
        "release_url": "https://pypi.org/project/tweetynet/0.2.0/",
        "requires_dist": [
            "vak",
            "crowsetta (>=1.0.0)"
        ],
        "requires_python": ">=3.6.0",
        "summary": "neural network that segments and labels birdsong",
        "version": "0.2.0"
    },
    "last_serial": 5230336,
    "releases": {
        "0.1.1a1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c43fb209051bb02add25364b279e8c14",
                    "sha256": "2137f5b8eb4130e715b401a679133710c3e87bb8b86625fb339dc98dfb571823"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "c43fb209051bb02add25364b279e8c14",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.5.0",
                "size": 51076,
                "upload_time": "2018-11-04T15:24:08",
                "url": "https://files.pythonhosted.org/packages/4f/38/3ace0ab868d6d14f9c9ba59236797cb395f0a7447b136771e58b46819776/tweetynet-0.1.1a1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "229803610f33c533fa2e88a969f04481",
                    "sha256": "58b0e1b5272b7629bdb9693d5633ad4b13e22bd6a3974cd1bca26d5a4c2edbf6"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a1.tar.gz",
                "has_sig": false,
                "md5_digest": "229803610f33c533fa2e88a969f04481",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.5.0",
                "size": 46372,
                "upload_time": "2018-11-04T15:24:10",
                "url": "https://files.pythonhosted.org/packages/98/4a/e6a71975693cc732e959da497b3376e870ddc09c6da7833f127f930ad396/tweetynet-0.1.1a1.tar.gz"
            }
        ],
        "0.1.1a2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9a36f4bb55986e0e63a7968f707931dd",
                    "sha256": "42c832e683cefd9fd7577e213ca41befa4d663e0c4f5c1887d07a1c83d8e7ee5"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a2-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "9a36f4bb55986e0e63a7968f707931dd",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.5.0",
                "size": 13024,
                "upload_time": "2018-11-17T20:47:57",
                "url": "https://files.pythonhosted.org/packages/b5/59/3f9f8049e4fd01c31b65dc736fb224d457cacf55925c7d6dbe66dd6f1bdd/tweetynet-0.1.1a2-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "536e36bbd1796190acca53b0ac0f10fd",
                    "sha256": "fe6bb074ee571209821c05431b219577b9136f81b9730627b0cf809033714896"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a2.tar.gz",
                "has_sig": false,
                "md5_digest": "536e36bbd1796190acca53b0ac0f10fd",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.5.0",
                "size": 15506,
                "upload_time": "2018-11-17T20:47:59",
                "url": "https://files.pythonhosted.org/packages/a7/14/1d8910b753e43b3a2d4d4afb53a2d5c4786e6117d9e7749da23ee9e8314b/tweetynet-0.1.1a2.tar.gz"
            }
        ],
        "0.1.1a3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "6ef34fb71a01017bd6c8ceec16478e6e",
                    "sha256": "3681f76a5ab66b0efdb274f60f5e9b4fa1cca26389e3789706169ae49d78dc85"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a3-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "6ef34fb71a01017bd6c8ceec16478e6e",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.6.0",
                "size": 16743,
                "upload_time": "2019-03-03T14:44:53",
                "url": "https://files.pythonhosted.org/packages/09/56/dc1df5b85ba787b18549608aca02ef2e987cd20a078f50c2ba57fa84e4ad/tweetynet-0.1.1a3-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "db095d15025db29ed69790fb90f3a1a3",
                    "sha256": "9e6f7a0fefbf08361310f1b895c0ab89748fd257d1619af0e38f9ad80f0e0126"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a3.tar.gz",
                "has_sig": false,
                "md5_digest": "db095d15025db29ed69790fb90f3a1a3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6.0",
                "size": 11854,
                "upload_time": "2019-03-03T14:44:54",
                "url": "https://files.pythonhosted.org/packages/11/e6/3aa28a3387a4bbee6a6a8077edecf4692752e224a01d6b8ac008b83890a8/tweetynet-0.1.1a3.tar.gz"
            }
        ],
        "0.1.1a4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "edec8d7fcf27e15fefed264cce75b3a9",
                    "sha256": "75802086d71fe444a90d4b82d5904b137f129f48f036f5d9af7dd1e5b6b5625c"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a4-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "edec8d7fcf27e15fefed264cce75b3a9",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.6.0",
                "size": 9862,
                "upload_time": "2019-03-18T02:19:11",
                "url": "https://files.pythonhosted.org/packages/8a/6f/39eb7c7c06e2c88f0b4b8c61c58775910ddc94f697b11da9139cc7affc00/tweetynet-0.1.1a4-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "fe8baf7a65444720793a45b67238839b",
                    "sha256": "cd988a825fe7d4c798440be4a61b867562db07578eae57a6d99802fbc103b993"
                },
                "downloads": -1,
                "filename": "tweetynet-0.1.1a4.tar.gz",
                "has_sig": false,
                "md5_digest": "fe8baf7a65444720793a45b67238839b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6.0",
                "size": 9811,
                "upload_time": "2019-03-18T02:19:13",
                "url": "https://files.pythonhosted.org/packages/43/10/6b0aebb3513b38d96c8d8b40e9a3e33037c62fc5e80d0da51b23b3fab56a/tweetynet-0.1.1a4.tar.gz"
            }
        ],
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c1b514c036a9034944c341e220fe5a25",
                    "sha256": "ff82e0d2aef7a580a9e2394d123d0f090ea95aaf6059e6f89f402a1babbf689e"
                },
                "downloads": -1,
                "filename": "tweetynet-0.2.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "c1b514c036a9034944c341e220fe5a25",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.6.0",
                "size": 12371,
                "upload_time": "2019-05-06T01:20:20",
                "url": "https://files.pythonhosted.org/packages/60/9c/b94f9810be7e114fbec37d46170866fc94b2815014fb033659aa446a8133/tweetynet-0.2.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "de71f98a9177ae087fe2b67d537e39d3",
                    "sha256": "f41147c7ace3730156d1f6e3b83c73120f7678ff47fbd84d45579abfc1673b57"
                },
                "downloads": -1,
                "filename": "tweetynet-0.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "de71f98a9177ae087fe2b67d537e39d3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6.0",
                "size": 14955,
                "upload_time": "2019-05-06T01:20:21",
                "url": "https://files.pythonhosted.org/packages/eb/bc/3cad38e87be4554619de083eac59530529afa40cb02a09f4518d2ba46ad2/tweetynet-0.2.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "c1b514c036a9034944c341e220fe5a25",
                "sha256": "ff82e0d2aef7a580a9e2394d123d0f090ea95aaf6059e6f89f402a1babbf689e"
            },
            "downloads": -1,
            "filename": "tweetynet-0.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c1b514c036a9034944c341e220fe5a25",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6.0",
            "size": 12371,
            "upload_time": "2019-05-06T01:20:20",
            "url": "https://files.pythonhosted.org/packages/60/9c/b94f9810be7e114fbec37d46170866fc94b2815014fb033659aa446a8133/tweetynet-0.2.0-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "de71f98a9177ae087fe2b67d537e39d3",
                "sha256": "f41147c7ace3730156d1f6e3b83c73120f7678ff47fbd84d45579abfc1673b57"
            },
            "downloads": -1,
            "filename": "tweetynet-0.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "de71f98a9177ae087fe2b67d537e39d3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6.0",
            "size": 14955,
            "upload_time": "2019-05-06T01:20:21",
            "url": "https://files.pythonhosted.org/packages/eb/bc/3cad38e87be4554619de083eac59530529afa40cb02a09f4518d2ba46ad2/tweetynet-0.2.0.tar.gz"
        }
    ]
}