bold Package

bold Package

bold.api Module

class bold.api.Request

Bases: builtins.object

Constructs a Request. Sends HTTP request.

Returns:class:Response <Response> object. Return type:A

get(service, **kwargs)

Does HTTP request to BOLD webservice.

Parameters:

• service – The BOLD API alias to interact with.
• kwargs – Paramenters send by users.

Returns:

A Response class containing parsed data as attribute items.

class bold.api.Response

Bases: builtins.object

Accepts and parses results from a call to the BOLD API.

Parses the data and returns a Response object.

items

list or str

Metadata from BOLD after parsing.

service

str

Alias of the method used to interact with BOLD.

_parse_data(service, result_string)

Parses XML response from BOLD.

Parameters:

• service – Alias of the method used to interact with BOLD.
• result_string – XML or JSON string returned from BOLD.

Returns:

List of all items as dictionaries.

_parse_fasta(result_string)

Parses string response from BOLD containing FASTA sequences.

Parameters:result_string – FASTA sequences as string returned from BOLD. Returns:List of all items as Biopython SeqRecord objects.

_parse_json(result_string)

Parses JSON response from BOLD.

Parameters:result_string – JSON string returned from BOLD. Returns:List of all items as dictionaries. Raises:ValueError – “BOLD did not return any result.”

_parse_xml(result_string)

Parses XML response from BOLD.

Parameters:result_string – XML string returned from BOLD. Returns:List of all items as dictionaries.

bold.api.call_full_data(taxon=None, ids=None, bin=None, container=None, institutions=None, researchers=None, geo=None, marker=None, format=None)

Call the Full Data Retrieval API (combined).

Parameters:

• taxon – Taxon name including the ranks: phylum, class, order, family, subfamily, genus and species. Example: taxon=’Bos taurus’.
• ids – Sample ids, process ids, museum ids and field ids. Example: ids=’ACRJP618|ACRJP619-11’.
• bin – BIN stands for Barcode Index number URI. Example: bin=’BOLD:AAA5125’.
• container – Containers include project codes and dataset codes. Example: container=’DS-EZROM’.
• institutions – Name of Specimen Storing Sites. Example: ‘institutions=Biodiversity Institute of Ontario’.
• researchers – Collectors and specimen indenfitiers. Example: researchers=’Thibaud Decaens’.
• geo – Geographic sites such as countries, provinces and states. Example: geo=’Alaska’.
• marker – Genetic marker code. Example: marker=’COI-5P’.
• format – Optional. format=’tsv’.

Returns:

The data is returned as a string in TSV format or list of dicts parsed from a XML file.

Raises:

ValueError – If format is not None or ‘tsv’.

Examples

>>> import bold
>>> res = bold.call_full_data(taxon='Hermeuptychia', geo='Peru')
>>> item = res.items[0]
>>> [item['sequences_sequence_genbank_accession'] for item in res.items]
['KF466142', 'KF466143', 'KF466144']

bold.api.call_id(seq, db)

Call the ID Engine API http://www.boldsystems.org/index.php/resources/api?type=idengine

Parameters:

• seq – DNA sequence string or seq_record object.
• db – The BOLD database of available records. Choices: COX1_SPECIES,’ COX1, COX1_SPECIES_PUBLIC, COX1_L640bp.

Returns:

List of dictionaries containing metadata. One dictionary per BOLD record.

Examples

>>> import bold
>>> seq = 'TTTTTGGTATTTGAGCAGGAATAGTAGGAACTTCTCTCAGTTTAATTATTCGAATAGAATTAGGTAATCCAGGTTTCTTAATTGGAGATGATCAAATTTATAATACTATTGTAACAGCCCATGCTTTTATTATAATTTTTTTTATAGTTATACCTATTGTAATTGGAGGATTTGGAAATTGACTAGTTCCCCTAATATTAGGTGCACCTGATATAGCTTTCCCTCGTATAAATAATATAAGATATTGACTACTTCCACCATCTTTAATATTATTAATTTCAAGTAGTATTGTAGAAAATGGAGCTGGAACAGGTTGAACAGTTTACCCCCCTCTTTCCTCTAATATTGCTCATAGAGGAACCTCAGTAGACTTAGCAATTTTTTCTCTTCATTTAGCTGGTATTTCTTCTATTTTAGGAGCTATTAATTTTATTACTACAATTATTAATATACGAGTTAATGGAATATCCTATGATCAAATACCTTTATTTGTTTGAGCTGTTGGAATTACAGCTCTTCTTTTACTTCTTTCTTTACCTGTTTTAGCAGGAGCTATCACAATACTTCTTACAGATCGAAATTTAAATACATCATTTTTTGATCCTGCAGGAGGAGGTGATCCAATTTTATACCAACATTTATTTTGATTTTTTGGTCACCC'
>>> res = bold.call_id(seq, db='COX1')
>>> item = res.items[1]
>>> item['bold_id']  # this is the ID assigned by BOLD
'GBLN3590-14'

bold.api.call_sequence_data(taxon=None, ids=None, bin=None, container=None, institutions=None, researchers=None, geo=None, marker=None)

Call the Specimen Data Retrieval API.

Parameters:

• taxon – Taxon name including the ranks: phylum, class, order, family, subfamily, genus and species. Example: taxon=’Bos taurus’.
• ids – Sample ids, process ids, museum ids and field ids. Example: ids=’ACRJP618|ACRJP619-11’.
• bin – BIN stands for Barcode Index number URI. Example: bin=’BOLD:AAA5125’.
• container – Containers include project codes and dataset codes. Example: container=’DS-EZROM’.
• institutions – Name of Specimen Storing Sites. Example: ‘institutions=Biodiversity Institute of Ontario’.
• researchers – Collectors and specimen indenfitiers. Example: researchers=’Thibaud Decaens’.
• geo – Geographic sites such as countries, provinces and states. Example: geo=’Alaska’.
• marker – Genetic marker code. Example: marker=’COI-5P’.

