Bananompy

This is a Python wrapper on the Bionomia API. Code follow the spirit/approach of the pygbif package, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks @sckott and other contributors.

Installation

Add this line to your application's requirements.txt:

bananompy

And then execute:

$ pip install -r requirements.txt

Or install it yourself as:

$ pip install bananompy

Usage

Import the library:

import bananompy

---

Suggest Collector Names

Get collector name suggestions with a limit of 5:

bananompy.suggest('Smith, Ja', limit=5) #  => MultiJson object

Filter suggestions to only public profiles

bananompy.suggest('Smith, Ja', is_public=True) #  => MultiJson object

Filter suggestions to only people that have occurrences associated with them:

bananompy.suggest('Smith, Ja', has_occurrences=True) #  => MultiJson object

---

Search Collectors

Search for a collector by name:

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

bananompy.person.search('Mary Agnes Chase', families_collected='Poaceae', strict=True) #  => MultiJson object

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

bananompy.person.search('Smith', date='1580-01-02', strict=True) #  => MultiJson object

Setting the callback parameter returns JSON-P wrapped in the provided callback string.

bananompy.person.search('Smith', callback='myFunction') #  => JSON-P object

Use the page parameter for pagination of the search results:

bananompy.person.search('Smith', page=2) #  => MultiJson object

---

Search Occurrences

Search for occurrences by GBIF datasetID and occurrenceID:

bananompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0') #  => MultiJson object

Setting the callback parameter returns JSON-P wrapped in the provided callback string.

bananompy.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 or WikiData identifiers:

bananompy.person.get('0000-0001-7618-5230') #  => JSON-LD object

---

Specimens

Get a person's specimens by their ORCID or WikiData identifiers. Use the page parameter for pagination.

bananompy.person.get('0000-0001-7618-5230', specimens=True) #  => JSON-LD object

bananompy.person.get('0000-0001-7618-5230', specimens=True, csv=True) #  => comma-separated values

---

Occurrences

Get an occurrence with a GBIF occurrenceID:

bananompy.occurrence.get('477976412') #  => JSON-LD object

---

Parsing human names

Note: Bionomia provides a RESTful API for the human name parsing dwc_agent gem which uses the 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.

Parse authorships with names separated by ; and each authorship set separated by \r\n:

bananompy.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:

bananompy.agent.search()

Search for an agent string with the query, q:

bananompy.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.)

bananompy.agent.get('4746282')

---

Development

After checking out the repo, change into the package directory cd bananompy, 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

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/SpeciesFileGroup/bananompy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The package is available as open source under the terms of the NCSA/Illinois license. You can learn more about the NCSA license on Wikipedia and compare it with other open source licenses at the Open Source Initiative.

Code of Conduct

Everyone interacting in the Bananompy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

[Unreleased]

[0.1.0] - 2023-10-27

• Initial release