occurrences module

occurrences.search(scientificname=None, aphiaid=None, obisid=None, resourceid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, year=None, qc=None, fields=None, limit=500, offset=0, **kwargs)

Search OBIS occurrences

Parameters:
  • aphiaid – [Fixnum] A obis occurrence identifier
  • scientificname – [String,Array] One or more scientific names from the OBIS backbone. All included and synonym taxa are included in the search.
  • year – [Fixnum] The 4 digit year. A year of 98 will be interpreted as AD 98. Supports range queries, smaller,larger (e.g., ‘1990,1991’, whereas ‘1991,1990’ wouldn’t work)
  • geometry – [String] Well Known Text (WKT). A WKT shape written as either POINT, LINESTRING, LINEARRING or POLYGON. Example of a polygon: ((30.1 10.1, 20, 20 40, 40 40, 30.1 10.1)) would be queried as http://bit.ly/1BzNwDq
  • obisid – [Fixnum] An OBIS id. This is listed as the id or valid_id in taxa/taxon results
  • aphiaid – [Fixnum] An Aphia id. This is listed as the worms_id in taxa/taxon results
  • resourceid – [Fixnum] An resource id
  • startdate – [Fixnum] Start date
  • enddate – [Boolean] End date
  • startdepth – [Fixnum] Start depth
  • enddepth – [Boolean] End depth
  • qc – [String] Quality control flags
  • fields – [Array] Array of field names
  • limit – [Fixnum] Number of results to return. Default: 1000
  • offset – [Fixnum] Start at record. Default: 0
Returns:

A dictionary

Usage:

from pyobis import occurrences as occ
occ.search(scientificname = 'Mola mola')

# Many names
occ.search(scientificname = ['Mola', 'Abra', 'Lanice', 'Pectinaria'])

# Use paging parameters (limit and start) to page. Note the different results
# for the two queries below.
occ.search(scientificname = 'Mola mola', offset=0, limit=10)
occ.search(scientificname = 'Mola mola', offset=10, limit=10)

# Search on a bounding box
## in well known text format
occ.search(geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', limit=20)
from pyobis import taxa
res = taxa.search(scientificname='Mola mola')['results'][0]
occ.search(obisid=res['id'], geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', limit=20)
occ.search(aphiaid=res['worms_id'], geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', limit=20)

# Get occurrences for a particular eventDate
occ.search(aphiaid=res['worms_id'], year="2013", limit=20)
occurrences.get(id, **kwargs)

Get an OBIS occurrence

Parameters:id – [Fixnum] An obis occurrence identifier
Returns:A dictionary

Usage:

from pyobis import occurrences as occ
occ.get(id = 14333)
occ.get(id = 135355)

# many at once
[ occ.get(id = x) for x in [14333, 135355, 276413] ]
occurrences.download(scientificname=None, aphiaid=None, obisid=None, resourceid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, year=None, qc=None, fields=None, **kwargs)

Download OBIS occurrences

Parameters:
  • aphiaid – [Fixnum] A obis occurrence identifier
  • scientificname – [String,Array] One or more scientific names from the OBIS backbone. All included and synonym taxa are included in the search.
  • year – [Fixnum] The 4 digit year. A year of 98 will be interpreted as AD 98. Supports range queries, smaller,larger (e.g., ‘1990,1991’, whereas ‘1991,1990’ wouldn’t work)
  • geometry – [String] Well Known Text (WKT). A WKT shape written as either POINT, LINESTRING, LINEARRING or POLYGON. Example of a polygon: ((30.1 10.1, 20, 20 40, 40 40, 30.1 10.1)) would be queried as http://bit.ly/1BzNwDq
  • obisid – [Fixnum] An OBIS id. This is listed as the id or valid_id in taxa/taxon results
  • aphiaid – [Fixnum] An Aphia id. This is listed as the worms_id in taxa/taxon results
  • resourceid – [Fixnum] An resource id
  • startdate – [Fixnum] Start date
  • enddate – [Boolean] End date
  • startdepth – [Fixnum] Start depth
  • enddepth – [Boolean] End depth
  • qc – [String] Quality control flags
  • fields – [Array] Array of field names
Returns:

An object of class ObisDownload with methods to continue accessing the data

Usage:

from pyobis import occurrences as occ

# query to generate a download job
res = occ.download(year = 2001, scientificname = 'Orcinus')

# get the uuid for your download job
res.uuid

# get status of download prep
res.status()

# fetch file, writes to disk
res.fetch()

# get file path
x.file_path

# unzip the file
import zipfile
import tempfile
import shutil
import os

zipf = zipfile.ZipFile(x, 'r')
dir = tempfile.mkdtemp()
zipf.extractall(dir)
fpath = dir + '/' + os.listdir(dir)[0]
zipf.close()

# read some lines of the csv
import csv
with open(fpath) as csvfile:
    reader = csv.DictReader(csvfile)
    for row in reader:
        print(row['genus'], row['species'])

# cleanup
shutil.rmtree(dir)
occurrences.ObisDownload()

ObisDownload class

methods:

  • uuid: get uuid for the download
  • status: get download status
  • fetch: retrieve the download