PaintOmics AI

---

Overview

PaintOmics takes several omic measurements from the same experiment — transcriptomics, proteomics, metabolomics, region-based assays such as ChIP-seq or Methyl-seq, and regulatory layers such as miRNA or transcription factors — and paints them together onto biological pathways, so that the layers can be read against each other rather than one at a time.

It supports KEGG, Reactome and MapMan pathways for organisms across all biological kingdoms, and any other organism present in those databases can be installed on request.

PaintOmics AI is the current release, and the successor to PaintOmics 4 (Nucleic Acids Research, 2022). It keeps everything PaintOmics 4 does and adds the AI interpretation agent, the MORE regulatory model, multi-condition designs, and a rebuilt interface — see What's new. The public instance runs on Supercomputador Drago (CSIC).

Try it without installing anything: https://paintomics.org

What's new in PaintOmics AI

Area	What changed
AI interpretation	New. An agent walks the KEGG, Reactome and OmniPath interactions with your values on them and writes a checked Results section with numbered citations — across the whole network, on any one pathway from its diagram, and as follow-up questions. Opt-in per job. Details below.
MORE regulatory model	Regulatory Omics gained the MORE model behind a method chooser, with three engines: PLS1 on a Rust port (default, measured byte-identical to R and several hundred times faster), PLS1 on R, and MLR on R. A job predicted not to fit inside the queue's budget is refused at submit time instead of being killed at the end.
Regulator–target network	New Step 3 panel drawing regulators against their targets with Cytoscape.js — free layout, per-condition colouring, search, spotlight, exports, and a "Find in pathways" hand-off into the pathway view. Regulation-per-condition tables sit alongside it.
Multi-condition designs	Analyses run across any number of conditions, not two. Per-condition significance stars in the Step 4 heatmaps, in Metabolite Hub and in Class Activity; columns labelled with your condition names; a Stouffer weights panel; and the combined-p-value statistics checked against SciPy.
Replicate aggregation	Replicates collapse onto the conditions you declare, in both the pathway visualization and MORE, and the experiment design is drafted from your column headers before a job exists.
Rebuilt interface	Navigation moved into the header and the left rail is gone; one token-based design system for surfaces, shapes and type; WCAG AA contrast throughout; a dark theme with a header toggle; a redrawn landing page and mark; a contents sidebar on the results page; and modernized dialogs, tables and upload controls.
Examples for every pipeline	Bundled, manifest-driven example datasets built from a seeded generator, with the pathways the enrichment should recover listed alongside the files. Load example now works for Regions2Genes, miRNA2Genes and MORE too, not only pathway acquisition.
Container deployment	A Docker Compose stack (nginx/TLS → app → MongoDB), a post-deployment smoke test that fails on the mistakes that are expensive to find in production, an operator runbook, and species installation from the command line.

The AI interpretation agent

It interprets a job as an agentic graph walk. One network per organism holds every KEGG, Reactome and OmniPath interaction, with your values laid on its nodes. An agent walks it from the nodes whose neighbourhoods hold surprisingly many relevant features and reads the values at every stop against your experiment design. A writer turns the chain into statements that separate what the pathways already draw from what goes beyond them, and a narrator writes them up as a Results section. The checks are code, not a second opinion: every quoted value must match the upload, every leg must be a drawn interaction, and every citation must be a paper the writer retrieved and read. Each [n] links to PubMed. The same walk runs on a single pathway from the Walk column of its diagram.

It is off unless you ask for it. The consent box in Step 1 says what leaves the server — your pathway results and the values of the matched features — and names the service that receives them; the server re-checks that consent before every request it sends, and refuses the job up front if no LLM token is configured. The provider is any OpenAI-compatible endpoint, and a deployment can switch the feature off entirely with AI_INTERPRETATION_ENABLED=false.

How it works

Step	What happens
1 · Upload	Pick an organism and the pathway databases to explore, decide whether to enable the AI interpretation, then upload one data matrix per omic — or load a bundled example.
2 · Match	Identifiers are converted to the ones the pathway databases use, and ambiguous metabolite names are resolved by you. The screen reports how many features mapped.
3 · Explore	Enrichment, classification, networks, hub and class analyses, metagenes, regulator–target networks, and pathway diagrams painted with every omic at once.

Analyses

Analysis	What it answers
Pathway enrichment	Which pathways are significantly affected, per omic and combined
Pathway classification	Where the affected pathways sit in the database hierarchy
Pathway interaction network	How the enriched pathways connect through shared features
Metabolite hub analysis	Which metabolites act as hubs for the observed changes
Metabolite class activity	Which chemical classes of metabolites move as a group
Regulatory omics (incl. MORE)	Which trans-acting regulators (miRNA, TF, SF, RBP…) drive the changes
Metagenes	The dominant expression trends inside a pathway
Pathway visualisation	All omics painted on one diagram, with per-feature heatmaps
AI interpretation	What the walk across your pathways' interactions shows biologically, with literature to back it

