Choosing a workflow
===================

.. The workflow status table and README accordion sections rely on raw
   HTML/JavaScript to fetch and render live status from the GitLab API. Those
   sections will be empty or broken in non-HTML output formats (PDF, LaTeX,
   man pages) and require internet access to display.

Which workflow fits your needs?
-------------------------------

RAFT workflows are designed for different analysis goals, so the best choice
depends on the biological question you are trying to answer.

For example, **LENS** is designed for tumor antigen discovery from short-read
data, while **Gene-Fusions** is designed for fusion detection.

Review the workflow table below to compare available workflows and their
current status.

Which workflow profile fits your needs?
---------------------------------------

Each workflow provides a ``standard`` profile by default. This profile is
intended to provide a balanced starting point for typical analyses.

Some workflows also offer additional profiles. For example, an ``exhaustive``
profile may run a broader set of tools, while a ``fast`` profile may prioritize
turnaround time over breadth.

Review the workflow details below to see which profiles are currently available
for each workflow.

Customizing the workflow configuration
--------------------------------------

RAFT allows users to fully customize the workflow to their liking. Specifically, users can modify:

 - Which tools are run
 - Which version of tools are run
 - Parameters passed to tools
 - References used throughout the workflow

Users can introduce these modifications through the `web-based user interface <https://spvensko.github.io/raft-ui/raft-config-generator.html>`_
when running RAFT.

.. figure:: _static/config-generator.png
   :alt: RAFT workflow configuration interface

   The RAFT workflow configuration interface.


Available workflows
--------------------

