wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,459 @@
+# Open Targets Platform API
+
+## Base URLs
+
+**GraphQL API (primary, recommended):**
+```
+https://api.platform.opentargets.org/api/v4/graphql
+```
+
+**Important:** The GraphQL endpoint requires HTTP POST with `Content-Type: application/json`. WebFetch (GET-only) will not work — use `curl` via shell instead:
+```bash
+curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"query":"{ target(ensemblId: \"ENSG00000157764\") { approvedSymbol approvedName } }"}' \
+  https://api.platform.opentargets.org/api/v4/graphql
+```
+
+**REST API (simpler queries):**
+```
+https://api.platform.opentargets.org/api/v4
+```
+
+## Authentication
+
+No API key required. All endpoints are public.
+
+## GraphQL API
+
+All GraphQL queries are sent as POST requests to the GraphQL endpoint.
+
+```
+POST https://api.platform.opentargets.org/api/v4/graphql
+Content-Type: application/json
+
+{
+  "query": "...",
+  "variables": { ... }
+}
+```
+
+### 1. Target information (by Ensembl Gene ID)
+
+```graphql
+query TargetInfo($ensemblId: String!) {
+  target(ensemblId: $ensemblId) {
+    id
+    approvedSymbol
+    approvedName
+    biotype
+    proteinIds {
+      id
+      source
+    }
+    tractability {
+      label
+      modality
+      value
+    }
+    safetyLiabilities {
+      event
+      effects {
+        direction
+        dosing
+      }
+    }
+    pathways {
+      pathway
+      pathwayId
+    }
+    functionDescriptions
+    subcellularLocations {
+      location
+    }
+  }
+}
+```
+
+**Variables:** `{ "ensemblId": "ENSG00000141510" }`
+
+**Example as URL (GET also supported for simple queries):**
+```
+https://api.platform.opentargets.org/api/v4/graphql?query={target(ensemblId:"ENSG00000141510"){id approvedSymbol approvedName biotype functionDescriptions}}
+```
+
+---
+
+### 2. Disease information (by EFO ID)
+
+```graphql
+query DiseaseInfo($efoId: String!) {
+  disease(efoId: $efoId) {
+    id
+    name
+    description
+    therapeuticAreas {
+      id
+      name
+    }
+    synonyms {
+      terms
+    }
+  }
+}
+```
+
+**Variables:** `{ "efoId": "EFO_0000311" }` (cancer)
+
+**Example as URL:**
+```
+https://api.platform.opentargets.org/api/v4/graphql?query={disease(efoId:"EFO_0000311"){id name description therapeuticAreas{id name}}}
+```
+
+---
+
+### 3. Target-Disease associations
+
+```graphql
+query Associations($ensemblId: String!, $page: Pagination!) {
+  target(ensemblId: $ensemblId) {
+    approvedSymbol
+    associatedDiseases(page: $page) {
+      count
+      rows {
+        disease {
+          id
+          name
+        }
+        score
+        datasourceScores {
+          id
+          score
+        }
+      }
+    }
+  }
+}
+```
+
+**Variables:**
+```json
+{
+  "ensemblId": "ENSG00000141510",
+  "page": { "index": 0, "size": 10 }
+}
+```
+
+**Example as URL:**
+```
+https://api.platform.opentargets.org/api/v4/graphql?query={target(ensemblId:"ENSG00000141510"){approvedSymbol associatedDiseases(page:{index:0,size:5}){count rows{disease{id name}score}}}}
+```
+
+---
+
+### 4. Disease-Target associations (from disease side)
+
+```graphql
+query DiseaseAssociations($efoId: String!, $page: Pagination!) {
+  disease(efoId: $efoId) {
+    name
+    associatedTargets(page: $page) {
+      count
+      rows {
+        target {
+          id
+          approvedSymbol
+        }
+        score
+        datasourceScores {
+          id
+          score
+        }
+      }
+    }
+  }
+}
+```
+
+**Variables:**
+```json
+{
+  "efoId": "EFO_0000311",
+  "page": { "index": 0, "size": 10 }
+}
+```
+
+---
+
+### 5. Evidence for a target-disease pair
+
+```graphql
+query Evidence($ensemblId: String!, $efoId: String!, $size: Int!) {
+  disease(efoId: $efoId) {
+    evidences(ensemblIds: [$ensemblId], size: $size) {
+      count
+      rows {
+        id
+        score
+        datasourceId
+        datatypeId
+        literature
+        diseaseFromSource
+        targetFromSourceId
+        resourceScore
+        urls {
+          niceName
+          url
+        }
+      }
+    }
+  }
+}
+```
+
+**Variables:**
+```json
+{
+  "ensemblId": "ENSG00000141510",
+  "efoId": "EFO_0000311",
+  "size": 10
+}
+```
+
+---
+
+### 6. Drug/molecule information
+
+```graphql
+query DrugInfo($chemblId: String!) {
+  drug(chemblId: $chemblId) {
+    id
+    name
+    drugType
+    maximumClinicalTrialPhase
+    hasBeenWithdrawn
+    mechanismsOfAction {
+      rows {
+        mechanismOfAction
+        targets {
+          id
+          approvedSymbol
+        }
+      }
+    }
+    indications {
+      rows {
+        disease {
+          id
+          name
+        }
+        maxPhaseForIndication
+      }
+    }
+    linkedDiseases {
+      count
+      rows {
+        id
+        name
+      }
+    }
+    linkedTargets {
+      count
+      rows {
+        id
+        approvedSymbol
+      }
+    }
+  }
+}
+```
+
+**Variables:** `{ "chemblId": "CHEMBL25" }` (aspirin)
+
+**Example as URL:**
+```
+https://api.platform.opentargets.org/api/v4/graphql?query={drug(chemblId:"CHEMBL25"){id name drugType maximumClinicalTrialPhase mechanismsOfAction{rows{mechanismOfAction targets{id approvedSymbol}}}}}
+```
+
+---
+
+### 7. Search across targets, diseases, and drugs
+
+```graphql
+query Search($queryString: String!, $entityNames: [String!], $page: Pagination!) {
+  search(queryString: $queryString, entityNames: $entityNames, page: $page) {
+    total
+    hits {
+      id
+      entity
+      name
+      description
+      score
+    }
+  }
+}
+```
+
+**Variables:**
+```json
+{
+  "queryString": "BRAF melanoma",
+  "entityNames": ["target", "disease", "drug"],
+  "page": { "index": 0, "size": 10 }
+}
+```
+
+**Example as URL:**
+```
+https://api.platform.opentargets.org/api/v4/graphql?query={search(queryString:"BRAF",entityNames:["target"],page:{index:0,size:5}){total hits{id entity name description}}}
+```
+
+---
+
+### 8. Known drugs for a target
+
+```graphql
+query KnownDrugs($ensemblId: String!, $size: Int!) {
+  target(ensemblId: $ensemblId) {
+    approvedSymbol
+    knownDrugs(size: $size) {
+      count
+      rows {
+        drug {
+          id
+          name
+          drugType
+          maximumClinicalTrialPhase
+        }
+        disease {
+          id
+          name
+        }
+        phase
+        status
+        mechanismOfAction
+        urls {
+          niceName
+          url
+        }
+      }
+    }
+  }
+}
+```
+
+**Variables:**
+```json
+{
+  "ensemblId": "ENSG00000157764",
+  "size": 10
+}
+```
+
+(ENSG00000157764 = BRAF)
+
+---
+
+### 9. Tractability (druggability)
+
+Included in the target query (see endpoint 1 above). Modalities include:
+- `SM` (small molecule)
+- `AB` (antibody)
+- `PR` (PROTAC)
+- `OC` (other clinical)
+
+---
+
+## REST API Endpoints
+
+These are simpler alternatives for common operations.
+
+### Search
+
+```
+GET /api/v4/search?q={query}&page=0&size=10
+```
+
+**Example:**
+```
+https://api.platform.opentargets.org/api/v4/search?q=TP53&size=5
+```
+
+**Response:**
+```json
+{
+  "total": 15,
+  "data": [
+    {
+      "id": "ENSG00000141510",
+      "entity": "target",
+      "name": "TP53",
+      "description": "Cellular tumor antigen p53",
+      "score": 142.5
+    }
+  ]
+}
+```
+
+---
+
+## Key Identifiers
+
+| Entity  | ID Format | Example |
+|---------|-----------|---------|
+| Target  | Ensembl Gene ID | `ENSG00000141510` (TP53) |
+| Disease | EFO/Mondo/HP/Orphanet | `EFO_0000311` (cancer), `MONDO_0007254` |
+| Drug    | ChEMBL ID | `CHEMBL25` (aspirin) |
+
+## Datasource IDs (for filtering evidence)
+
+- `ot_genetics_portal` -- Open Targets Genetics
+- `eva` -- ClinVar (via EVA)
+- `cancer_gene_census` -- COSMIC Cancer Gene Census
+- `chembl` -- ChEMBL (clinical trials)
+- `europepmc` -- Literature mining
+- `expression_atlas` -- Expression Atlas
+- `gene2phenotype` -- Gene2Phenotype
+- `genomics_england` -- Genomics England PanelApp
+- `intogen` -- IntOGen (cancer drivers)
+- `ot_crispr` -- Open Targets CRISPR screens
+- `progeny` -- PROGENy (pathway activity)
+- `reactome` -- Reactome pathways
+- `slapenrich` -- SLAPenrich
+- `sysbio` -- Systems biology
+- `uniprot_literature` -- UniProt literature
+
+## Pagination
+
+GraphQL uses `page: { index: Int, size: Int }` (0-based index).
+REST uses `page` and `size` query parameters.
+
+## Rate Limits
+
+- No API key required.
+- Fair-use rate limiting applies. No hard published limit.
+- For bulk data, use the Open Targets data downloads (Parquet files on GCS/FTP) rather than API.
+- Respect HTTP 429 and `Retry-After` headers.
+
+## Error Format
+
+GraphQL errors:
+```json
+{
+  "errors": [
+    {
+      "message": "Variable '$ensemblId' expected value of type 'String!' but got: null",
+      "locations": [{"line": 1, "column": 7}]
+    }
+  ]
+}
+```
+
+REST errors return appropriate HTTP status codes with JSON error bodies.
+
+## Tips
+
+- Use the GraphQL API for maximum flexibility -- request only the fields you need.
+- The GET method for GraphQL works for simple queries but POST is required for complex ones with variables.
+- Combine target + disease queries to get association scores with evidence breakdown.
+- Use `datasourceScores` in association queries to see which evidence sources contribute most.
+- The Open Targets Platform web UI at `https://platform.opentargets.org` has a GraphQL playground for testing queries.

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

