Predict cluster annotation embedding docs update

source/walkthroughs/antibody-hit-selection-ngs.rst

@@ -7,10 +7,9 @@ This recommended end-to-end workflow guides you through selecting antibody hits
 from NGS-derived libraries using the **Dataset Assay Details** page. Each step assumes 
 the previous step's output is in place.
 
-This walkthrough is task-oriented. For a detailed feature reference of the controls used below like Predict, Clustering, Advanced Filters, and the Antibody
-settings panel, see comprehensive guide at:doc:`/web-app/opmodels/dataset-assay`.
+This walkthrough is task-oriented. For a detailed feature reference of the controls used below, view the following pages: `predict withina a table <https://docs.openprotein.ai/web-app/poet/score-sequences.html>`, 'Clustering <https://docs.openprotein.ai/web-app/opmodels/cluster.html>`, and the `Antibody settings panel<https://docs.openprotein.ai/web-app/opmodels/antibody-annotations.html>`.
 
-.. figure:: /_static/walkthroughs/antibody-hit-selection-ngs/dataset-assay-overview.png
+.. figure:: /_static/walkthroughs/antibody-hit-selection-ngs/ngs-dataset-assay-overview.png
    :alt: Dataset Assay Details page overview, showing tabs, header chips, and action bar
 
 
@@ -44,6 +43,9 @@ On the **Dataset** tab, open the **Antibody** panel, then configure the followin
 
 You now have a fully annotated table view of the library.
 
+.. figure:: /_static/walkthroughs/antibody-hit-selection-ngs/ngs-antibody-view.png
+   :alt: open the antibody panel
+
 
 Reduce redundancy with Clustering
 =================================
@@ -61,6 +63,8 @@ downstream steps operate on diverse families.
 
 You now have a ``Cluster Number`` column.
 
+.. figure:: /_static/walkthroughs/antibody-hit-selection-ngs/ngs-cluster.png
+   :alt: view cluster column
 
 Pre-filter using NGS / antibody metadata
 ========================================
@@ -86,6 +90,8 @@ Open **Advanced Filters** from the Dataset tab and apply the following filters i
 Toggle **Show select column** if you want to see what got rejected instead of
 hiding it.
 
+.. figure:: /_static/walkthroughs/antibody-hit-selection-ngs/ngs-advanced-filters.png
+   :alt: view cluster column
 
 Score with Predict
 ======================
@@ -103,6 +109,9 @@ With the candidate set narrowed, run a model to rank within it.
 **Scale with parallel predictions**: You can run multiple predictions in parallel — for example, one for binding
 and one for developability. Each gets its own chip and its own column.
 
+.. figure:: /_static/walkthroughs/antibody-hit-selection-ngs/ngs-predict.png
+   :alt: view cluster column
+
 
 Combine signals
 ================

source/web-app/opmodels/antibody-annotation.rst

