String Database Visualize

STRING Database Skill Guide

This skill provides an interface to STRING Database API v12.0 for exploring protein-protein interaction (PPI) networks, physical and functional associations, functional term enrichment, cross-species homology, and genome-wide ranked expression analysis.

Prerequisites

The skill scripts run with uv (fast Python package manager) and require Python 3.10+. Dependencies such as polite-http are managed automatically via PEP 723 inline metadata.

Verify that uv is installed:

uv --version

If uv is not installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Without uv, use a virtualenv instead: pip install -r requirements.txt and call the script with python.

Output, Logging and Exit Codes

• stdout contains only result lines (summaries and Saved ... to: <path>); parse these.
• stderr contains structured log records. Increase verbosity with --log-level DEBUG placed before the subcommand, or set STRING_CLI_LOG_LEVEL.
• Exit codes: 0 success, 1 runtime/API/filesystem failure, 2 usage error (missing input files or credentials). Always check the exit code before trusting an output file.

Credentials

The Values/Ranks workflow needs an API key. Pass --api_key or export STRING_API_KEY. Never hardcode a key into a script or commit it.

Licensing and Access Notice

• Academic and non-profit usage of STRING is freely permitted under CC-BY 4.0.
• Commercial usage requires a license from the STRING consortium.
• Review full license conditions at https://string-db.org/cgi/access.
• License verification state is tracked in .licenses/string_database_LICENSE.txt.

Data Provenance Guarantee

Everything this skill outputs comes from a live STRING API v12.0 response, a live UniProt / AlphaFold / RCSB lookup, or a file the user supplied. There are no built-in gene tables, cached payloads or synthesized structures. If a value cannot be resolved, the tool reports it as unavailable rather than substituting a placeholder - report such gaps to the user honestly.

Core Operational Rules

1. Mandatory Taxon ID Resolution: Never query the STRING API without a confirmed NCBI Taxon ID. If the organism is not explicitly specified or known, use the species subcommand (uv run skills/string_database/scripts/string_cli.py species --query <name>) or prompt the user.

2. Mandatory Output Redirection: Always specify --output <path> when executing CLI commands. Never pipe raw multi-megabyte API payloads directly into stdout or context windows. Output directories are created automatically by the CLI.

3. Map Identifiers First: Always normalize gene symbols, UniProt accessions, or Ensembl identifiers using the map subcommand before performing complex network queries. Use --limit_to_best to deduplicate multiple isoform matches.

4. Safe File Inspection: When reading output files, use bounded commands to inspect data:

   • For TSV inspection: head -n 20 <output_file>
   • For specific column extraction: cut -f 1,2,6 <output_file> | head -n 20
   • For pattern matching: grep -i "<term>" <output_file>

5. Check Exit Codes and Logs: A non-zero exit code means the output file is absent or incomplete. Read the stderr log line (it includes actionable HINT: guidance for bad taxon IDs or unmappable identifiers) before retrying.

6. Chaining Identifier Files: --identifiers @path/to/file reads one identifier per line. Blank lines and # comments are skipped, only the first tab-delimited field of each line is used, and a leading STRING TSV header row is dropped — so a map/network result table can be fed straight into the next subcommand without preprocessing.

NCBI Taxon ID Reference Table

Common model organisms supported by STRING:

To query the built-in species dictionary:

uv run skills/string_database/scripts/string_cli.py species --query "mouse"

Interaction Score Interpretation

STRING interaction scores represent confidence calibration against gold-standard KEGG pathway co-membership (0 to 1000 scale in API parameters, 0.0 to 1.0 in outputs):

Evidence Channels

• escore (Experiments): Direct biochemical assays and high-throughput physical binding screens.
• dscore (Databases): Manually curated pathways from KEGG, Reactome, BioCyc, etc.
• tscore (Textmining): Co-occurrence statistics extracted from PubMed abstracts and full-text articles.
• ascore (Coexpression): Correlated gene expression profiles across diverse microarray and RNA-seq studies.
• nscore (Neighborhood): Conserved genomic synteny and operon structures in prokaryotes and eukaryotes.
• fscore (Gene Fusion): Single protein products in one species homologous to two separate genes in another.
• pscore (Co-occurrence): Phylogenetic profiles indicating coordinated presence/absence across genomes.