Two supporting tools convert data into a usable input format: Regions to Genes (RGmatch, for region-based assays) and miRNA to Genes. A file that is not in PaintOmics' format at all can be handed to the AI input converter: it sends a profile of the file — column names and types, row counts, and the first eight rows verbatim — to the model, runs the script the model writes in a sandbox in your browser, and shows you both the script and the validator's verdict before you accept the result. It ships switched off; enable it with AI_INPUT_CONVERTER=true.

Deploy your own instance

With Docker (recommended)

git clone https://github.com/ConesaLab/PaintOmics.git
cd PaintOmics

cp deploy/env.example deploy/.env
$EDITOR deploy/.env                        # PAINTOMICS_BASE_URL is mandatory
./deploy/make-cert.sh <your-hostname-or-ip>

docker compose -f deploy/compose.yaml up -d --build
./deploy/smoke-test.sh

Three containers: nginx (TLS) → app (Flask + uWSGI + in-process job queue) → MongoDB. The first build takes 15–30 minutes, most of it R packages. See deploy/README.md for configuration, backups, certificates, and the two constraints that must not be relaxed.

AI interpretation needs an OpenAI-compatible endpoint and its key in deploy/.env; without one the rest of the application runs normally and the feature refuses jobs, or set AI_INTERPRETATION_ENABLED=false to hide it.

From source (development)

Requires Python 3.11, MongoDB, R, and the libcairo2 shared library.

git clone https://github.com/ConesaLab/PaintOmics.git
cd PaintOmics

python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# R packages used by hub analysis, metagenes and regulatory omics
Rscript -e 'install.packages(c("purrr","amap","cluster","factoextra","mclust"))'

cd PaintomicsServer
python src/launch_server.py                # http://localhost:8000

The first launch copies src/resources/example_serverconf.py to src/conf/serverconf.py; edit that file (or the environment variables it reads) to set paths, MongoDB host, SMTP, quotas and the AI and MORE backends. ./start_server.sh does the same through a conda environment and starts MongoDB if it is not already running.

MORE runs on more-rs, discovered at PaintomicsServer/src/common/bioscripts/more-rs or on PATH. The binary is gitignored and dropped in per deployment; without it regulatory analysis is refused up front rather than failing inside the job. Set PAINTOMICS_MORE_RS=off to disable regulatory analysis, or to a path to name a binary explicitly.

Load pathway data

A fresh instance has an empty database — install each organism explicitly:

cd PaintomicsServer
python src/AdminTools/DBManager.py download --specie=mmu --kegg=1 --mapping=1 --common=1 --reactome=1
python src/AdminTools/DBManager.py install  --specie=mmu

Use --common=0 for every species after the first: the common step re-downloads shared KEGG reference data and dominates the runtime. Reactome curates human and infers about twenty other species — use --reactome=0 for the rest.

Tests

Tests are standalone scripts, run from PaintomicsServer:

cd PaintomicsServer
python -m src.tests.test_release_hygiene     # no secret is committed
python -m src.tests.test_pymongo4_compat     # no removed pymongo API is used
python -m src.tests.test_bug_fixes           # multi-condition statistics

Documentation

Full user guide: conesalab.github.io/PaintOmics — including accepted input formats, a step-by-step guide and the FAQ. The sources live in docs/ and build with mkdocs.

Video tutorials

Time	Topic
0:00	Introduction to PaintOmics
2:24	Pathway enrichment analysis
4:16	Metabolite hub analysis
6:30	Metabolite class activity analysis
8:13	Metagenes
10:09	Pathway interactions network
13:00	Regulatory omics

Time	Topic
0:00	Introduction to PaintOmics
0:59	Overview of the video
3:34	Gene expression and metabolomics data
16:11	Region-based omics data
19:20	Regulatory omics analysis

These cover the analyses as released in PaintOmics 4; the pipeline they describe is unchanged. More on the PaintOmics YouTube channel.

Citation

If PaintOmics contributed to your work, please cite:

PaintOmics 4: new tools for the integrative analysis of multi-omics datasets supported by multiple pathway databases. Nucleic Acids Research (2022). 10.1093/nar/gkac352

• PaintOmics 3 — Nucleic Acids Research (2018), 10.1093/nar/gky466
• PaintOmics 2 — Bioinformatics (2011), 10.1093/bioinformatics/btq594
• RGmatch — BMC Bioinformatics (2016), 10.1186/s12859-016-1293-1
• MORE — the regulatory model behind the Regulatory Omics option, BiostatOmics/MORE

BibTeX records are available from the More → Cite PaintOmics menu in the application.

Contact and contributing

Questions, bug reports and organism requests: open an issue — the bug and organism-request forms ask for the details that make a report reproducible — or write to [email protected].

Pull requests are welcome. CONTRIBUTING.md covers getting a development instance running, the test suites, and what the pull-request gate checks. Security problems go through SECURITY.md instead of the issue tracker; please do not report them publicly.

License

Distributed under the GNU General Public License, Version 3 — see LICENSE.

Acknowledgements

PaintOmics is developed by the Genomics of Gene Expression Lab and originated in the STATegra Project, funded by the European Commission's 7th Framework Programme.