.. raw:: html

   <style>
     .raft-wf-status {
       display: grid;
       gap: 1.5rem;
     }
     .raft-wf-status__meta {
       color: #4b5563;
       font-size: 0.95rem;
     }
     .raft-wf-status__error {
       border-left: 4px solid #b91c1c;
       background: #fef2f2;
       color: #7f1d1d;
       padding: 0.9rem 1rem;
     }
     .raft-wf-status__section {
       border: 1px solid #d1d5db;
       border-radius: 0.5rem;
       overflow: hidden;
       background: #ffffff;
     }
     .raft-wf-status__section-header {
       display: flex;
       justify-content: space-between;
       gap: 1rem;
       align-items: baseline;
       padding: 0.9rem 1rem;
       background: #f9fafb;
       border-bottom: 1px solid #e5e7eb;
     }
     .raft-wf-status__section-header h2 {
       margin: 0;
       font-size: 1.1rem;
     }
     .raft-wf-status__summary {
       color: #374151;
       font-size: 0.95rem;
       text-align: right;
     }
     .raft-wf-status__table-wrap {
       overflow-x: auto;
     }
     .raft-wf-status table {
       width: 100%;
       border-collapse: collapse;
     }
     .raft-wf-status th,
     .raft-wf-status td {
       padding: 0.7rem 1rem;
       text-align: left;
       border-bottom: 1px solid #e5e7eb;
       vertical-align: middle;
     }
     .raft-wf-status th {
       background: #ffffff;
       font-weight: 700;
     }
     .raft-wf-status td:last-child {
       text-align: center;
     }
     .raft-wf-status th:last-child {
       text-align: center;
     }
     .raft-wf-status tbody tr:hover {
       background: #f9fafb;
     }
     .raft-wf-status__badge {
       display: inline-block;
       min-width: 6.5rem;
       padding: 0.22rem 0.55rem;
       border-radius: 999px;
       font-size: 0.84rem;
       font-weight: 700;
       text-align: center;
       white-space: nowrap;
     }
     .raft-wf-status__badge--pass {
       background: #dcfce7;
       color: #166534;
     }
     .raft-wf-status__badge--fail {
       background: #fee2e2;
       color: #991b1b;
     }
     .raft-wf-status__badge--progress {
       background: #fef3c7;
       color: #92400e;
     }
     .raft-wf-status__badge--none {
       background: #e5e7eb;
       color: #374151;
     }
     .raft-wf-status__profiles {
       display: flex;
       flex-wrap: wrap;
       gap: 0.3rem;
     }
     .raft-wf-status__profile-tag {
       background: #eff6ff;
       color: #1d4ed8;
       border-radius: 4px;
       padding: 0.15rem 0.45rem;
       font-size: 0.82rem;
       font-family: monospace;
       white-space: nowrap;
     }
     .raft-wf-status__muted {
       color: #6b7280;
     }
     @media (max-width: 900px) {
       .raft-wf-status__section-header {
         display: block;
       }
       .raft-wf-status__summary {
         margin-top: 0.35rem;
         text-align: left;
       }
     }
     .raft-wf-readmes {
       margin-top: 2.5rem;
     }
     details.raft-wf-readme {
       border-top: 2px solid #e5e7eb;
       margin-top: 1.5rem;
     }
     details.raft-wf-readme summary {
       cursor: pointer;
       padding: 1rem 0 0.75rem;
       font-size: 1.25rem;
       font-weight: 700;
       color: #111827;
       user-select: none;
       list-style: none;
       display: flex;
       align-items: center;
       gap: 0.5rem;
     }
     details.raft-wf-readme summary::-webkit-details-marker { display: none; }
     details.raft-wf-readme summary::before {
       content: "\25B6";
       font-size: 0.7em;
       color: #6b7280;
       flex-shrink: 0;
       transition: transform 0.15s;
     }
     details.raft-wf-readme[open] summary::before {
       transform: rotate(90deg);
     }
     details.raft-wf-readme summary:hover { color: #1d4ed8; }
     details.raft-wf-readme summary:hover::before { color: #1d4ed8; }
     details.raft-wf-readme summary a { color: inherit; text-decoration: none; }
     details.raft-wf-readme summary a:hover { text-decoration: underline; }
     .raft-wf-readme__content {
       padding-bottom: 1rem;
     }
   </style>

   <div id="raft-workflow-status" class="raft-wf-status">
     <div id="raft-workflow-status-meta" class="raft-wf-status__meta">Loading workflows from GitLab...</div>
   </div>

Workflow details
----------------

.. raw:: html

   <div id="raft-workflow-readmes" class="raft-wf-readmes"></div>

   <script>
     (function () {
       const root = document.getElementById("raft-workflow-status");
       const readmesEl = document.getElementById("raft-workflow-readmes");
       const meta = document.getElementById("raft-workflow-status-meta");
       if (!root || !meta) return;

       const apiBase = "https://gitlab.com/api/v4";
       const orgGroup = "reproducible-analyses-framework-and-tools";
       const workflowsGroup = encodeURIComponent(orgGroup + "/modules/workflows");
       const workflowConfigsProject = encodeURIComponent(orgGroup + "/workflow-configs");

       const workflowDescriptions = {
         "lens":    "Tumor antigens",
         "clens":   "Tumor antigens",
         "mha":     "Minor Histocompatible Antigens",
         "stalr":   "Single-cell long-read tumor antigens",
         "tattalr": "Bulk long-read tumor antigens"
       };

       const hiddenWorkflows = new Set(["clens"]);
       const pinnedWorkflows = ["lens"];

       const gitlabIcon =
         '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"' +
         ' viewBox="0 0 380 380" style="vertical-align:middle">' +
         '<path fill="#e24329" d="M282.83 170.73l-.27-.69-26.14-68.22a6.81' +
         ' 6.81 0 0 0-2.69-3.24 7 7 0 0 0-8 .43 7 7 0 0 0-2.32 3.52l-17.65' +
         ' 54H154.29l-17.65-54a6.86 6.86 0 0 0-2.32-3.52 7 7 0 0 0-8-.43' +
         ' 6.87 6.87 0 0 0-2.69 3.24L97.44 170l-.26.69a48.54 48.54 0 0 0' +
         ' 16.1 56.1l.09.07.24.17 39.82 29.82 19.7 14.91 12 9.06a8.07 8.07' +
         ' 0 0 0 9.76 0l12-9.06 19.7-14.91 40.06-30 .1-.08a48.56 48.56 0 0' +
         ' 0 16.08-56.04z"/></svg>';

       function escapeHtml(value) {
         return String(value).replace(/[&<>"']/g, function (ch) {
           return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[ch];
         });
       }

       function statusMeta(raw) {
         if (raw === "success") return { label: "Pass", cls: "raft-wf-status__badge--pass" };
         if (raw === "failed" || raw === "canceled") return { label: "Fail", cls: "raft-wf-status__badge--fail" };
         if (raw === "no-pipeline") return { label: "No pipeline", cls: "raft-wf-status__badge--none" };
         if (String(raw).startsWith("http-") || raw === "unavailable") return { label: "Unavailable", cls: "raft-wf-status__badge--none" };
         return { label: "In progress", cls: "raft-wf-status__badge--progress" };
       }

       function compareStatus(a, b) {
         const rank = function (s) {
           if (s === "success") return 0;
           if (s === "failed" || s === "canceled") return 1;
           if (["running", "pending", "created", "preparing", "waiting_for_resource", "manual"].indexOf(s) !== -1) return 2;
           if (s === "no-pipeline") return 3;
           return 4;
         };
         return rank(a.pipelineStatus) - rank(b.pipelineStatus) || a.name.localeCompare(b.name);
       }

       async function fetchJson(url) {
         const res = await fetch(url, { headers: { Accept: "application/json" } });
         if (!res.ok) throw new Error("HTTP " + res.status + " for " + url);
         return res.json();
       }

       async function fetchAllProjects(group, simple) {
         const projects = [];
         const simpleParam = simple === false ? "" : "&simple=true";
         for (let page = 1; page < 20; page += 1) {
           const url = apiBase + "/groups/" + group + "/projects?include_subgroups=true" + simpleParam + "&per_page=100&page=" + page;
           const data = await fetchJson(url);
           if (!Array.isArray(data) || data.length === 0) break;
           projects.push.apply(projects, data);
           if (data.length < 100) break;
         }
         return projects;
       }

       async function fetchPipeline(project) {
         try {
           const url = apiBase + "/projects/" + encodeURIComponent(project.id) + "/pipelines?per_page=1";
           const data = await fetchJson(url);
           if (!Array.isArray(data) || data.length === 0) return { status: "no-pipeline", ref: "" };
           return { status: data[0].status || "unknown", ref: data[0].ref || "" };
         } catch (err) {
           const m = /HTTP (\d+)/.exec(String(err && err.message || ""));
           return { status: m ? "http-" + m[1] : "unavailable", ref: "" };
         }
       }

       // Fetch all .config files from the workflow-configs repo and build a
       // map of { workflowName: [profileName, ...] }.
       // Filename convention:
       //   <workflow>.config              → "standard" profile
       //   <workflow>.<profile>.config    → named profile
       async function fetchWorkflowConfigMap() {
         const map = {};
         try {
           const project = await fetchJson(apiBase + "/projects/" + workflowConfigsProject);
           const branch = encodeURIComponent(project.default_branch || "main");
           const files = [];
           for (let page = 1; page < 20; page += 1) {
             const url = apiBase + "/projects/" + project.id +
                         "/repository/tree?ref=" + branch + "&per_page=100&page=" + page;
             const data = await fetchJson(url);
             if (!Array.isArray(data) || data.length === 0) break;
             files.push.apply(files, data);
             if (data.length < 100) break;
           }
           files.forEach(function (f) {
             if (f.type !== "blob" || !f.name.endsWith(".config")) return;
             const base = f.name.slice(0, -7); // strip ".config"
             const dot = base.indexOf(".");
             if (dot === -1) {
               // <workflow>.config → standard profile
               if (!map[base]) map[base] = [];
               if (map[base].indexOf("standard") === -1) map[base].push("standard");
             } else {
               // <workflow>.<profile>.config → named profile
               const workflow = base.slice(0, dot);
               const profile = base.slice(dot + 1);
               if (!map[workflow]) map[workflow] = [];
               if (map[workflow].indexOf(profile) === -1) map[workflow].push(profile);
             }
           });
         } catch (err) {
           // Return empty map; table will show "—" for all profiles
         }
         return map;
       }

       // Workflow config files are bundled with RAFT at src/raft/ui/static/workflows/,
       // not hosted on GitLab. This map records which workflows have all three required
       // UI config files (manifest-ui.json, report-ui.json, status.json).
       // Update this map when new workflows gain config file support.
       const workflowsWithConfigFiles = new Set(["lens"]);

       async function mapWithConcurrency(items, limit, worker) {
         const results = new Array(items.length);
         let index = 0;
         async function run() {
           while (true) {
             const current = index++;
             if (current >= items.length) return;
             results[current] = await worker(items[current], current);
           }
         }
         const workers = [];
         const n = Math.min(limit, items.length || 1);
         for (let i = 0; i < n; i++) workers.push(run());
         await Promise.all(workers);
         return results;
       }

       function renderProfileTags(profiles) {
         if (!profiles || profiles.length === 0) {
           return '<span class="raft-wf-status__muted">—</span>';
         }
         return '<div class="raft-wf-status__profiles">' +
           profiles.map(function (p) {
             return '<span class="raft-wf-status__profile-tag">' + escapeHtml(p) + "</span>";
           }).join("") +
           "</div>";
       }

       function renderTable(rows) {
         const counts = { Pass: 0, Fail: 0, "In progress": 0, "No pipeline": 0, Unavailable: 0 };
         rows.forEach(function (r) { counts[statusMeta(r.pipelineStatus).label] += 1; });
         const total = rows.length;
         const summary = Object.keys(counts)
           .filter(function (k) { return counts[k] > 0; })
           .map(function (k) {
             return k + ": " + counts[k] + " (" + ((counts[k] / total) * 100).toFixed(0) + "%)";
           }).join(", ") || "No repositories found";

         const tbody = rows.map(function (row) {
           const badge = statusMeta(row.pipelineStatus);
           const nameCell = '<a href="#workflow-' + escapeHtml(row.name) + '" ' +
             'onclick="var el=document.getElementById(\'workflow-' + escapeHtml(row.name) + '\');if(el)el.open=true;">' +
             escapeHtml(row.name) + "</a>";
           return "<tr>" +
             "<td>" + nameCell + "</td>" +
             "<td>" + escapeHtml(workflowDescriptions[row.name] || "") + "</td>" +
             "<td>" + renderProfileTags(row.profiles) + "</td>" +
             '<td><span class="raft-wf-status__badge ' + badge.cls + '">' + escapeHtml(badge.label) + "</span>" +
             (row.pipelineRef ? ' <span class="raft-wf-status__muted">(' + escapeHtml(row.pipelineRef) + ")</span>" : "") +
             "</td>" +
             '<td><a href="' + escapeHtml(row.webUrl + "/-/issues") + '">Report an issue</a></td>' +
             '<td style="text-align:center"><a href="' + escapeHtml(row.webUrl) +
             '" target="_blank" rel="noopener" title="View on GitLab">' + gitlabIcon + '</a></td>' +
             "</tr>";
         }).join("");

         return '<section class="raft-wf-status__section">' +
           '<div class="raft-wf-status__section-header">' +
             "<h2>Workflows</h2>" +
             '<div class="raft-wf-status__summary">' + escapeHtml(summary) + "</div>" +
           "</div>" +
           '<div class="raft-wf-status__table-wrap">' +
             "<table>" +
               "<thead><tr><th>Workflow</th><th>Description</th><th>Workflow Profiles</th><th>CI Status</th><th></th><th></th></tr></thead>" +
               "<tbody>" + tbody + "</tbody>" +
             "</table>" +
           "</div>" +
         "</section>";
       }

       async function fetchReadme(project) {
         try {
           const branch = encodeURIComponent(project.default_branch || "main");
           const url = apiBase + "/projects/" + encodeURIComponent(project.id) +
                       "/repository/files/README.md/raw?ref=" + branch;
           const res = await fetch(url, { headers: { Accept: "text/plain" } });
           if (!res.ok) return null;
           return res.text();
         } catch (e) {
           return null;
         }
       }

       function loadMarked() {
         return new Promise(function (resolve, reject) {
           if (window.marked) return resolve();
           var s = document.createElement("script");
           s.src = "https://cdn.jsdelivr.net/npm/marked/marked.min.js";
           s.onload = resolve;
           s.onerror = function () { reject(new Error("Failed to load marked.js")); };
           document.head.appendChild(s);
         });
       }

       async function load() {
         try {
           meta.textContent = "Loading workflows from GitLab...";

           // Fetch config map, workflow list, and all projects under workflow-configs
           // in parallel. The workflow-configs projects are used to check for required
           // supporting repos (e.g. lens-human-fastqs, lens-human-refs, lens-human-demo).
           const workflowConfigsGroup = encodeURIComponent(orgGroup + "/workflow-configs");
           const [configMap, workflowProjects, configRepos] = await Promise.all([
             fetchWorkflowConfigMap(),
             fetchAllProjects(workflowsGroup, false),
             fetchAllProjects(workflowConfigsGroup)
           ]);

           // Build a set of all repo names (last path segment) under workflow-configs
           const configRepoNames = new Set(configRepos.map(function (p) { return p.path; }));

           // Keep only workflows that have all required supporting repos AND
           // all three UI config files (manifest-ui.json, report-ui.json, status.json)
           const projects = workflowProjects.filter(function (p) {
             const name = p.path;
             return configRepoNames.has(name + "-human-fastqs") &&
                    configRepoNames.has(name + "-human-refs") &&
                    configRepoNames.has(name + "-human-demo") &&
                    workflowsWithConfigFiles.has(name);
           });

           meta.textContent = "Loading pipeline status...";

           const rows = await mapWithConcurrency(projects, 8, async function (project) {
             const pipeline = await fetchPipeline(project);
             return {
               name: project.path,
               webUrl: project.web_url,
               projectId: project.id,
               defaultBranch: project.default_branch || "main",
               pipelineStatus: pipeline.status,
               pipelineRef: pipeline.ref,
               profiles: configMap[project.path] || []
             };
           });

           // Remove hidden workflows, then sort: pinned first, rest by CI status
           const filtered = rows.filter(function (r) { return !hiddenWorkflows.has(r.name); });
           filtered.sort(function (a, b) {
             const pa = pinnedWorkflows.indexOf(a.name);
             const pb = pinnedWorkflows.indexOf(b.name);
             if (pa !== -1 || pb !== -1) {
               if (pa === -1) return 1;
               if (pb === -1) return -1;
               return pa - pb;
             }
             return compareStatus(a, b);
           });
           const rows2 = filtered;

           const now = new Date();
           root.innerHTML =
             '<div class="raft-wf-status__meta">Last loaded from GitLab: ' + escapeHtml(now.toLocaleString()) + "</div>" +
             renderTable(rows2);

           // Render README sections below the table, in same order as the table
           if (readmesEl && rows.length > 0) {
             readmesEl.innerHTML = '<div class="raft-wf-status__meta">Loading workflow READMEs...</div>';
             await loadMarked();
             const sorted = rows2.slice();
             const readmeResults = await mapWithConcurrency(sorted, 4, async function (row) {
               const text = await fetchReadme({ id: row.projectId, default_branch: row.defaultBranch });
               return { row: row, text: text };
             });
             readmesEl.innerHTML = "";
             readmeResults.forEach(function (r) {
               const details = document.createElement("details");
               details.id = "workflow-" + r.row.name;
               details.className = "raft-wf-readme";
               var readmeContent = r.row.name === 'lens'
                 ? '<p><a href="https://uselens.io" target="_blank" rel="noopener">Visit uselens.io →</a></p>'
                 : (r.text ? window.marked.parse(r.text) : '<p><em>README not available.</em></p>');
               details.innerHTML =
                 '<summary>' + escapeHtml(r.row.name.toUpperCase()) + '</summary>' +
                 '<div class="raft-wf-readme__content">' + readmeContent + '</div>';
               readmesEl.appendChild(details);
             });
           }

         } catch (err) {
           root.innerHTML = '<div class="raft-wf-status__error">' +
             "Unable to load workflow status from GitLab. This can happen because of network restrictions, " +
             "GitLab rate limiting, or browser CORS policy. " +
             "Error: " + escapeHtml(String(err && err.message || err)) +
             "</div>";
         }
       }

       load();
     })();
   </script>