doc(use-cases): add Use Cases guide + UC1 γ-secretase reproduction

docs/source/conf.py

@@ -13,10 +13,11 @@
 # Create notebooks rst and table rst first
 from create_tables_doc import generate_table_rst
 from create_notebooks_docs import (export_example_notebooks_to_rst, export_tutorial_notebooks_to_rst,
-                                   export_protocol_notebooks_to_rst)
+                                   export_protocol_notebooks_to_rst, export_use_case_notebooks_to_rst)
 
 export_tutorial_notebooks_to_rst()
 export_protocol_notebooks_to_rst()
+export_use_case_notebooks_to_rst()
 export_example_notebooks_to_rst()
 generate_table_rst()
 

docs/source/create_notebooks_docs.py

@@ -35,6 +35,7 @@
 FOLDER_SOURCE = os.path.dirname(os.path.abspath(__file__)) + SEP
 FOLDER_TUTORIALS = FOLDER_PROJECT + "tutorials" + SEP
 FOLDER_PROTOCOLS = FOLDER_PROJECT + "protocols" + SEP
+FOLDER_USE_CASES = FOLDER_PROJECT + "use_cases" + SEP
 FOLDER_GENERATED_RST = FOLDER_SOURCE + "generated" + SEP  # Saving .rst directly in 'generated'
 FOLDER_EXAMPLES = FOLDER_PROJECT + "examples" + SEP
 FOLDER_EXAMPLES_RST = FOLDER_GENERATED_RST + "examples" + SEP
@@ -122,6 +123,29 @@ def export_protocol_notebooks_to_rst():
             writer.write(output, resources, notebook_name=filename.replace('.ipynb', ''))
 
 
+def export_use_case_notebooks_to_rst():
+    """Export Jupyter use cases to RST without execution.
+
+    Use-case notebooks live flat in the top-level ``use_cases/`` folder and are
+    written to the same ``generated/`` directory as the tutorials and protocols,
+    so the ``use_cases.rst`` toctree references them as ``generated/<name>``.
+    """
+    for filename in os.listdir(FOLDER_USE_CASES):
+        if filename.endswith('.ipynb') and filename not in LIST_EXCLUDE:
+            notebook_name = filename.replace('.ipynb', '')
+            full_path = os.path.join(FOLDER_USE_CASES, filename)
+            # Load the notebook
+            with open(full_path, 'r') as f:
+                notebook = nbformat.read(f, as_version=4)
+            # Convert to notebook to RST
+            custom_preprocessor = CustomPreprocessor(notebook_name=notebook_name)
+            rst_exporter = nbconvert.RSTExporter(preprocessors=[custom_preprocessor])
+            output, resources = rst_exporter.from_notebook_node(notebook)
+            # Write the RST and any accompanying files (like images)
+            writer = FilesWriter(build_directory=FOLDER_GENERATED_RST)
+            writer.write(output, resources, notebook_name=filename.replace('.ipynb', ''))
+
+
 def export_example_notebooks_to_rst():
     """Export Jupyter examples to RST without execution."""
     for root, dirs, files in os.walk(FOLDER_EXAMPLES):

docs/source/getting_started.rst

@@ -3,7 +3,7 @@
    The paths to notebooks are relative to ensure compatibility with the Sphinx referencing system
    used throughout the documentation. Getting Started is the onboarding pillar: only the first
    success belongs here (install + first result + publication-ready plots), no deep theory — that
-   is what the Tutorials and Protocols pillars are for.
+   is what the Tutorials, Protocols, and Use Cases pillars are for.
 ..
 
 

docs/source/index.rst

@@ -19,7 +19,7 @@ Pick a section by what you want to do:
    - **New here** and want a first result → :ref:`Getting Started <getting_started>`.
    - Learn what **one specific tool** does, with its parameters and outputs → :ref:`Tutorials <tutorials>`.
    - **Design a valid, end-to-end analysis** for a biological question → :ref:`Protocols <protocols>`.
-   - **Adapt a full biological case study** to your own data → Use Cases *(coming soon)*.
+   - **Adapt a full biological case study** to your own data → :ref:`Use Cases <use_cases>`.
    - Look up the **exact signature, parameters, or return value** → :doc:`API <api>`.
 
 Install
