wotann 0.5.0 → 0.5.39

package/skills/scientific/database-lookup/references/string.md

@@ -0,0 +1,283 @@
+# STRING REST API
+
+## Base URL
+
+```
+https://string-db.org/api
+```
+
+## URL Pattern
+
+```
+/api/{output_format}/{method}
+```
+
+- **output_format**: `json`, `tsv`, `tsv-no-header`, `image`, `svg` (not all formats for all endpoints)
+- **method**: endpoint name (see below)
+
+## Authentication
+
+No API key required. All endpoints are public.
+
+## Key Endpoints
+
+### 1. Resolve protein identifiers
+
+Map protein names/identifiers to STRING internal IDs. Always do this first to get canonical STRING IDs.
+
+```
+GET /api/json/resolve?identifier={query}&species={taxid}
+```
+
+| Parameter    | Type   | Description |
+|-------------|--------|-------------|
+| `identifier` | string | **Required.** Protein name, gene symbol, or external ID. |
+| `species`    | int    | NCBI taxonomy ID (9606 = human, 10090 = mouse). Recommended to avoid ambiguity. |
+
+**Example:**
+```
+https://string-db.org/api/json/resolve?identifier=TP53&species=9606
+```
+
+**Response:**
+```json
+[
+  {
+    "stringId": "9606.ENSP00000269305",
+    "preferredName": "TP53",
+    "ncbiTaxonId": 9606,
+    "taxonName": "Homo sapiens",
+    "annotation": "Cellular tumor antigen p53; ..."
+  }
+]
+```
+
+---
+
+### 2. Get interaction partners (network)
+
+```
+GET /api/json/interaction_partners?identifiers={proteins}&species={taxid}
+```
+
+| Parameter           | Type   | Description |
+|--------------------|--------|-------------|
+| `identifiers`       | string | **Required.** Protein name(s). Use `%0d` (newline) to separate multiple. |
+| `species`           | int    | NCBI taxonomy ID. |
+| `limit`             | int    | Max number of interaction partners to return (per input protein). |
+| `required_score`    | int    | Minimum combined score (0-1000). Default: 400. Common thresholds: 400 (medium), 700 (high), 900 (highest). |
+| `network_type`      | string | `functional` (default, all associations) or `physical` (physical binding only). |
+
+**Example:**
+```
+https://string-db.org/api/json/interaction_partners?identifiers=TP53&species=9606&limit=10&required_score=900
+```
+
+**Response:**
+```json
+[
+  {
+    "stringId_A": "9606.ENSP00000269305",
+    "stringId_B": "9606.ENSP00000261842",
+    "preferredName_A": "TP53",
+    "preferredName_B": "MDM2",
+    "ncbiTaxonId": 9606,
+    "score": 0.999,
+    "nscore": 0,
+    "fscore": 0,
+    "pscore": 0,
+    "ascore": 0.93,
+    "escore": 0.994,
+    "dscore": 0.9,
+    "tscore": 0.981
+  }
+]
+```
+
+Score channels: `nscore` (neighborhood), `fscore` (fusion), `pscore` (phylogenetic co-occurrence), `ascore` (co-expression), `escore` (experimental), `dscore` (database/curated), `tscore` (text mining).
+
+---
+
+### 3. Get network interactions between a set of proteins
+
+```
+GET /api/json/network?identifiers={proteins}&species={taxid}
+```
+
+| Parameter         | Type   | Description |
+|------------------|--------|-------------|
+| `identifiers`     | string | **Required.** Protein names separated by `%0d` (newline-encoded). |
+| `species`         | int    | NCBI taxonomy ID. |
+| `required_score`  | int    | Minimum combined score (0-1000). |
+| `network_type`    | string | `functional` or `physical`. |
+| `add_nodes`       | int    | Number of additional interactors to add (expands the network). |
+
+**Example — network among a set of proteins:**
+```
+https://string-db.org/api/json/network?identifiers=TP53%0dBRCA1%0dATM%0dCHEK2%0dMDM2&species=9606&required_score=700
+```
+
+Returns all pairwise interactions among the input set.
+
+---
+
+### 4. Network image
+
+```
+GET /api/image/network?identifiers={proteins}&species={taxid}
+GET /api/svg/network?identifiers={proteins}&species={taxid}
+```
+
+Returns a PNG image or SVG of the interaction network.
+
+**Example:**
+```
+https://string-db.org/api/image/network?identifiers=TP53%0dBRCA1%0dMDM2&species=9606
+```
+
+---
+
+### 5. Functional enrichment analysis
+
+Perform Gene Ontology, KEGG pathway, and other enrichment analysis on a set of proteins.
+
+```
+GET /api/json/enrichment?identifiers={proteins}&species={taxid}
+```
+
+| Parameter     | Type   | Description |
+|--------------|--------|-------------|
+| `identifiers` | string | **Required.** Newline-separated (`%0d`) protein names. |
+| `species`     | int    | NCBI taxonomy ID. |
+
+**Example:**
+```
+https://string-db.org/api/json/enrichment?identifiers=TP53%0dBRCA1%0dATM%0dCHEK2%0dCDK2%0dCDKN1A&species=9606
+```
+
+**Response:**
+```json
+[
+  {
+    "category": "Process",
+    "term": "GO:0006974",
+    "description": "cellular response to DNA damage stimulus",
+    "number_of_genes": 6,
+    "number_of_genes_in_background": 781,
+    "ncbiTaxonId": 9606,
+    "inputGenes": "TP53,BRCA1,ATM,CHEK2,CDK2,CDKN1A",
+    "preferredNames": "TP53,BRCA1,ATM,CHEK2,CDK2,CDKN1A",
+    "p_value": 1.2e-12,
+    "fdr": 5.6e-10
+  }
+]
+```
+
+Categories include: `Process` (GO Biological Process), `Function` (GO Molecular Function), `Component` (GO Cellular Component), `KEGG`, `Pfam`, `InterPro`, `SMART`, `Keyword` (UniProt), `Reactome`, `WikiPathways`, `HPO` (Human Phenotype Ontology).
+
+---
+
+### 6. Get protein annotations/info
+
+```
+GET /api/json/get_string_ids?identifiers={proteins}&species={taxid}
+```
+
+Maps arbitrary names to STRING IDs with annotation text.
+
+**Example:**
+```
+https://string-db.org/api/json/get_string_ids?identifiers=CDK2%0dp53&species=9606
+```
+
+**Response:**
+```json
+[
+  {
+    "queryIndex": 0,
+    "queryItem": "CDK2",
+    "stringId": "9606.ENSP00000266970",
+    "ncbiTaxonId": 9606,
+    "taxonName": "Homo sapiens",
+    "preferredName": "CDK2",
+    "annotation": "Cyclin-dependent kinase 2; ..."
+  }
+]
+```
+
+---
+
+### 7. Get homology / best-hit in another species
+
+```
+GET /api/json/homology?identifiers={proteins}&species={taxid}&species_b={taxid_b}
+```
+
+| Parameter   | Type | Description |
+|------------|------|-------------|
+| `identifiers` | string | Source protein(s). |
+| `species`     | int | Source species. |
+| `species_b`   | int | Target species for homolog lookup. |
+
+**Example:**
+```
+https://string-db.org/api/json/homology?identifiers=TP53&species=9606&species_b=10090
+```
+
+---
+
+### 8. PPI enrichment (is my set more connected than expected?)
+
+```
+GET /api/json/ppi_enrichment?identifiers={proteins}&species={taxid}
+```
+
+**Example:**
+```
+https://string-db.org/api/json/ppi_enrichment?identifiers=TP53%0dBRCA1%0dATM%0dCHEK2&species=9606
+```
+
+**Response:**
+```json
+[
+  {
+    "number_of_nodes": 4,
+    "number_of_edges": 6,
+    "average_node_degree": 3.0,
+    "local_clustering_coefficient": 1.0,
+    "expected_number_of_edges": 1,
+    "p_value": 0.000123
+  }
+]
+```
+
+---
+
+## Common Species Taxonomy IDs
+
+| Species | Taxon ID |
+|---------|----------|
+| Homo sapiens (human) | 9606 |
+| Mus musculus (mouse) | 10090 |
+| Rattus norvegicus (rat) | 10116 |
+| Drosophila melanogaster (fruit fly) | 7227 |
+| Saccharomyces cerevisiae (yeast) | 4932 |
+| Caenorhabditis elegans (worm) | 6239 |
+| Danio rerio (zebrafish) | 7955 |
+| Escherichia coli K12 | 511145 |
+| Arabidopsis thaliana | 3702 |
+
+## Rate Limits
+
+- No published hard rate limit, but the API is intended for programmatic access at moderate rates.
+- Recommended: **max 1 request per second**.
+- For large-scale data downloads, use the flat-file downloads on the STRING website instead.
+- If you send too many requests, you may receive HTTP 429 or temporary blocking.
+- Multiple identifiers per request is strongly preferred over multiple single-identifier requests.
+
+## Error Handling
+
+- Returns HTTP 400 for malformed requests.
+- Returns HTTP 404 if no matching protein is found.
+- Empty JSON array `[]` if the query is valid but returns no results (e.g., no interactions above the threshold).
+- Include `species` parameter whenever possible to avoid ambiguous identifier resolution.

