ProteoViewer

ProteoViewer is an interactive visualization application for exploring analysis-ready outputs generated by Proteoflux. It is designed as a pure consumer of ProteoFlux results and does not perform any preprocessing or statistical computation itself.

ProteoViewer can be used:

• locally, as a standalone desktop (Linux or Windows) application,
• centrally, as a multi-user web service (e.g. in a core facility),

---

Key features

• Interactive exploration of ProteoFlux .h5ad results
• Quality control and preprocessing diagnostics
• PCA, MDS, and hierarchical clustering
• Differential expression analysis (volcano plots, shrinkage diagnostics)
• Feature-level trends across samples, conditions, and contrasts
• No recomputation: all results are rendered from precomputed values

---

Help / FAQ

A small guide to using ProteoViewer:

ProteoViewer Help / FAQ

---

Installation

ProteoViewer is a Python application built on Panel, Bokeh, and the scientific Python ecosystem.

1. Clone the repository

git clone https://github.com/Afanc/proteoviewer.git
cd proteoviewer

2. Create a Python environment and install

Recommended: Conda / Mamba

conda create -n proteoviewer python=3.13
conda activate proteoviewer
pip install -r requirements.txt

Alternative: virtualenv

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

Running ProteoViewer locally

From the repository root:

python app.py

For development with auto-reload:

panel serve app.py --autoreload

By default, ProteoViewer starts a local web server and opens the interface in your browser. If it does not open by itself, try loading http://localhost:5006/

---

Running ProteoViewer as a service (Linux)

ProteoViewer can be deployed as a persistent, multi-user web service (e.g. in a core facility).

A minimal example systemd unit file is provided in proteoviewer.service. You will typically need to adapt:

• the Python environment path
• the working directory
• upload directories
• user permissions

Example:

[Service]
User=youruser
WorkingDirectory=/opt/ProteoViewer
Environment="PATH=/opt/conda/envs/proteoviewer/bin:/usr/bin"
EnvironmentFile=-/opt/Proteoviewer/proteoviewer-example.env
ExecStart=/opt/conda/envs/proteoviewer/bin/python app.py
Restart=always

Proteoviewer can be customized via an environment file when running as a service. An example configuration is provided proteoviewer-example.env. Edit this file to adjust:

• Facility logo path
• Default data directories
• Host/port settings
• Number of workers

HTTP Upload Support

ProteoViewer includes an optional HTTP-based file upload interface for large datasets.

This is designed for deployments where:

• users access ProteoViewer remotely
• direct filesystem access is not available
• large .h5ad files need to be transferred reliably

Overview

• Uploads are handled via a dedicated HTTP service (Flask-based), separate from the main ProteoViewer app
• The service exposes a simple /upload endpoint accepting .h5ad files
• Each upload is stored in a unique directory and can then be loaded into the viewer
• Typically deployed behind a reverse proxy (e.g. Apache or Nginx)

Service deployment

A minimal systemd unit file is provided in proteoviewer-upload.service.

Example:

[Service]
User=youruser
WorkingDirectory=/opt/ProteoViewer
EnvironmentFile=/opt/Proteoviewer/proteoviewer.env
ExecStart=/opt/conda/envs/proteoviewer/bin/python /opt/ProteoViewer/upload_server.py
Restart=always

---

Windows executable

GitHub Actions builds

This repository includes a GitHub Actions workflow that automatically builds a Windows executable on each release. The resulting .zip file can be downloaded directly from the release page.

Building locally with PyInstaller

Proteoviewer can also be customized and compiled on Windows as a standalone Windows executable with PyInstaller.

cd Proteoviewer
.venv\Scripts\activate.bat
python -m PyInstaller proteoviewer.spec

The executable will be created under:

dist/proteoviewer/

---

Input data

ProteoViewer expects ProteoFlux-generated .h5ad files. All statistics, clustering, and preprocessing steps must be computed by ProteoFlux.

ProteoViewer will never modify or recompute the underlying data.

---

License

ProteoViewer is released under the MIT License. See the LICENSE file for details.

---

Relationship to ProteoFlux and Citation

ProteoViewer is a companion application to Proteoflux, but is developed and released as a separate repository to keep analysis and visualization concerns strictly separated.

If you use ProteoFlux in your work, please cite:

ProteoFlux (latest version). Zenodo. https://doi.org/10.5281/zenodo.18640998

A peer-reviewed publication is currently under submission.