Compare
Access KinForm, UniKP, DLKcat, TurNup, EITLEM, CataPro, CatPred, OmniESI, RealKcat, IECata, and MMISA-KM through one interface.
+Access KinForm, UniKP, DLKcat, TurNup, EITLEM, CataPro, CatPred, OmniESI, CatRange, IECata, and MMISA-KM through one interface.
Extend
diff --git a/docs/project/supported_methods.rst b/docs/project/supported_methods.rst index 24df8c57..f3c993b7 100644 --- a/docs/project/supported_methods.rst +++ b/docs/project/supported_methods.rst @@ -23,7 +23,7 @@ Supported engines - CatPred, kcat and Km. - OmniESI, kcat and Km. - OmniESI + O2DENet, kcat and Km. -- RealKcat, kcat and Km. +- CatRange, kcat and Km. - IECata, kcat/Km. - MMISA-KM, Km. diff --git a/frontend/src/components/ApiDocs/ApiDocs.jsx b/frontend/src/components/ApiDocs/ApiDocs.jsx index cab05f0c..dcde8c40 100644 --- a/frontend/src/components/ApiDocs/ApiDocs.jsx +++ b/frontend/src/components/ApiDocs/ApiDocs.jsx @@ -574,7 +574,7 @@ export default function ApiDocs() { "KinForm-L": 0, "CatPred": 0, "OmniESI": 0, - "RealKcat": 0, + "CatRange": 0, "IECata": 1, "MMISA-KM": 0, "Server": 0 @@ -589,7 +589,7 @@ export default function ApiDocs() { "KinForm-L": 1500, "CatPred": 2048, "OmniESI": 1000, - "RealKcat": 1022, + "CatRange": 1024, "IECata": 1000, "MMISA-KM": 500, "Server": 10000 @@ -905,10 +905,10 @@ export default function ApiDocs() {RealKcatCatRangeProtein Sequence, SubstrateIECata![\"Open](\"https://colab.research.google.com/assets/colab-badge.svg\"){kind=icon}
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "**Robust Prediction of Enzyme Variant Kinetics with CatRange**\n",
+ "\n",
+ "This notebook predicts enzyme kinetic parameter ranges ($k_{\\text{cat}}$ and $K_M$) for protein sequences and substrates using CatRange.\n",
+ "\n",
+ "Before the kinetics step runs, the workflow uses [**CLEAN** (An Enzyme Function Prediction Tool using Contrastive Learning)](https://github.com/tttianhao/CLEAN) on each protein sequence to:\n",
+ "- predict a likely **EC number**\n",
+ "- report a **CLEAN confidence score** for the top EC assignment\n",
+ "- decide whether that sequence should continue to the CatRange kinetics step\n",
+ "\n",
+ "_No coding experience required. Collapse cells to keep the notebook clean._\n",
+ "\n",
+ "---\n",
+ "\n",
+ "## **How to Use**\n",
+ "1. **Select Mode**: `Demo`, `Interactive`, `Bulk`, or `Bulk-large`\n",
+ "2. **Select Mutation Pathway**:\n",
+ " - **Mechanistic Mutation-Aware (default)** - recommended; better reflects graded mutation effects\n",
+ " - **Binary Over-Simplified (poor and optional)** - legacy simplified mode for comparison only\n",
+ "3. **Run the cells sequentially below**\n",
+ "4. **Enter inputs or upload a CSV when prompted**\n",
+ "5. **Review the EC and kinetics output table**\n",
+ "6. **Download either `inference_results.csv` only or all output files**\n",
+ "\n",
+ "> ⚠️ Each time you run the pipeline cell, Colab will:\n",
+ "> - Install required dependencies\n",
+ "> - Download pretrained model files\n",
+ "> - Run CLEAN first, then run CatRange only on rows that pass the CLEAN screen\n",
+ "\n",
+ "---\n",
+ "\n",
+ "## **What CLEAN Does in This Pipeline**\n",
+ "- CLEAN uses the **protein sequence only** to predict a likely EC number.\n",
+ "- The top EC call is written to `clean_top_ec_number`.\n",
+ "- Its CLEAN confidence score is written to `clean_top_confidence`.\n",
+ "- `clean_top_confidence` is a model confidence score for the top EC call, not an experimental measurement of catalytic activity.\n",
+ "- If a row does **not** pass the CLEAN enzyme screen, that row is still kept in the final output, but the CatRange prediction columns are marked as `skipped`.\n",
+ "\n",
+ "## **Modes**\n",
+ "- **`Demo`**: test the pipeline with built-in examples\n",
+ "- **`Interactive`**: manually enter up to 10 enzyme-substrate pairs\n",
+ "- **`Bulk`**: upload a CSV with 10 or fewer rows\n",
+ " - [Sample CSV](https://drive.google.com/uc?export=download&id=1X9bR67NW-sTNHaKU4W1Htlfxhl-OKMmu)\n",
+ "- **`Bulk-large`**: upload a CSV with more than 10 rows\n",
+ " - Includes the +/-1 class error columns around each CatRange prediction\n",
+ " - GPU is recommended for larger jobs\n",
+ " - If your sequences are long (roughly >500 aa), start with a very small `BATCH_SIZE` such as `1` or `2`, then increase gradually\n",
+ "\n",
+ "## **Input Requirements**\n",
+ "- Required CSV columns: `sequence` and `Isomeric SMILES`\n",
+ "- One row should contain one enzyme-substrate pair\n",
+ "- Extra spaces are removed automatically during setup\n",
+ "\n",
+ "## **Length Limits**\n",
+ "- Minimum sequence length: **9 amino acids**\n",
+ "- Maximum sequence length: **1022 amino acids**\n",
+ "- Minimum SMILES length: **2 characters**\n",
+ "- Maximum SMILES length: **512 characters**\n",
+ "- Rows outside these limits are kept in the final CSV and marked as `skipped`\n",
+ "\n",
+ "## **Output Files**\n",
+ "- `inference_results.csv`: user-facing summary table with EC calls, enzyme classification, kinetics ranges, uncertainty ranges, and units\n",
+ "- `inference_results_detailed.csv`: technical output columns, including the full CLEAN fields and support score\n",
+ "- `clean_screened.csv`: CLEAN results for all submitted rows\n",
+ "- `clean_catrange_ready.csv`: only the rows passed from CLEAN into CatRange\n",
+ "- `run_config.json`: saved settings used for the run\n",
+ "\n",
+ "\n",
+ "## **Notebook Release**\n",
+ "- `2026-03-17-optimized`\n"
+ ],
+ "metadata": {
+ "id": "BPpF3-QZGKjT"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "#@title 1. Prepare input and save the run settings\n",
+ "mode = \"Demo\" #@param [\"Demo\", \"Interactive\", \"Bulk\", \"Bulk-large\"]\n",
+ "mutation_mode = \"Mechanistic Mutation-Aware (default)\" #@param [\"Mechanistic Mutation-Aware (default)\", \"Binary Over-Simplified (poor and optional)\"]\n",
+ "clean_non_enzyme_threshold = 0.5 #@param {type:\"number\"}\n",
+ "batch_size = 20 #@param {type:\"integer\"}\n",
+ "\n",
+ "import hashlib\n",
+ "import io\n",
+ "import json\n",
+ "import os\n",
+ "from pathlib import Path\n",
+ "\n",
+ "import pandas as pd\n",
+ "from IPython.display import display\n",
+ "\n",
+ "NOTEBOOK_RELEASE = \"2026-03-17-optimized\"\n",
+ "MAX_SEQ_LENGTH = 1022\n",
+ "MAX_SMILES_LENGTH = 512\n",
+ "CSV_OUT = \"infer_input.csv\"\n",
+ "RUN_CONFIG_OUT = \"run_config.json\"\n",
+ "BATCH_SIZE = int(batch_size)\n",
+ "\n",
+ "if not 0 <= float(clean_non_enzyme_threshold) <= 1:\n",
+ " raise ValueError(\"clean_non_enzyme_threshold must be between 0 and 1.\")\n",
+ "if BATCH_SIZE < 1:\n",
+ " raise ValueError(\"batch_size must be at least 1.\")\n",
+ "\n",
+ "try:\n",
+ " from google.colab import files as _colab_files\n",
+ " IS_COLAB = True\n",
+ "except Exception:\n",
+ " _colab_files = None\n",
+ " IS_COLAB = False\n",
+ "\n",
+ "def _clean(df):\n",
+ " df = df.copy()\n",
+ " required = {\"sequence\", \"Isomeric SMILES\"}\n",
+ " missing = sorted(required.difference(df.columns))\n",
+ " if missing:\n",
+ " raise ValueError(\n",
+ " \"Input CSV is missing required column(s): \" + \", \".join(missing)\n",
+ " )\n",
+ " df[\"sequence\"] = df[\"sequence\"].astype(str).str.replace(r\"\\s+\", \"\", regex=True)\n",
+ " df[\"Isomeric SMILES\"] = df[\"Isomeric SMILES\"].astype(str).str.replace(r\"\\s+\", \"\", regex=True)\n",
+ " if \"clean_row_id\" not in df.columns:\n",
+ " df.insert(0, \"clean_row_id\", range(len(df)))\n",
+ " return df\n",
+ "\n",
+ "def _sha256(path):\n",
+ " return hashlib.sha256(Path(path).read_bytes()).hexdigest()\n",
+ "\n",
+ "def _preview(df):\n",
+ " preview = df.copy()\n",
+ " preview[\"sequence_length\"] = preview[\"sequence\"].astype(str).str.len()\n",
+ " preview[\"smiles_length\"] = preview[\"Isomeric SMILES\"].astype(str).str.len()\n",
+ " preview[\"within_length_limits\"] = (\n",
+ " preview[\"sequence_length\"].le(MAX_SEQ_LENGTH)\n",
+ " & preview[\"smiles_length\"].le(MAX_SMILES_LENGTH)\n",
+ " )\n",
+ " return preview\n",
+ "\n",
+ "if mode == \"Bulk\":\n",
+ " if IS_COLAB:\n",
+ " uploaded = _colab_files.upload()\n",
+ " if not uploaded:\n",
+ " raise RuntimeError(\"No file was uploaded.\")\n",
+ " filename = list(uploaded.keys())[0]\n",
+ " df = pd.read_csv(io.BytesIO(uploaded[filename]))\n",
+ " else:\n",
+ " csv_path = input(\"Path to CSV with 'sequence' and 'Isomeric SMILES': \").strip()\n",
+ " if not csv_path:\n",
+ " raise RuntimeError(\"No CSV path was provided.\")\n",
+ " df = pd.read_csv(csv_path)\n",
+ " df = _clean(df)\n",
+ "elif mode == \"Bulk-large\":\n",
+ " if IS_COLAB:\n",
+ " uploaded = _colab_files.upload()\n",
+ " if not uploaded:\n",
+ " raise RuntimeError(\"No file was uploaded.\")\n",
+ " filename = list(uploaded.keys())[0]\n",
+ " df = pd.read_csv(io.BytesIO(uploaded[filename]))\n",
+ " else:\n",
+ " csv_path = input(\"Path to CSV with 'sequence' and 'Isomeric SMILES': \").strip()\n",
+ " if not csv_path:\n",
+ " raise RuntimeError(\"No CSV path was provided.\")\n",
+ " df = pd.read_csv(csv_path)\n",
+ " df = _clean(df)\n",
+ "elif mode in (\"Interactive\", \"Demo\"):\n",
+ " pairs = []\n",
+ " if mode == \"Demo\":\n",
+ " pairs = [\n",
+ " (\n",
+ " \"MKVAVLGAAGGIGQALALLLKTQLPSGSELSLYDIAPVTPGVAVDLSHIPTAVKIKGFSGEDATPALEGADVVLISAGVARKPGMDRSDLFNVNAGIVKNLVQQVAKTCPKACIGIITNPVNTTVAIAAEVLKKAGVYDKNKLFGVTTLDIIRSNTFVAELKGKQPGEVEVPVIGGHSGVTILPLLSQVPGVSFTEQEVADLTKRIQNAGTEVVEAKAGGGSATLSMGQAAARFGLSLVRALQGEQGVVECAYVEGDGQYARFFSQPLLLGKNGVEERKSIGTLSAFEQNALEGMLDTLKKDIALGEEFVNK\",\n",
+ " \"C(C(=O)C(=O)O)C(=O)O\",\n",
+ " ),\n",
+ " (\n",
+ " \"MGVEQILKRKTGVIVGEDVHNLFTYAKEHKFAIPAINVTSSSTAVAALEAARDSKSPIILQTSNGGAAYFAGKGISNEGQNASIKGAIAAAHYIRSIAPAYGIPVVLHSDHCAKKLLPWFDGMLEADEAYFKEHGEPLFSSHMLDLSEETDEENISTCVKYFKRMAAMDQWLEMEIGITGGEEDGVNNENADKEDLYTKPEQVYNVYKALHPISPNFSIAAAFGNCHGLYAGDIALRPEILAEHQKYTREQVGCKEEKPLFLVFHGGSGSTVQEFHTGIDNGVVKVNLDTDCQYAYLTGIRDYVLNKKDYIMSPVGNPEGPEKPNKKFFDPRVWVREGEKTMGAKITKSLETFRTTNTL\",\n",
+ " \"C([C@H](C=O)O)OP(=O)(O)O\",\n",
+ " ),\n",
+ " (\"M\" * 1023, \"C(C=O)\"),\n",
+ " (\"MKKVAV\", \"C\" + \"C\" * 512),\n",
+ " ]\n",
+ " else:\n",
+ " max_pairs = 10\n",
+ " while len(pairs) < max_pairs:\n",
+ " sequence = input(f\"Sequence #{len(pairs) + 1} (blank to stop): \").strip()\n",
+ " if not sequence:\n",
+ " break\n",
+ " smiles = input(\"Isomeric SMILES: \").strip()\n",
+ " if not smiles:\n",
+ " print(\"Skipping blank SMILES entry.\")\n",
+ " continue\n",
+ " pairs.append((sequence, smiles))\n",
+ " if not pairs:\n",
+ " raise RuntimeError(\"No inputs were provided.\")\n",
+ " df = pd.DataFrame(pairs, columns=[\"sequence\", \"Isomeric SMILES\"])\n",
+ " df = _clean(df)\n",
+ "else:\n",
+ " raise ValueError(mode)\n",
+ "\n",
+ "preview_df = _preview(df)\n",
+ "df.to_csv(CSV_OUT, index=False)\n",
+ "\n",
+ "rows_over_limits = int((~preview_df[\"within_length_limits\"]).sum())\n",
+ "run_config = {\n",
+ " \"notebook_release\": NOTEBOOK_RELEASE,\n",
+ " \"mode\": mode,\n",
+ " \"mutation_mode\": mutation_mode,\n",
+ " \"clean_non_enzyme_threshold\": float(clean_non_enzyme_threshold),\n",
+ " \"batch_size\": BATCH_SIZE,\n",
+ " \"clean_esm_batches_per_clean_inference\": BATCH_SIZE,\n",
+ " \"input_rows\": int(len(df)),\n",
+ " \"rows_over_limits\": rows_over_limits,\n",
+ " \"input_csv\": os.path.abspath(CSV_OUT),\n",
+ " \"input_sha256\": _sha256(CSV_OUT),\n",
+ "}\n",
+ "Path(RUN_CONFIG_OUT).write_text(json.dumps(run_config, indent=2))\n",
+ "\n",
+ "print(f\"Prepared {len(df)} row(s) for mode={mode}.\")\n",
+ "print(\"CLEAN will predict a top EC number and confidence score before any catrange kinetics predictions are made.\")\n",
+ "print(f\"CLEAN will use esm_batches_per_clean_inference={BATCH_SIZE} in this notebook.\")\n",
+ "print(f\"Accepted sequence length range: 9 to {MAX_SEQ_LENGTH} amino acids.\")\n",
+ "print(f\"Accepted SMILES length range: 2 to {MAX_SMILES_LENGTH} characters.\")\n",
+ "if mode != \"Bulk-large\":\n",
+ " print(f\"Batch size is saved as {BATCH_SIZE} and only used by Bulk-large mode.\")\n",
+ "if rows_over_limits:\n",
+ " print(\n",
+ " f\"Warning: {rows_over_limits} row(s) exceed the sequence or SMILES limits and will be marked as skipped.\"\n",
+ " )\n",
+ "print(\"Saved infer_input.csv and run_config.json for this run.\")\n",
+ "\n",
+ "display_columns = [\n",
+ " column\n",
+ " for column in [\n",
+ " \"clean_row_id\",\n",
+ " \"sequence_length\",\n",
+ " \"smiles_length\",\n",
+ " \"within_length_limits\",\n",
+ " ]\n",
+ " if column in preview_df.columns\n",
+ "]\n",
+ "if display_columns:\n",
+ " display(preview_df[display_columns].head(min(10, len(preview_df))))\n",
+ "\n",
+ "from IPython import get_ipython\n",
+ "\n",
+ "ip = get_ipython()\n",
+ "env_values = {\n",
+ " \"MODE\": mode,\n",
+ " \"CSV_PATH\": os.path.abspath(CSV_OUT),\n",
+ " \"BATCH_SIZE\": str(BATCH_SIZE),\n",
+ " \"MUTATION_MODE\": mutation_mode,\n",
+ " \"CLEAN_NON_ENZYME_THRESHOLD\": str(float(clean_non_enzyme_threshold)),\n",
+ " \"RUN_CONFIG_PATH\": os.path.abspath(RUN_CONFIG_OUT),\n",
+ " \"NOTEBOOK_RELEASE\": NOTEBOOK_RELEASE,\n",
+ "}\n",
+ "for key, value in env_values.items():\n",
+ " ip.run_line_magic(\"env\", f\"{key}={value}\")\n"
+ ],
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/",
+ "height": 435
+ },
+ "cellView": "form",
+ "id": "XGMrWhdZPAs9",
+ "outputId": "297c2d3e-3a6f-4bff-c58e-e8896bd43deb"
+ },
+ "execution_count": null,
+ "outputs": [
+ {
+ "output_type": "stream",
+ "name": "stdout",
+ "text": [
+ "Prepared 4 row(s) for mode=Demo.\n",
+ "CLEAN will predict a top EC number and confidence score before any catrange kinetics predictions are made.\n",
+ "CLEAN will use esm_batches_per_clean_inference=20 in this notebook.\n",
+ "Accepted sequence length range: 9 to 1022 amino acids.\n",
+ "Accepted SMILES length range: 2 to 512 characters.\n",
+ "Batch size is saved as 20 and only used by Bulk-large mode.\n",
+ "Warning: 2 row(s) exceed the sequence or SMILES limits and will be marked as skipped.\n",
+ "Saved infer_input.csv and run_config.json for this run.\n"
+ ]
+ },
+ {
+ "output_type": "display_data",
+ "data": {
+ "text/plain": [
+ " clean_row_id sequence_length smiles_length within_length_limits\n",
+ "0 0 312 20 True\n",
+ "1 1 359 24 True\n",
+ "2 2 1023 6 False\n",
+ "3 3 6 513 False"
+ ],
+ "text/html": [
+ "\n",
+ " | \n", + " | clean_row_id | \n", + "sequence_length | \n", + "smiles_length | \n", + "within_length_limits | \n", + "
|---|---|---|---|---|
| 0 | \n", + "0 | \n", + "312 | \n", + "20 | \n", + "True | \n", + "
| 1 | \n", + "1 | \n", + "359 | \n", + "24 | \n", + "True | \n", + "
| 2 | \n", + "2 | \n", + "1023 | \n", + "6 | \n", + "False | \n", + "
| 3 | \n", + "3 | \n", + "6 | \n", + "513 | \n", + "False | \n", + "
| \n", + " | metric | \n", + "value | \n", + "
|---|---|---|
| 0 | \n", + "Rows classified as enzyme | \n", + "2 | \n", + "
| 1 | \n", + "Rows with catrange kinetics predictions | \n", + "2 | \n", + "
| \n", + " | Input row | \n", + "Protein sequence | \n", + "Substrate (Isomeric SMILES) | \n", + "Classified as enzyme? | \n", + "Predicted EC number | \n", + "Other possible EC numbers | \n", + "Pipeline note | \n", + "Predicted kcat range (s^-1) | \n", + "Predicted kcat uncertainty range (s^-1) | \n", + "Predicted KM range (M) | \n", + "Predicted KM uncertainty range (M) | \n", + "
|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", + "0 | \n", + "MKVAVLGAAGGIGQALALLLKTQLPSGSELSLYDIAPVTPGVAVDL... | \n", + "C(C(=O)C(=O)O)C(=O)O | \n", + "Yes | \n", + "1.1.1.37 | \n", + "NaN | \n", + "catrange prediction completed | \n", + "[1.00e+02, 1.00e+03] s^-1 | \n", + "[1.00e+01, 1.00e+08] s^-1 | \n", + "[1.00e-05, 1.00e-04] M | \n", + "[1.00e-14, 1.00e-03] M | \n", + "
| 1 | \n", + "1 | \n", + "MGVEQILKRKTGVIVGEDVHNLFTYAKEHKFAIPAINVTSSSTAVA... | \n", + "C([C@H](C=O)O)OP(=O)(O)O | \n", + "Yes | \n", + "4.1.2.13 | \n", + "NaN | \n", + "catrange prediction completed | \n", + "[1.00e+00, 1.00e+01] s^-1 | \n", + "[1.00e-01, 1.00e+02] s^-1 | \n", + "[1.00e-04, 1.00e-03] M | \n", + "[1.00e-05, 1.00e-02] M | \n", + "