package/skills/scientific/database-lookup/references/tcga-gdc.md

@@ -0,0 +1,58 @@
+# TCGA / GDC Data Portal API
+
+## Base URL
+```
+https://api.gdc.cancer.gov
+```
+
+## Auth
+No auth for public data. Token needed only for controlled-access downloads.
+
+## Key Endpoints
+
+All search endpoints accept GET or POST (POST preferred for complex filters).
+
+| Endpoint | Description |
+|----------|-------------|
+| `/projects` | List/filter cancer projects (e.g. TCGA-BRCA) |
+| `/cases` | Search cases (patients/samples) |
+| `/files` | Search/filter files (BAM, VCF, expression) |
+| `/genes` | Search gene-level data |
+| `/ssms` | Search simple somatic mutations |
+| `/ssm_occurrences` | Mutation occurrences across cases |
+| `/files/{uuid}` | File metadata by UUID |
+| `/data/{uuid}` | Download file by UUID |
+
+## Filter Syntax (POST body)
+```json
+{
+  "filters": {
+    "op": "in",
+    "content": {"field": "cases.project.project_id", "value": ["TCGA-BRCA"]}
+  },
+  "fields": "file_id,file_name,data_type",
+  "format": "JSON",
+  "size": 10
+}
+```
+Operators: `in`, `=`, `!=`, `>`, `<`, `>=`, `<=`, `is`, `not`, `and`, `or`
+
+## Example Calls
+```
+# List projects
+https://api.gdc.cancer.gov/projects?size=5&fields=project_id,name,primary_site
+
+# BRCA1 mutations (POST)
+curl -X POST https://api.gdc.cancer.gov/ssms \
+  -H "Content-Type: application/json" \
+  -d '{"filters":{"op":"in","content":{"field":"consequence.transcript.gene.symbol","value":["BRCA1"]}},"fields":"ssm_id,genomic_dna_change","size":5}'
+
+# Cases in TCGA-LUAD
+https://api.gdc.cancer.gov/cases?filters=%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22project.project_id%22%2C%22value%22%3A%5B%22TCGA-LUAD%22%5D%7D%7D&size=3&fields=submitter_id,disease_type
+```
+
+## Pagination
+`from` (offset) and `size` (limit, max 10000). Default size is 10.
+
+## Rate Limits
+No strict limit for metadata queries. Use GDC Transfer Tool for bulk file downloads.