@@ -0,0 +1,116 @@
+Automatic Antibody Annotation
+==============================
+
+This tutorial shows you how the platform automatically annotates antibody sequences on upload: identifying CDR regions, flagging known liabilities, and calling germline V-genes, alleles, and mutation load, all without a separate annotation step.
+
+Use this as a starting point for screening a dataset for developability risk or germline diversity before moving on to embedding, clustering, or scoring.
+
+If you run into any challenges or have questions while getting started, please contact `OpenProtein.AI support <https://www.openprotein.ai/contact>`_.
+
+
+What You Need Before Starting
+------------------------------
+
+You need a sequence-only CSV file of antibody sequences. No header row or extra metadata columns are required, the platform detects VH and VL chains on its own and needs no manual chain labeling or numbering.
+
+
+Upload Your Dataset
+^^^^^^^^^^^^^^^^^^^^^
+
+Upload your CSV the same way you would a `dataset<https://docs.openprotein.ai/web-app/opmodels/uploading-your-data.html>`. You do not need to upload a csv with properties. If the sequences are recognized as antibodies, the table automatically gains a set of **CDR1** / **CDR2** / **CDR3** / **Liability** chips above the grid, and an **Antibody** entry appears in the table toolbar alongside **Dataset Info**, **Kabat**, **Consensus**, **Settings**, **Collapse**, **Filters**, and **Export**.
+
+No separate annotation job is needed. Non-antibody protein datasets will not show the Antibody control, since there's no CDR or germline structure to annotate.
+
+
+
+Viewing the antibody settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Click **Antibody** in the toolbar to open the annotation panel.
+
+- **Highlight CDRs** lets you toggle **Show CDR1** / **CDR2** / **CDR3** independently. Each region is color-coded directly inside the VH and VL sequence text in the table.
+- **Sequence view** offers **Aligned** (pad sequences to a common length for side-by-side comparison) and **Trim non-standard positions**.
+- The numbering scheme used to define the CDR boundaries (Kabat, by default) is set from the separate **Kabat** dropdown next to Antibody in the toolbar.
+
+.. image:: /_static/opmodels/annontation/annontation-1.png
+  :alt: Antibody panel open showing Highlight CDRs, Sequence view, Liabilities, and Show antibody columns controls
+
+
+Review Flagged Liabilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The **Liabilities** section flags residues or motifs known to affect antibody developability.
+
+- Choose **Highlight** to mark liabilities directly in the sequence text while still seeing every row.
+- Switch to **Filter** to narrow the table down to rows that contain a flagged liability.
+- **Show column** adds a dedicated Liability column to the grid, matching the red **Liability** chip shown above the table alongside the CDR chips.
+
+Use Highlight while you're still exploring the dataset broadly, and switch to Filter once you're ready to narrow in on sequences that need to be deprioritized or redesigned around a specific liability.
+
+
+Choose which antibody columns to show
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Show antibody columns** controls which germline and mutation metrics appear in the grid. It's split into two groups:
+
+- **Gene**: Germline pair, Heavy V-Gene, and Light V-Gene, each with an **Allele** toggle that switches the calls between gene-level (for example ``IGHV1-69``) and allele-level (for example ``IGHV1-69*01``) precision.
+- **Metrics**: Germline pair frequency, Total Mutations, CDR3 length, and Germline distance, numeric summaries computed from each sequence's alignment back to its called germline.
+
+
+Read the Annotated Table
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Every selected column appears directly in the grid. VH and VL show the full sequence with CDR1, CDR2, and CDR3 shaded in distinct colors inline, followed by the germline and mutation columns you selected: Germline Pair, Germline Pair Frequency, Heavy V-Gene, Light V-Gene, Total Mutations, and more.
+
+.. image:: /_static/opmodels/annontation/annotation-2.png
+  :alt: Dataset table with VH and VL columns showing color-coded CDR highlighting, plus Germline Pair, Germline Pair Frequency, Heavy V-Gene, Light V-Gene, and Total Mutations columns
+
+From here, sort or filter on any of these columns the same way you would elsewhere in the table, and combine them with Embedding, Cluster, or Predictions to bring germline and liability context into hit selection.
+
+
+Column Reference
+-----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30
+   :align: left
+
+   * - Column
+     - What it tells you
+   * - Germline Pair
+     - The closest matching heavy and light germline gene (or allele, if the Allele toggle is on) called together, for example ``IGHV1-69*01_IGLV1-44*01``.
+   * - Germline Pair Frequency
+     - How often this exact germline pairing occurs across the dataset, a quick signal of whether a sequence sits in a common or rare germline background.
+   * - Heavy V-Gene / Light V-Gene
+     - The called germline V-gene for each chain individually, with the Allele toggle switching between gene-level and allele-level precision.
+   * - Total Mutations
+     - Count of amino acid differences between the sequence and its called germline, a proxy for how far a sequence has diverged through affinity maturation or engineering.
+   * - CDR3 length
+     - Length of the CDR3 loop, useful for spotting unusually long or short CDR3s that may affect developability or expression.
+   * - Germline distance
+     - Overall sequence distance from the called germline, a broader divergence measure than Total Mutations alone.
+   * - Liability
+     - Flags residues or motifs associated with known developability risks (for example deamidation, oxidation, glycosylation sites), shown inline via Highlight or as its own column via Show column.
+
+
+Tips and Troubleshooting
+--------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20
+   :align: left
+
+   * - Question
+     - Answer
+   * - Do I need to tell the platform which columns are heavy chain versus light chain?
+     - No. A sequence-only upload is enough, the platform detects VH and VL chains and numbers them automatically. There's no separate setup step before the Antibody panel becomes available.
+   * - Why would I turn on Allele instead of leaving germline calls at the gene level?
+     - Allele-level calls (for example ``IGHV1-69*01``) are more specific and useful when you need to track fine-grained germline differences, such as comparing sequences that share a V-gene but differ by allele. Gene-level calls are easier to scan when you just want a broad family view.
+   * - My sequences aren't getting annotated as antibodies.
+     - Confirm the upload is a plain sequence-only CSV or FASTA (no unexpected extra columns before the sequence data) and that the sequences resemble recognizable antibody variable domains. Non-antibody protein datasets won't show the Antibody control since there's no CDR or germline structure to annotate.
+   * - How does this relate to Embedding, Cluster, and Predictions?
+     - Antibody annotation is descriptive context computed directly from sequence, it doesn't require an embedding job to run first. You can use it on its own to screen for liabilities and germline diversity, or alongside Embedding, Cluster, and Predictions for a fuller view when selecting hits.
+
+Please contact `OpenProtein.AI support <https://www.openprotein.ai/contact>`_ if the suggested solutions don't resolve the issue.

