# String Database Visualize > Search protein-protein interactions (PPI), calculate functional enrichment (GO, KEGG, Reactome, UniProt), extract interaction subnetworks and partners, perform orthology mapping, and run rank-based gene set enrichment analysis (Values/Ranks GSEA) via the STRING Database API v12.0. - Skill: `terravic/string-database-visualize` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add terravic/string-database-visualize` - Raw SKILL.md: https://api.skillmd.com/api/skills/terravic/string-database-visualize/raw - Safety review: pending (external: skill-scanner WARNING, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: terravic (https://skillmd.com/u/terravic) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/terravic/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: ```bash uv --version ``` If `uv` is not installed: ```bash 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: `); 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 `) or prompt the user. 2. **Mandatory Output Redirection**: Always specify `--output ` 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 ` - For specific column extraction: `cut -f 1,2,6 | head -n 20` - For pattern matching: `grep -i "" ` 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: | NCBI Taxon ID | Scientific Name | Common Name | | :--- | :--- | :--- | | **9606** | Homo sapiens | Human | | **10090** | Mus musculus | Mouse | | **10116** | Rattus norvegicus | Rat | | **7955** | Danio rerio | Zebrafish | | **7227** | Drosophila melanogaster | Fruit fly | | **6239** | Caenorhabditis elegans | Nematode / C. elegans | | **4932** | Saccharomyces cerevisiae | Baker's yeast | | **4896** | Schizosaccharomyces pombe | Fission yeast | | **3702** | Arabidopsis thaliana | Thale cress / Arabidopsis | | **511145** | Escherichia coli str. K-12 substr. MG1655 | E. coli K-12 | | **224308** | Bacillus subtilis subsp. subtilis str. 168 | B. subtilis | | **9615** | Canis lupus familiaris | Dog | | **9823** | Sus scrofa | Pig | | **9913** | Bos taurus | Cow / Cattle | | **9031** | Gallus gallus | Chicken | To query the built-in species dictionary: ```bash 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): | Score Range | Confidence Level | Interpretation | | :--- | :--- | :--- | | **0.900 - 1.000** (900+) | Highest confidence | Supported by direct experimental data and curated database records. | | **0.700 - 0.899** (700-899) | High confidence | Plausible physical interactions or high co-expression correlation. | | **0.400 - 0.699** (400-699) | Medium confidence | Default threshold; captures functional associations and co-mentions. | | **0.150 - 0.399** (150-399) | Low confidence | Exploratory associations; high false positive rate. | ### 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**: ```bash 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**: ```bash 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**: ```bash 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**: ```bash 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)**: ```bash 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**: ```bash 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**: ```bash 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**: ```bash # 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**: ```bash 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**: ```bash 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: ```tsv 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**: ```bash # Keep the key out of shell history and process listings export STRING_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 "" \ --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](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**: ```bash 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**: ```bash 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**: ```bash 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 ` 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](references/mapping.md): Identifier normalization, synonyms, and column schemas. - [Interactions & Networks](references/interactions.md): Functional vs physical networks, partner retrieval, and visualization. - [Functional Enrichment](references/enrichment.md): Statistical models, categories (GO, KEGG, Reactome), and PPI enrichment. - [Values/Ranks Analysis](references/valuesranks.md): GSEA-style ranking input preparation and async polling. - [Scores and Metrics](references/scores_and_metrics.md): Calibration benchmarks, evidence channel weights, and Bayesian scoring.