Skip to content

Rewrite public About pages into code-accurate first-time user help #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s-t-h merged 2 commits into from
Aug 21, 2026
Merged

Rewrite public About pages into code-accurate first-time user help #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1e1112
Rewrite public about/help pages for first-time users
Copilot Aug 21, 2026
d2514b9
Add repository URL to citation section
Copilot Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 20 additions & 29 deletions app/phagegap/templates/about/contact.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,28 @@
<section id="code-availability" class="about-section">
<h1>Code availability</h1>
<p>
The source code of this project is freely available on GitHub:
<code><a href="https://github.com/Integrative-Transcriptomics/PhageGap">Integrative-Transcriptomics/PhageGap</a></code>
contains the code base for this web application.
<code><a href="https://github.com/Integrative-Transcriptomics/phage_dark_matter">Integrative-Transcriptomics/phage_dark_matter</a></code>
contains the code base for the underlying prediction model.
</p>
</section>

<section id="contact" class="about-section">
<h1>Contact</h1>
<address style="font-family: monospace; font-size: smaller">
Simon Hackl [simon.hackl(at)uni-tuebingen.de]
<br />
Integrative Transcriptomics, Institute for Bioinformatics and
Medical Informatics, University Tübingen
<br />
Sand 14, 72076 Tübingen, Germany
</address>
<p>For questions or issues, use the project repository or contact the listed maintainer.</p>
<ul>
<li>
<b>Project repository:</b>
<a href="https://github.com/Integrative-Transcriptomics/PhageGap" target="_blank" rel="noopener">Integrative-Transcriptomics/PhageGap</a>
</li>
<li>
<b>Maintainer contact:</b>
Simon Hackl (<code>simon.hackl(at)uni-tuebingen.de</code>)
</li>
<li>
<b>Affiliation:</b>
Integrative Transcriptomics, Institute for Bioinformatics and Medical Informatics, University Tübingen
</li>
</ul>
</section>

<section id="citation" class="about-section">
<h1>Citation</h1>
<p>If you use this software, please cite it as below:</p>
<h2>Citation</h2>
<p>If you use this software, please cite:</p>
<div class="remark" style="font-family: monospace; font-size: smaller">
<p><i>PhageGAP: Prediction of phage protein function using protein language models</i></p>
<p>
Simon Hackl, Mona Scheurenbrand, Kay Nieselt, Maik Wolfram-Schauerte
</p>
<p>
Unpublished. GitHub:
<code><a href="https://github.com/Integrative-Transcriptomics/PhageGap">Integrative-Transcriptomics/PhageGap</a></code>
</p>
<p>Simon Hackl, Mona Scheurenbrand, Kay Nieselt, Maik Wolfram-Schauerte</p>
<p>Unpublished software; source code: <a href="https://github.com/Integrative-Transcriptomics/PhageGap" target="_blank" rel="noopener">https://github.com/Integrative-Transcriptomics/PhageGap</a></p>
</div>
</section>
</section>
111 changes: 44 additions & 67 deletions app/phagegap/templates/about/descriptions.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,50 @@
<section id="overview" class="about-section">
<h1>Overview</h1>
<p>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
</p>
<section id="results-and-terms" class="about-section">
<h1>Results and terms</h1>
<p>This page explains the main items shown after you run <code>Function Classification</code>.</p>
</section>

<section id="protein-embeddings" class="about-section">
<h2>Protein embeddings</h2>
<p>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
</p>
<section id="global-embedding-landscape" class="about-section">
<h2>Global Embedding Landscape</h2>
<ul>
<li><b>Reference points:</b> proteins from the built-in reference metadata, grouped by functional category color.</li>
<li><b>User Data:</b> proteins from your submission.</li>
<li><b>Click a User Data point:</b> opens linked details (prediction bars, nearest-neighbor alignment, structure, and optional genomic focus).</li>
<li><b>Nearest-neighbor link:</b> a line is drawn from the selected user protein to its nearest reference protein.</li>
</ul>
</section>