package/skills/scientific/database-lookup/references/treasury.md

@@ -0,0 +1,215 @@
+# US Treasury Fiscal Data API Reference
+
+## Overview
+The US Treasury's Fiscal Data API provides machine-readable access to federal financial data: national debt, treasury securities, interest rates, yield curves, revenue, spending, and more. Maintained by the Bureau of the Fiscal Service.
+
+## Base URL
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service
+```
+
+## Authentication
+**No API key required.** The API is fully open and public.
+
+## Rate Limits
+- **No formal rate limits published.**
+- Reasonable use expected; no authentication or throttling documented.
+- For bulk data, use pagination with large page sizes.
+
+---
+
+## Key Endpoints
+
+### URL Pattern
+All dataset endpoints follow:
+```
+GET /services/api/fiscal_service/{endpoint}?{parameters}
+```
+
+### Common Query Parameters (apply to all endpoints)
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fields` | string | Comma-separated list of fields to return |
+| `filter` | string | Filter expression: `field:operator:value` (e.g., `record_date:gte:2024-01-01`) |
+| `sort` | string | Sort fields: `field` (asc) or `-field` (desc); comma-separated |
+| `page[number]` | int | Page number (default 1) |
+| `page[size]` | int | Results per page (default 100, max 10000) |
+| `format` | string | `json` (default) or `csv` |
+
+**Filter Operators:**
+`eq` (equals), `lt`, `lte`, `gt`, `gte`, `in` (comma-separated values)
+
+---
+
+### 1. Treasury Yield Curve Rates (Daily)
+```
+GET /v2/accounting/od/avg_interest_rates
+```
+
+**Better endpoint for yield curves:**
+```
+GET /v1/accounting/od/rates_of_exchange
+```
+
+**Daily Treasury Par Yield Curve Rates:**
+Note: Daily yield curve rates are published at `https://home.treasury.gov/resource-center/data-chart-center/interest-rates/` and available via the TreasuryDirect API. For programmatic access via Fiscal Data:
+
+```
+GET /v2/accounting/od/avg_interest_rates
+```
+
+**Example -- Average interest rates on Treasury securities:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates?filter=record_date:gte:2024-01-01&sort=-record_date&page[size]=100
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "record_date": "2024-10-31",
+      "security_type_desc": "Treasury Bills",
+      "security_desc": "Treasury Bills",
+      "avg_interest_rate_amt": "5.223",
+      "src_line_nbr": "1",
+      "record_fiscal_year": "2025",
+      "record_fiscal_quarter": "1",
+      "record_calendar_year": "2024",
+      "record_calendar_quarter": "4",
+      "record_calendar_month": "10",
+      "record_calendar_day": "31"
+    }
+  ],
+  "meta": {
+    "count": 100,
+    "labels": { ... },
+    "dataTypes": { ... },
+    "dataFormats": { ... },
+    "total-count": 1234,
+    "total-pages": 13
+  },
+  "links": {
+    "self": "&page%5Bnumber%5D=1&page%5Bsize%5D=100",
+    "first": "&page%5Bnumber%5D=1&page%5Bsize%5D=100",
+    "prev": null,
+    "next": "&page%5Bnumber%5D=2&page%5Bsize%5D=100",
+    "last": "&page%5Bnumber%5D=13&page%5Bsize%5D=100"
+  }
+}
+```
+
+---
+
+### 2. Debt to the Penny (Daily National Debt)
+```
+GET /v2/accounting/od/debt_to_penny
+```
+
+**Example -- Debt since 2024:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny?filter=record_date:gte:2024-01-01&sort=-record_date&page[size]=10
+```
+
+**Key Fields:** `record_date`, `tot_pub_debt_out_amt`, `intragov_hold_amt`, `debt_held_public_amt`
+
+---
+
+### 3. Treasury Securities Auctions
+```
+GET /v1/accounting/od/auctions_query
+```
+
+**Example -- Recent T-Bill auctions:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/auctions_query?filter=security_type:eq:Bill&sort=-auction_date&page[size]=10
+```
+
+**Key Fields:** `cusip`, `security_type`, `security_term`, `auction_date`, `issue_date`, `maturity_date`, `high_yield`, `high_discount_rate`, `bid_to_cover_ratio`, `total_accepted`
+
+---
+
+### 4. Monthly Treasury Statement (Revenue & Outlays)
+```
+GET /v1/accounting/mts/mts_table_5
+```
+
+**Example -- Federal receipts/outlays:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/mts/mts_table_5?filter=record_date:gte:2024-01-01&sort=-record_date&page[size]=50
+```
+
+---
+
+### 5. Federal Spending by Category
+```
+GET /v1/accounting/mts/mts_table_9
+```
+
+**Example:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/mts/mts_table_9?filter=record_date:gte:2024-01-01&sort=-record_date
+```
+
+---
+
+### 6. Treasury Reporting Rates of Exchange
+```
+GET /v1/accounting/od/rates_of_exchange
+```
+
+**Example -- Exchange rates for a quarter:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/rates_of_exchange?filter=record_date:eq:2024-09-30&page[size]=200
+```
+
+**Key Fields:** `country_currency_desc`, `exchange_rate`, `record_date`, `effective_date`
+
+---
+
+### 7. Interest Expense on the Debt
+```
+GET /v2/accounting/od/interest_expense
+```
+
+**Example:**
+```
+https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/interest_expense?filter=record_fiscal_year:eq:2024&sort=-record_date
+```
+
+---
+
+### 8. Savings Bonds Rates
+```
+GET /v2/accounting/od/sb_value
+```
+
+---
+
+## Common Endpoint Paths
+
+| Endpoint | Description |
+|----------|-------------|
+| `v2/accounting/od/debt_to_penny` | Daily total public debt outstanding |
+| `v2/accounting/od/avg_interest_rates` | Average interest rates on Treasury securities |
+| `v1/accounting/od/auctions_query` | Treasury securities auction results |
+| `v1/accounting/od/rates_of_exchange` | Treasury reporting rates of exchange |
+| `v2/accounting/od/interest_expense` | Interest expense on the public debt |
+| `v1/accounting/mts/mts_table_5` | Monthly Treasury statement: receipts/outlays |
+| `v1/accounting/mts/mts_table_9` | Monthly Treasury statement: outlays by function |
+| `v2/accounting/od/statement_net_cost` | Statement of net cost |
+| `v2/accounting/od/debt_outstanding` | Historical debt outstanding (annual) |
+
+## Response Format
+All JSON responses share the same envelope:
+- `data`: Array of result objects
+- `meta`: Contains `count`, `total-count`, `total-pages`, field labels and data types
+- `links`: Pagination links (`self`, `first`, `prev`, `next`, `last`)
+
+## Notes
+- All monetary amounts are returned as strings to preserve precision.
+- Dates use `YYYY-MM-DD` format in the `record_date` field.
+- The `filter` parameter supports chaining: `filter=field1:eq:val1,field2:gte:val2`.
+- Use `fields=` to reduce response size by requesting only needed columns.
+- The API documentation and dataset explorer is at: https://fiscaldata.treasury.gov/api-documentation/
+- For Treasury yield curve rates specifically, FRED series `DGS1`, `DGS2`, `DGS5`, `DGS10`, `DGS30` may be more convenient.