source/web-app/opmodels/cluster-sequences.rst

@@ -0,0 +1,159 @@
+Cluster sequences in a table
+=====================================
+
+Overview
+--------
+
+Clustering groups the sequences in a table by similarity in embedding space, using hierarchical clustering on top of a protein language model embedding (for example, PoET-2). Once a clustering job finishes, every sequence gets a cluster label you can view as a color-coded UMAP, browse as a column in the table, and use to filter or select groups of related sequences.
+
+
+Where this applies
+---------------------
+
+The Cluster control lives in the same toolbar (alongside Embedding and Predictions) above every sequence table in the product, so the steps below work the same way across **Generate**, **Score**, and **Design**.
+
+
+Before you start
+-------------------
+
+- Have a sequence table open.
+- Clustering runs on top of an **embedding**. You will be able to pick an embedding model as part of the setup, so you don't need to precompute one separately.
+- How to build the **prompt** for the embedding model, see Embedding Model and Prompt below.
+
+
+1. Open the cluster panel
+----------------------------
+
+In the toolbar above the table, click the **Cluster** dropdown (it reads ``None`` if nothing is clustered yet). This opens the **Cluster** panel, which lists any existing clustering jobs that had already been run against the table and their settings (embedding, method, linkage, distance metric).
+
+To start a new one, click **New clustering** in the top-right of the panel.
+
+.. figure:: /_static/opmodels/cluster/cluster-1.png
+   :alt: new cluster job
+
+**Tip:** If a clustering job has already been run on this table, you can just select it from this list instead of creating a new one, jump to Step 4 below.
+
+
+2. Configure the Cclustering job
+-----------------------------------
+
+**New clustering** opens the **Cluster Sequences** dialog. This clusters every sequence in the table using the embedding model and method you choose here.
+
+.. figure:: /_static/opmodels/cluster/cluster-2.png
+   :alt: configuring settings for embedding model
+
+*The Cluster sequences dialog: pick an embedding model and prompt on top, then a reduction type and hierarchical clustering method below.*
+
+Embedding model and prompt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Embedding model**: choose which protein language model generates the embeddings sequences are clustered on. The current recommended default is **PoET-2**.
+- **Prompt**: PoET family models are conditional, so they need a prompt for context. Reuse an existing saved prompt from the list, or click **+ Create new prompt** to build a new one. See `prompt and prompt sampling methods <./prompts.rst>`_ on how to build a prompt.
+
+.. figure:: /_static/opmodels/cluster/cluster-3.png
+   :alt: building a prompt for PoET-2 as the selected embedding model
+
+**Note:** Models without a conditional prompt requirement (e.g. ESM) will skip the prompt step. If you see the error *"Prompt Query: Please enter a sequence or upload a file..."*, either finish building/selecting a prompt or switch to a model that doesn't require one.
+
+Reduction type and clustering method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Reduction type**: how per-residue embeddings are collapsed into a single vector per sequence (Recommended: ``Mean``).
+- **Linkage method**: the hierarchical clustering linkage criterion (Recommended: ``Ward``).
+- **Distance metric**: the distance used between embedding vectors (Recommended: ``Euclidean``). Some linkage methods, like Ward, require Euclidean distance and will lock this field automatically.
+
+.. figure:: /_static/opmodels/cluster/cluster-4.png
+   :alt: configuring cluster method and reduction types
+
+When everything is set, click **Run**.
+
+
+3. Run the job and wait for it to finish
+--------------------------------------------
+
+Clustering runs asynchronously. After you click Run, a job status bar appears above the table, and the **Jobs** counter in the top-right increments. You can keep working, open the Jobs panel any time to check progress, and the new cluster becomes selectable in the Cluster dropdown once it completes. Refresh your browser to view the completed jobs.
+
+
+4. Select the cluster and tune its resolution
+-------------------------------------------------
+
+Open the Cluster dropdown and click a clustering run to select it. Two additional controls appear for hierarchical clusterings:
+
+- **Number of clusters**: cuts the hierarchical dendrogram to produce exactly this many clusters.
+- **Cluster distance**: alternatively, cut the dendrogram at a given distance threshold, adjusting one updates the other.
+
+.. figure:: /_static/opmodels/cluster/cluster-5.png
+   :alt: configuring cluster distance and number of clusters
+
+Both update instantly against the already-computed job, so you can explore coarser or finer groupings without re-running the clustering. Click **Deselect cluster** to go back to ``None``.
+
+*With a cluster selected, use Number of clusters or Cluster distance to change resolution on the fly.*
+
+
+5. Use the results
+----------------------
+
+- **UMAP tab**: in the right-hand Dataset panel, set **Discrete** to **Cluster** to color every point by its cluster assignment, using a distinct-colors legend numbered 1, 2, 3, etc.
+- **Dataset / results table**: each row shows its assigned cluster once a clustering is selected, so you can sort or filter the table by cluster.
+- **Downstream actions**: select a cluster's points on the UMAP (click, or Shift-drag to multi-select) to view them in the table.
+
+.. figure:: /_static/opmodels/cluster/cluster-6.gif
+   :alt: selecting sequences in a cluster to view in the table
+
+*UMAP colored by cluster (Discrete to Cluster), with each of the 10 clusters shown in a distinct color.*
+
+**Tip:** Switch **Discrete** back to a continuous property at any time to compare cluster structure against an experimental readout side by side.
+
+
+Settings reference
+----------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 12 30
+   :align: left
+
+   * - Setting
+     - Required?
+     - What it controls
+   * - Embedding model
+     - Required
+     - Which protein language model produces the per-sequence embeddings clustering runs on (PoET-2, ESM variants, AbLang, etc.).
+   * - Prompt
+     - Model-dependent
+     - Context sequences used by conditional models (PoET family). Reuse a saved prompt or build one via Homology Search, MSA upload, Property Based Sample, or direct Upload.
+   * - Reduction type
+     - Required
+     - How per-residue embeddings are pooled into one vector per sequence (e.g. Mean).
+   * - Linkage method
+     - Required
+     - Hierarchical clustering linkage criterion, e.g. Ward, complete, average.
+   * - Distance metric
+     - Required
+     - Distance function between embeddings, e.g. Euclidean. Some linkage methods force this to Euclidean.
+   * - Number of clusters
+     - Post-run
+     - Cuts the dendrogram to a target cluster count. Adjustable after the job completes, no re-run needed.
+   * - Cluster distance
+     - Post-run
+     - Cuts the dendrogram at a distance threshold instead of a fixed count. Linked to Number of clusters.
+
+
+Tips and troubleshooting
+----------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20
+   :align: left
+
+   * - Question
+     - Answer
+   * - The Run button gives a "Prompt Query" error.
+     - The selected embedding model needs a prompt but none is attached yet. Select an existing prompt from the list, finish building a new one and submit it, or pick a model that doesn't require a prompt.
+   * - Can I re-cluster with different settings without losing my current one?
+     - Yes. Click New clustering again to start another run with different embedding/method settings. Every run is saved and listed in the Cluster dropdown, so you can switch between them freely.
+   * - Do I need to rerun the job to see more or fewer clusters?
+     - No. Number of clusters and Cluster distance are applied on top of the already-computed dendrogram, so changing them is instant.
+   * - Does this work the same in Design and Predict results tables?
+     - Yes. The Cluster control sits in the same toolbar position in Dataset, Design, and Predict result views, and the setup dialog and UMAP coloring behave identically.