Add a first run MS2Query tutorial

Author: niekdejonge

ms2query/notebooks/tutorial.ipynb

@@ -0,0 +1,196 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "70e60490",
+   "metadata": {},
+   "source": [
+    "# Tutorial for running MS2Query and creating your own libraries"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4d564033",
+   "metadata": {},
+   "source": [
+    "# optional: download a matchms cleaned library\n",
+    "The code below downloads an already matchms cleaned library and an MS2DeepScore model. You can also use your own library, but make sure you know what you are doing and clean the library first. If you just have a few reference spectra, it is probably best to combine your spectra with the reference spectra below to make sure the MS2Query search works properly. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b7df418e",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The file ./zenodo_files\\data_split_inchikeys.json already exists, the file won't be downloaded\n",
+      "The file ./zenodo_files\\merged_and_cleaned_libraries_1.mgf already exists, the file won't be downloaded\n",
+      "The file ./zenodo_files\\ms2deepscore_model.pt already exists, the file won't be downloaded\n"
+     ]
+    }
+   ],
+   "source": [
+    "import requests\n",
+    "import os\n",
+    "from tqdm import tqdm\n",
+    "\n",
+    "def download_file(link, file_name):\n",
+    "    response = requests.get(link, stream=True)\n",
+    "    if os.path.exists(file_name):\n",
+    "        print(f\"The file {file_name} already exists, the file won't be downloaded\")\n",
+    "        return\n",
+    "    total_size = int(response.headers.get('content-length', 0))\n",
+    "\n",
+    "    with open(file_name, \"wb\") as f, tqdm(desc=\"Downloading file\", total=total_size, unit='B', unit_scale=True, unit_divisor=1024,) as bar:\n",
+    "        for chunk in response.iter_content(chunk_size=1024):\n",
+    "            if chunk:\n",
+    "                f.write(chunk)\n",
+    "                bar.update(len(chunk))  # Update progress bar by the chunk size\n",
+    "folder_to_store_zenodo_files = \"./zenodo_files\"\n",
+    "os.makedirs(folder_to_store_zenodo_files, exist_ok=True)\n",
+    "\n",
+    "download_file(\"https://zenodo.org/records/16882111/files/merged_and_cleaned_libraries_1.mgf?download=1\", \n",
+    "              os.path.join(folder_to_store_zenodo_files, \"merged_and_cleaned_libraries_1.mgf\"))\n",
+    "download_file(\"https://zenodo.org/records/17826815/files/ms2deepscore_model.pt?download=1\", \n",
+    "              os.path.join(folder_to_store_zenodo_files, \"ms2deepscore_model.pt\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fa99d2dd",
+   "metadata": {},
+   "source": [
+    "# Specify file location \n",
+    "Replace with your file names"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6db579a9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "library_spectra_file = os.path.join(folder_to_store_zenodo_files, \"merged_and_cleaned_libraries_1.mgf\")\n",
+    "ms2deepscore_model_file_name = os.path.join(folder_to_store_zenodo_files, \"ms2deepscore_model.pt\")\n",
+    "query_spectrum_file = \"replace_with_your_lib_spectra.mgf\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f521c1c4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "1017531it [09:51, 1720.67it/s]\n"
+     ]
+    }
+   ],
+   "source": [
+    "from matchms.importing import load_from_mgf\n",
+    "from tqdm import tqdm\n",
+    "\n",
+    "library_spectra = list(tqdm(load_from_mgf(library_spectra_file)))\n",
+    "query_spectra = list(tqdm(load_from_mgf(query_spectrum_file)))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "64534dd6",
+   "metadata": {},
+   "source": [
+    "# Create the reference library files\n",
+    "The code below will precompute everything needed to run MS2Query. It will save this in the same folder as your ms2deepscore model. \n",
+    "The files created are \"embeddings.npz\", \"top_k_tanimoto_scores.parquet\", \"library_metadata.parquet\". "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "669a489a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ms2query.ms2query_development.ReferenceLibrary import ReferenceLibrary\n",
+    "reference_library = ReferenceLibrary.create_from_spectra(library_spectra, ms2deepscore_model_file_name)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dfd0a633",
+   "metadata": {},
+   "source": [
+    "# Run MS2Query\n",
+    "The code above only has to be run once after that you can load the library faster from the saved files. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e6cf44e2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# no need to run if you just created the libary above\n",
+    "reference_library = ReferenceLibrary.load_from_directory(folder_to_store_zenodo_files)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "566b2b0d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = reference_library.run_ms2query(query_spectra)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "98ce9660",
+   "metadata": {},
+   "source": [
+    "print(results)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b7e3b533",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results.to_csv(\"ms2query_results.csv\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "ms2query_2",
+   "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.11.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}