A model-agnostic AI co-scientist for ML engineering and scientific research. Give it a goal and it reads the literature, writes and runs code, runs experiments, and writes up results. Run `openscience` to open the workspace in your browser. Bring your own API key from any provider, or use Atlas for managed models and compute. Built with Bun and TypeScript. Apache License 2.0.
Showing the changes to backend/cli/skills/databases/string-database/references/string_reference.md (1 of 3865 files). Show all
Unified · Split
| @@ -0,0 +1,455 @@ | |||
| 1 | # STRING Database API Reference | ||
| 2 | |||
| 3 | ## Overview | ||
| 4 | |||
| 5 | STRING (Search Tool for the Retrieval of Interacting Genes/Proteins) is a comprehensive database of known and predicted protein-protein interactions integrating data from over 40 sources. | ||
| 6 | |||
| 7 | **Database Statistics (v12.0+):** | ||
| 8 | - Coverage: 5000+ genomes | ||
| 9 | - Proteins: ~59.3 million | ||
| 10 | - Interactions: 20+ billion | ||
| 11 | - Data types: Physical interactions, functional associations, co-expression, co-occurrence, text-mining, databases | ||
| 12 | |||
| 13 | **Core Data Resource:** Designated by Global Biodata Coalition and ELIXIR | ||
| 14 | |||
| 15 | ## API Base URLs | ||
| 16 | |||
| 17 | - **Current version**: https://string-db.org/api | ||
| 18 | - **Version-specific**: https://version-12-0.string-db.org/api (for reproducibility) | ||
| 19 | - **API documentation**: https://string-db.org/help/api/ | ||
| 20 | |||
| 21 | ## Best Practices | ||
| 22 | |||
| 23 | 1. **Identifier Mapping**: Always map identifiers first using `get_string_ids` for faster subsequent queries | ||
| 24 | 2. **Use STRING IDs**: Prefer STRING identifiers (e.g., `9606.ENSP00000269305`) over gene names | ||
| 25 | 3. **Specify Species**: For networks with >10 proteins, always specify species NCBI taxon ID | ||
| 26 | 4. **Rate Limiting**: Wait 1 second between API calls to avoid server overload | ||
| 27 | 5. **Versioned URLs**: Use version-specific URLs for reproducible research | ||
| 28 | 6. **POST over GET**: Use POST requests for large protein lists | ||
| 29 | 7. **Caller Identity**: Include `caller_identity` parameter for tracking (e.g., your application name) | ||
| 30 | |||
| 31 | ## API Methods | ||
| 32 | |||
| 33 | ### 1. Identifier Mapping (`get_string_ids`) | ||
| 34 | |||
| 35 | **Purpose**: Maps common protein names, gene symbols, UniProt IDs, and other identifiers to STRING identifiers. | ||
| 36 | |||
| 37 | **Endpoint**: `/api/tsv/get_string_ids` | ||
| 38 | |||
| 39 | **Parameters**: | ||
| 40 | - `identifiers` (required): Protein names/IDs separated by newlines (`%0d`) | ||
| 41 | - `species` (required): NCBI taxon ID | ||
| 42 | - `limit`: Number of matches per identifier (default: 1) | ||
| 43 | - `echo_query`: Include query term in output (1 or 0) | ||
| 44 | - `caller_identity`: Application identifier | ||
| 45 | |||
| 46 | **Output Format**: TSV with columns: | ||
| 47 | - `queryItem`: Original query | ||
| 48 | - `queryIndex`: Query position | ||
| 49 | - `stringId`: STRING identifier | ||
| 50 | - `ncbiTaxonId`: Species taxon ID | ||
| 51 | - `taxonName`: Species name | ||
| 52 | - `preferredName`: Preferred gene name | ||
| 53 | - `annotation`: Protein description | ||
| 54 | |||
| 55 | **Example**: | ||
| 56 | ``` | ||
| 57 | identifiers=TP53%0dBRCA1&species=9606&limit=1 | ||
| 58 | ``` | ||
| 59 | |||
| 60 | **Use cases**: | ||
| 61 | - Converting gene symbols to STRING IDs | ||
| 62 | - Validating protein identifiers | ||
| 63 | - Finding canonical protein names | ||
| 64 | |||
| 65 | ### 2. Network Data (`network`) | ||
| 66 | |||
| 67 | **Purpose**: Retrieves protein-protein interaction network data in tabular format. | ||
| 68 | |||
| 69 | **Endpoint**: `/api/tsv/network` | ||
| 70 | |||
| 71 | **Parameters**: | ||
| 72 | - `identifiers` (required): Protein IDs separated by `%0d` | ||
| 73 | - `species`: NCBI taxon ID | ||
| 74 | - `required_score`: Confidence threshold 0-1000 (default: 400) | ||
| 75 | - 150: low confidence | ||
| 76 | - 400: medium confidence | ||
| 77 | - 700: high confidence | ||
| 78 | - 900: highest confidence | ||
| 79 | - `network_type`: `functional` (default) or `physical` | ||
| 80 | - `add_nodes`: Add N interacting proteins (0-10) | ||
| 81 | - `caller_identity`: Application identifier | ||
| 82 | |||
| 83 | **Output Format**: TSV with columns: | ||
| 84 | - `stringId_A`, `stringId_B`: Interacting proteins | ||
| 85 | - `preferredName_A`, `preferredName_B`: Gene names | ||
| 86 | - `ncbiTaxonId`: Species | ||
| 87 | - `score`: Combined interaction score (0-1000) | ||
| 88 | - `nscore`: Neighborhood score | ||
| 89 | - `fscore`: Fusion score | ||
| 90 | - `pscore`: Phylogenetic profile score | ||
| 91 | - `ascore`: Coexpression score | ||
| 92 | - `escore`: Experimental score | ||
| 93 | - `dscore`: Database score | ||
| 94 | - `tscore`: Text-mining score | ||
| 95 | |||
| 96 | **Network Types**: | ||
| 97 | - **Functional**: All interaction evidence types (recommended for most analyses) | ||
| 98 | - **Physical**: Only direct physical binding evidence | ||
| 99 | |||
| 100 | **Example**: | ||
| 101 | ``` | ||
| 102 | identifiers=9606.ENSP00000269305%0d9606.ENSP00000275493&required_score=700 | ||
| 103 | ``` | ||
| 104 | |||
| 105 | ### 3. Network Image (`image/network`) | ||
| 106 | |||
| 107 | **Purpose**: Generates visual network representation as PNG image. | ||
| 108 | |||
| 109 | **Endpoint**: `/api/image/network` | ||
| 110 | |||
| 111 | **Parameters**: | ||
| 112 | - `identifiers` (required): Protein IDs separated by `%0d` | ||
| 113 | - `species`: NCBI taxon ID | ||
| 114 | - `required_score`: Confidence threshold 0-1000 | ||
| 115 | - `network_flavor`: Visualization style | ||
| 116 | - `evidence`: Show evidence types as colored lines | ||
| 117 | - `confidence`: Show confidence as line thickness | ||
| 118 | - `actions`: Show activating/inhibiting interactions | ||
| 119 | - `add_nodes`: Add N interacting proteins (0-10) | ||
| 120 | - `caller_identity`: Application identifier | ||
| 121 | |||
| 122 | **Output**: PNG image (binary data) | ||
| 123 | |||
| 124 | **Image Specifications**: | ||
| 125 | - Format: PNG | ||
| 126 | - Size: Automatically scaled based on network size | ||
| 127 | - High-resolution option available (add `?highres=1`) | ||
| 128 | |||
| 129 | **Example**: | ||
| 130 | ``` | ||
| 131 | identifiers=TP53%0dMDM2&species=9606&network_flavor=evidence | ||
| 132 | ``` | ||
| 133 | |||
| 134 | ### 4. Interaction Partners (`interaction_partners`) | ||
| 135 | |||
| 136 | **Purpose**: Retrieves all STRING interaction partners for given protein(s). | ||
| 137 | |||
| 138 | **Endpoint**: `/api/tsv/interaction_partners` | ||
| 139 | |||
| 140 | **Parameters**: | ||
| 141 | - `identifiers` (required): Protein IDs | ||
| 142 | - `species`: NCBI taxon ID | ||
| 143 | - `required_score`: Confidence threshold 0-1000 | ||
| 144 | - `limit`: Maximum number of partners (default: 10) | ||
| 145 | - `caller_identity`: Application identifier | ||
| 146 | |||
| 147 | **Output Format**: TSV with same columns as `network` method | ||
| 148 | |||
| 149 | **Use cases**: | ||
| 150 | - Finding hub proteins | ||
| 151 | - Expanding networks | ||
| 152 | - Discovery of novel interactions | ||
| 153 | |||
| 154 | **Example**: | ||
| 155 | ``` | ||
| 156 | identifiers=TP53&species=9606&limit=20&required_score=700 | ||
| 157 | ``` | ||
| 158 | |||
| 159 | ### 5. Functional Enrichment (`enrichment`) | ||
| 160 | |||
| 161 | **Purpose**: Performs functional enrichment analysis for a set of proteins across multiple annotation databases. | ||
| 162 | |||
| 163 | **Endpoint**: `/api/tsv/enrichment` | ||
| 164 | |||
| 165 | **Parameters**: | ||
| 166 | - `identifiers` (required): List of protein IDs | ||
| 167 | - `species` (required): NCBI taxon ID | ||
| 168 | - `caller_identity`: Application identifier | ||
| 169 | |||
| 170 | **Enrichment Categories**: | ||
| 171 | - **Gene Ontology**: Biological Process, Molecular Function, Cellular Component | ||
| 172 | - **KEGG Pathways**: Metabolic and signaling pathways | ||
| 173 | - **Pfam**: Protein domains | ||
| 174 | - **InterPro**: Protein families and domains | ||
| 175 | - **SMART**: Domain architecture | ||
| 176 | - **UniProt Keywords**: Curated functional keywords | ||
| 177 | |||
| 178 | **Output Format**: TSV with columns: | ||
| 179 | - `category`: Annotation category | ||
| 180 | - `term`: Term ID | ||
| 181 | - `description`: Term description | ||
| 182 | - `number_of_genes`: Genes in input with this term | ||
| 183 | - `number_of_genes_in_background`: Total genes with this term | ||
| 184 | - `ncbiTaxonId`: Species | ||
| 185 | - `inputGenes`: Comma-separated gene list | ||
| 186 | - `preferredNames`: Comma-separated gene names | ||
| 187 | - `p_value`: Enrichment p-value (uncorrected) | ||
| 188 | - `fdr`: False discovery rate (corrected p-value) | ||
| 189 | |||
| 190 | **Statistical Method**: Fisher's exact test with Benjamini-Hochberg FDR correction | ||
| 191 | |||
| 192 | **Example**: | ||
| 193 | ``` | ||
| 194 | identifiers=TP53%0dMDM2%0dATM%0dCHEK2&species=9606 | ||
| 195 | ``` | ||
| 196 | |||
| 197 | ### 6. PPI Enrichment (`ppi_enrichment`) | ||
| 198 | |||
| 199 | **Purpose**: Tests if a network has significantly more interactions than expected by chance. | ||
| 200 | |||
| 201 | **Endpoint**: `/api/json/ppi_enrichment` | ||
| 202 | |||
| 203 | **Parameters**: | ||
| 204 | - `identifiers` (required): List of protein IDs | ||
| 205 | - `species`: NCBI taxon ID | ||
| 206 | - `required_score`: Confidence threshold | ||
| 207 | - `caller_identity`: Application identifier | ||
| 208 | |||
| 209 | **Output Format**: JSON with fields: | ||
| 210 | - `number_of_nodes`: Proteins in network | ||
| 211 | - `number_of_edges`: Interactions observed | ||
| 212 | - `expected_number_of_edges`: Expected interactions (random) | ||
| 213 | - `p_value`: Statistical significance | ||
| 214 | |||
| 215 | **Interpretation**: | ||
| 216 | - p-value < 0.05: Network is significantly enriched | ||
| 217 | - Low p-value indicates proteins form functional module | ||
| 218 | |||
| 219 | **Example**: | ||
| 220 | ``` | ||
| 221 | identifiers=TP53%0dMDM2%0dATM%0dCHEK2&species=9606 | ||
| 222 | ``` | ||
| 223 | |||
| 224 | ### 7. Homology Scores (`homology`) | ||
| 225 | |||
| 226 | **Purpose**: Retrieves protein similarity/homology scores. | ||
| 227 | |||
| 228 | **Endpoint**: `/api/tsv/homology` | ||
| 229 | |||
| 230 | **Parameters**: | ||
| 231 | - `identifiers` (required): Protein IDs | ||
| 232 | - `species`: NCBI taxon ID | ||
| 233 | - `caller_identity`: Application identifier | ||
| 234 | |||
| 235 | **Output Format**: TSV with homology scores between proteins | ||
| 236 | |||
| 237 | **Use cases**: | ||
| 238 | - Identifying protein families | ||
| 239 | - Paralog analysis | ||
| 240 | - Cross-species comparisons | ||
| 241 | |||
| 242 | ### 8. Version Information (`version`) | ||
| 243 | |||
| 244 | **Purpose**: Returns current STRING database version. | ||
| 245 | |||
| 246 | **Endpoint**: `/api/tsv/version` | ||
| 247 | |||
| 248 | **Output**: Version string (e.g., "12.0") | ||
| 249 | |||
| 250 | ## Common Species NCBI Taxon IDs | ||
| 251 | |||
| 252 | | Organism | Common Name | Taxon ID | | ||
| 253 | |----------|-------------|----------| | ||
| 254 | | Homo sapiens | Human | 9606 | | ||
| 255 | | Mus musculus | Mouse | 10090 | | ||
| 256 | | Rattus norvegicus | Rat | 10116 | | ||
| 257 | | Drosophila melanogaster | Fruit fly | 7227 | | ||
| 258 | | Caenorhabditis elegans | C. elegans | 6239 | | ||
| 259 | | Saccharomyces cerevisiae | Yeast | 4932 | | ||
| 260 | | Arabidopsis thaliana | Thale cress | 3702 | | ||
| 261 | | Escherichia coli K-12 | E. coli | 511145 | | ||
| 262 | | Danio rerio | Zebrafish | 7955 | | ||
| 263 | | Gallus gallus | Chicken | 9031 | | ||
| 264 | |||
| 265 | Full list: https://string-db.org/cgi/input?input_page_active_form=organisms | ||
| 266 | |||
| 267 | ## STRING Identifier Format | ||
| 268 | |||
| 269 | STRING uses Ensembl protein IDs with taxon prefix: | ||
| 270 | - Format: `{taxonId}.{ensemblProteinId}` | ||
| 271 | - Example: `9606.ENSP00000269305` (human TP53) | ||
| 272 | |||
| 273 | **ID Components**: | ||
| 274 | - **Taxon ID**: NCBI taxonomy identifier | ||
| 275 | - **Protein ID**: Usually Ensembl protein ID (ENSP...) | ||
| 276 | |||
| 277 | ## Interaction Confidence Scores | ||
| 278 | |||
| 279 | STRING provides combined confidence scores (0-1000) based on multiple evidence channels: | ||
| 280 | |||
| 281 | ### Evidence Channels | ||
| 282 | |||
| 283 | 1. **Neighborhood (nscore)**: Gene fusion and conserved genomic neighborhood | ||
| 284 | 2. **Fusion (fscore)**: Gene fusion events across species | ||
| 285 | 3. **Phylogenetic Profile (pscore)**: Co-occurrence across species | ||
| 286 | 4. **Coexpression (ascore)**: RNA expression correlation | ||
| 287 | 5. **Experimental (escore)**: Biochemical/genetic experiments | ||
| 288 | 6. **Database (dscore)**: Curated pathway/complex databases | ||
| 289 | 7. **Text-mining (tscore)**: Literature co-occurrence | ||
| 290 | |||
| 291 | ### Recommended Thresholds | ||
| 292 | |||
| 293 | - **150**: Low confidence (exploratory analysis) | ||
| 294 | - **400**: Medium confidence (standard analysis) | ||
| 295 | - **700**: High confidence (conservative analysis) | ||
| 296 | - **900**: Highest confidence (very stringent) | ||
| 297 | |||
| 298 | ## Output Formats | ||
| 299 | |||
| 300 | ### Available Formats | ||
| 301 | |||
| 302 | 1. **TSV**: Tab-separated values (default, best for data processing) | ||
| 303 | 2. **JSON**: JavaScript Object Notation (structured data) | ||
| 304 | 3. **XML**: Extensible Markup Language | ||
| 305 | 4. **PSI-MI**: Proteomics Standards Initiative format | ||
| 306 | 5. **PSI-MITAB**: Tab-delimited PSI-MI format | ||
| 307 | 6. **PNG**: Image format (for network visualizations) | ||
| 308 | 7. **SVG**: Scalable vector graphics (for network visualizations) | ||
| 309 | |||
| 310 | ### Format Selection | ||
| 311 | |||
| 312 | Replace `/tsv/` in URL with desired format: | ||
| 313 | - `/json/network` - JSON format | ||
| 314 | - `/xml/network` - XML format | ||
| 315 | - `/image/network` - PNG image | ||
| 316 | |||
| 317 | ## Error Handling | ||
| 318 | |||
| 319 | ### HTTP Status Codes | ||
| 320 | |||
| 321 | - **200 OK**: Successful request | ||
| 322 | - **400 Bad Request**: Invalid parameters or syntax | ||
| 323 | - **404 Not Found**: Protein/species not found | ||
| 324 | - **500 Internal Server Error**: Server error | ||
| 325 | |||
| 326 | ### Common Errors | ||
| 327 | |||
| 328 | 1. **"No proteins found"**: Invalid identifiers or species mismatch | ||
| 329 | 2. **"Species required"**: Missing species parameter for large networks | ||
| 330 | 3. **Empty results**: No interactions above score threshold | ||
| 331 | 4. **Timeout**: Network too large, reduce protein count | ||
| 332 | |||
| 333 | ## Advanced Features | ||
| 334 | |||
| 335 | ### Bulk Network Upload | ||
| 336 | |||
| 337 | For complete proteome analysis: | ||
| 338 | 1. Navigate to https://string-db.org/ | ||
| 339 | 2. Select "Upload proteome" option | ||
| 340 | 3. Upload FASTA file | ||
| 341 | 4. STRING generates complete interaction network and predicts functions | ||
| 342 | |||
| 343 | ### Values/Ranks Enrichment API | ||
| 344 | |||
| 345 | For differential expression/proteomics data: | ||
| 346 | |||
| 347 | 1. **Get API Key**: | ||
| 348 | ``` | ||
| 349 | /api/json/get_api_key | ||
| 350 | ``` | ||
| 351 | |||
| 352 | 2. **Submit Data**: Tab-separated protein ID and value pairs | ||
| 353 | |||
| 354 | 3. **Check Status**: | ||
| 355 | ``` | ||
| 356 | /api/json/valuesranks_enrichment_status?job_id={id} | ||
| 357 | ``` | ||
| 358 | |||
| 359 | 4. **Retrieve Results**: Access enrichment tables and figures | ||
| 360 | |||
| 361 | **Requirements**: | ||
| 362 | - Complete protein set (no filtering) | ||
| 363 | - Numeric values for each protein | ||
| 364 | - Proper species identifier | ||
| 365 | |||
| 366 | ### Network Customization | ||
| 367 | |||
| 368 | **Network Size Control**: | ||
| 369 | - `add_nodes=N`: Adds N most connected proteins | ||
| 370 | - `limit`: Controls partner retrieval | ||
| 371 | |||
| 372 | **Confidence Filtering**: | ||
| 373 | - Adjust `required_score` based on analysis goals | ||
| 374 | - Higher scores = fewer false positives, more false negatives | ||
| 375 | |||
| 376 | **Network Type Selection**: | ||
| 377 | - `functional`: All evidence (recommended for pathway analysis) | ||
| 378 | - `physical`: Direct binding only (recommended for structural studies) | ||
| 379 | |||
| 380 | ## Integration with Other Tools | ||
| 381 | |||
| 382 | ### Python Libraries | ||
| 383 | |||
| 384 | **requests** (recommended): | ||
| 385 | ```python | ||
| 386 | import requests | ||
| 387 | url = "https://string-db.org/api/tsv/network" | ||
| 388 | params = {"identifiers": "TP53", "species": 9606} | ||
| 389 | response = requests.get(url, params=params) | ||
| 390 | ``` | ||
| 391 | |||
| 392 | **urllib** (standard library): | ||
| 393 | ```python | ||
| 394 | import urllib.request | ||
| 395 | url = "https://string-db.org/api/tsv/network?identifiers=TP53&species=9606" | ||
| 396 | response = urllib.request.urlopen(url) | ||
| 397 | ``` | ||
| 398 | |||
| 399 | ### R Integration | ||
| 400 | |||
| 401 | **STRINGdb Bioconductor package**: | ||
| 402 | ```R | ||
| 403 | library(STRINGdb) | ||
| 404 | string_db <- STRINGdb$new(version="12", species=9606) | ||
| 405 | ``` | ||
| 406 | |||
| 407 | ### Cytoscape | ||
| 408 | |||
| 409 | STRING networks can be imported into Cytoscape for visualization and analysis: | ||
| 410 | 1. Use stringApp plugin | ||
| 411 | 2. Import TSV network data | ||
| 412 | 3. Apply layouts and styling | ||
| 413 | |||
| 414 | ## Data License | ||
| 415 | |||
| 416 | STRING data is freely available under **Creative Commons BY 4.0** license: | ||
| 417 | - ✓ Free to use for academic and commercial purposes | ||
| 418 | - ✓ Attribution required | ||
| 419 | - ✓ Modifications allowed | ||
| 420 | - ✓ Redistribution allowed | ||
| 421 | |||
| 422 | **Citation**: Szklarczyk et al. (latest publication) | ||
| 423 | |||
| 424 | ## Rate Limits and Usage | ||
| 425 | |||
| 426 | - **Rate limiting**: No strict limit, but avoid rapid-fire requests | ||
| 427 | - **Recommendation**: Wait 1 second between calls | ||
| 428 | - **Large datasets**: Use bulk download from https://string-db.org/cgi/download | ||
| 429 | - **Proteome-scale**: Use web upload feature instead of API | ||
| 430 | |||
| 431 | ## Related Resources | ||
| 432 | |||
| 433 | - **STRING website**: https://string-db.org | ||
| 434 | - **Download page**: https://string-db.org/cgi/download | ||
| 435 | - **Help center**: https://string-db.org/help/ | ||
| 436 | - **API documentation**: https://string-db.org/help/api/ | ||
| 437 | - **Publications**: https://string-db.org/cgi/about | ||
| 438 | |||
| 439 | ## Troubleshooting | ||
| 440 | |||
| 441 | **No results returned**: | ||
| 442 | - Verify species parameter matches identifiers | ||
| 443 | - Check identifier format | ||
| 444 | - Lower confidence threshold | ||
| 445 | - Use identifier mapping first | ||
| 446 | |||
| 447 | **Timeout errors**: | ||
| 448 | - Reduce number of input proteins | ||
| 449 | - Split large queries into batches | ||
| 450 | - Use bulk download for proteome-scale analyses | ||
| 451 | |||
| 452 | **Version inconsistencies**: | ||
| 453 | - Use version-specific URLs | ||
| 454 | - Check STRING version with `/version` endpoint | ||
| 455 | - Update identifiers if using old IDs | ||