Improve projection notebook

tutorials/Projection/notebook.ipynb

@@ -1,5 +1,22 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6e867844",
+   "metadata": {},
+   "source": [
+    "# PanGBank Tutorial: Projecting AMR-Annotated Pangenomes onto a New Genome\n",
+    "\n",
+    "This tutorial demonstrates how to:\n",
+    "1. Retrieve pangenomes from [PanGBank](https://pangbank.genoscope.cns.fr/)\n",
+    "2. Annotate gene families with [AMRFinderPlus](https://github.com/ncbi/amr)\n",
+    "3. Inject AMR metadata into the pangenome\n",
+    "4. Project the pangenome onto a query genome assembly\n",
+    "5. Explore projected AMR genes with interactive genome views\n",
+    "\n",
+    "**Before starting, run the initialization cell below once.**"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -49,14 +66,34 @@
     "!{amrfinder_command} -u"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "bdf40c4e",
+   "metadata": {},
+   "source": [
+    "## Step 1: Download the Reference Pangenome\n",
+    "\n",
+    "Retrieve the *Acinetobacter nosocomialis* pangenome from the GTDB_refseq collection using PanGBank."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "5c2d7235-6a21-4871-9a30-75ad37277999",
    "metadata": {},
    "outputs": [],
    "source": [
-    "! pangbank search-pangenomes -t s__Acinetobacter_nosocomialis -c GTDB_refseq --download --release-version 1.0.0"
+    "! pangbank search-pangenomes -t s__Acinetobacter_nosocomialis -c GTDB_refseq --download --release-version 2.0.0"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "940dc52d",
+   "metadata": {},
+   "source": [
+    "## Step 1.1: Select the Downloaded Pangenome File\n",
+    "\n",
+    "Set the pangenome file path used by all subsequent commands."
    ]
   },
   {
@@ -66,7 +103,17 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "pangenome_file = \"pangbank/GTDB_refseq_s__Acinetobacter_nosocomialis_id47.h5\""
+    "pangenome_file = \"pangbank/GTDB_refseq_s__Acinetobacter_nosocomialis_id10852.h5\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6b2af9d2",
+   "metadata": {},
+   "source": [
+    "## Step 2: Extract Protein Family Sequences\n",
+    "\n",
+    "Export all protein family sequences from the selected pangenome so they can be screened by AMRFinderPlus."
    ]
   },
   {
@@ -80,6 +127,16 @@
     "families_protein_sequences = \"families_faa_output/all_protein_families.faa.gz\""
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "67568c36",
+   "metadata": {},
+   "source": [
+    "## Step 3: Annotate Protein Families with AMRFinderPlus\n",
+    "\n",
+    "Run AMRFinderPlus on exported family proteins, format the output for PPanGGOLiN metadata ingestion, then attach AMR annotations to pangenome families."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -118,6 +175,16 @@
     "! {pp_command} metadata --pangenome {pangenome_file} --metadata  amrfinder_result.tsv  --source amrfinder --assign families"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a17058e3",
+   "metadata": {},
+   "source": [
+    "## Step 4: Project the Pangenome onto a Query Genome\n",
+    "\n",
+    "Download a query assembly and run PPanGGOLiN projection to map pangenome families and metadata onto this genome."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -138,6 +205,18 @@
     "! {pp_command} projection -p {pangenome_file} --fasta GCA_036820015.1_ASM3682001v1_genomic.fna.gz --gff --proksee"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "5ca02ca4",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "# Data Analysis: Visualizing the Projected Genome\n",
+    "\n",
+    "Render the Proksee/CGView JSON output to inspect projected genomic features in an interactive circular view."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -200,6 +279,16 @@
     "HTML(html)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "3e923c5f",
+   "metadata": {},
+   "source": [
+    "## Extract AMR Features from the Projected GFF\n",
+    "\n",
+    "Load the projected GFF file, collect AMR-related attributes, and build a structured table for downstream exploration."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -263,6 +352,16 @@
     "df = pd.DataFrame(data, columns=[\"seqid\", \"type\", \"start\", \"end\", \"strand\", \"ID\", \"partition\", \"family\"] + AMR_FIELDS)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "15c5235f",
+   "metadata": {},
+   "source": [
+    "## Inspect the Final AMR Annotation Table\n",
+    "\n",
+    "Display the parsed AMR feature table for quick manual review."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,