Detailed Workflows

Workflow 1: Protein Interaction Exploration and Network Visualization

Use this workflow to query interactions between known seed proteins, expand subnetworks, and generate publication-quality figures.

1. Resolve and Map Identifiers:

   uv run skills/string_database/scripts/string_cli.py map \
     --identifiers TP53 MDM2 CDKN1A RB1 \
     --species 9606 \
     --limit_to_best \
     --output results/mapped_genes.tsv
   

2. Check PPI Enrichment Significance:

   uv run skills/string_database/scripts/string_cli.py ppi-enrichment \
     --identifiers @results/mapped_genes.tsv \
     --species 9606 \
     --required_score 400 \
     --output results/ppi_enrichment.tsv
   

3. Extract Network Interactions:

   uv run skills/string_database/scripts/string_cli.py network \
     --identifiers @results/mapped_genes.tsv \
     --species 9606 \
     --required_score 700 \
     --summary \
     --output results/network_edges.tsv
   

4. Retrieve Direct Interaction Partners:

   uv run skills/string_database/scripts/string_cli.py partners \
     --identifiers 9606.ENSP00000269305 \
     --species 9606 \
     --limit 10 \
     --required_score 700 \
     --output results/tp53_partners.tsv
   

5. Generate Network Diagram (SVG / PNG):

   uv run skills/string_database/scripts/string_cli.py image \
     --identifiers @results/mapped_genes.tsv \
     --species 9606 \
     --format svg \
     --network_flavor confidence \
     --output results/network_diagram.svg
   

Workflow 2: Gene Set Functional Enrichment and Pathway Analysis

Use this workflow to identify over-represented biological pathways, gene ontology terms, and protein domains for a gene list.

1. Map Input Gene List:

   uv run skills/string_database/scripts/string_cli.py map \
     --identifiers @sample_data/synthetic_cancer_genes.txt \
     --species 9606 \
     --limit_to_best \
     --output results/cancer_genes_mapped.tsv
   

2. Run Functional Enrichment with Filtering:

   uv run skills/string_database/scripts/string_cli.py enrichment \
     --identifiers @results/cancer_genes_mapped.tsv \
     --species 9606 \
     --fdr 0.05 \
     --summary \
     --output results/enrichment_all.tsv
   

3. Extract Specific Pathway Categories:

   # Filter for KEGG Pathways
   uv run skills/string_database/scripts/string_cli.py enrichment \
     --identifiers @results/cancer_genes_mapped.tsv \
     --species 9606 \
     --category KEGG \
     --fdr 0.01 \
     --summary \
     --output results/enrichment_kegg.tsv
   
   # Filter for Reactome Pathways
   uv run skills/string_database/scripts/string_cli.py enrichment \
     --identifiers @results/cancer_genes_mapped.tsv \
     --species 9606 \
     --category Reactome \
     --fdr 0.01 \
     --output results/enrichment_reactome.tsv
   

4. Inspect Enriched Terms:

   head -n 20 results/enrichment_kegg.tsv
   

Workflow 3: Genome-Wide Ranked Expression Analysis (Values/Ranks GSEA)

Use this workflow when you have full-genome differential expression data (e.g. signed -log10(p-value) or log2FC) without an arbitrary cutoff.

1. Acquire API Key:

   uv run skills/string_database/scripts/string_cli.py valuesranks-key \
     --output results/api_key.json
   

   The response carries a note saying the key activates within 30 minutes; in practice it is often usable immediately. If a submit returns {"status": "error"} the CLI logs STRING's message and exits 1 - wait and retry rather than minting another key. Reuse an existing key from STRING_API_KEY whenever one is available.

