{% extends 'base.html' %}
{% block content %}
<p class="eyebrow">OMICSBASE GUIDE</p>
<h1>Documents</h1>
<p class="muted">This guide explains the main pages, roles, and steps for adding, reviewing, correcting, and analyzing data in OmicsBase.</p>

<section class="card documents-section">
  <h2>How the main pages fit together</h2>
  <p>Use the left menu to move between the data catalog, submissions, processing results, record maintenance, messages, and this guide.</p>
  <ul>
    <li><strong>Data Interface</strong> is the searchable catalog. Its project-by-data-type matrix, filters, and record table help you find and select records. The action buttons below Search export selected records, create an RNA-seq expression plot, or create a Genome Browser Data Hub file.</li>
    <li><strong>My submissions</strong> shows batches submitted by your account and their review status. <strong>Approval queue</strong> is available to Curators and Administrators for reviewing submitted batches.</li>
    <li><strong>Submit data</strong> validates a metadata workbook or Records TSV and shows a preview before a batch is submitted for review.</li>
    <li><strong>Add processed results</strong> connects processed output folders and files to submitted data records. Confirmed outputs appear on their matching record pages.</li>
    <li><strong>Data Record Update</strong> lets Curators and Administrators correct one existing record at a time. <strong>Inbox</strong> contains private messages and workflow notifications; <strong>Documents</strong> is this guide.</li>
  </ul>
</section>

<section class="card documents-section">
  <h2>Data submission and approval workflow</h2>
  <p class="documents-callout">The standard workflow is: Curator creates a project → User uploads metadata → Curator approves the data entry → Curator adds the processed result.</p>
  <div class="documents-flow" aria-label="Data submission workflow">
    <article class="documents-flow-step"><h3>Curator adds a project</h3><p>Open Project and create the destination project before metadata is submitted. Use the project code and description that should appear in the catalog.</p></article>
    <article class="documents-flow-step"><h3>User uploads metadata</h3><p>Open Submit data, download the Excel template or use the Records TSV, complete the record fields, and upload the file. Review the validation preview, then confirm submission for Curator approval.</p></article>
    <article class="documents-flow-step"><h3>Curator approves data entries</h3><p>Open Approval queue and inspect the submitted batch and validation notes. Approve valid records, add an unrecognized Data Type when appropriate, or return the batch with a correction note.</p></article>
    <article class="documents-flow-step"><h3>Curator adds processed results</h3><p>Open Add processed results, choose the submitted batch, scan the registered public folder, match output folders to records, review the matches, and submit the results for confirmation.</p></article>
  </div>
  <h3>Step-by-step details</h3>
  <ol>
    <li><strong>Prepare the project.</strong> A Curator or Administrator opens Project, adds the project code and name, and checks that submitters can choose it.</li>
    <li><strong>Prepare and validate metadata.</strong> A submitter downloads the Excel template or uses the Records TSV. Complete one row per data record, including its project, data type, sample, organism, assay, and file information. Upload the workbook or TSV on Submit data. OmicsBase validates the fields and displays a preview; correct any reported errors and upload again.</li>
    <li><strong>Send the batch for review.</strong> After checking the preview, confirm the submission. The batch is pending and is not yet part of the approved catalog. Track its status under My submissions.</li>
    <li><strong>Review and approve.</strong> A Curator opens Approval queue, reviews the batch and its rows, and approves it or returns it with a note. If a submitted Data Type is not in the approved vocabulary, the Curator can add the term and approve the batch or return it for correction.</li>
    <li><strong>Register processed output.</strong> After data approval, the Curator opens Add processed results and selects the previous submission batch. Register the public parent folder, scan it, inspect the discovered sample folders, and match each output to the correct record. Confirm the mapping and review the processed-result submission. Approved downstream files are then linked from the corresponding data records.</li>
  </ol>
</section>

<section class="card documents-section">
  <h2>Correcting an existing data entry</h2>
  <p>Data Record Update is restricted to Curators and Administrators. Search for a record, open its correction form, and update one record at a time. Review the proposed metadata, then save to confirm the correction. OmicsBase records an audit entry and sends a notification to the original submitter and Curator; the notification details are retained with the log.</p>
  <p>For a whole submission batch that needs changes, use the batch update or return-for-correction workflow instead of editing records one by one.</p>
</section>

<section class="card documents-section">
  <h2>Expression Plot</h2>
  <ol>
    <li>Open Data Interface, search or filter the catalog, and select the RNA-seq records to compare. The current limit is 20 records per plot.</li>
    <li>Click Expression Plot. Every selected record must have a registered processed-results URL and an approved processed result with a counts file. The counts file must be readable and contain matching gene rows, gene names, and gene lengths across samples.</li>
    <li>OmicsBase merges the selected count tables and calculates expression values. It uses RPKM for read counts and FPKM for fragment counts identified as fragments in the processed-result metadata.</li>
    <li>On the plot page, search for a gene name. The matching samples are displayed as a bar plot and in the searchable expression table.</li>
  </ol>
  <p class="muted">If a selection contains a non-RNA-seq record, a required URL, approved result, or counts file is missing, or the count tables do not agree, OmicsBase reports the issue and returns you to the catalog with the selection preserved.</p>
</section>

<section class="card documents-section">
  <h2>Genome Browser Data Hub</h2>
  <p>Select records in Data Interface and click Genome Browser Data Hub. OmicsBase includes confirmed public BigWig files and indexed BEDGraph files in a WashU-compatible JSON download. A BEDGraph must have its matching Tabix index. The current limit is 100 records. Records without a confirmed supported visualization file are reported as errors.</p>
</section>
{% endblock %}