@@ -0,0 +1,255 @@
+# OpenWeatherMap API Reference
+
+## Base URL
+```
+https://api.openweathermap.org
+```
+
+## Authentication
+- **API Key: REQUIRED.** Register for a free key at https://home.openweathermap.org/users/sign_up
+- Pass as query parameter: `&appid=YOUR_KEY`
+- Free tier key activates within a few hours of registration.
+
+## Rate Limits (Free Tier)
+- **60 calls per minute** (1,000 calls/day for some endpoints).
+- **Current weather, 5-day forecast, geocoding:** Available on free tier.
+- **One Call 3.0:** Requires subscription (1,000 free calls/day with credit card on file).
+- **Historical data, air pollution history:** Requires paid plan for extended ranges.
+
+---
+
+## Key Endpoints
+
+### 1. Current Weather
+```
+GET /data/2.5/weather
+```
+
+**Parameters:**
+| Parameter | Type   | Required | Default  | Description |
+|-----------|--------|----------|----------|-------------|
+| `q`       | string | Cond.    | -        | City name, optionally with state/country: `London`, `London,GB`, `Portland,OR,US`. |
+| `lat`     | float  | Cond.    | -        | Latitude (use with `lon`). |
+| `lon`     | float  | Cond.    | -        | Longitude (use with `lat`). |
+| `id`      | int    | Cond.    | -        | City ID (from OWM city list). |
+| `zip`     | string | Cond.    | -        | Zip/postal code with country: `90210,US`, `SW1,GB`. |
+| `units`   | string | No       | `standard` | `standard` (Kelvin), `metric` (Celsius), `imperial` (Fahrenheit). |
+| `lang`    | string | No       | `en`     | Language code for descriptions. |
+| `appid`   | string | Yes      | -        | API key. |
+
+One location parameter (`q`, `lat`+`lon`, `id`, or `zip`) is required.
+
+**Example:**
+```
+https://api.openweathermap.org/data/2.5/weather?lat=40.7128&lon=-74.0060&units=metric&appid=YOUR_KEY
+```
+
+**Response:**
+```json
+{
+  "coord": {"lon": -74.006, "lat": 40.7128},
+  "weather": [
+    {
+      "id": 800,
+      "main": "Clear",
+      "description": "clear sky",
+      "icon": "01d"
+    }
+  ],
+  "base": "stations",
+  "main": {
+    "temp": 22.5,
+    "feels_like": 21.8,
+    "temp_min": 20.1,
+    "temp_max": 24.3,
+    "pressure": 1013,
+    "humidity": 55,
+    "sea_level": 1013,
+    "grnd_level": 1010
+  },
+  "visibility": 10000,
+  "wind": {"speed": 3.6, "deg": 220, "gust": 5.1},
+  "clouds": {"all": 0},
+  "dt": 1700000000,
+  "sys": {
+    "country": "US",
+    "sunrise": 1699960000,
+    "sunset": 1699996000
+  },
+  "timezone": -18000,
+  "id": 5128581,
+  "name": "New York",
+  "cod": 200
+}
+```
+
+### 2. 5-Day / 3-Hour Forecast (Free)
+```
+GET /data/2.5/forecast
+```
+Returns forecast data in 3-hour intervals for 5 days (40 data points). Same location parameters as current weather.
+
+**Additional Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cnt`     | int  | Number of 3-hour steps to return (max 40). |
+
+**Example:**
+```
+https://api.openweathermap.org/data/2.5/forecast?q=London,GB&units=metric&cnt=8&appid=YOUR_KEY
+```
+
+**Response:**
+```json
+{
+  "cod": "200",
+  "message": 0,
+  "cnt": 8,
+  "list": [
+    {
+      "dt": 1700000000,
+      "main": {
+        "temp": 10.5,
+        "feels_like": 8.2,
+        "temp_min": 9.8,
+        "temp_max": 10.5,
+        "pressure": 1020,
+        "humidity": 80
+      },
+      "weather": [{"id": 802, "main": "Clouds", "description": "scattered clouds", "icon": "03d"}],
+      "clouds": {"all": 40},
+      "wind": {"speed": 4.1, "deg": 250},
+      "visibility": 10000,
+      "pop": 0.2,
+      "dt_txt": "2024-01-15 12:00:00"
+    }
+  ],
+  "city": {
+    "id": 2643743,
+    "name": "London",
+    "coord": {"lat": 51.5085, "lon": -0.1257},
+    "country": "GB",
+    "population": 1000000,
+    "timezone": 0,
+    "sunrise": 1699950000,
+    "sunset": 1699982000
+  }
+}
+```
+`pop` is probability of precipitation (0.0 to 1.0).
+
+### 3. Geocoding
+```
+GET /geo/1.0/direct
+GET /geo/1.0/reverse
+GET /geo/1.0/zip
+```
+
+**Direct geocoding (city name to coordinates):**
+```
+https://api.openweathermap.org/geo/1.0/direct?q=London,GB&limit=5&appid=YOUR_KEY
+```
+Returns array of `{name, lat, lon, country, state}`.
+
+**Reverse geocoding (coordinates to city name):**
+```
+https://api.openweathermap.org/geo/1.0/reverse?lat=51.5085&lon=-0.1257&limit=1&appid=YOUR_KEY
+```
+
+**Zip code geocoding:**
+```
+https://api.openweathermap.org/geo/1.0/zip?zip=90210,US&appid=YOUR_KEY
+```
+
+### 4. One Call API 3.0 (Subscription Required)
+```
+GET /data/3.0/onecall
+```
+Comprehensive endpoint returning current, minutely (1h), hourly (48h), daily (8d), and alerts in one call.
+
+**Parameters:**
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `lat`     | float  | Yes      | Latitude. |
+| `lon`     | float  | Yes      | Longitude. |
+| `exclude` | string | No       | Comma-separated parts to exclude: `current`, `minutely`, `hourly`, `daily`, `alerts`. |
+| `units`   | string | No       | `standard`, `metric`, `imperial`. |
+| `appid`   | string | Yes      | API key. |
+
+**Example:**
+```
+https://api.openweathermap.org/data/3.0/onecall?lat=40.7128&lon=-74.006&exclude=minutely,alerts&units=metric&appid=YOUR_KEY
+```
+
+### 5. Air Pollution
+```
+GET /data/2.5/air_pollution
+GET /data/2.5/air_pollution/forecast
+GET /data/2.5/air_pollution/history
+```
+
+**Parameters:** `lat`, `lon`, `appid` (required). For history: `start` and `end` (Unix timestamps).
+
+**Example:**
+```
+https://api.openweathermap.org/data/2.5/air_pollution?lat=40.7128&lon=-74.006&appid=YOUR_KEY
+```
+
+**Response:**
+```json
+{
+  "coord": {"lon": -74.006, "lat": 40.7128},
+  "list": [
+    {
+      "main": {"aqi": 2},
+      "components": {
+        "co": 230.31,
+        "no": 0.5,
+        "no2": 15.0,
+        "o3": 68.0,
+        "so2": 2.5,
+        "pm2_5": 8.1,
+        "pm10": 12.3,
+        "nh3": 1.0
+      },
+      "dt": 1700000000
+    }
+  ]
+}
+```
+AQI scale: 1=Good, 2=Fair, 3=Moderate, 4=Poor, 5=Very Poor. Components in ug/m3.
+
+---
+
+## Weather Condition Codes
+| Range   | Category |
+|---------|----------|
+| 2xx     | Thunderstorm |
+| 3xx     | Drizzle |
+| 5xx     | Rain |
+| 6xx     | Snow |
+| 7xx     | Atmosphere (fog, mist, haze) |
+| 800     | Clear |
+| 80x     | Clouds |
+
+Weather icons: `https://openweathermap.org/img/wn/{icon}@2x.png`
+
+## Free Tier vs Paid Summary
+| Endpoint | Free | Subscription |
+|----------|------|-------------|
+| Current weather | Yes | Yes |
+| 5-day/3-hour forecast | Yes | Yes |
+| Geocoding | Yes | Yes |
+| Air pollution (current) | Yes | Yes |
+| One Call 3.0 | 1000/day (credit card required) | Yes |
+| Historical weather | No | Yes |
+| Daily forecast 16-day | No | Yes |
+| Climatic forecast 30-day | No | Yes |
+
+## Notes
+- All timestamps (`dt`, `sunrise`, `sunset`) are **Unix epoch seconds (UTC)**.
+- `timezone` field is offset in seconds from UTC (e.g. -18000 = UTC-5).
+- Default temperature unit is Kelvin. Always specify `units=metric` or `units=imperial`.
+- City name queries (`q=`) can be ambiguous. Prefer `lat`+`lon` for precision, using geocoding first if needed.
+- Weather icon URL pattern: `https://openweathermap.org/img/wn/{icon}@2x.png` (e.g. `01d` for clear day).
+- Error responses return `{"cod": 401, "message": "Invalid API key"}` or similar.