unicatdb 2.0

Python library for accessing API of the UniCatDB - Universal Catalog Database for biological findings.

UniCatDB API library

Python library for accessing API of the UniCatDB - Universal Catalog Database for biological findings.

UniCatDB is a coherent yet flexible interdisciplinary storage solution for cataloging findings data of various research groups, focused mainly on green biology. Configurable by the researchers themselves, provides shared access enabling interoperability if desired, and is accessible by user-friendly interface on either desktop, laptop or tablet - both in the lab and on the go.

See www.unicatdb.org for more details and contact.

Getting started

1. Install the library to your Python environment.

   Typically, for local Python on your desktop, run pip install command in shell:

   pip install unicatdb
   

   For other environments, such as Jupiter notebook, see respective documentation for instructions on how to install pip packages.

   For example, in Jupiter notebook, paste this snippet the top (source: here for details):

   # Install a pip package in the current Jupyter kernel
   
   import sys
   !{sys.executable} -m pip install unicatdb
   

2. Login to the UniCatDB (https://app.unicatdb.org)

3. Obtain your API credentials (API key and Personal access token) - click on your profile in toolbar, then on API Access button

4. Use credentials in API client configuration, see usage examples bellow

Structure

The core of the library is in module unicatdb.opeapi_client which consists of code generated via the modified OpenAPI Generator and the interface corresponds to the UniCatDB API specifications available at https://api.unicatdb.org

For more convenient access, wrappers are provided in unicatdb.api module - this is your entrypoint for most common tasks.

Usage examples

The "Hello world"

What this does: Get first ten findings from the database

import unicatdb
from typing import List
from pprint import pprint

# %% Paste your API key and Personal access token from https://account.unicatdb.org/

configuration = unicatdb.Configuration(
    access_token='<PASTE YOUR API KEY TOKEN HERE>'
)

# %% Query some data
from unicatdb.openapi_client import UserScopedTenant, FindingArrayResponse
with unicatdb.Client(configuration) as client:

    # list my available workspaces (a.k.a tenants) ...
    my_workspaces: List[UserScopedTenant] = client.tenants.api_tenants_available_get()
    pprint(my_workspaces)

    # ... and if I have one, list some of it's finding
    if my_workspaces:
        selected_workspace = my_workspaces[0]

        findings: FindingArrayResponse = client.findings.api_findings_get(selected_workspace.id)
        pprint(findings)

Advanced query example

What this does: Get only the name, amount and dynamic data of the top 10 findings sorted by amount greatest-first, of which taxonomy's genus contains 'vulgare':

import unicatdb
from typing import List
from pprint import pprint

# %% Paste your API key and Personal access token from https://app.unicatdb.org/

configuration = unicatdb.Configuration(
    access_token='<PASTE YOUR API KEY TOKEN HERE>'
)

# %% Query some data - e.g. apply filtering, sorting and paging during the API call to leave the heavy-lifting to the server

from unicatdb.openapi_client import UserScopedTenant, FindingArrayResponse, FindingFieldsQuery, PageQuery

with unicatdb.Client(configuration) as client:

    # list my available workspaces (a.k.a tenants) ...
    my_workspaces: List[UserScopedTenant] = client.tenants.api_tenants_available_get()
    pprint(my_workspaces)

    # ... and if I have one, list some of it's finding
    if my_workspaces:
        selected_workspace = my_workspaces[0]

        filter_expressions = {
            "taxonomyName.species": "like:vulgare"
        }
    
        fetch_only_fields = FindingFieldsQuery(findings="documentName,amount,dynamicData")
    
        findings: FindingArrayResponse = client.findings.api_findings_get(
            selected_workspace.id,
            sort="-amount",
            filter=filter_expressions,
            fields=fetch_only_fields,
            page=PageQuery(number=1,size=10)
        )
    
        pprint(findings)