<section id="prediction-model" class="about-section">
<h2>Prediction model</h2>
<p>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
</p>
<section id="prediction-values" class="about-section">
<h2>Function Prediction values</h2>
<ul>
<li><code>top1</code>, <code>top2</code>, <code>top3</code>: three ranked predicted labels.</li>
<li><code>P(top1)</code>, <code>P(top2)</code>, <code>P(top3)</code>: corresponding probabilities.</li>
<li><code>nearest_neighbor_ID</code>: closest reference protein used for detailed comparison.</li>
<li><code>nearest_neighbor_distance</code>: distance to that reference in embedding space (smaller means closer).</li>
</ul>
</section>

<section id="functional-classes" class="about-section">
<h2>Functional classes</h2>
<p>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
</p>
<table class="table striped compact">
<thead>
<tr>
<th>Class</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Class A</td>
<td>Lorem ipsum dolor sit amet.</td>
</tr>
<tr>
<td>Class B</td>
<td>Lorem ipsum dolor sit amet.</td>
</tr>
<tr>
<td>Class C</td>
<td>Lorem ipsum dolor sit amet.</td>
</tr>
</tbody>
</table>
</section>
<section id="nearest-neighbor-views" class="about-section">
<h2>Nearest-neighbor views</h2>
<ul>
<li><b>Sequence Alignment:</b> residue-level comparison between your selected protein and its nearest neighbor.</li>
<li><b>Structure view:</b> nearest-neighbor 3D structure with alignment-based coloring; available quality values may include mean pLDDT and predicted TM-score.</li>
</ul>
</section>

<section id="genomic-context-meaning" class="about-section">
<h2>Genomic Context</h2>
<p>After GFF upload, CDS features are shown by genomic position and strand.</p>
<ul>
<li>If a CDS <code>Name</code> matches a submitted protein ID, its block is colored by the predicted category.</li>
<li>Feature tooltips can show <code>ID</code>, <code>locus_tag</code>, position, strand, product, and predicted category.</li>
</ul>
</section>

<section id="functional-categories" class="about-section">
<h2>Functional categories used in the interface</h2>
<p>Reference proteins are displayed in these top-level categories:</p>
<div class="remark">
Replication, NA processing, Structural, Assembly, Translation, Anti-Defense, Effectors, Host takeover, Lysis, Lysogeny, AMGs
</div>
<p>Predicted labels (<code>top1</code> etc.) are displayed alongside their mapped top-level category in tooltips and charts.</p>
</section>
103 changes: 30 additions & 73 deletions app/phagegap/templates/about/legal.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,48 @@
<section id="legal-information" class="about-section">
<h1>Legal information</h1>
<h1>Legal and privacy information</h1>
<p>This page summarizes legal and privacy-relevant behavior visible in this repository.</p>
</section>

<section id="cookie-usage" class="about-section">
<h2>Cookie usage</h2>
<section id="license" class="about-section">
<h2>License</h2>
<p>
We use a strictly necessary non-tracking session cookie so that you can
access your data. (1) Your data will not be accessible to other people.
(2) No personalized data is collected or shared with third parties and you
will not be tracked by this cookie. The cookie will automatically expire
after 24 you close your browser. By using our website, you consent to the
use of this cookie.
PhageGAP is distributed under the GNU General Public License v3.0.
See <a href="https://www.gnu.org/licenses/gpl-3.0.en.html" target="_blank" rel="noopener">GNU GPL-3.0</a> and the repository <code>LICENSE</code> file.
</p>
</section>