package/skills/scientific/database-lookup/references/ucsc-genome.md

@@ -0,0 +1,135 @@
+# UCSC Genome Browser REST API Reference
+
+## Overview
+Provides programmatic access to genome annotations, gene tracks, sequence data,
+and other resources from the UCSC Genome Browser database.
+
+## Base URL
+`https://api.genome.ucsc.edu`
+
+## Auth
+None required (public, unauthenticated).
+
+## Response Format
+JSON for all endpoints.
+
+## Key Endpoints
+
+### List available genomes
+```
+GET /list/ucscGenomes
+```
+Returns all genome assemblies (hg38, mm39, etc.) with descriptions.
+
+### List tracks for a genome
+```
+GET /list/tracks?genome=hg38
+```
+Returns all annotation tracks available for the specified assembly.
+
+### List chromosomes/contigs
+```
+GET /list/chromosomes?genome=hg38
+```
+Optional: add `&track=<trackName>` to limit to chroms with data in that track.
+
+### List tables in a track
+```
+GET /list/schema?genome=hg38&track=knownGene
+```
+Returns table schema including field names, types, and SQL create statement.
+
+### Get track data (annotations)
+```
+GET /getData/track?genome=hg38&track=knownGene&chrom=chr1&start=11873&end=14409
+```
+Parameters:
+- `genome` -- assembly name (required)
+- `track` -- track name (required)
+- `chrom` -- chromosome (optional, limits to one chrom)
+- `start`, `end` -- 0-based half-open coordinates (optional, requires chrom)
+- `maxItemsOutput` -- limit number of items returned (default 1000 for some tracks)
+
+### Get sequence
+```
+GET /getData/sequence?genome=hg38&chrom=chr1&start=11873&end=11893
+```
+Returns DNA sequence for the specified region. Coordinates are 0-based half-open.
+
+### Search for a term
+```
+GET /search?search=BRCA1&genome=hg38
+```
+Returns matching positions across tracks (gene names, accessions, etc.).
+
+### Get hub genome data
+```
+GET /list/hubGenomes?hubUrl=<hubURL>
+```
+Lists genomes available in a track hub.
+
+## Example calls
+
+### Get RefSeq gene annotations in a region
+```
+GET https://api.genome.ucsc.edu/getData/track?genome=hg38&track=ncbiRefSeq&chrom=chr17&start=43044295&end=43125483
+```
+
+### Get DNA sequence
+```
+GET https://api.genome.ucsc.edu/getData/sequence?genome=hg38&chrom=chr7&start=117119148&end=117119178
+```
+
+### Response example (sequence)
+```json
+{
+  "genome": "hg38",
+  "chrom": "chr7",
+  "start": 117119148,
+  "end": 117119178,
+  "dna": "atgcagatatcagcgatgcagatcgatcg..."
+}
+```
+
+### Response example (track data)
+```json
+{
+  "genome": "hg38",
+  "track": "ncbiRefSeq",
+  "chrom": "chr17",
+  "start": 43044295,
+  "end": 43125483,
+  "ncbiRefSeq": [
+    {
+      "chrom": "chr17",
+      "chromStart": 43044295,
+      "chromEnd": 43125483,
+      "name": "NM_007294.4",
+      "strand": "-",
+      "name2": "BRCA1",
+      "exonCount": 23,
+      "exonStarts": "43044295,43047642,...",
+      "exonEnds": "43045802,43047703,..."
+    }
+  ]
+}
+```
+
+## Coordinate system
+All coordinates are **0-based, half-open** (standard BED format). This means
+`start` is inclusive and `end` is exclusive.
+
+## Rate Limits
+- No published hard rate limits
+- The API is intended for moderate programmatic use; bulk downloads should use
+  the MySQL public server (genome-mysql.soe.ucsc.edu) or BigBed/BigWig file downloads
+- Requests returning very large result sets may be truncated via `maxItemsOutput`
+
+## Common genome values
+- `hg38` -- Human GRCh38 (current)
+- `hg19` -- Human GRCh37
+- `mm39` -- Mouse GRCm39
+- `mm10` -- Mouse GRCm38
+- `dm6` -- Drosophila
+- `danRer11` -- Zebrafish
+- `sacCer3` -- Yeast