{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Library: Quick Start"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1. Load TCRs into a data frame"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Examples of files you may want to load:\n",
    "\n",
    "- **10X**: `filtered_contig_annotations.csv`\n",
    "\n",
    "- **Adaptive**: `Sample_TCRB.tsv`\n",
    "\n",
    "- **IMGT**: Output from `MiXCR` or other tools"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import tcrconvert\n",
    "import pandas as pd\n",
    "\n",
    "tcr_file = tcrconvert.get_example_path('tenx.csv')\n",
    "tcrs = pd.read_csv(tcr_file)[['barcode', 'v_gene', 'j_gene', 'cdr3']]\n",
    "tcrs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2. Convert"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_tcrs = tcrconvert.convert_gene(tcrs, frm='tenx', to='adaptive')\n",
    "new_tcrs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Tip**: Suppress INFO-level messages by setting `verbose=False`. Warnings and errors will still appear.\n",
    "\n",
    "> **Tip**: If your Adaptive data lacks `x_resolved`/`xMaxResolved` columns, create them yourself by combining the `x_gene`/`xGeneName` and `x_allele`/`xGeneAllele` columns. See the FAQs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## AIRR data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Supply the standard AIRR gene column names to `frm_cols`:\n",
    "\n",
    "```python\n",
    "new_airr = tcrconvert.convert_gene(airr, frm = \"imgt\", to = \"adaptive\", \n",
    "                                   frm_cols = c('v_call', 'd_call', 'j_call', 'c_call'))\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom column names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, `TCRconvert` assumes these column names based on the input nomenclature (`frm`):\n",
    "\n",
    "- `frm='imgt'` : `['v_gene', 'd_gene', 'j_gene', 'c_gene']`\n",
    "\n",
    "- `frm='tenx'` : `['v_gene', 'd_gene', 'j_gene', 'c_gene']`\n",
    "\n",
    "- `frm='adaptive'` : `['v_resolved', 'd_resolved', 'j_resolved']`\n",
    "\n",
    "- `frm='adaptivev2'` : `['vMaxResolved', 'dMaxResolved', 'jMaxResolved']`\n",
    "\n",
    "You can override these columns using `frm_cols`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**1. Load 10X data with custom column names**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "custom_file = tcrconvert.get_example_path('customcols.csv')\n",
    "\n",
    "custom = pd.read_csv(custom_file)\n",
    "custom"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**2. Specify names using `frm_cols` and convert to IMGT**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "custom_new = tcrconvert.convert_gene(\n",
    "    custom,\n",
    "    frm='tenx',\n",
    "    to='imgt',\n",
    "    verbose=False,\n",
    "    frm_cols=['myVgene', 'myDgene', 'myJgene', 'myCgene'],\n",
    ")\n",
    "custom_new"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rhesus or mouse data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use `species='rhesus'` or `species='mouse'`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_tcrs = tcrconvert.convert_gene(\n",
    "    tcrs, frm='tenx', to='imgt', verbose=False, species='rhesus'\n",
    ")  # or 'mouse'\n",
    "new_tcrs"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "tcrconvert",
   "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}