Updating docs for mnpFlex

Author: mattloose

CHANGELOG.md

@@ -58,7 +58,7 @@ and this project (almost) adheres to [Semantic Versioning](https://semver.org/sp
 - IGV-ready BAM creation for consistent genome browser loading.
 - Workflow support for `igv_bam` and `snp_analysis` job types.
 - SNP analysis queueing from the GUI with concurrency control.
-- MNP-FLEX upload support for bedMethyl outputs for beta users with Epignostix credentials (https://epignostix.com/). Supply credentials via `MNPFLEX_USER` and `MNPFLEX_PASS` environment variables.
+- MNP-FLEX upload support for bedMethyl outputs for beta users with Epignostix credentials (https://epignostix.com/). The initial implementation used `MNPFLEX_USER` and `MNPFLEX_PASS`; current GUI and batch integrations use `MNPFLEX_USERNAME` and `MNPFLEX_PASSWORD`.
 - `robin utils mgmt` command to summarize MGMT CpG site methylation counts from `mgmt_sorted.bam` outputs.
 
 ### Changed

README.md

@@ -15,6 +15,7 @@
 - [Common issues](#common-issues)
 - [Usage](#usage)
   - [BAM read limit and MinKNOW](#bam-read-limit-and-minknow-settings)
+  - [Optional MNP-Flex integration](#optional-mnp-flex-integration)
 - [Command reference](#command-reference)
 - [Known issues and limitations](#known-issues-and-limitations)
 - [Performance](#performance)
@@ -167,6 +168,18 @@ You can add that to your shell config (after conda init).
 
 On machines with **≤ 64 GB RAM**, restart the machine (or at least Dorado) before a heavy run. Dorado can retain memory indefinitely; on a P2i, after a run on position A and then B, restarting after position B (once basecalling finishes) is recommended.
 
+### Optional MNP-Flex integration
+
+ROBIN can submit methylation data to the commercial **MNP-Flex** service from
+Heidelberg Epignostix and display the returned results in the GUI. This
+requires an agreement and credentials from Epignostix.
+
+Set `MNPFLEX_USERNAME` and `MNPFLEX_PASSWORD` in the server environment before
+starting ROBIN. See the
+[MNP-Flex setup guide](docs/getting-started/mnpflex.md) for configuration,
+data-transfer considerations, optional API settings, operation, and
+troubleshooting.
+
 ### Example workflows
 
 Primary pattern:

docs/getting-started/mnpflex.md

@@ -0,0 +1,138 @@
+# MNP-Flex setup
+
+ROBIN can submit methylation data to **MNP-Flex** and display the returned
+classification, quality-control, and MGMT results in the web interface.
+MNP-Flex is a commercial service provided by
+[Heidelberg Epignostix GmbH](https://epignostix.com/).
+
+## Before you begin
+
+You need:
+
+- An agreement with Epignostix covering use of MNP-Flex.
+- An Epignostix username and password with access to the MNP-Flex service.
+- A ROBIN workflow that produces the per-sample methylation parquet file.
+- Network access from the machine running ROBIN to the Epignostix service.
+
+ROBIN sends sample-derived methylation data to an external service. Confirm
+that this is permitted by your local information-governance and data-transfer
+policies before enabling the integration.
+
+## Configure credentials
+
+Set the credentials in the environment of the **server process running
+ROBIN**, before starting `robin workflow`:
+
+```bash
+export MNPFLEX_USERNAME="your-epignostix-username"
+export MNPFLEX_PASSWORD="your-epignostix-password"
+```
+
+Then start ROBIN from the same shell:
+
+```bash
+robin workflow <data_folder> \
+  --work-dir <output_folder> \
+  --reference <reference.fa> \
+  --center <center_id>
+```
+
+Both variables are required. If either is absent, ROBIN hides the MNP-Flex
+controls and does not submit samples.
+
+Do not put credentials in the repository, command history, workflow output,
+screenshots, or other files that may be shared. For a persistent deployment,
+configure these variables through the service manager or secret-management
+system used to launch ROBIN.
+
+!!! note "Legacy variable names"
+
+    Older ROBIN code and release notes may refer to `MNPFLEX_USER` and
+    `MNPFLEX_PASS`. Current GUI and batch integration uses
+    `MNPFLEX_USERNAME` and `MNPFLEX_PASSWORD`; use the current names for new
+    deployments.
+
+## Optional settings
+
+The defaults match the standard Epignostix integration. Change these only when
+Epignostix supplies different values:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MNPFLEX_BASE_URL` | `https://app.epignostix.com` | Epignostix API base URL |
+| `MNPFLEX_WORKFLOW_ID` | `18` | MNP-Flex workflow identifier |
+| `MNPFLEX_CLIENT_ID` | `ROBIN` | OAuth client identifier |
+| `MNPFLEX_CLIENT_SECRET` | `SECRET` | OAuth client secret |
+| `MNPFLEX_SCOPE` | empty | Optional OAuth scope |
+
+For example:
+
+```bash
+export MNPFLEX_WORKFLOW_ID="18"
+export MNPFLEX_BASE_URL="https://app.epignostix.com"
+```
+
+## Confirm that it is enabled
+
+After restarting ROBIN:
+
+1. Open a sample page.
+2. Look for the **MNP-Flex results** section.
+3. Use **Generate MNP-Flex subset BED** to confirm that the sample methylation
+   parquet can be prepared.
+4. Use **Run MNP-Flex analysis** to submit that sample.
+
+The samples overview also shows **mnpflex run all** when credentials are
+available. This runs MNP-Flex sequentially for eligible samples that do not
+already have results.
+
+ROBIN may automatically submit a completed sample when its analysis jobs have
+finished and no MNP-Flex result is present.
+
+## Inputs and outputs
+
+ROBIN reconstructs bedMethyl data from the sample parquet, prepares the subset
+required by MNP-Flex, uploads it, and retrieves the result bundle.
+
+Files are written within the sample output directory:
+
+```text
+<sample-id>/
+├── <sample-id>.mnpflex.bed
+├── <sample-id>.MNPFlex.subset.bed
+└── mnpflex_results_<sample-id>/
+    └── bundle_summary.json
+```
+
+Additional plots and result files may be present in the results directory.
+These files feed both the sample page and ROBIN-generated reports.
+
+## Troubleshooting
+
+**The MNP-Flex section or bulk button is missing**
+
+- Confirm both `MNPFLEX_USERNAME` and `MNPFLEX_PASSWORD` are set for the
+  process that launches ROBIN.
+- Restart ROBIN after changing its environment.
+- If ROBIN is launched by a service, setting variables in an interactive shell
+  does not change the service environment.
+
+**The sample cannot generate a subset BED**
+
+- Confirm the sample output directory contains `<sample-id>.parquet` or
+  another sample parquet file.
+- Confirm methylation preprocessing completed successfully.
+
+**Authentication or upload fails**
+
+- Check the credentials with Epignostix.
+- Confirm the machine can reach `MNPFLEX_BASE_URL`.
+- Confirm any custom workflow ID, client ID, client secret, or scope with
+  Epignostix.
+- Review the ROBIN log for messages containing `MNPFlex`.
+
+**Results do not appear immediately**
+
+- MNP-Flex processing is asynchronous and can take time.
+- Use the section's status and refresh controls, and check the ROBIN log for
+  upload, polling, or result-download errors.

docs/releases/v0.5.md

@@ -57,7 +57,10 @@
 - **Classification:** scoring and aggregation improved across **Sturgeon / NanoDX / PanNanoDX / Random Forest**.
 - **CNV (GUI):** bin-width selector; chromosome set aligned with reports (chr0–22, X, Y; excludes chrM and odd contigs).
 - **Fusion (GUI):** faster refresh when the fusion section is built; optional timing logs for diagnostics.
-- **MNP-Flex:** optional **Epignostix** upload for bedMethyl (`MNPFLEX_USER` / `MNPFLEX_PASS`); panel hides empty fields until data exists.
+- **MNP-Flex:** optional **Epignostix** upload for bedMethyl. Current
+  deployments should use `MNPFLEX_USERNAME` / `MNPFLEX_PASSWORD`; the initial
+  implementation used `MNPFLEX_USER` / `MNPFLEX_PASS`. See
+  [MNP-Flex setup](../getting-started/mnpflex.md).
 - **Target** analysis always emits **`targets_exceeding_threshold.bed`** for downstream SNP use.
 
 ### Reports and PDFs

docs/using-robin/index.md

@@ -34,6 +34,11 @@ Sign in, use the **menu**, **Dark mode**, **Links**, **Log out**, and read the t
 **Run summary**, **Classification**, **Analysis**, reports, and optional **Sample details**.
 </div>
 
+<div class="robin-feature-card" markdown>
+### [MNP-Flex setup](../getting-started/mnpflex.md)
+Configure Epignostix credentials, submit samples, and troubleshoot the optional MNP-Flex integration.
+</div>
+
 <div class="robin-feature-card" markdown>
 ### [Troubleshooting](troubleshooting.md)
 Connection, sign-in, unknown sample, dark mode, reports.

docs/using-robin/sample-results.md

@@ -235,16 +235,18 @@ Some sites show an **MNP-Flex results** block in the sample page. It may include
 
 A toolbar may show whether the integration is **idle**, **busy**, or **running**. If you never see this block, your deployment may not use MNP-Flex, or credentials may not be configured.
 
-**Applying your Epignostix credentials in ROBIN:** The ROBIN process that runs the workflow and web UI reads **environment variables** on the **server** (not in the browser). Set the username and password Epignostix gave you before starting ROBIN, for example:
+**Applying your Epignostix credentials in ROBIN:** The ROBIN process that runs the workflow and web UI reads **environment variables** on the **server** (not in the browser). Set the username and password Epignostix gave you before starting ROBIN:
 
-- **`MNPFLEX_USERNAME`** — your Epignostix user name  
-- **`MNPFLEX_PASSWORD`** — your Epignostix password  
+```bash
+export MNPFLEX_USERNAME="your-epignostix-username"
+export MNPFLEX_PASSWORD="your-epignostix-password"
+```
 
 If either variable is missing, ROBIN does not show the MNP-Flex block and will not run the integration.
 
-How you set them depends on your setup: typically export them in the shell before `robin …` - whoever operates the sequencing machine or server should make them **persistent** and **secure** (never commit them to git).
-
-Your administrator may also tune optional settings (for example **`MNPFLEX_BASE_URL`**, **`MNPFLEX_WORKFLOW_ID`**, OAuth **`MNPFLEX_CLIENT_ID`** / **`MNPFLEX_CLIENT_SECRET`**, **`MNPFLEX_SCOPE`**) if Epignostix instructs you to; defaults match the standard Epignostix app integration.
+For the complete operator guide, including secure persistent configuration,
+optional API settings, data-transfer considerations, bulk operation, output
+files, and troubleshooting, see [MNP-Flex setup](../getting-started/mnpflex.md).
 
 ---
 

mkdocs.yml

@@ -79,6 +79,7 @@ nav:
     - At startup (disclaimer, GUI, password): getting-started/startup.md
     - Library Preparation: getting-started/library-preparation.md
     - MinKNOW Configuration: getting-started/minknow-configuration.md
+    - MNP-Flex Setup: getting-started/mnpflex.md
   - Command-line reference:
     - Overview: cli/index.md
     - workflow command: cli/workflow.md
@@ -91,4 +92,4 @@ nav:
     - First steps and navigation: using-robin/authentication-and-layout.md
     - Tour of the screens: using-robin/pages-and-routes.md
     - Reading your results: using-robin/sample-results.md
-    - Troubleshooting: using-robin/troubleshooting.md
+    - Troubleshooting: using-robin/troubleshooting.md