| Name | xenopy JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | https://github.com/realzza/xenopy |
| Summary | The most straightforward and efficient python wrapper for xeno-canto API 2.0 |
| upload_time | 2022-05-05 09:45:19 |
| maintainer | |
| docs_url | None |
| author | Ziang Zhou |
| requires_python | >=3.6 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# XenoPy
[](https://www.codefactor.io/repository/github/realzza/xenopy)
**`XenoPy`** is a python library that builds upon [xeno-canto API 2.0](https://xeno-canto.org/article/153).
## Install
Install from `pip`.
```bash
pip install xenopy
```
Checkout the [**birdData**](https://github.com/realzza/xenopy/tree/birdData) branch to implement XenoPy from source. (ps: birdData is the former name of XenoPy)
## Usage Snippet
You can directly search for bird data for a specific species. For instance, we retrieve data for [*African Silverbill*](https://xeno-canto.org/species/Euodice-cantans) whom's `quality` better than `C` since `2020-01-01`.
```python
from xenopy import Query
q = Query(name="African silverbill", q_gt="C", since="2020-01-01")
```
### Retrieve Metafiles
```python
# retrieve metadata
metafiles = q.retrieve_meta(verbose=True)
```
### Retrieve Recordings
```python
# retrieve recordings
q.retrieve_recordings(multiprocess=True, nproc=10, attempts=10, outdir="datasets/")
```
The retrieved recordings will be located in `datasets/`, organized by bird species names.
The default downloading mode is single-threaded. `multiprocess` flag controls the usage of multiple downloading processes. `nproc` is only applicable when the `multiprocess` flag is on. The saving directory can be specified at `outDir`.
Two files will be generated while running `retrieve_recordings`, `kill_multiprocess.sh`, and `failed.txt`. To interrupt multiprocess data retrieval, one can run `bash kill_multiprocess.sh` in the terminal. 'failed.txt' contains recordings that failed the retrieval, if any. The two files will be removed automatically removed after downloading finishes. `failed.txt` will preserve if not empty so that you can check the failed recordings out.
## Define a `Query`
As you can tell from the [Usage Snippet](#Usage-Snippet), defining a query is the most important step in communicating with the API. We determined the following interface to form a query based on the xeno-canto [search tips](https://xeno-canto.org/help/search).
```markdown
name: Species Name. Specify the name of bird you intend to retrieve data from. Both English names and Latin names are acceptable.
gen: Genus. Genus is part of a species' latin name, so it is searched by default when performing a basic search (as mentioned above).
ssp: subspecies
rec: recordist. Search for all recordings from a particular recordist.
cnt: country. Search for all recordings from a particular country.
loc: location. Search for all recordings from a specific location.
rmk: remarks. Many recordists leave remarks about the recording,and this field can be searched using the rmk tag. For example, rmk:playback will return a list of recordings for which the recordist left a comment about the use of playback. This field accepts a 'matches' operator.
lat: latitude.
lon: longtitude
box: search for recordings that occur within a given rectangle. The general format of the box tag is as follows: box:LAT_MIN,LON_MIN,LAT_MAX,LON_MAX. Note that there must not be any spaces between the coordinates.
also: To search for recordings that have a given species in the background.
type: Search for recordings of a particular sound type, e.g., type='song'
nr: number. To search for a known recording number, use the nr tag: for example nr:76967. You can also search for a range of numbers as nr:88888-88890.
lc: license.
q: quality ratings.
q_lt: quality ratings less than
q_gt: quality ratings better than
Usage Examples:
Recordings are rated by quality. Quality ratings range from A (highest quality) to E (lowest quality). To search for recordings that match a certain quality rating, use the q, q_lt, and q_gt tags. For example:
- q:A will return recordings with a quality rating of A.
- q:0 search explicitly for unrated recordings
- q_lt:C will return recordings with a quality rating of D or E.
- q_gt:C will return recordings with a quality rating of B or A.
len: recording length control parameter.
len_lt: recording length less than
len_gt: recording length greater than
Usage Examples:
len:10 will return recordings with a duration of 10 seconds (with a margin of 1%, so actually between 9.9 and 10.1 seconds)
len:10-15 will return recordings lasting between 10 and 15 seconds.
len_lt:30 will return recordings half a minute or shorter in length.
len_gt:120 will return recordings longer than two minutes in length.
area: continents. Valid values for this tag: africa, america, asia, australia, europe.
since:
Usage Examples:
- since=3, since the past three days
- since=YYYY-MM-DD, since the particular date
year: year
month: month. year and month tags allow you to search for recordings that were recorded on a certain date.
```
## Update History
 [**v0.0.4**](https://pypi.org/project/xenopy/0.0.4/)
- Support Query by bird `name`.
- Cut inessential processes in query traffic.
- Optimized query assignment strategy in recording retrieval.
## todo
- [x] create query object for single species, containing features like
- [x] retrieve metedata
- [x] retrieve bird songs
- [x] add multiprocessing downloading feature
## Open Source
The first generation of `xenocanto` [package](https://github.com/ntivirikin/xeno-canto-py) is hard to use also inefficient. Thus I wrapped the [2.0 API](https://xeno-canto.org/article/153) version in a more straightforward and efficient interface.
Feel free to file an issue had you encountered any bugs, or prompt a PR to `XenoPy` to join me in maintenance and optimization.
Raw data
{
"_id": null,
"home_page": "https://github.com/realzza/xenopy",
"name": "xenopy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Ziang Zhou",
"author_email": "ziang.zhou518@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/52/19/ae35248f012c8a6b9d04c46c87beca5ce031a3a2350a0b62df76e38a83ae/xenopy-0.0.4.tar.gz",
"platform": null,
"description": "# XenoPy\n \n \n \n \n[](https://www.codefactor.io/repository/github/realzza/xenopy) \n\n**`XenoPy`** is a python library that builds upon [xeno-canto API 2.0](https://xeno-canto.org/article/153).\n\n## Install\nInstall from `pip`.\n```bash\npip install xenopy\n```\nCheckout the [**birdData**](https://github.com/realzza/xenopy/tree/birdData) branch to implement XenoPy from source. (ps: birdData is the former name of XenoPy)\n\n\n## Usage Snippet\nYou can directly search for bird data for a specific species. For instance, we retrieve data for [*African Silverbill*](https://xeno-canto.org/species/Euodice-cantans) whom's `quality` better than `C` since `2020-01-01`.\n```python\nfrom xenopy import Query\n\nq = Query(name=\"African silverbill\", q_gt=\"C\", since=\"2020-01-01\")\n```\n\n### Retrieve Metafiles\n```python\n# retrieve metadata\nmetafiles = q.retrieve_meta(verbose=True)\n```\n\n### Retrieve Recordings\n```python\n# retrieve recordings\nq.retrieve_recordings(multiprocess=True, nproc=10, attempts=10, outdir=\"datasets/\")\n```\nThe retrieved recordings will be located in `datasets/`, organized by bird species names.\n\nThe default downloading mode is single-threaded. `multiprocess` flag controls the usage of multiple downloading processes. `nproc` is only applicable when the `multiprocess` flag is on. The saving directory can be specified at `outDir`.\n\nTwo files will be generated while running `retrieve_recordings`, `kill_multiprocess.sh`, and `failed.txt`. To interrupt multiprocess data retrieval, one can run `bash kill_multiprocess.sh` in the terminal. 'failed.txt' contains recordings that failed the retrieval, if any. The two files will be removed automatically removed after downloading finishes. `failed.txt` will preserve if not empty so that you can check the failed recordings out.\n\n## Define a `Query`\nAs you can tell from the [Usage Snippet](#Usage-Snippet), defining a query is the most important step in communicating with the API. We determined the following interface to form a query based on the xeno-canto [search tips](https://xeno-canto.org/help/search).\n```markdown\nname: Species Name. Specify the name of bird you intend to retrieve data from. Both English names and Latin names are acceptable.\ngen: Genus. Genus is part of a species' latin name, so it is searched by default when performing a basic search (as mentioned above).\nssp: subspecies\nrec: recordist. Search for all recordings from a particular recordist.\ncnt: country. Search for all recordings from a particular country.\nloc: location. Search for all recordings from a specific location.\nrmk: remarks. Many recordists leave remarks about the recording,and this field can be searched using the rmk tag. For example, rmk:playback will return a list of recordings for which the recordist left a comment about the use of playback. This field accepts a 'matches' operator.\nlat: latitude.\nlon: longtitude\nbox: search for recordings that occur within a given rectangle. The general format of the box tag is as follows: box:LAT_MIN,LON_MIN,LAT_MAX,LON_MAX. Note that there must not be any spaces between the coordinates.\nalso: To search for recordings that have a given species in the background.\ntype: Search for recordings of a particular sound type, e.g., type='song'\nnr: number. To search for a known recording number, use the nr tag: for example nr:76967. You can also search for a range of numbers as nr:88888-88890.\nlc: license.\nq: quality ratings. \nq_lt: quality ratings less than\nq_gt: quality ratings better than\n Usage Examples:\n Recordings are rated by quality. Quality ratings range from A (highest quality) to E (lowest quality). To search for recordings that match a certain quality rating, use the q, q_lt, and q_gt tags. For example:\n - q:A will return recordings with a quality rating of A.\n - q:0 search explicitly for unrated recordings\n - q_lt:C will return recordings with a quality rating of D or E.\n - q_gt:C will return recordings with a quality rating of B or A.\nlen: recording length control parameter.\nlen_lt: recording length less than\nlen_gt: recording length greater than\n Usage Examples:\n len:10 will return recordings with a duration of 10 seconds (with a margin of 1%, so actually between 9.9 and 10.1 seconds)\n len:10-15 will return recordings lasting between 10 and 15 seconds.\n len_lt:30 will return recordings half a minute or shorter in length.\n len_gt:120 will return recordings longer than two minutes in length.\narea: continents. Valid values for this tag: africa, america, asia, australia, europe.\nsince: \n Usage Examples:\n - since=3, since the past three days\n - since=YYYY-MM-DD, since the particular date\nyear: year\nmonth: month. year and month tags allow you to search for recordings that were recorded on a certain date. \n```\n\n## Update History\n\n [**v0.0.4**](https://pypi.org/project/xenopy/0.0.4/)\n- Support Query by bird `name`.\n- Cut inessential processes in query traffic.\n- Optimized query assignment strategy in recording retrieval.\n\n## todo\n- [x] create query object for single species, containing features like\n - [x] retrieve metedata\n - [x] retrieve bird songs\n- [x] add multiprocessing downloading feature\n\n## Open Source\nThe first generation of `xenocanto` [package](https://github.com/ntivirikin/xeno-canto-py) is hard to use also inefficient. Thus I wrapped the [2.0 API](https://xeno-canto.org/article/153) version in a more straightforward and efficient interface.\nFeel free to file an issue had you encountered any bugs, or prompt a PR to `XenoPy` to join me in maintenance and optimization.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "The most straightforward and efficient python wrapper for xeno-canto API 2.0",
"version": "0.0.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "853176b59e7ad1b769fff968c0f8c718",
"sha256": "e5a2604280bfa7c63fa25fa0c783810372a87dd931159f6dcd604666dbf5bcb9"
},
"downloads": -1,
"filename": "xenopy-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "853176b59e7ad1b769fff968c0f8c718",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 20061,
"upload_time": "2022-05-05T09:45:17",
"upload_time_iso_8601": "2022-05-05T09:45:17.400626Z",
"url": "https://files.pythonhosted.org/packages/f3/7b/95ff5d710afeb0629c2c1c3e913fee7ba5eef1b563c92fabd06ce991f43b/xenopy-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "bb47fcbf94968fdc89a0fe8dad15a9aa",
"sha256": "c98031dc6311153b3e81bd7552901651ade433121f4f975a522ceba5ef9dcacd"
},
"downloads": -1,
"filename": "xenopy-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "bb47fcbf94968fdc89a0fe8dad15a9aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 20539,
"upload_time": "2022-05-05T09:45:19",
"upload_time_iso_8601": "2022-05-05T09:45:19.650470Z",
"url": "https://files.pythonhosted.org/packages/52/19/ae35248f012c8a6b9d04c46c87beca5ce031a3a2350a0b62df76e38a83ae/xenopy-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-05-05 09:45:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "realzza",
"github_project": "xenopy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xenopy"
}
