{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# BCR clustering\n",
    "\n",
    "![dandelion_logo](img/dandelion_logo_illustration.png)\n",
    "\n",
    "On the topic of finding clones/clonotypes, there are many ways used for clustering BCRs, almost all involving some measure based on sequence similarity. There are also a lot of very well established guidelines and criterias maintained by the BCR community. For example, *immcantation* uses a number of model-based [methods](https://changeo.readthedocs.io/en/stable/methods/clustering.html) to group clones based on the distribution of length-normalised junctional hamming distance while others use the whole BCR V(D)J sequence to define clones as shown in this recent [paper](https://www.nature.com/articles/s41586-019-1595-3.pdf)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***Import modules***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dandelion==0.1.0 pandas==1.1.4 numpy==1.19.4 matplotlib==3.3.3 networkx==2.5 scipy==1.5.3 skbio==0.5.6\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "import pandas as pd\n",
    "import dandelion as ddl\n",
    "ddl.logging.print_header()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "scanpy==1.6.0 anndata==0.7.4 umap==0.4.6 numpy==1.19.4 scipy==1.5.3 pandas==1.1.4 scikit-learn==0.23.2 statsmodels==0.12.1 python-igraph==0.8.3 leidenalg==0.8.3\n"
     ]
    }
   ],
   "source": [
    "# change directory to somewhere more workable\n",
    "os.chdir(os.path.expanduser('/Users/kt16/Downloads/dandelion_tutorial/'))\n",
    "# I'm importing scanpy here to make use of its logging module.\n",
    "import scanpy as sc\n",
    "sc.settings.verbosity = 3\n",
    "import warnings\n",
    "warnings.filterwarnings('ignore')\n",
    "sc.logging.print_header()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***Read in the previously saved files***\n",
    "\n",
    "I will work with the same example from the previous notebook since I have the filtered V(D)J data stored in a `Dandelion` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dandelion class object with n_obs = 838 and n_contigs = 1700\n",
       "    data: 'sequence_id', 'sequence', 'rev_comp', 'productive', 'v_call', 'd_call', 'j_call', 'sequence_alignment', 'germline_alignment', 'junction', 'junction_aa', 'v_cigar', 'd_cigar', 'j_cigar', 'stop_codon', 'vj_in_frame', 'locus', 'junction_length', 'np1_length', 'np2_length', 'v_sequence_start', 'v_sequence_end', 'v_germline_start', 'v_germline_end', 'd_sequence_start', 'd_sequence_end', 'd_germline_start', 'd_germline_end', 'j_sequence_start', 'j_sequence_end', 'j_germline_start', 'j_germline_end', 'v_score', 'v_identity', 'v_support', 'd_score', 'd_identity', 'd_support', 'j_score', 'j_identity', 'j_support', 'fwr1', 'fwr2', 'fwr3', 'fwr4', 'cdr1', 'cdr2', 'cdr3', 'cell_id', 'c_call', 'consensus_count', 'umi_count', 'v_call_10x', 'd_call_10x', 'j_call_10x', 'junction_10x', 'junction_10x_aa', 'v_call_genotyped', 'germline_alignment_d_mask', 'sample_id', 'c_sequence_alignment', 'c_germline_alignment', 'c_sequence_start', 'c_sequence_end', 'c_score', 'c_identity', 'c_support', 'c_call_10x', 'junction_aa_length', 'fwr1_aa', 'fwr2_aa', 'fwr3_aa', 'fwr4_aa', 'cdr1_aa', 'cdr2_aa', 'cdr3_aa', 'sequence_alignment_aa', 'v_sequence_alignment_aa', 'd_sequence_alignment_aa', 'j_sequence_alignment_aa', 'mu_freq', 'duplicate_count'\n",
       "    metadata: 'sample_id', 'locus_heavy', 'locus_light', 'productive_heavy', 'productive_light', 'v_call_genotyped_heavy', 'v_call_genotyped_light', 'j_call_heavy', 'j_call_light', 'c_call_heavy', 'c_call_light', 'umi_count_heavy_0', 'umi_count_light_0', 'umi_count_light_1', 'umi_count_light_2', 'junction_aa_heavy', 'junction_aa_light', 'status', 'productive', 'isotype', 'vdj_status_detail', 'vdj_status'\n",
       "    distance: None\n",
       "    edges: None\n",
       "    layout: None\n",
       "    graph: None"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vdj = ddl.read_h5('dandelion_results.h5')\n",
    "vdj"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finding clones\n",
    "\n",
    "The following is *dandelion*'s implementation of a rather conventional method to define clones, `tl.find_clones`. \n",
    "\n",
    "Clone definition is based on the following criterias:\n",
    "\n",
    "    (1) Identical IGH V-J gene usage.\n",
    "\n",
    "    (2) Identical CDR3 junctional sequence length.\n",
    "\n",
    "    (3) CDR3 Junctional sequences attains a minimum of % sequence similarity, based on hamming distance. The similarity cut-off is tunable (default is 85%).\n",
    "\n",
    "    (4) Light chain usage. If cells within clones use different light chains, the clone will be splitted following the same conditions for heavy chains in (1-3) as above. \n",
    "\n",
    "The 'clone_id' name follows a `{A}_{B}_{C}_{D}` format and largely reflects the conditions above where:\n",
    "\n",
    "    {A} indicates if the contigs use the same IGH V/J genes.\n",
    "    \n",
    "    {B} indicates if IGH junctional sequences are equal in length.\n",
    "    \n",
    "    {C} indicates if clones are splitted based on junctional hamming distance threshold\n",
    "    \n",
    "    {D} indicates light chain pairing. \n",
    "\n",
    "The last position will not be annotated if there's only one group of light chains usage detected in the clone."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Running `tl.find_clones`\n",
    "The function will take a file path, a pandas `DataFrame` (for example if you've used pandas to read in the filtered file already), or a `Dandelion` class object. The default mode for calculation of junctional hamming distance is to use the CDR3 junction amino acid sequences, specified via the `key` option (`None` defaults to `junction_aa`). You can switch it to using CDR3 junction nucleotide sequences (`key = 'junction'`, or even the full V(D)J amino acid sequence (`key = 'sequence_alignment_aa`), as long as the column name exists in the `.data` slot.\n",
    "\n",
    "If you want to use the alleles for defining V-J gene usuage, specify:\n",
    "```python\n",
    "by_alleles = True\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Finding clonotypes\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Finding clones based on heavy chains : 100%|██████████| 176/176 [00:00<00:00, 2821.65it/s]\n",
      "Refining clone assignment based on light chain pairing : 100%|██████████| 819/819 [00:00<00:00, 1216.02it/s]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " finished: Updated Dandelion object: \n",
      "   'data', contig-indexed clone table\n",
      "   'metadata', cell-indexed clone table\n",
      " (0:00:01)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "Dandelion class object with n_obs = 838 and n_contigs = 1700\n",
       "    data: 'sequence_id', 'sequence', 'rev_comp', 'productive', 'v_call', 'd_call', 'j_call', 'sequence_alignment', 'germline_alignment', 'junction', 'junction_aa', 'v_cigar', 'd_cigar', 'j_cigar', 'stop_codon', 'vj_in_frame', 'locus', 'junction_length', 'np1_length', 'np2_length', 'v_sequence_start', 'v_sequence_end', 'v_germline_start', 'v_germline_end', 'd_sequence_start', 'd_sequence_end', 'd_germline_start', 'd_germline_end', 'j_sequence_start', 'j_sequence_end', 'j_germline_start', 'j_germline_end', 'v_score', 'v_identity', 'v_support', 'd_score', 'd_identity', 'd_support', 'j_score', 'j_identity', 'j_support', 'fwr1', 'fwr2', 'fwr3', 'fwr4', 'cdr1', 'cdr2', 'cdr3', 'cell_id', 'c_call', 'consensus_count', 'umi_count', 'v_call_10x', 'd_call_10x', 'j_call_10x', 'junction_10x', 'junction_10x_aa', 'v_call_genotyped', 'germline_alignment_d_mask', 'sample_id', 'c_sequence_alignment', 'c_germline_alignment', 'c_sequence_start', 'c_sequence_end', 'c_score', 'c_identity', 'c_support', 'c_call_10x', 'junction_aa_length', 'fwr1_aa', 'fwr2_aa', 'fwr3_aa', 'fwr4_aa', 'cdr1_aa', 'cdr2_aa', 'cdr3_aa', 'sequence_alignment_aa', 'v_sequence_alignment_aa', 'd_sequence_alignment_aa', 'j_sequence_alignment_aa', 'mu_freq', 'duplicate_count', 'clone_id'\n",
       "    metadata: 'clone_id', 'clone_id_by_size', 'sample_id', 'locus_heavy', 'locus_light', 'productive_heavy', 'productive_light', 'v_call_genotyped_heavy', 'v_call_genotyped_light', 'j_call_heavy', 'j_call_light', 'c_call_heavy', 'c_call_light', 'umi_count_heavy_0', 'umi_count_light_0', 'umi_count_light_1', 'umi_count_light_2', 'junction_aa_heavy', 'junction_aa_light', 'status', 'productive', 'isotype', 'vdj_status_detail', 'vdj_status'\n",
       "    distance: None\n",
       "    edges: None\n",
       "    layout: None\n",
       "    graph: None"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ddl.tl.find_clones(vdj)\n",
    "vdj"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will return a new column with the column name `'clone_id'` as per convention. If a file path is provided as input, it will also save the file automatically into the base directory of the file name. Otherwise, a `Dandelion` object will be returned."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>clone_id</th>\n",
       "      <th>clone_id_by_size</th>\n",
       "      <th>sample_id</th>\n",
       "      <th>locus_heavy</th>\n",
       "      <th>locus_light</th>\n",
       "      <th>productive_heavy</th>\n",
       "      <th>productive_light</th>\n",
       "      <th>v_call_genotyped_heavy</th>\n",
       "      <th>v_call_genotyped_light</th>\n",
       "      <th>j_call_heavy</th>\n",
       "      <th>...</th>\n",
       "      <th>umi_count_light_0</th>\n",
       "      <th>umi_count_light_1</th>\n",
       "      <th>umi_count_light_2</th>\n",
       "      <th>junction_aa_heavy</th>\n",
       "      <th>junction_aa_light</th>\n",
       "      <th>status</th>\n",
       "      <th>productive</th>\n",
       "      <th>isotype</th>\n",
       "      <th>vdj_status_detail</th>\n",
       "      <th>vdj_status</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC</th>\n",
       "      <td>140_3_1</td>\n",
       "      <td>362</td>\n",
       "      <td>sc5p_v2_hs_PBMC_10k</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGK</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV1-69</td>\n",
       "      <td>IGKV1-8</td>\n",
       "      <td>IGHJ3</td>\n",
       "      <td>...</td>\n",
       "      <td>43.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CATTYYYDSSGYYQNDAFDIW</td>\n",
       "      <td>CQQYYSYPRTF</td>\n",
       "      <td>IGH + IGK</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG</th>\n",
       "      <td>88_4_1</td>\n",
       "      <td>278</td>\n",
       "      <td>sc5p_v2_hs_PBMC_10k</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGL</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV1-2</td>\n",
       "      <td>IGLV5-45</td>\n",
       "      <td>IGHJ3</td>\n",
       "      <td>...</td>\n",
       "      <td>90.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CAREIEGDGVFEIW</td>\n",
       "      <td>CMIWHSSAWVV</td>\n",
       "      <td>IGH + IGL</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC</th>\n",
       "      <td>98_2_2</td>\n",
       "      <td>726</td>\n",
       "      <td>sc5p_v2_hs_PBMC_10k</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGK</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV5-51</td>\n",
       "      <td>IGKV1D-8</td>\n",
       "      <td>IGHJ3</td>\n",
       "      <td>...</td>\n",
       "      <td>22.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CARHIRGNRFGNDAFDIW</td>\n",
       "      <td>CQQYYSFPYTF</td>\n",
       "      <td>IGH + IGK</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT</th>\n",
       "      <td>64_8_1</td>\n",
       "      <td>645</td>\n",
       "      <td>sc5p_v2_hs_PBMC_10k</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGL</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV3-15</td>\n",
       "      <td>IGLV6-57</td>\n",
       "      <td>IGHJ4</td>\n",
       "      <td>...</td>\n",
       "      <td>40.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CTTDDEKRPYSGSYLPFDYW</td>\n",
       "      <td>CQSYDSSNVVF</td>\n",
       "      <td>IGH + IGL</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Multi_light_j</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT</th>\n",
       "      <td>9_4_1</td>\n",
       "      <td>677</td>\n",
       "      <td>sc5p_v2_hs_PBMC_10k</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGL</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV3-33</td>\n",
       "      <td>IGLV2-14</td>\n",
       "      <td>IGHJ6</td>\n",
       "      <td>...</td>\n",
       "      <td>36.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CARDWVRGVNDMDVW</td>\n",
       "      <td>CSSYTSSSTRVF</td>\n",
       "      <td>IGH + IGL</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG</th>\n",
       "      <td>63_8_2</td>\n",
       "      <td>181</td>\n",
       "      <td>vdj_v1_hs_pbmc3</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGK</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV4-59</td>\n",
       "      <td>IGKV1-12</td>\n",
       "      <td>IGHJ4</td>\n",
       "      <td>...</td>\n",
       "      <td>33.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CARVNVGGIAVAGYFDYW</td>\n",
       "      <td>CQQANSFPLTF</td>\n",
       "      <td>IGH + IGK</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT</th>\n",
       "      <td>128_8_1</td>\n",
       "      <td>723</td>\n",
       "      <td>vdj_v1_hs_pbmc3</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGK</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV3-21</td>\n",
       "      <td>IGKV3-20</td>\n",
       "      <td>IGHJ6</td>\n",
       "      <td>...</td>\n",
       "      <td>18.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CARVRQEYYDFWSGYPAEVYYYMDVW</td>\n",
       "      <td>CQQYGSSPLFTF</td>\n",
       "      <td>IGH + IGK</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG</th>\n",
       "      <td>146_7_2</td>\n",
       "      <td>799</td>\n",
       "      <td>vdj_v1_hs_pbmc3</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGL</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV3-48</td>\n",
       "      <td>IGLV2-14</td>\n",
       "      <td>IGHJ4</td>\n",
       "      <td>...</td>\n",
       "      <td>80.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CAREKYDFWSGDSYYFDYW</td>\n",
       "      <td>CSSYTSSSTRVF</td>\n",
       "      <td>IGH + IGL</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Single</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT</th>\n",
       "      <td>145_4_2</td>\n",
       "      <td>276</td>\n",
       "      <td>vdj_v1_hs_pbmc3</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGK</td>\n",
       "      <td>T</td>\n",
       "      <td>T</td>\n",
       "      <td>IGHV4-34</td>\n",
       "      <td>IGKV1-39|IGKV1D-39</td>\n",
       "      <td>IGHJ3</td>\n",
       "      <td>...</td>\n",
       "      <td>5.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CARRRLTYYYDSSGPLSAFDIW</td>\n",
       "      <td>CQQSYSTPRTF</td>\n",
       "      <td>IGH + IGK</td>\n",
       "      <td>T + T</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Multi_light_v</td>\n",
       "      <td>Single</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC</th>\n",
       "      <td>124_4_1_1|124_4_1_2</td>\n",
       "      <td>635|368</td>\n",
       "      <td>vdj_v1_hs_pbmc3</td>\n",
       "      <td>IGH</td>\n",
       "      <td>IGL|IGL</td>\n",
       "      <td>T</td>\n",
       "      <td>T|F</td>\n",
       "      <td>IGHV4-4</td>\n",
       "      <td>IGLV1-40|IGLV1-51</td>\n",
       "      <td>IGHJ5</td>\n",
       "      <td>...</td>\n",
       "      <td>58.0</td>\n",
       "      <td>15.0</td>\n",
       "      <td>NaN</td>\n",
       "      <td>CARGGVSTAFWFDPW</td>\n",
       "      <td>CQSYDRSLGGHYVF|CGTWDSSLSAGCA</td>\n",
       "      <td>IGH + IGL|IGL</td>\n",
       "      <td>T + T|F</td>\n",
       "      <td>IgM</td>\n",
       "      <td>Single + Multi_light_v|Multi_light_j</td>\n",
       "      <td>Multi</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>838 rows × 24 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                 clone_id clone_id_by_size  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC              140_3_1              362   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG               88_4_1              278   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC               98_2_2              726   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT               64_8_1              645   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT                9_4_1              677   \n",
       "...                                                   ...              ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                   63_8_2              181   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                  128_8_1              723   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                  146_7_2              799   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT                  145_4_2              276   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC      124_4_1_1|124_4_1_2          635|368   \n",
       "\n",
       "                                                sample_id locus_heavy  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC  sc5p_v2_hs_PBMC_10k         IGH   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG  sc5p_v2_hs_PBMC_10k         IGH   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC  sc5p_v2_hs_PBMC_10k         IGH   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT  sc5p_v2_hs_PBMC_10k         IGH   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT  sc5p_v2_hs_PBMC_10k         IGH   \n",
       "...                                                   ...         ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG          vdj_v1_hs_pbmc3         IGH   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT          vdj_v1_hs_pbmc3         IGH   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG          vdj_v1_hs_pbmc3         IGH   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT          vdj_v1_hs_pbmc3         IGH   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC          vdj_v1_hs_pbmc3         IGH   \n",
       "\n",
       "                                     locus_light productive_heavy  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC         IGK                T   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG         IGL                T   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC         IGK                T   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT         IGL                T   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT         IGL                T   \n",
       "...                                          ...              ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG             IGK                T   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT             IGK                T   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG             IGL                T   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT             IGK                T   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC         IGL|IGL                T   \n",
       "\n",
       "                                     productive_light v_call_genotyped_heavy  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC                T               IGHV1-69   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG                T                IGHV1-2   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC                T               IGHV5-51   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT                T               IGHV3-15   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT                T               IGHV3-33   \n",
       "...                                               ...                    ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                    T               IGHV4-59   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                    T               IGHV3-21   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                    T               IGHV3-48   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT                    T               IGHV4-34   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC                  T|F                IGHV4-4   \n",
       "\n",
       "                                     v_call_genotyped_light j_call_heavy  ...  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC                IGKV1-8        IGHJ3  ...   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG               IGLV5-45        IGHJ3  ...   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC               IGKV1D-8        IGHJ3  ...   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT               IGLV6-57        IGHJ4  ...   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT               IGLV2-14        IGHJ6  ...   \n",
       "...                                                     ...          ...  ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                   IGKV1-12        IGHJ4  ...   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                   IGKV3-20        IGHJ6  ...   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                   IGLV2-14        IGHJ4  ...   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT         IGKV1-39|IGKV1D-39        IGHJ3  ...   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC          IGLV1-40|IGLV1-51        IGHJ5  ...   \n",
       "\n",
       "                                     umi_count_light_0 umi_count_light_1  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC              43.0               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG              90.0               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC              22.0               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT              40.0               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT              36.0               NaN   \n",
       "...                                                ...               ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                  33.0               NaN   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                  18.0               NaN   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                  80.0               NaN   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT                   5.0               NaN   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC                  58.0              15.0   \n",
       "\n",
       "                                     umi_count_light_2  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT               NaN   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT               NaN   \n",
       "...                                                ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                   NaN   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                   NaN   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                   NaN   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT                   NaN   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC                   NaN   \n",
       "\n",
       "                                               junction_aa_heavy  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC       CATTYYYDSSGYYQNDAFDIW   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG              CAREIEGDGVFEIW   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC          CARHIRGNRFGNDAFDIW   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT        CTTDDEKRPYSGSYLPFDYW   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT             CARDWVRGVNDMDVW   \n",
       "...                                                          ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG              CARVNVGGIAVAGYFDYW   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT      CARVRQEYYDFWSGYPAEVYYYMDVW   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG             CAREKYDFWSGDSYYFDYW   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT          CARRRLTYYYDSSGPLSAFDIW   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC                 CARGGVSTAFWFDPW   \n",
       "\n",
       "                                                 junction_aa_light  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC                   CQQYYSYPRTF   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG                   CMIWHSSAWVV   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC                   CQQYYSFPYTF   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT                   CQSYDSSNVVF   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT                  CSSYTSSSTRVF   \n",
       "...                                                            ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                       CQQANSFPLTF   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                      CQQYGSSPLFTF   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                      CSSYTSSSTRVF   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT                       CQQSYSTPRTF   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC      CQSYDRSLGGHYVF|CGTWDSSLSAGCA   \n",
       "\n",
       "                                             status  productive isotype  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC      IGH + IGK       T + T     IgM   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG      IGH + IGL       T + T     IgM   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC      IGH + IGK       T + T     IgM   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT      IGH + IGL       T + T     IgM   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT      IGH + IGL       T + T     IgM   \n",
       "...                                             ...         ...     ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG          IGH + IGK       T + T     IgM   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT          IGH + IGK       T + T     IgM   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG          IGH + IGL       T + T     IgM   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT          IGH + IGK       T + T     IgM   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC      IGH + IGL|IGL     T + T|F     IgM   \n",
       "\n",
       "                                                         vdj_status_detail  \\\n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC                       Single + Single   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG                       Single + Single   \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC                       Single + Single   \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT                Single + Multi_light_j   \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT                       Single + Single   \n",
       "...                                                                    ...   \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG                           Single + Single   \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT                           Single + Single   \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG                           Single + Single   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT                    Single + Multi_light_v   \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC      Single + Multi_light_v|Multi_light_j   \n",
       "\n",
       "                                     vdj_status  \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCCGTTGTC     Single  \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCGAGAACG     Single  \n",
       "sc5p_v2_hs_PBMC_10k_AAACCTGTCTTGAGAC     Single  \n",
       "sc5p_v2_hs_PBMC_10k_AAAGATGGTCGAATCT     Single  \n",
       "sc5p_v2_hs_PBMC_10k_AACCATGCAAGCTGTT     Single  \n",
       "...                                         ...  \n",
       "vdj_v1_hs_pbmc3_TCTTCGGTCCTAAGTG         Single  \n",
       "vdj_v1_hs_pbmc3_TGCACCTCAGACAAAT         Single  \n",
       "vdj_v1_hs_pbmc3_TGTATTCTCTGTTGAG         Single  \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCAGGATCT         Single  \n",
       "vdj_v1_hs_pbmc3_TTTATGCTCCTAGAAC          Multi  \n",
       "\n",
       "[838 rows x 24 columns]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vdj.metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Alternative : Running `tl.define_clones`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, a wrapper to call *changeo's* `DefineClones.py` is also included. To run it, you need to choose the distance threshold for clonal assignment. To facilitate this, the function `pp.calculate_threshold` will run [shazam's distToNearest](https://shazam.readthedocs.io/en/stable/topics/distToNearest/) function and return a plot showing the length normalized hamming distance distribution and automated threshold value. \n",
    "\n",
    "Again, `pp.calculate_threshold` will take a file path, pandas `DataFrame` or `Dandelion` object as input. If a dandelion object is provided, the threshold value will be inserted into the `.threshold` slot. For more fine control, please use the `DefineClones.py` function [directly](https://immcantation.readthedocs.io/en/stable/tutorials/10x_tutorial.html).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calculating threshold\n",
      "      Threshold method 'density' did not return with any values. Switching to method = 'gmm'.\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 450x250 with 4 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<ggplot: (360081101)>\n",
      " finished: Updated Dandelion object: \n",
      "   'threshold', threshold value for tuning clonal assignment\n",
      " (0:00:43)\n"
     ]
    }
   ],
   "source": [
    "ddl.pp.calculate_threshold(vdj)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.21354295894548617"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# see the actual value in .threshold slot\n",
    "vdj.threshold"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also manually select a value as the threshold if you wish."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calculating threshold\n",
      "      Threshold method 'density' did not return with any values. Switching to method = 'gmm'.\n"
     ]
    },
    {
     "data": {
      "image/png": "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oBQEBQXx66+/0rFjR1uLUoBly5Yxf/58k8sLh/N0IaJFOxg7duxgzpw5REVFFXjif/311xk9ejRyeeHPGRqNhpycnKc2s2VZwNnZmeeff97WYhikXr16thZBYMeIHo6DsWDBAoKCgpg8ebLB8y1atKBZs2a697lDIN988w116tTB2dmZM2fOALBq1SqeeeYZnJ2dqVq1KpMnTyY7O1t37bRp0/Dw8CjQRv7hrdw21q5dS3BwMK6uroSFhXHx4kW96yRJYt68edSuXRtnZ2dq1qzJf/7znwL1b9u2jbp16+Li4sJzzz3HiRMninOLTOLOnTsMHjyYmjVr4urqSkhICBMnTuTx48d65WQyGf/617/45JNP8PPzw8vLi48//hhJkti7dy+NGzfGw8ODjh07cvPmTd11ucNia9eu5Z133sHLyws/Pz/mzZsHwIYNG6hTpw7lypWjd+/epKamFrg275Ba9erVee+991iyZAnVqlWjfPnyvPrqqyQlJenJ+9dff9GuXTtcXFwIDg5m7dq1vPLKK4SFhRV5T7744guqV6+Om5sbnTp14sqVKwXK5B9Su3XrFuHh4QQEBODi4kKNGjV04f2nTZvG9OnTefjwITKZDJlMppPjwoUL9O3blypVquDm5ka9evWYP38+OTk5Be7Dd999p0uhHBQUxMcff6xnpwB///03vXv3xsfHBzc3N5599lnWr1+vO2+q7QlKh+jhOBDZ2dkcPXqUPn36oFSa/tH+/vvvxMbG8umnn+Ll5UWVKlVYvHgxo0aNYsSIEXz++eecPHmSadOmcefOHVavXl1s2U6dOsXVq1eZO3cuAJMnT+all17i4sWLODs7A/DBBx/w5ZdfMmnSJFq2bMmxY8cYP348rq6uvPvuuwCcOXOG1157jS5durBgwQJiYmIIDw9HrVabJIckSQV+jHKP5yU5ORkfHx8WLFiAt7c3ly5dYtq0acTHx7NmzRq9skuWLKFjx4589913/O9//yMqKgqNRsPevXuZNGkSTk5OjBo1iiFDhrB79269aydPnszrr7/O5s2b+eGHHxg7dizJyckcPHiQzz77jPv37/P+++8zbtw4Vq1aZVS3H3/8kcuXL7N06VKSk5MZPXo077//Phs2bADg0aNHvPjii3h5efHdd98BEBUVRWpqKiEhIUbr3r59O5GRkQwcOJC+ffvy+++/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\n",
      "text/plain": [
       "<Figure size 450x250 with 4 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<ggplot: (360720905)>\n",
      " finished: Updated Dandelion object: \n",
      "   'threshold', threshold value for tuning clonal assignment\n",
      " (0:00:26)\n"
     ]
    }
   ],
   "source": [
    "ddl.pp.calculate_threshold(vdj, manual_threshold = 0.1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.1"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# see the updated .threshold slot\n",
    "vdj.threshold"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "We can run `tl.define_clones` to call *changeo's* `DefineClones.py`; see [here](https://changeo.readthedocs.io/en/stable/methods/clustering.html) for more info. Note, if a `pandas.DataFrame` or file path is provided as the input, the value in dist option (corresponds to threshold value) needs to be manually supplied. If a `Dandelion` object is provided, it will automatically retrieve it from the threshold slot. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Finding clones\n",
      " finished: Updated Dandelion object: \n",
      "   'data', contig-indexed clone table\n",
      "   'metadata', cell-indexed clone table\n",
      " (0:00:09)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "Dandelion class object with n_obs = 838 and n_contigs = 1700\n",
       "    data: 'sequence_id', 'sequence', 'rev_comp', 'productive', 'v_call', 'd_call', 'j_call', 'sequence_alignment', 'germline_alignment', 'junction', 'junction_aa', 'v_cigar', 'd_cigar', 'j_cigar', 'stop_codon', 'vj_in_frame', 'locus', 'junction_length', 'np1_length', 'np2_length', 'v_sequence_start', 'v_sequence_end', 'v_germline_start', 'v_germline_end', 'd_sequence_start', 'd_sequence_end', 'd_germline_start', 'd_germline_end', 'j_sequence_start', 'j_sequence_end', 'j_germline_start', 'j_germline_end', 'v_score', 'v_identity', 'v_support', 'd_score', 'd_identity', 'd_support', 'j_score', 'j_identity', 'j_support', 'fwr1', 'fwr2', 'fwr3', 'fwr4', 'cdr1', 'cdr2', 'cdr3', 'cell_id', 'c_call', 'consensus_count', 'umi_count', 'v_call_10x', 'd_call_10x', 'j_call_10x', 'junction_10x', 'junction_10x_aa', 'v_call_genotyped', 'germline_alignment_d_mask', 'sample_id', 'c_sequence_alignment', 'c_germline_alignment', 'c_sequence_start', 'c_sequence_end', 'c_score', 'c_identity', 'c_support', 'c_call_10x', 'junction_aa_length', 'fwr1_aa', 'fwr2_aa', 'fwr3_aa', 'fwr4_aa', 'cdr1_aa', 'cdr2_aa', 'cdr3_aa', 'sequence_alignment_aa', 'v_sequence_alignment_aa', 'd_sequence_alignment_aa', 'j_sequence_alignment_aa', 'mu_freq', 'duplicate_count', 'clone_id', 'changeo_clone_id'\n",
       "    metadata: 'clone_id', 'clone_id_by_size', 'sample_id', 'locus_heavy', 'locus_light', 'productive_heavy', 'productive_light', 'v_call_genotyped_heavy', 'v_call_genotyped_light', 'j_call_heavy', 'j_call_light', 'c_call_heavy', 'c_call_light', 'umi_count_heavy_0', 'umi_count_light_0', 'umi_count_light_1', 'umi_count_light_2', 'junction_aa_heavy', 'junction_aa_light', 'status', 'productive', 'isotype', 'vdj_status_detail', 'vdj_status', 'changeo_clone_id'\n",
       "    distance: None\n",
       "    edges: None\n",
       "    layout: None\n",
       "    graph: None"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ddl.tl.define_clones(vdj, key_added = 'changeo_clone_id')\n",
    "vdj"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that I specified the option `key_added` and this adds the output from `tl.define_clones` into a separate column. If left as default (`None`), it will write into `clone_id` column. The same option can be specified in `tl.find_clones` earlier."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generation of BCR network\n",
    "*dandelion* generates a network to facilitate visualisation of results. This uses the full V(D)J contig sequences instead of just the junctional sequences to chart a tree-like network for each clone. The actual visualization will be achieved through `scanpy` later.\n",
    "\n",
    "**tl.generate_network**\n",
    "\n",
    "First we need to generate the network. `tl.generate_network` will take a V(D)J table that has clones defined, specifically under the `'clone_id'` column. The default mode is to use amino acid sequences for constructing Levenshtein distance matrices, but can be toggled using the `key` option.\n",
    "\n",
    "If you have a pre-processed table parsed from immcantation's [method](https://changeo.readthedocs.io/en/stable/examples/10x.html), or any other method as long as it's in a *AIRR* format, the table can be used as well.\n",
    "\n",
    "You can specify the `clone_key` option for generating the network for the clone id definition of choice as long as it exists as a column in the `.data` slot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Generating network\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Calculating distances... : 100%|██████████| 4/4 [00:03<00:00,  1.15it/s]\n",
      "Generating edge list : 100%|██████████| 7/7 [00:00<00:00, 848.90it/s]\n",
      "Linking edges : 100%|██████████| 821/821 [00:00<00:00, 5324.08it/s]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "generating network layout\n",
      " finished: Updated Dandelion object: \n",
      "   'data', contig-indexed clone table\n",
      "   'metadata', cell-indexed clone table\n",
      "   'distance', heavy and light chain distance matrices\n",
      "   'edges', network edges\n",
      "   'layout', network layout\n",
      "   'graph', network (0:00:10)\n"
     ]
    }
   ],
   "source": [
    "ddl.tl.generate_network(vdj)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This step works reasonably fast here but will take quite a while when a lot of contigs are provided.\n",
    "\n",
    "You can also downsample the number of cells. This will return a new object as a downsampled copy of the original with it's own distance matrix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Generating network\n",
      "Downsampling to 500 cells.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Calculating distances... : 100%|██████████| 4/4 [00:01<00:00,  3.40it/s]\n",
      "Generating edge list : 100%|██████████| 2/2 [00:00<00:00, 757.03it/s]\n",
      "Linking edges : 100%|██████████| 492/492 [00:00<00:00, 6924.50it/s]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "generating network layout\n",
      " finished: Updated Dandelion object: \n",
      "   'data', contig-indexed clone table\n",
      "   'metadata', cell-indexed clone table\n",
      "   'distance', heavy and light chain distance matrices\n",
      "   'edges', network edges\n",
      "   'layout', network layout\n",
      "   'graph', network (0:00:08)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "Dandelion class object with n_obs = 500 and n_contigs = 1016\n",
       "    data: 'sequence_id', 'sequence', 'rev_comp', 'productive', 'v_call', 'd_call', 'j_call', 'sequence_alignment', 'germline_alignment', 'junction', 'junction_aa', 'v_cigar', 'd_cigar', 'j_cigar', 'stop_codon', 'vj_in_frame', 'locus', 'junction_length', 'np1_length', 'np2_length', 'v_sequence_start', 'v_sequence_end', 'v_germline_start', 'v_germline_end', 'd_sequence_start', 'd_sequence_end', 'd_germline_start', 'd_germline_end', 'j_sequence_start', 'j_sequence_end', 'j_germline_start', 'j_germline_end', 'v_score', 'v_identity', 'v_support', 'd_score', 'd_identity', 'd_support', 'j_score', 'j_identity', 'j_support', 'fwr1', 'fwr2', 'fwr3', 'fwr4', 'cdr1', 'cdr2', 'cdr3', 'cell_id', 'c_call', 'consensus_count', 'umi_count', 'v_call_10x', 'd_call_10x', 'j_call_10x', 'junction_10x', 'junction_10x_aa', 'v_call_genotyped', 'germline_alignment_d_mask', 'sample_id', 'c_sequence_alignment', 'c_germline_alignment', 'c_sequence_start', 'c_sequence_end', 'c_score', 'c_identity', 'c_support', 'c_call_10x', 'junction_aa_length', 'fwr1_aa', 'fwr2_aa', 'fwr3_aa', 'fwr4_aa', 'cdr1_aa', 'cdr2_aa', 'cdr3_aa', 'sequence_alignment_aa', 'v_sequence_alignment_aa', 'd_sequence_alignment_aa', 'j_sequence_alignment_aa', 'mu_freq', 'duplicate_count', 'clone_id', 'changeo_clone_id'\n",
       "    metadata: 'clone_id', 'clone_id_by_size', 'sample_id', 'locus_heavy', 'locus_light', 'productive_heavy', 'productive_light', 'v_call_genotyped_heavy', 'v_call_genotyped_light', 'j_call_heavy', 'j_call_light', 'c_call_heavy', 'c_call_light', 'umi_count_heavy_0', 'umi_count_light_0', 'umi_count_light_1', 'umi_count_light_2', 'junction_aa_heavy', 'junction_aa_light', 'status', 'productive', 'isotype', 'vdj_status_detail', 'vdj_status'\n",
       "    distance: 'heavy_0', 'light_0', 'light_1', 'light_2'\n",
       "    edges: 'source', 'target', 'weight'\n",
       "    layout: layout for 500 vertices, layout for 10 vertices\n",
       "    graph: networkx graph of 500 vertices, networkx graph of 10 vertices "
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vdj_downsample = ddl.tl.generate_network(vdj, downsample = 500)\n",
    "vdj_downsample"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**check the newly re-initialized Dandelion object**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Dandelion class object with n_obs = 838 and n_contigs = 1700\n",
       "    data: 'sequence_id', 'sequence', 'rev_comp', 'productive', 'v_call', 'd_call', 'j_call', 'sequence_alignment', 'germline_alignment', 'junction', 'junction_aa', 'v_cigar', 'd_cigar', 'j_cigar', 'stop_codon', 'vj_in_frame', 'locus', 'junction_length', 'np1_length', 'np2_length', 'v_sequence_start', 'v_sequence_end', 'v_germline_start', 'v_germline_end', 'd_sequence_start', 'd_sequence_end', 'd_germline_start', 'd_germline_end', 'j_sequence_start', 'j_sequence_end', 'j_germline_start', 'j_germline_end', 'v_score', 'v_identity', 'v_support', 'd_score', 'd_identity', 'd_support', 'j_score', 'j_identity', 'j_support', 'fwr1', 'fwr2', 'fwr3', 'fwr4', 'cdr1', 'cdr2', 'cdr3', 'cell_id', 'c_call', 'consensus_count', 'umi_count', 'v_call_10x', 'd_call_10x', 'j_call_10x', 'junction_10x', 'junction_10x_aa', 'v_call_genotyped', 'germline_alignment_d_mask', 'sample_id', 'c_sequence_alignment', 'c_germline_alignment', 'c_sequence_start', 'c_sequence_end', 'c_score', 'c_identity', 'c_support', 'c_call_10x', 'junction_aa_length', 'fwr1_aa', 'fwr2_aa', 'fwr3_aa', 'fwr4_aa', 'cdr1_aa', 'cdr2_aa', 'cdr3_aa', 'sequence_alignment_aa', 'v_sequence_alignment_aa', 'd_sequence_alignment_aa', 'j_sequence_alignment_aa', 'mu_freq', 'duplicate_count', 'clone_id', 'changeo_clone_id'\n",
       "    metadata: 'clone_id', 'clone_id_by_size', 'sample_id', 'locus_heavy', 'locus_light', 'productive_heavy', 'productive_light', 'v_call_genotyped_heavy', 'v_call_genotyped_light', 'j_call_heavy', 'j_call_light', 'c_call_heavy', 'c_call_light', 'umi_count_heavy_0', 'umi_count_light_0', 'umi_count_light_1', 'umi_count_light_2', 'junction_aa_heavy', 'junction_aa_light', 'status', 'productive', 'isotype', 'vdj_status_detail', 'vdj_status', 'changeo_clone_id'\n",
       "    distance: 'heavy_0', 'light_0', 'light_1', 'light_2'\n",
       "    edges: 'source', 'target', 'weight'\n",
       "    layout: layout for 838 vertices, layout for 24 vertices\n",
       "    graph: networkx graph of 838 vertices, networkx graph of 24 vertices "
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vdj"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The graph/networks can be accessed through the `.graph` slot as an `networkx` graph object if you want to extract the data for network statistics or make any changes to the network."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At this point, we can save the dandelion object; the file can be quite big because the distance matrix is not sparse. I reccomend some form of compression (I use `bzip2` below but that can impact on read/write times significantly). See [here](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_hdf.html) for options compression options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "vdj.write_h5('dandelion_results.h5', complib = 'bzip2')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python (dandelion)",
   "language": "python",
   "name": "dandelion"
  },
  "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.7.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
