Sequences Client tutorial¶

Introduction¶

This tutorial will show you how to use the refget.SequenceClient class to interact with a remote Refget sequences API.

Learning objectives

• How do I connect to a remote refget sequences API?
• How do I retrieve sequences by their digest?
• How do I get sequence metadata and service information?
• How does error handling work when sequences are not found?

First, record some versions used in this tutorial:

In [1]:

from platform import python_version 
python_version()

from platform import python_version python_version()

Out[1]:

'3.12.3'

In [2]:

import refget
refget.__version__

import refget refget.__version__

Out[2]:

'0.10.0'

Connecting to a remote API¶

The refget package provides a simple Python wrapper around a remote hosted refget sequences API. Provide the base url when construction a SequenceClient object and you can retrieve sequences from the remote server.

In [3]:

from refget.clients import SequenceClient

seq_client = SequenceClient(urls=["https://beta.ensembl.org/data/refget/"])

from refget.clients import SequenceClient seq_client = SequenceClient(urls=["https://beta.ensembl.org/data/refget/"])

In [4]:

seq_client.get_sequence("6681ac2f62509cfc220d78751b8dc524", start=0, end=10)

seq_client.get_sequence("6681ac2f62509cfc220d78751b8dc524", start=0, end=10)

Out[4]:

'CCACACCACA'

In [5]:

seq_client.get_sequence("6681ac2f62509cfc220d78751b8dc524", start=0, end=50)

seq_client.get_sequence("6681ac2f62509cfc220d78751b8dc524", start=0, end=50)

Out[5]:

'CCACACCACACCCACACACCCACACACCACACCACACACCACACCACACC'

You can also hit the {digest}/metadata and service_info API endpoints described in the refget API specification:

In [6]:

seq_client.get_metadata("6681ac2f62509cfc220d78751b8dc524")

seq_client.get_metadata("6681ac2f62509cfc220d78751b8dc524")

Out[6]:

{'metadata': {'id': '6681ac2f62509cfc220d78751b8dc524',
  'md5': '6681ac2f62509cfc220d78751b8dc524',
  'trunc512': '959cb1883fc1ca9ae1394ceb475a356ead1ecceff5824ae7',
  'ga4gh': 'SQ.lZyxiD_ByprhOUzrR1o1bq0ezO_1gkrn',
  'length': 230218,
  'aliases': []}}

In [7]:

seq_client.service_info()

seq_client.service_info()

Out[7]:

{'id': 'refget.infra.ebi.ac.uk',
 'name': 'Refget server',
 'type': {'group': 'org.ga4gh', 'artifact': 'refget', 'version': '2.0.0'},
 'description': None,
 'organization': {'name': 'EMBL-EBI', 'url': 'https://ebi.ac.uk/'},
 'contactUrl': None,
 'documentationUrl': None,
 'createdAt': None,
 'updatedAt': None,
 'environment': None,
 'version': '1.0.1',
 'refget': {'circular_supported': False,
  'subsequence_limit': None,
  'algorithms': ['md5', 'ga4gh', 'trunc512'],
  'identifier_types': None}}

Error handling¶

When requesting a sequence that doesn't exist, a compliant server should return a 404 error. The client will raise a ConnectionError if all URLs fail:

Note: Some servers may return different error codes (e.g., 500) for invalid digests. The client handles this by trying all configured URLs before failing.

In [8]:

seq_client.get_sequence('BogusDigest')

seq_client.get_sequence('BogusDigest')

All URLs failed:
Error from https://beta.ensembl.org/data/refget: 404 Client Error: Not Found for url: https://beta.ensembl.org/data/refget/sequence/BogusDigest

Summary

• SequenceClient(urls) connects to a remote refget sequences API
• client.get_sequence(digest) retrieves sequences, with optional start/end positions
• client.get_metadata(digest) returns sequence length and aliases