@@ -85,6 +85,7 @@ classes grouped by capability, the prediction levels (residue / domain / protein
 
    tutorials.rst
    protocols.rst
+   use_cases.rst
 
 .. toctree::
    :maxdepth: 2

docs/source/index/introduction.rst

@@ -50,8 +50,9 @@ mental models necessary for effective application, and see the :ref:`Evaluation
 strategies for a transparent, objective analysis of the algorithms´ outcomes.
 
 **Guides**: For hands-on experience, the :ref:`Tutorials <tutorials>` teach each tool with its
-parameters and outputs, while the :ref:`Protocols <protocols>` walk through complete, end-to-end
-analyses for biological questions.
+parameters and outputs, the :ref:`Protocols <protocols>` walk through complete, end-to-end
+analyses for biological questions, and the :ref:`Use Cases <use_cases>` reproduce published
+studies end to end from bundled data.
 
 **Reference**: Look up the exact signatures in the :ref:`API <api>` documentation, browse the
 overview :ref:`Tables <tables>` (including the **AAontology** scale classification and benchmark

docs/source/index/release_notes.rst

@@ -199,9 +199,14 @@ Added
 - **A minimal CPP analysis** tutorial (``tutorial0_minimal``): the shortest end-to-end
   loop — load a dataset, run CPP, read out the signature.
 - **Documentation navigation**: the sidebar is grouped into four sections — *Overview*,
-  *Guides* (Tutorials · Protocols), *Reference*, and *Project* — and the landing page gains a
-  "You want to… / Go to" routing table; the previously unwired **Comparison Harness**
-  tutorial (``tutorial6_comparison_harness``) is now reachable.
+  *Guides* (Tutorials · Protocols · Use Cases), *Reference*, and *Project* — and the landing
+  page gains a "You want to… / Go to" routing table; the previously unwired **Comparison
+  Harness** tutorial (``tutorial6_comparison_harness``) is now reachable.
+- **Use Cases** guide (third *Guides* subchapter): each use case reproduces a published
+  study end to end from bundled data. The first, *UC1: Charting gamma-secretase substrates*
+  (``use_case1_gamma_secretase``), reproduces the key results of Breimann *et al.*, Nat.
+  Commun. 2025 — the CPP signature and the CPP-vs-scale-based benchmark (~85% balanced
+  accuracy) — on the bundled ``DOM_GSEC`` set.
 - **Standardized tutorial header box**: every tool tutorial now opens with a uniform
   green *You will learn* box (Tool · Input · Output · Best used for · Related protocol ·
   Related API), giving a one-glance answer to *what tool, what goes in, what comes out,

docs/source/index/usage_principles/prediction_tasks.rst

@@ -165,5 +165,7 @@ Where to go next
      this table into a start-to-finish workflow.
    - **Mechanics:** the per-function :ref:`tutorials <tutorials>` cover
      ``CPP``, ``SequenceFeature``, ``AAclust``, and the rest.
+   - **Full case studies:** the :ref:`use cases <use_cases>` reproduce a
+     published study end to end, as a template to adapt to your own data.
    - **Vocabulary:** every term used here is defined in the
      :ref:`glossary <glossary>`.

docs/source/use_cases.rst

@@ -0,0 +1,32 @@
+..
+   Developer Notes:
+   Use-case notebooks live in the top-level ``use_cases/`` folder (flat) and are
+   auto-converted to ``generated/`` by ``create_notebooks_docs.py`` (called from
+   ``conf.py``). A use case reproduces a published study end to end from bundled
+   data; it must stay distinct from the per-function Tutorials and the
+   single-question Protocols (no content overlap).
+..
+
+
+.. _use_cases:
+
+Use Cases
+=========
+
+**Tutorials, protocols, and use cases are different things.** A
+:ref:`tutorial <tutorials>` teaches you *one function*. A :ref:`protocol <protocols>`
+teaches you a *workflow* that answers one biological question. A **use case** goes
+one level up: it **reproduces a published study** end to end with AAanalysis, so you
+can see that a real result drops out of the standard pipeline — and use it as the
+template to adapt to your own paper-style analysis. Where a use case calls a tool,
+it links to that tool's tutorial for the mechanics instead of repeating them, so the
+three stay distinct with no overlap.
+
+Each use case runs from **bundled data only** (no downloads) and is a simplified,
+fast reproduction: it reproduces the *key results* and the *biology*, and points to
+the Protocols for scaling up to the full study.
+
+.. toctree::
+   :maxdepth: 1
+
+   generated/use_case1_gamma_secretase