<section id="medical-disclaimer" class="about-section">
<h2>Medical disclaimer</h2>
<p>
If medical information is provided on this site, it is provided as an
information resource only, and is not to be used or relied on for any
diagnostic or treatment purposes.
</p>
<section id="cookie-and-session-use" class="about-section">
<h2>Cookie and session use</h2>
<ul>
<li>A consent cookie named <code>phagegap_consent</code> is required before API requests are accepted.</li>
<li>A server session cookie named <code>phagegap_session</code> is used for request protection (including CSRF token handling).</li>
<li>Session cookie settings in this repository include <code>Secure</code>, <code>HttpOnly</code>, and <code>SameSite=Lax</code>.</li>
</ul>
</section>

<section id="content-liability" class="about-section">
<h2>Content liability</h2>
<section id="data-handling" class="about-section">
<h2>Data handling (repository-based scope)</h2>
<ul>
<li>This repository implements FASTA and GFF upload/submit endpoints and returns analysis data to the browser.</li>
<li>This repository does not implement user accounts or a database-backed project storage layer.</li>
<li>Users can explicitly export results/session files locally from the browser via toolbar actions.</li>
</ul>
<p>
The contents of our pages were created with the utmost care. However, we
cannot guarantee the accuracy, completeness and actuality of the
content. As a service provider, we are responsible for our own content
on these pages under the general laws according to § 7 TMG. According to
§§ 8 to 10 TMG, however, we are not obligated as a service provider to
monitor transmitted or stored third-party information or to investigate
circumstances that indicate illegal activity. Obligations to remove or
block the use of information under the general laws remain unaffected.
However, liability in this regard is only possible from the point in
time at which a concrete infringement of the law becomes known. If we
become aware of such infringements, we will remove this content
immediately.
This summary reflects only this codebase. It does not by itself define external infrastructure policy or retention beyond this repository.
</p>
</section>

<section id="link-liability" class="about-section">
<h2>Link liability</h2>
<section id="disclaimer" class="about-section">
<h2>Disclaimer</h2>
<p>
This page may contain links to external websites of third parties, on
whose contents we have no influence. We cannot take any liability for
these external contents. The respective provider or operator of the
pages is always responsible for the content of the linked pages. The
linked pages were checked for possible legal violations at the time of
linking. Illegal contents were not recognizable at the time of linking.
However, a permanent control of the contents of the linked pages is not
reasonable without concrete evidence of a violation of the law. If we
become aware of any infringements, we will remove such links
immediately.
The software is provided without warranty as described in GPL-3.0.
Use results as computational support and verify findings in your own analysis workflow.
</p>
</section>

<section id="data-privacy" class="about-section">
<h2>Data privacy</h2>
<p>
The use of our website is possible without providing personal data and
no processed data is stored. If personal data (such as name, address or
e-mail addresses) is collected, this is on a voluntary basis. This data
will not be passed on to third parties without your express consent. We
point out that data transmission over the Internet (e.g. communication
by e-mail) may yield security gaps. Complete protection of data against
access by third parties is not possible. The use of contact data
published within the framework of the impressum by third parties for the
purpose of sending advertising and information material is hereby
expressly prohibited. The operators of the pages expressly reserve the
right to take legal action in the event of the sending of advertising
information, such as spam e-mails.
</p>
<section id="required-legal-details" class="about-section">
<h2>Additional legal details</h2>
<!-- TODO: Add legally required provider/impressum details (responsible entity, address, and official contact channel). -->
<!-- TODO: Add deployment-specific privacy details (hosting provider, log retention, and any external processors), if applicable. -->
<p>Some deployment-specific legal details are not defined in this repository and must be provided by the operating institution.</p>
</section>

<section id="copyright" class="about-section">
<h2>Copyright</h2>
<p>
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version. This program is distributed in the hope that
it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details: <a
href="https://www.gnu.org/licenses/gpl-3.0.en.html"
target="_blank">www.gnu.org/licenses/gpl-3.0.en</a>.
</p>
</section>
84 changes: 73 additions & 11 deletions app/phagegap/templates/about/usage.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,74 @@
<section id="usage" class="about-section">
<h1>Usage</h1>
<p>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
</p>
</section>
<h1>How to use PhageGAP</h1>

