# Bionompy
This is a Python wrapper on the [Bionomia](https://bionomia.net) API. Code follow the spirit/approach of the [pygbif](https://github.com/gbif/pygbif/graphs/contributors) package, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks [@sckott](https://github.com/sckott) and other [contributors](https://github.com/gbif/pygbif/graphs/contributors).
## Installation
Add this line to your application's requirements.txt:
```python
bionompy
```
And then execute:
$ pip install -r requirements.txt
Or install it yourself as:
$ pip install bionompy
## Usage
Import the library:
```
import bionompy
```
---
### Suggest Collector Names
Get collector name suggestions with a limit of 5:
```python
bionompy.suggest('Smith, Ja', limit=5) # => MultiJson object
```
Filter suggestions to only public profiles
```python
bionompy.suggest('Smith, Ja', is_public=True) # => MultiJson object
```
Filter suggestions to only people that have occurrences associated with them:
```python
bionompy.suggest('Smith, Ja', has_occurrences=True) # => MultiJson object
```
---
### Search Collectors
Search for a collector by name:
```python
bionompy.person.search('Mary Agnes Chase') # => MultiJson object
```
Filter the people search by taxonomic families_collected or taxonomic families_identified. If strict is set to true, then matches must include the taxonomic families.
```python
bionompy.person.search('Mary Agnes Chase', families_collected='Poaceae', strict=True) # => MultiJson object
```
```python
bionompy.person.search('Mary Agnes Chase', families_identified='Poaceae', strict=True) # => MultiJson object
```
Filter the search by whether the person was living on the specimen collection/identification date. If strict is set to true, it requires that they were alive on the date.
```python
bionompy.person.search('Smith', date='1580-01-02', strict=True) # => MultiJson object
```
Setting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.
```python
bionompy.person.search('Smith', callback='myFunction') # => JSON-P object
```
Use the page parameter for pagination of the search results:
```python
bionompy.person.search('Smith', page=2) # => MultiJson object
```
---
### Search Occurrences
Search for occurrences by [GBIF](https://gbif.org) [datasetID](https://www.gbif.org/dataset/f86a681d-7db8-483b-819a-248def18b70a) and [occurrenceID](https://www.gbif.org/occurrence/1804069383):
```python
bionompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0') # => MultiJson object
```
Setting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.
```python
bionompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0', callback='myFunction') # => JSON-P object
```
---
### Collectors
Get a person's profile by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers:
```python
bionompy.person.get('0000-0001-7618-5230') # => JSON-LD object
```
---
### Specimens
Get a person's specimens by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers. Use the page parameter for pagination.
```python
bionompy.person.get('0000-0001-7618-5230', specimens=True) # => JSON-LD object
```
```python
bionompy.person.get('0000-0001-7618-5230', specimens=True, csv=True) # => comma-separated values
```
---
### Occurrences
Get an occurrence with a [GBIF](https://www.gbif.org/occurrence/search) occurrenceID:
```python
bionompy.occurrence.get('477976412') # => JSON-LD object
```
---
### Parsing human names
**Note:** [Bionomia](https://bionomia.net) provides a RESTful API for the human name parsing [dwc_agent](https://rubygems.org/gems/dwc_agent) gem which uses the [namae](https://rubygems.org/gems/namae) gem, and you likely will get better performance using those gems directly if parsing a large number of human names. A similar library in Python to the namae Ruby gem is [nameparser](https://github.com/derek73/python-nameparser).
Parse authorships with names separated by `;` and each authorship set separated by `\r\n`:
```python
bionompy.parse(names='Henry Robert Nicollon des Abbayes; Groom Q\r\nMrs. John Errol Chandos Aberdeen') # => MultiJson object
```
---
### Agent Strings
Agent strings are people names from occurrence labels that have not been associated with a person's identifier yet.
**Note:** There is no restful API for agent strings, so these methods use beautifulsoup4 and the lxml parser to scrape the values from the Bionomia website.
Get a random list of agent strings:
```python
bionompy.agent.search()
```
Search for an agent string with the query, q:
```python
bionompy.agent.search(q='Mary Agnes')
```
Get an agent string's occurrences by ID (***Warning:*** The agent string identifiers are temporary and change every 2 weeks when new agent strings are imported into Bionomia and the website also goes down with a 503 error during agent string updates.)
```python
bionompy.agent.get('4746282')
```
---
## Development
After checking out the repo, change into the package directory `cd bionompy`, run `pip install .` to install the package, and `pip install -r requirements.txt` to install the dependencies. Then, run `pytest` to run the tests. You can also run `bin/console` for an interactive Python prompt that will allow you to experiment with the above example commands.
## Other Bionomia Libraries
* Ruby Gem: [bananomia](https://github.com/SpeciesFileGroup/bananomia)
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/SpeciesFileGroup/bionompy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/SpeciesFileGroup/bionompy/blob/main/CODE_OF_CONDUCT.md).
## License
The package is available as open source under the terms of the [NCSA/Illinois](https://github.com/SpeciesFileGroup/bionompy/blob/main/LICENSE.txt) license. You can learn more about the NCSA license on [Wikipedia](https://en.wikipedia.org/wiki/University_of_Illinois/NCSA_Open_Source_License) and compare it with other open source licenses at the [Open Source Initiative](https://opensource.org/license/uoi-ncsa-php/).
## Code of Conduct
Everyone interacting in the Bionompy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/SpeciesFileGroup/bionompy/blob/main/CODE_OF_CONDUCT.md).
## [Unreleased]
## [0.1.0] - 2023-10-27
- Initial release
Raw data
{
"_id": null,
"home_page": "http://github.com/speciesfilegroup/bionompy",
"name": "bionompy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "bionomia,biodiversity,collectors,specimens,API,web-services,species,natural history,taxonomists,biologists",
"author": "Geoff Ower",
"author_email": "gdower@illinois.edu",
"download_url": "https://files.pythonhosted.org/packages/b6/cf/bf1391237f7e6c049caae75e6c12627fb8d808fa7a18479f94deec16e03c/bionompy-0.0.1.tar.gz",
"platform": null,
"description": "# Bionompy\n\n\n\nThis is a Python wrapper on the [Bionomia](https://bionomia.net) API. Code follow the spirit/approach of the [pygbif](https://github.com/gbif/pygbif/graphs/contributors) package, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks [@sckott](https://github.com/sckott) and other [contributors](https://github.com/gbif/pygbif/graphs/contributors).\n\n## Installation\n\nAdd this line to your application's requirements.txt:\n\n```python\nbionompy\n```\n\nAnd then execute:\n\n $ pip install -r requirements.txt\n\nOr install it yourself as:\n\n $ pip install bionompy\n\n## Usage\n\n\nImport the library:\n```\nimport bionompy\n```\n\n---\n### Suggest Collector Names\nGet collector name suggestions with a limit of 5:\n```python\nbionompy.suggest('Smith, Ja', limit=5) # => MultiJson object\n```\nFilter suggestions to only public profiles\n```python\nbionompy.suggest('Smith, Ja', is_public=True) # => MultiJson object\n```\nFilter suggestions to only people that have occurrences associated with them:\n```python\nbionompy.suggest('Smith, Ja', has_occurrences=True) # => MultiJson object\n```\n\n---\n### Search Collectors\nSearch for a collector by name:\n```python\nbionompy.person.search('Mary Agnes Chase') # => MultiJson object\n```\n\nFilter the people search by taxonomic families_collected or taxonomic families_identified. If strict is set to true, then matches must include the taxonomic families.\n```python\nbionompy.person.search('Mary Agnes Chase', families_collected='Poaceae', strict=True) # => MultiJson object\n```\n```python\nbionompy.person.search('Mary Agnes Chase', families_identified='Poaceae', strict=True) # => MultiJson object\n```\n\nFilter the search by whether the person was living on the specimen collection/identification date. If strict is set to true, it requires that they were alive on the date.\n```python\nbionompy.person.search('Smith', date='1580-01-02', strict=True) # => MultiJson object\n```\n\nSetting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.\n```python\nbionompy.person.search('Smith', callback='myFunction') # => JSON-P object\n```\n\nUse the page parameter for pagination of the search results:\n```python\nbionompy.person.search('Smith', page=2) # => MultiJson object\n```\n\n---\n### Search Occurrences\nSearch for occurrences by [GBIF](https://gbif.org) [datasetID](https://www.gbif.org/dataset/f86a681d-7db8-483b-819a-248def18b70a) and [occurrenceID](https://www.gbif.org/occurrence/1804069383):\n```python\nbionompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0') # => MultiJson object\n```\nSetting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.\n```python\nbionompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0', callback='myFunction') # => JSON-P object\n```\n\n---\n### Collectors\nGet a person's profile by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers:\n```python\nbionompy.person.get('0000-0001-7618-5230') # => JSON-LD object\n```\n---\n### Specimens\nGet a person's specimens by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers. Use the page parameter for pagination.\n```python\nbionompy.person.get('0000-0001-7618-5230', specimens=True) # => JSON-LD object\n```\n\n```python\nbionompy.person.get('0000-0001-7618-5230', specimens=True, csv=True) # => comma-separated values\n```\n---\n### Occurrences\nGet an occurrence with a [GBIF](https://www.gbif.org/occurrence/search) occurrenceID:\n```python\nbionompy.occurrence.get('477976412') # => JSON-LD object\n```\n---\n### Parsing human names\n**Note:** [Bionomia](https://bionomia.net) provides a RESTful API for the human name parsing [dwc_agent](https://rubygems.org/gems/dwc_agent) gem which uses the [namae](https://rubygems.org/gems/namae) gem, and you likely will get better performance using those gems directly if parsing a large number of human names. A similar library in Python to the namae Ruby gem is [nameparser](https://github.com/derek73/python-nameparser).\n\nParse authorships with names separated by `;` and each authorship set separated by `\\r\\n`:\n```python\nbionompy.parse(names='Henry Robert Nicollon des Abbayes; Groom Q\\r\\nMrs. John Errol Chandos Aberdeen') # => MultiJson object\n```\n\n---\n### Agent Strings\nAgent strings are people names from occurrence labels that have not been associated with a person's identifier yet.\n\n**Note:** There is no restful API for agent strings, so these methods use beautifulsoup4 and the lxml parser to scrape the values from the Bionomia website.\n\nGet a random list of agent strings:\n```python\nbionompy.agent.search()\n```\n\nSearch for an agent string with the query, q:\n```python\nbionompy.agent.search(q='Mary Agnes')\n```\n\nGet an agent string's occurrences by ID (***Warning:*** The agent string identifiers are temporary and change every 2 weeks when new agent strings are imported into Bionomia and the website also goes down with a 503 error during agent string updates.)\n```python\nbionompy.agent.get('4746282')\n```\n\n---\n\n## Development\n\nAfter checking out the repo, change into the package directory `cd bionompy`, run `pip install .` to install the package, and `pip install -r requirements.txt` to install the dependencies. Then, run `pytest` to run the tests. You can also run `bin/console` for an interactive Python prompt that will allow you to experiment with the above example commands.\n\n## Other Bionomia Libraries\n\n* Ruby Gem: [bananomia](https://github.com/SpeciesFileGroup/bananomia)\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/SpeciesFileGroup/bionompy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/SpeciesFileGroup/bionompy/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe package is available as open source under the terms of the [NCSA/Illinois](https://github.com/SpeciesFileGroup/bionompy/blob/main/LICENSE.txt) license. You can learn more about the NCSA license on [Wikipedia](https://en.wikipedia.org/wiki/University_of_Illinois/NCSA_Open_Source_License) and compare it with other open source licenses at the [Open Source Initiative](https://opensource.org/license/uoi-ncsa-php/).\n\n## Code of Conduct\n\nEveryone interacting in the Bionompy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/SpeciesFileGroup/bionompy/blob/main/CODE_OF_CONDUCT.md).\n\n\n## [Unreleased]\n\n## [0.1.0] - 2023-10-27\n\n- Initial release\n",
"bugtrack_url": null,
"license": "NCSA",
"summary": "Python client for Bionomia",
"version": "0.0.1",
"project_urls": {
"Download": "https://github.com/speciesfilegroup/bionompy/archive/refs/tags/v0.0.1.tar.gz",
"Homepage": "http://github.com/speciesfilegroup/bionompy"
},
"split_keywords": [
"bionomia",
"biodiversity",
"collectors",
"specimens",
"api",
"web-services",
"species",
"natural history",
"taxonomists",
"biologists"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7e65fc0da31a8d4e9ca99a661a0f36c9d27e92b0865bdd85327cca3bf4e7edaf",
"md5": "78225f7b4a70d8955ecd56cbf8bb9013",
"sha256": "2602bb3aef49b810827834b6720ca0ccb7b60cd8e6c831b4af5b1b354db3ea23"
},
"downloads": -1,
"filename": "bionompy-0.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "78225f7b4a70d8955ecd56cbf8bb9013",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 14308,
"upload_time": "2023-10-27T19:00:20",
"upload_time_iso_8601": "2023-10-27T19:00:20.484555Z",
"url": "https://files.pythonhosted.org/packages/7e/65/fc0da31a8d4e9ca99a661a0f36c9d27e92b0865bdd85327cca3bf4e7edaf/bionompy-0.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b6cfbf1391237f7e6c049caae75e6c12627fb8d808fa7a18479f94deec16e03c",
"md5": "6a2c271eabdced2a4779b6947f53aa16",
"sha256": "7bd02dab10ae645334083ec1a8f59bb52055083aff38c0a2238bdcdae05c550c"
},
"downloads": -1,
"filename": "bionompy-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6a2c271eabdced2a4779b6947f53aa16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13090,
"upload_time": "2023-10-27T19:00:22",
"upload_time_iso_8601": "2023-10-27T19:00:22.218935Z",
"url": "https://files.pythonhosted.org/packages/b6/cf/bf1391237f7e6c049caae75e6c12627fb8d808fa7a18479f94deec16e03c/bionompy-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-27 19:00:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "speciesfilegroup",
"github_project": "bionompy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "bionompy"
}
JSON