Returns:

DNA sequences of matching records in FASTA format.

Examples

>>> import bold
>>> res = bold.call_sequence_data(taxon='Hermeuptychia', geo='Peru')
>>> items = res.items
>>> [item.id for item in items]
['GBLN4477-14|Hermeuptychia', 'GBLN4478-14|Hermeuptychia', 'GBLN4479-14|Hermeuptychia']

bold.api.call_specimen_data(taxon=None, ids=None, bin=None, container=None, institutions=None, researchers=None, geo=None, format=None)

Call the Specimen Data Retrieval API.

Parameters:

• taxon – Taxon name including the ranks: phylum, class, order, family, subfamily, genus and species. Example: taxon=’Bos taurus’.
• ids – Sample ids, process ids, museum ids and field ids. Example: ids=’ACRJP618|ACRJP619-11’.
• bin – BIN stands for Barcode Index number URI. Example: bin=’BOLD:AAA5125’.
• container – Containers include project codes and dataset codes. Example: container=’DS-EZROM’.
• institutions – Name of Specimen Storing Sites. Example: ‘institutions=Biodiversity Institute of Ontario’.
• researchers – Collectors and specimen indenfitiers. Example: researchers=’Thibaud Decaens’.
• geo – Geographic sites such as countries, provinces and states. Example: geo=’Alaska’.
• format – Optional: format='tsv' will return results a string containing data in tab-separated values. If not used, the data will be returned as dictionary (default behaviour).

Raises:

ValueError – If format is not None and not ‘tsv’.

Returns:

Matching specimen data records as string in TSV format or as list of dictionaries.

Examples

>>> import bold
>>> bin = 'BOLD:AAE2777'
>>> res = bold.call_specimen_data(bin=bin)
>>> class_taxon_names = [item['taxonomy_class_taxon_name'] for item in res.items]
>>> class_taxon_names[0]
'Insecta'

bold.api.call_taxon_data(tax_id, data_type=None, include_tree=None)

Call the TaxonData API. It has several methods to get additional metadata.

Parameters:

• tax_id – Taxon to get information for.
• data_type – basic|all|images. Default is basic.
• include_tree – Optional. Also returns information for parent taxa. True or False (default).

Returns:

List of dictionaries containing metadata for a given taxon.

Raises:

ValueError – If include_tree is not True or False.

Examples

>>> import bold
>>> tax_id = 88899
>>> res = bold.call_taxon_data(tax_id, data_type='basic,images')
>>> item = res.items[0]
>>> item['taxon']
'Momotus'
>>> [(i['image'], i['photographer']) for i in item['images']]
[('BSPBB/MJM_7364_IMG_2240_d+1345758620.JPG', 'Oscar Lopez')]

bold.api.call_taxon_search(taxonomic_identification, fuzzy=None)

Call the TaxonSearch API http://www.boldsystems.org/index.php/resources/api?type=taxonomy#Ideasforwebservices-SequenceParameters

Parameters:

• taxonomic_identification – species or any taxon name
• fuzzy – False by default

Returns:

List of dictionaries containing metadata. One dictionary per BOLD record.

Raises:

ValueError – If fuzzy is not True or False.

Examples

>>> import bold
>>> taxonomic_identification = 'Euptychia ordinata'
>>> res = bold.call_taxon_search(taxonomic_identification, fuzzy=False)
>>> item = res.items[0]  # there can be more than one result
>>> item['tax_id']
302603

bold.api.call_trace_files(taxon=None, ids=None, bin=None, container=None, institutions=None, researchers=None, geo=None, marker=None)

Trace files can be retrieved from BOLD by querying with several parameters.

Parameters:

• taxon – Taxon name including the ranks: phylum, class, order, family, subfamily, genus and species. Example: taxon=’Bos taurus’.
• ids – Sample ids, process ids, museum ids and field ids. Example: ids=’ACRJP618|ACRJP619-11’.
• bin – BIN stands for Barcode Index number URI. Example: bin=’BOLD:AAA5125’.
• container – Containers include project codes and dataset codes. Example: container=’DS-EZROM’.
• institutions – Name of Specimen Storing Sites. Example: ‘institutions=Biodiversity Institute of Ontario’.
• researchers – Collectors and specimen indenfitiers. Example: researchers=’Thibaud Decaens’.
• geo – Geographic sites such as countries, provinces and states. Example: geo=’Alaska’.
• marker – Genetic marker code. Example: marker=’COI-5P’.

Returns:

A TAR file consisting of compressed Trace Files (traces in either .ab1 or .scf format) along with a file listing the Process ID, taxon and marker for each Trace File included.

Examples

>>> import bold
>>> res = bold.call_trace_files(taxon='Euptychia mollis',
...                             institutions='York University')
>>> with open("trace_files.tar", "wb") as handle:
...     handle.write(res.file_contents)
4106240

bold.api.request(service, **kwargs)

Builds our request based on given arguments. Used internally.

Parameters:

• service – The BOLD API alias to interact with. Examples: call_id, call_taxon_search.
• kwargs – Arguments passed by users when calling our methods.

Returns:

Request object with service alias, correct URL and user arguments.

bold.utils Module

bold.utils._prepare_sequence(seq_record)

Outputs a DNA sequence as string.

Parameters:seq_record – Either sequence as string or sequence object Returns:sequence as string