quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# CARBonAra for sequence design"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from carbonara import CARBonAra, imprint_sampling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating sequences"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# initialize carbonara model and define device for acceleration\n",
    "carbonara = CARBonAra(device_name=\"cuda\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simple sequence generation for monomers, multimers and with context\n",
    "\n",
    "General sequence sampling with all required and optional options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|██████████| 100/100 [00:07<00:00, 12.71it/s]\n"
     ]
    }
   ],
   "source": [
    "# sample sequences\n",
    "sequences, scores, pssm, structure_scaffold = imprint_sampling(\n",
    "    # required arguments\n",
    "    carbonara=carbonara,               # runtime for the carbonara model\n",
    "    pdb_filepath=\"examples/1zns.pdb\",  # input scaffold structure filepath\n",
    "    num_sample=100,                    # number of sequences to sample\n",
    "    imprint_ratio=0.5,                 # percentage of the prediction to use as prior information for sampling\n",
    "    # optional arguments\n",
    "    b_sampled=True,                    # if true, uses sampling from probability for more diversity, if false, uses maximum confidence for sampling\n",
    "    known_chains=[],                   # list of known chains (e.g. ['A', 'B']) for partial sequence prediction\n",
    "    known_positions=[],                # list of known sequence position (e.g. [37, 38, 39, 40]) for partial sequence prediction\n",
    "    unknown_positions=[],              # list of unknown sequence position (e.g. [37, 38, 39, 40]) and will overwite the other known flags\n",
    "    ignored_amino_acids=[],            # list of amino-acids to completely ignore for the sequence sampling (e.g. ['C'])\n",
    "    ignore_hetatm=False,               # flag to ignore hetatm in the structure\n",
    "    ignore_wat=False,                  # flag to ignore water in the structure\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Outputs of the `imprint_sampling`:\n",
    "\n",
    "* `sequences`: list of generated sequences\n",
    "* `scores`: average confidence of the generated sequences\n",
    "* `pssm`: position-specific scoring matrix (carbonara raw output with prior information)\n",
    "* `structure_scaffold`: dictionary containing the structure information of the scaffold"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Partial sequence generation using prior sequence information\n",
    "\n",
    "Sample sequences with chain `A` known to the model and fixed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|██████████| 100/100 [00:05<00:00, 17.95it/s]\n"
     ]
    }
   ],
   "source": [
    "# sample sequences with chain 'A' known to the model and fixed\n",
    "sequences, scores, pssm, structure_scaffold = imprint_sampling(\n",
    "    # required arguments\n",
    "    carbonara=carbonara,               # runtime for the carbonara model\n",
    "    pdb_filepath=\"examples/2oob.pdb\",  # input scaffold structure filepath\n",
    "    num_sample=100,                    # number of sequences to sample\n",
    "    imprint_ratio=0.5,                 # percentage of the prediction to use as prior information for sampling\n",
    "    known_chains=['A'],                # list of known chains (e.g. ['A', 'B']) for partial sequence prediction\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Partial sequence generation can also be controled with:\n",
    "* `known_positions`: list of sequence position from the reference structure that are known to the model and will be fixed in the output sequence\n",
    "* `unknown_positions`: list of unknown sequence position that will be sampled and the rest of the sequence(s) will be known and fixed. This option will overwrite the other as it will set everything to be known except the listed positions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving structure scaffold\n",
    "\n",
    "The b-factor column of the scaffold contains the known (1.0) and to unknown (0.0). This feature is useful to easily verify and debug partial sequence prediction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from carbonara import save_pdb, split_by_chain"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "save_pdb(split_by_chain(structure_scaffold), \"examples/2oob_scaffold.pdb\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exporting the outputs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving generated sequences and scores"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "from carbonara import write_fasta"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "sequence: LENVDAKIAKLMGEGYAFEEVKRALEIAQNNVEVARSILREFAF:MKIHVKTLDGKTITLEVEPSDTIENVKQKIEAKEGIPPDNQVLIYAGRQLEDKRTLADYNIQKNSTLYLVLR\n",
      "score: 0.850\n"
     ]
    }
   ],
   "source": [
    "# the sequences are split by chain and can be concatenate in format compatible with AlphaFold\n",
    "print(f\"sequence: {':'.join(sequences[0])}\")\n",
    "print(f\"score: {scores[0]:.3f}\")\n",
    "\n",
    "# saving generated sequence to a fasta file\n",
    "write_fasta(\"examples/2oob_example.fasta\", ':'.join(sequences[0]), info=\"sequence generated for 2oob with chain A known\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving the Position-Specific Scoring Matrix"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "from carbonara import std_aminoacids"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "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>LEU</th>\n",
       "      <th>GLU</th>\n",
       "      <th>ARG</th>\n",
       "      <th>LYS</th>\n",
       "      <th>VAL</th>\n",
       "      <th>ILE</th>\n",
       "      <th>PHE</th>\n",
       "      <th>ASP</th>\n",
       "      <th>TYR</th>\n",
       "      <th>ALA</th>\n",
       "      <th>THR</th>\n",
       "      <th>SER</th>\n",
       "      <th>GLN</th>\n",
       "      <th>ASN</th>\n",
       "      <th>PRO</th>\n",
       "      <th>GLY</th>\n",
       "      <th>HIS</th>\n",
       "      <th>TRP</th>\n",
       "      <th>MET</th>\n",
       "      <th>CYS</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.00</td>\n",
       "      <td>1.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</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",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>111</th>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.53</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.99</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.74</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.03</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>112</th>\n",
       "      <td>1.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.46</td>\n",
       "      <td>0.01</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>113</th>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.20</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>114</th>\n",
       "      <td>0.97</td>\n",
       "      <td>0.15</td>\n",
       "      <td>0.03</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.15</td>\n",
       "      <td>0.64</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.06</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.10</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.14</td>\n",
       "      <td>0.01</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>115</th>\n",
       "      <td>0.04</td>\n",
       "      <td>0.02</td>\n",
       "      <td>0.94</td>\n",
       "      <td>0.94</td>\n",
       "      <td>0.05</td>\n",
       "      <td>0.03</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.01</td>\n",
       "      <td>0.14</td>\n",
       "      <td>0.08</td>\n",
       "      <td>0.06</td>\n",
       "      <td>0.11</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.04</td>\n",
       "      <td>0.00</td>\n",
       "      <td>0.03</td>\n",
       "      <td>0.12</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>116 rows × 20 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "      LEU   GLU   ARG   LYS   VAL   ILE   PHE  ASP   TYR   ALA   THR   SER  \\\n",
       "0    1.00  0.00  0.00  0.00  0.00  0.00  0.00  0.0  0.00  0.00  0.00  0.00   \n",
       "1    0.00  1.00  0.00  0.00  0.00  0.00  0.00  0.0  0.00  0.00  0.00  0.00   \n",
       "2    0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.0  0.00  0.00  0.00  0.00   \n",
       "3    0.00  0.00  0.00  0.00  1.00  0.00  0.00  0.0  0.00  0.00  0.00  0.00   \n",
       "4    0.00  0.00  0.00  0.00  0.00  0.00  0.00  1.0  0.00  0.00  0.00  0.00   \n",
       "..    ...   ...   ...   ...   ...   ...   ...  ...   ...   ...   ...   ...   \n",
       "111  0.00  0.00  0.00  0.00  0.00  0.00  0.53  0.0  0.99  0.00  0.00  0.00   \n",
       "112  1.00  0.00  0.00  0.00  0.00  0.00  0.00  0.0  0.00  0.02  0.00  0.00   \n",
       "113  0.00  0.00  0.00  0.00  1.00  0.01  0.00  0.0  0.00  0.01  0.02  0.00   \n",
       "114  0.97  0.15  0.03  0.02  0.15  0.64  0.02  0.0  0.01  0.00  0.06  0.00   \n",
       "115  0.04  0.02  0.94  0.94  0.05  0.03  0.00  0.0  0.00  0.01  0.14  0.08   \n",
       "\n",
       "      GLN   ASN  PRO   GLY   HIS   TRP   MET   CYS  \n",
       "0    0.00  0.00  0.0  0.00  0.00  0.00  0.00  0.00  \n",
       "1    0.00  0.00  0.0  0.00  0.00  0.00  0.00  0.00  \n",
       "2    0.00  1.00  0.0  0.00  0.00  0.00  0.00  0.00  \n",
       "3    0.00  0.00  0.0  0.00  0.00  0.00  0.00  0.00  \n",
       "4    0.00  0.00  0.0  0.00  0.00  0.00  0.00  0.00  \n",
       "..    ...   ...  ...   ...   ...   ...   ...   ...  \n",
       "111  0.01  0.01  0.0  0.00  0.74  0.02  0.01  0.03  \n",
       "112  0.01  0.00  0.0  0.02  0.00  0.00  0.46  0.01  \n",
       "113  0.00  0.01  0.0  0.00  0.00  0.00  0.00  0.20  \n",
       "114  0.10  0.00  0.0  0.00  0.01  0.01  0.14  0.01  \n",
       "115  0.06  0.11  0.0  0.00  0.04  0.00  0.03  0.12  \n",
       "\n",
       "[116 rows x 20 columns]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = pd.DataFrame(pssm, columns=std_aminoacids)\n",
    "df.round(2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.to_csv(\"examples/2oob_example_pssm.csv\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "carbonara-release",
   "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.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}