2. Prepare Ranked Input TSV: Format: Two columns (Gene Symbol/Identifier \t Numeric Rank Score), no header. Example:

   TP53    8.45
   CDKN1A    6.12
   MDM2    5.80
   MYC    -4.20
   BCL2    -6.10
   

   Malformed rows (missing score, non-numeric score, empty identifier) are reported with line numbers in the log and skipped; if nothing valid remains the command exits 1 without contacting the API.

3. Submit Ranked Dataset and Wait for Results:

   # Keep the key out of shell history and process listings
   export STRING_API_KEY="<API_KEY>"
   
   # Submit job (optionally add --rank_direction -1 or 1 to test a single tail)
   uv run skills/string_database/scripts/string_cli.py valuesranks-submit \
     --input_file sample_data/synthetic_ranked_expression.tsv \
     --species 9606 \
     --output results/valuesranks_job.json
   
   # Poll until completion and download final TSV (transient errors are retried)
   uv run skills/string_database/scripts/string_cli.py valuesranks-status \
     --job_id "<JOB_ID>" \
     --wait \
     --timeout 600 \
     --output results/valuesranks_results.tsv
   

   Job statuses are queued, running, failed and success. On success the CLI follows the absolute download_url from the status record (there is no separate results endpoint) and writes the enrichment TSV to --output. Without --wait the raw status JSON is written instead. See references/valuesranks.md for the output schema.

Workflow 4: Cross-Species Orthology Mapping and Functional Transfer

Use this workflow to identify orthologs and compare protein interactions between species.

1. Query Best Homology Matches:

   uv run skills/string_database/scripts/string_cli.py homology-best \
     --identifiers TP53 MDM2 \
     --species 9606 \
     --species_b 10090 \
     --output results/human_mouse_orthologs.tsv
   

2. Inspect Orthology Match Details:

   head -n 20 results/human_mouse_orthologs.tsv
   

Workflow 5: Interactive HTML Dashboard Generation

Use this workflow to generate a standalone interactive HTML dashboard when presenting evaluation results to users in AI agent harnesses supporting HTML preview panes.

1. Process Analysis Datasets: Run mapping, network extraction, PPI enrichment, and functional enrichment first (Workflows 1 and 2). At least one output file must be supplied; the command exits non-zero if a named file is missing, so a "successful" run always means real data was rendered.

2. Generate Standalone Dashboard:

   uv run skills/string_database/scripts/string_cli.py dashboard \
     --title "STRING Protein Interaction & Pathway Analysis" \
     --map_file results/mapped_genes.tsv \
     --network_file results/network_edges.tsv \
     --ppi_file results/ppi_enrichment.tsv \
     --enrichment_file results/enrichment_kegg.tsv \
     --output results/dashboard.html
   

   What the dashboard renders:

   • Metrics, network edges and enrichment tables come only from the files above.
   • For each mapped protein the builder resolves a UniProt accession, sequence length and domain features live, then downloads the AlphaFold model (or the RCSB experimental entry) for the 3D viewer. Each structure is labelled with its source database.
   • Proteins with no resolvable structure or annotation display an explicit "not available" state; nothing is invented to fill the panel.

   Add --no-fetch-structures for a deterministic, fully offline build (no UniProt/AlphaFold/RCSB traffic), and --structure-timeout <seconds> to bound slow lookups.

3. Emit as User-Facing Artifact: When working in an agent conversation, emit the HTML file as a user-facing artifact named dashboard.html with ArtifactMetadata: { UserFacing: true, Summary: "Interactive Evaluation Dashboard", RequestFeedback: false }. This renders immediately in the preview pane.

Domain Reference Links

For detailed schemas, column specifications, and advanced query options, consult the reference documentation:

• Mapping Guide: Identifier normalization, synonyms, and column schemas.
• Interactions & Networks: Functional vs physical networks, partner retrieval, and visualization.
• Functional Enrichment: Statistical models, categories (GO, KEGG, Reactome), and PPI enrichment.
• Values/Ranks Analysis: GSEA-style ranking input preparation and async polling.
• Scores and Metrics: Calibration benchmarks, evidence channel weights, and Bayesian scoring.