libica

Python SDK to programmatically call Illumina Connected Analytics (ICA) Genomic (multi-omics) data platform and BioInformatics web services. This SDK supports ICA v2 API.

• ICA v2 API: https://help.ica.illumina.com/reference/r-api
• Install through pip like so:

pip install libica

Overview

• Tested for Python 3.8, 3.9, 3.10, 3.11, 3.12
• See changelog and closed milestones
• Test Coverage
• Wiki
• SDK Guide: PyDoc
• User Guide: https://umccr-illumina.github.io/libica/

Roadmap

• See opening milestones for current planning and next SDK release

Example

• See examples directory for some example scripts
• See wrapica and icav2-cli-plugins for client application that build on top of SDK

Getting started with SDK for ICA v2

See pilot.py

# List all data in a project
import os
from contextlib import closing

from libica.openapi.v2 import Configuration, ApiClient, ApiException
from libica.openapi.v2.api.project_data_api import ProjectDataApi
from libica.openapi.v2.model.project_data import ProjectData
from libica.openapi.v2.model.project_data_paged_list import ProjectDataPagedList

if __name__ == '__main__':

    project_id = os.environ['ICAV2_PROJECT_ID']
    file_path = [""]  # empty will list everything under project

    icav2_access_token = os.environ['ICAV2_ACCESS_TOKEN']
    ica_url = "https://ica.illumina.com/ica/rest"

    configuration = Configuration(
        host=ica_url,
        access_token=icav2_access_token,
    )
    # configuration.debug = True  # uncomment to debug API call logging

    api_client = ApiClient(
        configuration=configuration,
        header_name="Content-Type",
        header_value="application/vnd.illumina.v3+json",
    )

    with closing(api_client) as ctx_api_client:
        project_data_api: ProjectDataApi = ProjectDataApi(api_client=ctx_api_client)

        try:
            page_token = ""
            while True:
                project_data_paged_list: ProjectDataPagedList = project_data_api.get_project_data_list(
                    project_id=project_id,
                    file_path=file_path,
                    page_size=str(1000),
                    page_token=page_token,
                )

                for item in project_data_paged_list.items:
                    project_data: ProjectData = item
                    print((
                        project_data.data.id,  # fil.<ID> (or) fol.<ID>
                        project_data.data.details.path,
                        project_data.data.details.data_type,
                    ))

                page_token = project_data_paged_list.next_page_token
                if not project_data_paged_list.next_page_token:
                    break

        except ApiException as e:
            print(e)

Development

• Setup virtual environment and activate it

• Install dev dependencies

make install

• To bring up mock API μ-services

make up

• To run tests suites

make unit
make autounit

• To run full suite, smoke test

make test

AutoGen Workflow

• SDK is autogenerated from OpenAPI definitions
• There are few tools required for this autogen workflow to work.
  1. openapi-generator-cli -- used to generate code and doc
  2. redocly/cli -- validate definitions
• Toolchains are as follows.

node -v
v20.17.0

npm i -g yarn
yarn -v
4.4.0

yarn install

yarn openapi-generator-cli help
yarn redocly lint --help

• API mock server prism is set up through docker compose as follows.

docker --version
Docker version 27.1.1, build 6312585

make up
make ps
make test_ica_mock
make test_icav2_mock
docker compose logs

• All the autogen config and arrangement refer to syncapi.sh and syncapi2.sh which is called through Makefile targets.

Generator Version

• See generator version compatibility
• Select generator version as follows:

yarn openapi-generator-cli version-manager list

Notice

• MIT License and DISCLAIMER
• The Advanced Genomics Collaboration (TAGC)