SigRepo: An R package for storing, sharing, and comparing omic signatures

What is SigRepo?

High-throughput studies produce a growing volume of omic signatures. Most of them end up in supplementary tables, with inconsistent metadata and no shared representation, so they are rarely reused and comparing a new result against prior work stays a manual job.

SigRepo is a platform that treats signatures as first-class, reusable objects: stored in a common representation with controlled metadata, searchable, shareable, and analyzable in place rather than only downloadable.

This repository is the R client. It talks to a running SigRepo_Server instance, which provides the MySQL database, the REST API, the web interface, and an MCP server for AI agents. You can use the client against our deployed server or against your own.

Signatures are represented as R6 objects defined by OmicSignature, our in-house package (GPL-3), which pairs a curated feature set with its underlying differential-expression table and a controlled metadata vocabulary.

• Overview of the object structure
• Create an OmicSignature (OmS)
• Create an OmicSignatureCollection (OmSC)

What you can do with the client

Store and organize

• Upload signatures (addSignature()) and collections (addCollection()), update (updateSignature()) and remove (deleteSignature()) them.
• Group related signatures into collections (addSignatureToCollection()), and share them with specific users (addUserToSignature(), addUserToCollection()).

Search and retrieve

• Search metadata without pulling whole objects (searchSignature(), searchCollection()).
• Retrieve full signatures and collections, including their difexp tables (getSignature(), getCollection(), getSignatureFeatureSet()).
• Browse controlled vocabularies (searchOrganism(), searchPhenotype(), searchPlatform(), searchSampleType(), searchAssayType()).

Analyze

• Compare any set of signatures (compareSignatures()) by feature overlap, rank-based Kolmogorov–Smirnov statistics, or GSEA.
• Run gene set enrichment against MSigDB with hypeR (runHypeR(), prepareHypeRSignatures()).

Installation

# Load devtools package
library(devtools)

# Install SigRepo
devtools::install_github(repo = 'montilab/SigRepo')

# Install OmicSignature
devtools::install_github(repo = 'montilab/OmicSignature')

# Load packages
library(tidyverse)
library(SigRepo)
library(OmicSignature)

Before you begin

Navigate to our sigrepo.org portal to create an account. On the login page, click "Register here!" and fill out the registration form. You will receive an email when your account has been activated.

Each person should use their own account. Due to SQL constraints, multiple users sharing one account (for example, several people running this tutorial on a shared test login) will fail to connect.

Connect to the database

Once you have an account, create a connection handler with newConnHandler():

# Create a connection handler
conn_handler <- SigRepo::newConnHandler(
  dbname = "sigrepo",
  host = "sigrepo.org",
  port = 3306,
  user = <your_username>,
  password = <your_password>
)

SigRepo stores that handler internally for the current R session, so most functions can be called either way:

# Option 1: explicit connection handler
SigRepo::searchSignature(
  conn_handler = conn_handler,
  signature_name = "example_signature"
)

# Option 2: use stored handler from newConnHandler()
SigRepo::searchSignature(
  signature_name = "example_signature"
)

Accounts and visibility

There are three types of user accounts:

• admin has READ and WRITE access to all signatures in the database.
• editor has READ and WRITE access to only their own uploaded signatures.
• viewer has READ-ONLY access to publicly available signatures.

SigRepo holds unpublished and sensitive signatures, so each signature carries a visibility flag:

• visibility = 1 (public, the default) — available to every account.
• visibility = 0 (private) — retrievable only by the owner and users they have granted access to.

Note the difference between the two access paths: searchSignature() returns metadata only and is visible to everyone, while getSignature() returns the signature itself and does enforce visibility.

Comparing signatures

compareSignatures() wraps OmicSignature::compare_omic_signatures() so a set of signatures can be compared directly:

# Compare several signatures by feature overlap
result <- SigRepo::compareSignatures(
  signature_names = c("signature_a", "signature_b", "signature_c"),
  method = "overlap"
)

result$comparisons$level1_vs_level1$jaccard

Supported methods:

Method	What it measures	Needs difexp
overlap	Jaccard index + Fisher exact test on the retained feature sets	no
ks_rank	where one signature’s features fall in another’s ranking	yes
ks_score	the ranking scores of those features vs. the rest	yes
gsea	GSEA enrichment (via fgsea), with leading edge	yes

For bi-directional signatures, comparisons are performed per matched group label, so “up vs. up” and “down vs. down” are reported separately.

AI and agent access

SigRepo runs a Model Context Protocol (MCP) server at https://sigrepo.org/mcp/, so AI assistants can query the repository directly — searching signatures, retrieving signature context, comparing signatures, browsing gene sets, and running enrichment, all grounded in the stored data rather than the model’s recollection.

With Claude Code:

claude mcp add --transport http sigrepo https://sigrepo.org/mcp/

Every tool call takes your SigRepo api_key as an argument (the same credential the REST API uses); retrieve it with SigRepo::getAPIKey(). This repository also ships a connect-sigrepo-mcp skill under .claude/skills/ that handles the setup.

In development

The following are active work and not yet available in the released package:

• AI-assisted signature authoring. The main barrier to contributing is curation, not storage: a depositor has to reshape a differential-expression result, assign controlled metadata, and satisfy the schema. We are building an agent that reads a study’s differential-expression output and description, proposes metadata from SigRepo’s controlled vocabularies, and emits a validated OmicSignature for the depositor to review — turning contribution from a curation task into a review step.
• A modernized web interface for browsing, inspecting, and comparing signatures.
• Additional external gene-set resources. Because analyses are exposed as discrete API endpoints over a common signature representation, new resources can be added without schema changes.

Guides

• Uploading Signature Tutorial
• Uploading Signature Collection Tutorial
• Setting up your own SigRepo_Server

Questions, or want an account? Contact us.