{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "# SequenceCollectionClient tutorial\n\n## Introduction \n\nThe `refget` Python package contains a class called `SequenceCollectionClient` that provides a simple Python API for interacting with a remote refget sequence collections server.\n\n<div class=\"admonition success\">\n  <p class=\"admonition-title\">Learning objectives</p>\n  <ul>\n    <li>How do I connect to a remote sequence collections API?</li>\n    <li>How do I list and retrieve sequence collections?</li>\n    <li>How do I compare two sequence collections?</li>\n    <li>How do I use pydantic models to work with collections locally?</li>\n  </ul>\n</div>"
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:47.191519Z",
     "iopub.status.busy": "2026-01-23T01:50:47.191359Z",
     "iopub.status.idle": "2026-01-23T01:50:47.233734Z",
     "shell.execute_reply": "2026-01-23T01:50:47.233281Z"
    }
   },
   "outputs": [],
   "source": [
    "import refget\n",
    "from refget.clients import SequenceCollectionClient"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connecting to a service\n",
    "\n",
    "In order to use the client, you'll need a remote service API to connect to.\n",
    "Then, you can create a `SequenceCollectionClient` to interact with the service from within Python.\n",
    "\n",
    "You can use the public instance at `https://seqcolapi.databio.org/` to test things out.\n",
    "\n",
    "Alternatively, you can start a local demo service by cloning the `refget` package (https://github.com/refgenie/refget) and running:\n",
    "\n",
    "```console\n",
    "bash deployment/demo_up.sh\n",
    "```\n",
    "\n",
    "This will launch a temporary postgres database and load it with 6 small demo sequences, and then run a barebones API service on localhost.\n",
    "\n",
    "For this demo, we'll connect to the public server:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:47.235300Z",
     "iopub.status.busy": "2026-01-23T01:50:47.235175Z",
     "iopub.status.idle": "2026-01-23T01:50:47.237297Z",
     "shell.execute_reply": "2026-01-23T01:50:47.237042Z"
    }
   },
   "outputs": [],
   "source": [
    "seqcol_client = SequenceCollectionClient(urls=[\"https://seqcolapi.databio.org\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:47.238305Z",
     "iopub.status.busy": "2026-01-23T01:50:47.238193Z",
     "iopub.status.idle": "2026-01-23T01:50:47.419138Z",
     "shell.execute_reply": "2026-01-23T01:50:47.418550Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SequenceCollectionClient>\n",
       "  Service ID: org.databio.seqcolapi\n",
       "  Service Name: Sequence collections\n",
       "  API URLs:    https://seqcolapi.databio.org"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Listing available sequence collections\n",
    "\n",
    "Now that you have a client connected to a server, you can interact with this object to query the API. First, check what sequence collections are available in this server: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:47.467296Z",
     "iopub.status.busy": "2026-01-23T01:50:47.467114Z",
     "iopub.status.idle": "2026-01-23T01:50:47.651241Z",
     "shell.execute_reply": "2026-01-23T01:50:47.650893Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'pagination': {'page': 0, 'page_size': 100, 'total': 181},\n",
       " 'results': ['QvT5tAQ0B8Vkxd-qFftlzEk2QyfPtgOv',\n",
       "  'Tpdsg75D4GKCGEHtIiDSL9Zx-DSuX5V8',\n",
       "  'UNGAdNDmBbQbHihecPPFxwTydTcdFKxL',\n",
       "  'sv7GIP1K0qcskIKF3iaBmQpaum21vH74',\n",
       "  'aVzHaGFlUDUNF2IEmNdzS_A8lCY0stQH',\n",
       "  'L5fggdWYz5tCr4v8XbPYoOwv79Sqmf1W',\n",
       "  'z96v5ZjkPeAOPWAkpncHa59zyhxlmA8C',\n",
       "  'cXJuMM86vTyFfDg8YmS4zz_Y5pxc9EMA',\n",
       "  'BY-s_FI0fxMmvkGCnpoz4z_Srp1QSnVF',\n",
       "  '9c-Gmzj9r3yI0EGRN5KXcEKZByxDRHJz',\n",
       "  'Wv2J0rQt9jGmemVOkUKbiCPeKKh7K4hF',\n",
       "  'Yl0xxd5KI6ck-HKE7mjqR0FGBSNCWsmP',\n",
       "  'tp9ZfZEkktdJCfmFlB1onGk9k8W7Xfjm',\n",
       "  'FZFXW2FOxEmBHn44zmjwBfapkZnI4Yzu',\n",
       "  '3E2NkEjuuq2ZX1_TVE9tvhdZ45XONDXY',\n",
       "  '7CsoHohLou-p0Z4Y_Gldm2bB3MEq4C9t',\n",
       "  '9NiCPDwk78tGarBtS5ha8vmnXykoP83S',\n",
       "  'ridlFVcLUGw5RsKjdoj-pgVB56C3ZhKS',\n",
       "  'ktq3ftHq5g-ugEpB8xnb_Cnk9c4Vzfg_',\n",
       "  '-Z38q8izmrexleQATeOvcp0sZo6aSXMa',\n",
       "  'YpME_umld1FGsSAlPZsJxz7q3Xz-UNo-',\n",
       "  'X-54vS61VplNRcN3GJ0QHxqN7I5FFMKj',\n",
       "  '7XbdAKmGnJHJOBicVGkt4hBt0W0z2zB9',\n",
       "  'EnZH-5CYVPgSxnnKFQ0-xro5OOrCbj_K',\n",
       "  'lT6s6i5mJWLjlSTtk1u1fzBsud-R1z3K',\n",
       "  'hBL_bP6_TMwNz6d2onDk4exTM05pH571',\n",
       "  'qx2unhq5rrjuRcBeVxW6-92Wl3hA8LPY',\n",
       "  'cUGYma8HKNZ-Qzy2UCDa-RUB1QlW2vcW',\n",
       "  '5ctzQDRIPLAVfzhX81OzXj1A6ofPIHXh',\n",
       "  'BARU2J9BmUUzKIoRJk8SlazBLgG_WnMB',\n",
       "  'uMILkzcfBLWf56Xq1PBK5UDaIalRdjEY',\n",
       "  'viakH33D2OTwAAIYXcTn2rY2ArcJ486R',\n",
       "  'xI7Bug9JJh5cUUcq_HI6ONaVjOeN2yEa',\n",
       "  'foP8Q5nxO0YZ1H7m2GN_xZGmbHXWCNIn',\n",
       "  '1xqSjxx5xeZRYfo0sVKjV82bJKfxiNPH',\n",
       "  'ErA56bpzOfKEvKi9uTFmRz8nR595EH5h',\n",
       "  'tfNkR4jeFw8qKAYtOpHYRh01Et-CBXwV',\n",
       "  'BlDP0j9QzBeAbvKdkprFR3vyDUTvzezl',\n",
       "  'F_lbBpEe8Co3ZFgkdkAMAq8tqlJOO6BK',\n",
       "  'noca7T51pn-dra2DMpMeRMcTFlk9q2_p',\n",
       "  'uylVMt4BIYBOfnMEPRUX7VVbnQufeGZr',\n",
       "  'Pv-mz-TS6t-rAyYf41UjiPWuJ6rK3R05',\n",
       "  'Yn1FqmexS1iucDjTXRWw2Gg2Vj7bTcsT',\n",
       "  'FQh-53xvRuCNaIiCmCg9nfOdngNfyEhf',\n",
       "  's0nMiOFHPsIBrm2bd3PkzWXKLKWQZq70',\n",
       "  'FAImtq4VUhjhCzA8XUVeaPbN-FPP_dc1',\n",
       "  'WlLs87buR_PgAdrYGkD1tn1dExkPo7WO',\n",
       "  'kBKu6z2ngo2XZ-vxUaJ3RbtTwK9fR9UC',\n",
       "  'J8YisyMpdmvsIcd7SQQvSsp58G38h0eT',\n",
       "  'zZDivqzD2pxfCT4OiWa0ApQDuXB_I9Q7',\n",
       "  'P4qZHOwdErr9jB1RkyspfUqLMPazkU81',\n",
       "  'x1n0w2sabOjURD3JnXzh1oILsnHD7cze',\n",
       "  '9pWYhSXKoPs5MztgG7lW6WbM6Nww5SSr',\n",
       "  'Up7qPEU3wLWvyPk5pAf_ophGONWttqBo',\n",
       "  'S60ZrqFZW2btcYS_54hQhqLwB_PG46vS',\n",
       "  'YtHbWHlP60GTZCncgUBjMOPmp2ADfq2J',\n",
       "  's1oLd_T8-4SF_SQ7NJ24Eqc3cOqiWFha',\n",
       "  '71sPqYAdG9B62MdODjOGBO9n34Oamukl',\n",
       "  'R105AJTp5LXkugKvtrpe0J1qhkXBndOe',\n",
       "  '9ejLildtKroMlW_--YOf7OIEvhIQ42xv',\n",
       "  'N22SVILZfhznaY_8FLYBpaMw2By-_J9Y',\n",
       "  'RGLI3hkWHeWUGSBXtS8BN80KZVX0K8im',\n",
       "  't4ndxEKXlH5dgCcm1nQMd57HbXA7ExIf',\n",
       "  'AJTqvyFQv1mzQGUlzqLha92UYCH5fCqv',\n",
       "  'e0OIqapSqCGDsa-6glrVq3PED1AHB5AY',\n",
       "  '-Sfh5nx4f7dSrGDdfmz7xA0nsN5jh-mN',\n",
       "  'D115Vk9KZyz5NIxf6udt0fpXaFaArK-1',\n",
       "  '2VZUmoMe5uteOo5nLZXc8-71IU6e82cS',\n",
       "  'IvT_UNXmjZ4MCVuNAYC8zqN6sUdKdj23',\n",
       "  'ah6D9N3T9vQB-ilo3Y2fMBZVfl38ejiu',\n",
       "  'eC3SeAJvdmDHQ9-YwEcAcXupcFb633wG',\n",
       "  'G-lXbNy5hM1rt0XTLAUfJpVZIVT_ZgpE',\n",
       "  'XnH51MmuPgO2TNhlEiANnFQ2wvTYdNor',\n",
       "  'jAgF570djYDrb7L9kBfLZ46fCPWiS5TW',\n",
       "  'FH-REWvpU7rtFRmBiIa_2ep7OciOW4GR',\n",
       "  '5PllS1Hx4hsVQbhz84-1qJ5ZZQOWAqNu',\n",
       "  'JTKSBZJsyIzdS1IK1KKTdiCpC3nmqs1i',\n",
       "  'KZ1LmrEYEsAvtF4v3wUBXuPENsOF0T8c',\n",
       "  'qBmTdlCFm2J4cy9pQDJFYAAhulYftM8L',\n",
       "  'qu9RljQ54ocenwxL1nwhbOwwhUXB-Jyi',\n",
       "  '41awQ9hgSvnbePsbamrEck9Pfj-lxoI-',\n",
       "  'sEX03-p2sKmrN6DpsWxo1_uQVC8GxT8L',\n",
       "  'R903f2HZFUgV3WtHy2-bkyNg9-7Nu0v7',\n",
       "  '0qveCdMlbF_kYn6XWb7YBy-FtRZ6gSAL',\n",
       "  'v8p2oLGpP6w9_wIK0CQ9WEgaCiHPGL9x',\n",
       "  '8KHugp4XuYhEmPCmZ3jF2p5gdii399Ao',\n",
       "  'k0GGcUuZsX2r8ffpikvlVYm57Rxm-8_z',\n",
       "  'awlJ5Q7EPDVlwXWH8LPN93oJ5jY2uajW',\n",
       "  '6DfkalgYxFZiYAKpJf19dbpnS-dGzi4m',\n",
       "  'WwIG41XDzO0BTmEpzT7nPXv6Dfx7h4ju',\n",
       "  'Hve5dblWYLxu1p9Cp930NB8twHGCsf6X',\n",
       "  '2WhejNO718T5jvB4DVTAz-A_JF03iIkz',\n",
       "  'XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk',\n",
       "  'WwRUlIPk1nsiORfSBJ8DDjKMYLA7Awa1',\n",
       "  '5U4uuCojgp6NAMQsDl3YljwOfya_lczj',\n",
       "  'n-7ePSo865wXqyAoED8M0hxM9MwqiFr4',\n",
       "  'gjDBvYx_b8sLCOPq1hPHWiGHyuzph3iR',\n",
       "  'S2LsYzDB_k60GIQM6omCxqD_NvmvCwn5',\n",
       "  'tnf8kmb_OfmKlY5q8xsdmXMb05dNOCH1',\n",
       "  'n-EXNThlm5QoXUZUBUsV5Np0467xppj0']}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.list_collections()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This gives you top-level digests for the collections.\n",
    "\n",
    "## Retrieving a sequence collection\n",
    "\n",
    "Retrieve a collections using its digest like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:47.652609Z",
     "iopub.status.busy": "2026-01-23T01:50:47.652460Z",
     "iopub.status.idle": "2026-01-23T01:50:47.849221Z",
     "shell.execute_reply": "2026-01-23T01:50:47.848495Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'lengths': [8, 4, 4],\n",
       " 'names': ['chrX', 'chr1', 'chr2'],\n",
       " 'sequences': ['SQ.iYtREV555dUFKg2_agSJW6suquUyPpMw',\n",
       "  'SQ.YBbVX0dLKG1ieEDCiMmkrTZFt_Z5Vdaj',\n",
       "  'SQ.AcLxtBuKEPk_7PGE_H4dGElwZHCujwH6'],\n",
       " 'sorted_sequences': ['SQ.AcLxtBuKEPk_7PGE_H4dGElwZHCujwH6',\n",
       "  'SQ.YBbVX0dLKG1ieEDCiMmkrTZFt_Z5Vdaj',\n",
       "  'SQ.iYtREV555dUFKg2_agSJW6suquUyPpMw'],\n",
       " 'name_length_pairs': [{'length': 8, 'name': 'chrX'},\n",
       "  {'length': 4, 'name': 'chr1'},\n",
       "  {'length': 4, 'name': 'chr2'}]}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.get_collection(\"XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This gives you the **level 2** representation of the sequence collection, which is the canonical, expanded representation. You can also request the more compact **level 1** representation, which gives you digests for each of the attributes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:47.851734Z",
     "iopub.status.busy": "2026-01-23T01:50:47.851559Z",
     "iopub.status.idle": "2026-01-23T01:50:48.026680Z",
     "shell.execute_reply": "2026-01-23T01:50:48.026135Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'lengths': 'cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX',\n",
       " 'names': 'Fw1r9eRxfOZD98KKrhlYQNEdSRHoVxAG',\n",
       " 'sequences': '0uDQVLuHaOZi1u76LjV__yrVUIz9Bwhr',\n",
       " 'sorted_sequences': 'KgWo6TT1Lqw6vgkXU9sYtCU9xwXoDt6M',\n",
       " 'name_length_pairs': 'B9MESWM8k-hK_OeQK8bZNAG74pLY0Ujq',\n",
       " 'sorted_name_length_pairs': 'zjM1Ie9m0zFbqsAnZ6jAJSXuFpKTr40J'}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.get_collection(\"XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk\", level=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These attributes are useful because you can use them in the same way you use a top-level sequence digest to look up values of a specific attribute using the `get_attribute` function.\n",
    "\n",
    "For example, here we will use the lengths digest to retrieve just the value of this attribute.\n",
    "You can see it matches the expanded version retrieved above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:48.028760Z",
     "iopub.status.busy": "2026-01-23T01:50:48.028558Z",
     "iopub.status.idle": "2026-01-23T01:50:48.183827Z",
     "shell.execute_reply": "2026-01-23T01:50:48.183123Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[8, 4, 4]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.get_attribute(\"lengths\", \"cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also discover attributes available in the server with the `list_attributes` function, which will list all available values of a specific attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:48.185532Z",
     "iopub.status.busy": "2026-01-23T01:50:48.185310Z",
     "iopub.status.idle": "2026-01-23T01:50:48.356229Z",
     "shell.execute_reply": "2026-01-23T01:50:48.355611Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'pagination': {'page': 0, 'page_size': 3, 'total': 155},\n",
       " 'results': ['cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX',\n",
       "  'x5qpE4FtMkvlwpKIzvHs3a02Nex5tthp',\n",
       "  '7-_HdxYiRf-AJLBKOTaJUdxXrUkIXs6T']}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.list_attributes(\"lengths\", page_size=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Discovering sequence collections with specific attributes\n",
    "\n",
    "One of the useful applications of attribute digests is that we can use them to discover other sequence collections that share a specific attribute value. \n",
    "\n",
    "For example, say we want to find all the collections hosted by this server that have the particular set of sequence lengths `[8,4,4]`.\n",
    "We can use the `list_collections` function again, but this time adding some new parameters to specify that we want to retrieve the collections with a specific value for the `lengths` attribute, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:48.358521Z",
     "iopub.status.busy": "2026-01-23T01:50:48.358291Z",
     "iopub.status.idle": "2026-01-23T01:50:48.548924Z",
     "shell.execute_reply": "2026-01-23T01:50:48.548278Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'pagination': {'page': 0, 'page_size': 2, 'total': 181},\n",
       " 'results': ['QvT5tAQ0B8Vkxd-qFftlzEk2QyfPtgOv',\n",
       "  'Tpdsg75D4GKCGEHtIiDSL9Zx-DSuX5V8']}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.list_collections(page=0, \n",
    "                               page_size=2, \n",
    "                               lengths=\"cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will allow you to identify other sequence collections.\n",
    "\n",
    "## Comparing two sequence collections\n",
    "\n",
    "One of the powerful advanced features of the sequence collections standard is the comparison function, which allows you to get detailed information about how similar two sequence collections are. \n",
    "\n",
    "In this example, let's compare the two sequence collections that had identical `lengths` attributes, to see how these two collections differ. Remember, if they had no differences, they would have the same top-level digest, so we know they're different somehow... the comparison function will give us more information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:48.551282Z",
     "iopub.status.busy": "2026-01-23T01:50:48.551035Z",
     "iopub.status.idle": "2026-01-23T01:50:48.760605Z",
     "shell.execute_reply": "2026-01-23T01:50:48.760015Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'digests': {'a': 'UNGAdNDmBbQbHihecPPFxwTydTcdFKxL',\n",
       "  'b': 'aVzHaGFlUDUNF2IEmNdzS_A8lCY0stQH'},\n",
       " 'attributes': {'a_only': [],\n",
       "  'b_only': [],\n",
       "  'a_and_b': ['lengths',\n",
       "   'name_length_pairs',\n",
       "   'names',\n",
       "   'sequences',\n",
       "   'sorted_sequences']},\n",
       " 'array_elements': {'a': {'lengths': 3,\n",
       "   'name_length_pairs': 3,\n",
       "   'names': 3,\n",
       "   'sequences': 3,\n",
       "   'sorted_sequences': 3},\n",
       "  'b': {'lengths': 3,\n",
       "   'name_length_pairs': 3,\n",
       "   'names': 3,\n",
       "   'sequences': 3,\n",
       "   'sorted_sequences': 3},\n",
       "  'a_and_b': {'lengths': 3,\n",
       "   'name_length_pairs': 1,\n",
       "   'names': 3,\n",
       "   'sequences': 3,\n",
       "   'sorted_sequences': 3},\n",
       "  'a_and_b_same_order': {'lengths': True,\n",
       "   'name_length_pairs': True,\n",
       "   'names': False,\n",
       "   'sequences': True,\n",
       "   'sorted_sequences': True}}}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol_client.compare(\n",
    "    \"UNGAdNDmBbQbHihecPPFxwTydTcdFKxL\",\n",
    "    \"aVzHaGFlUDUNF2IEmNdzS_A8lCY0stQH\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This comparison output gives us a lot of detail. You can get the full details on how to interpret the results in the [documentation on comparing sequence collections](https://ga4gh.github.io/refget/compare_collections/).\n",
    "\n",
    "Briefly, we can see that the collections each have 3 sequences, and these are mostly matching -- the only value under `array_elements` that is not 3 is the `name_length_pairs`, which is 1. We can also see that the `a_and_b_same_order` says `names: False`. This means we are dealing with two collections, in which one pair of sequences has had the names swapped -- the names are all the same, but not in the right order. The lengths are identical and in the same order (which is why we pulled these two collections out by filtering by length attribute digest). And the sequence contents are also the same, and in the same order. The only reason these aren't the same collection is the name swap.\n",
    "\n",
    "This example shows how the comparison function can be used to provide deep insight into how two sequence collections compare.\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using pydantic models\n",
    "\n",
    "One of the really cool things about the `refget` package is that it provides pydantic models for sequence collections and other relevant data types. We can use these objects to analyze and manage sequence collections locally. Let's walk through some of the things you can do with these objects.\n",
    "\n",
    "We provide a `SequenceCollection` object that gives you some nice ways to interact with these objects in Python. From a dictionary representation you retrieve from an API, you can construct a Pydantic object like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:48.763206Z",
     "iopub.status.busy": "2026-01-23T01:50:48.762913Z",
     "iopub.status.idle": "2026-01-23T01:50:49.276551Z",
     "shell.execute_reply": "2026-01-23T01:50:49.275959Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "SequenceCollection(digest='XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk', sorted_name_length_pairs_digest='zjM1Ie9m0zFbqsAnZ6jAJSXuFpKTr40J')"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from refget.models import SequenceCollection\n",
    "\n",
    "seqcol_dict = seqcol_client.get_collection(\"XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk\")\n",
    "seqcol = SequenceCollection.from_dict(seqcol_dict)\n",
    "seqcol"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This object is very useful. You can use it to get this sequence collection in a variety of different formats:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:49.277986Z",
     "iopub.status.busy": "2026-01-23T01:50:49.277788Z",
     "iopub.status.idle": "2026-01-23T01:50:49.281264Z",
     "shell.execute_reply": "2026-01-23T01:50:49.280832Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'lengths': [8, 4, 4],\n",
       " 'names': ['chrX', 'chr1', 'chr2'],\n",
       " 'sequences': ['SQ.iYtREV555dUFKg2_agSJW6suquUyPpMw',\n",
       "  'SQ.YBbVX0dLKG1ieEDCiMmkrTZFt_Z5Vdaj',\n",
       "  'SQ.AcLxtBuKEPk_7PGE_H4dGElwZHCujwH6'],\n",
       " 'sorted_sequences': ['SQ.AcLxtBuKEPk_7PGE_H4dGElwZHCujwH6',\n",
       "  'SQ.YBbVX0dLKG1ieEDCiMmkrTZFt_Z5Vdaj',\n",
       "  'SQ.iYtREV555dUFKg2_agSJW6suquUyPpMw'],\n",
       " 'name_length_pairs': [{'length': 8, 'name': 'chrX'},\n",
       "  {'length': 4, 'name': 'chr1'},\n",
       "  {'length': 4, 'name': 'chr2'}]}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol.level2()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:49.282461Z",
     "iopub.status.busy": "2026-01-23T01:50:49.282357Z",
     "iopub.status.idle": "2026-01-23T01:50:49.285195Z",
     "shell.execute_reply": "2026-01-23T01:50:49.284793Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'lengths': 'cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX',\n",
       " 'names': 'Fw1r9eRxfOZD98KKrhlYQNEdSRHoVxAG',\n",
       " 'sequences': '0uDQVLuHaOZi1u76LjV__yrVUIz9Bwhr',\n",
       " 'sorted_sequences': 'KgWo6TT1Lqw6vgkXU9sYtCU9xwXoDt6M',\n",
       " 'name_length_pairs': 'B9MESWM8k-hK_OeQK8bZNAG74pLY0Ujq',\n",
       " 'sorted_name_length_pairs': 'zjM1Ie9m0zFbqsAnZ6jAJSXuFpKTr40J'}"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol.level1()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:49.286333Z",
     "iopub.status.busy": "2026-01-23T01:50:49.286219Z",
     "iopub.status.idle": "2026-01-23T01:50:49.288950Z",
     "shell.execute_reply": "2026-01-23T01:50:49.288550Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX'"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol.lengths.digest"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:49.290021Z",
     "iopub.status.busy": "2026-01-23T01:50:49.289920Z",
     "iopub.status.idle": "2026-01-23T01:50:49.292838Z",
     "shell.execute_reply": "2026-01-23T01:50:49.292423Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'name': 'chrX',\n",
       "  'length': 8,\n",
       "  'sequence': 'SQ.iYtREV555dUFKg2_agSJW6suquUyPpMw'},\n",
       " {'name': 'chr1',\n",
       "  'length': 4,\n",
       "  'sequence': 'SQ.YBbVX0dLKG1ieEDCiMmkrTZFt_Z5Vdaj'},\n",
       " {'name': 'chr2',\n",
       "  'length': 4,\n",
       "  'sequence': 'SQ.AcLxtBuKEPk_7PGE_H4dGElwZHCujwH6'}]"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol.itemwise()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can access individual attributes like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:49.293976Z",
     "iopub.status.busy": "2026-01-23T01:50:49.293873Z",
     "iopub.status.idle": "2026-01-23T01:50:49.296661Z",
     "shell.execute_reply": "2026-01-23T01:50:49.296214Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'B9MESWM8k-hK_OeQK8bZNAG74pLY0Ujq'"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol.name_length_pairs.digest"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:50:49.297739Z",
     "iopub.status.busy": "2026-01-23T01:50:49.297638Z",
     "iopub.status.idle": "2026-01-23T01:50:49.300509Z",
     "shell.execute_reply": "2026-01-23T01:50:49.300035Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'length': 8, 'name': 'chrX'},\n",
       " {'length': 4, 'name': 'chr1'},\n",
       " {'length': 4, 'name': 'chr2'}]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seqcol.name_length_pairs.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because this is a `SQLModel` object, you could also use this to create and interact with a database easily. You can find reference documentation in the [models](/refget/reference/models/) section."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "<div class=\"admonition success\">\n  <p class=\"admonition-title\">Summary</p>\n  <ul>\n    <li><code>SequenceCollectionClient(urls)</code> connects to a remote seqcol API</li>\n    <li><code>client.list_collections()</code> and <code>client.get_collection(digest)</code> for listing and retrieval</li>\n    <li><code>client.compare(digest_a, digest_b)</code> shows detailed differences between collections</li>\n    <li><code>SequenceCollection.from_dict()</code> creates pydantic models for local manipulation</li>\n  </ul>\n</div>"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}