<h2>Quick start</h2>
<ol>
<li>Paste protein FASTA text and/or upload a FASTA file.</li>
<li>Click <code>Function Classification</code>.</li>
<li>Click a <code>User Data</code> point in the <code>Global Embedding Landscape</code> to inspect predictions, nearest-neighbor alignment, and structure.</li>
<li>Optionally add genomic context from a GFF file.</li>
</ol>
</section>

<section id="provide-protein-sequences" class="about-section">
<h2>1) Provide protein sequences</h2>
<p>You can submit sequence data by text input, file upload, or both together. PhageGAP combines both inputs into one analysis request.</p>
<ul>
<li>Input must contain valid FASTA records.</li>
<li>The first token after <code>&gt;</code> is used as <code>protein_ID</code>.</li>
<li>The full FASTA header line is kept as description text.</li>
<li>Use unique protein IDs. Duplicate IDs in one submission keep only the last record; IDs already loaded in the current session are not added again.</li>
</ul>
<pre><code>&gt;prot_001 putative capsid protein
MNNR...
&gt;prot_002 tail fiber protein
MDSK...</code></pre>
</section>

<section id="run-analysis" class="about-section">
<h2>2) Run the analysis</h2>
<p>Click <code>Function Classification</code> to submit your proteins. New results are appended to your current session and shown as <code>User Data</code> in the landscape view.</p>
<p class="remark"><b>Important:</b> Classification and GFF uploads are rate-limited. If you submit again too quickly, wait and retry.</p>
</section>

<section id="explore-results" class="about-section">
<h2>3) Explore the results</h2>
<ul>
<li><b>Global Embedding Landscape:</b> shows reference proteins by category and your submitted proteins as <code>User Data</code>.</li>
<li><b>Function Prediction and Nearest Neighbor Structure:</b> top predictions (<code>top1</code>, <code>top2</code>, <code>top3</code>) with probabilities, plus nearest-neighbor structure.</li>
<li><b>Nearest Neighbor Sequence Alignment:</b> aligned residues for the selected protein and its nearest neighbor.</li>
<li><b>Selection tools:</b> clear selection, zoom the landscape, or maximize the structure panel.</li>
</ul>
<p>Click any <code>User Data</code> point to update all linked views.</p>
</section>

<section id="add-genomic-context" class="about-section">
<h2>4) Add genomic context</h2>
<p>Use <code>Add Genomic Context</code> in the toolbar to upload a <code>.gff</code> or <code>.gff3</code> file.</p>
<ul>
<li>Only <code>CDS</code> features are used.</li>
<li>Features should provide standard 9-column GFF records with <code>key=value</code> attributes.</li>
<li>For linking to submitted proteins, the GFF <code>Name</code> attribute must match FASTA protein IDs.</li>
</ul>
<p>When IDs match, predicted categories are shown on genomic features and selection in the landscape can zoom to local genomic neighborhoods.</p>
</section>

<section id="save-restore-export" class="about-section">
<h2>5) Save, restore, or export</h2>
<ul>
<li><code>Download Results</code>: exports current user results as TSV (<code>phagegap-results-YYYY-MM-DD.tsv</code>).</li>
<li><code>Download Session</code>: exports selected protein, user results, and genomic features as compressed JSON (<code>.json.gz</code>).</li>
<li><code>Reload Session</code>: restores a saved session file (<code>.gz</code> / <code>.json.gz</code>).</li>
<li><code>Screenshot</code>: saves a PNG image of the current analysis panels.</li>
</ul>
</section>

<section id="usage-notes" class="about-section">
<h2>Tips and important notes</h2>
<ul>
<li>You must accept the cookie consent banner before API-backed features are enabled.</li>
<li>At least one valid FASTA record is required.</li>
<li>Large requests may fail (server request size limit is approximately 500 KB).</li>
</ul>
<p>For interpretation guidance, see <a href="#results-and-terms">Results and terms</a>.</p>
</section>