Forge Tools phewas_catalog

phewas_catalog read

scidex.forge.phewas_catalog

Query the PheWAS Catalog (Vanderbilt BioVU) for cross-phenome variant-phenotype associations. Unlike single-trait GWAS, PheWAS returns ALL phenotypes associated with a variant simultaneously — critical for pleiotropic hypothesis generation. Accepts up to 10 rsIDs. Returns phecode, phenotype, p-value, odds ratio, cases, controls, and 95% CI per association. Up to 5 concurrent requests. rsIDs with no hits return empty associations (not in not_found). Absent rsIDs (HTTP 404) go to not_found. REST API: https://phewascatalog.org — public, no auth required.

HTTP: POST /api/scidex/forge/phewas_catalog

Invoke

Calls scidex.tool.invoke on the substrate with this tool name. Edit the JSON below — it must match the input schema. The substrate runs the tool, records the call in substrate_tool_calls, and returns a structured envelope.

Sign in to invoke this tool. Schema and curl snippet are visible to anyone.

Schemas

Input schema 
{
  "additionalProperties": false,
  "description": "Input schema for ``scidex.forge.phewas_catalog``.",
  "properties": {
    "rsids": {
      "description": "List of dbSNP rsIDs to query (e.g. [\"rs429358\", \"rs7412\"]). Maximum 10 rsIDs per call. Each must start with 'rs' followed by one or more digits (case-insensitive).",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 1,
      "title": "Rsids",
      "type": "array"
    },
    "p_value_threshold": {
      "default": 0.05,
      "description": "Maximum p-value for inclusion. Default 0.05 (nominal significance). Lower to 5e-8 for genome-wide significance or raise to 0.5 for exploratory screens.",
      "exclusiveMinimum": 0,
      "maximum": 1,
      "title": "P Value Threshold",
      "type": "number"
    },
    "top_k": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If set, return only the top K most significant associations (lowest p-value first) per rsID. Default None returns all passing associations.",
      "title": "Top K"
    }
  },
  "required": [
    "rsids"
  ],
  "title": "ForgePheWASIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "PheWASAssociation": {
      "description": "One PheWAS phenotype association for a variant.",
      "properties": {
        "phecode": {
          "description": "PheWAS phenotype code (e.g. '250.2').",
          "title": "Phecode",
          "type": "string"
        },
        "phenotype": {
          "description": "Phenotype name (e.g. 'Type 2 diabetes').",
          "title": "Phenotype",
          "type": "string"
        },
        "p_value": {
          "description": "Association p-value.",
          "title": "P Value",
          "type": "number"
        },
        "odds_ratio": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Odds ratio for the association. None if not reported.",
          "title": "Odds Ratio"
        },
        "cases": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Number of cases in the study. None if not reported.",
          "title": "Cases"
        },
        "controls": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Number of controls in the study. None if not reported.",
          "title": "Controls"
        },
        "confidence_interval_95": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "95% confidence interval formatted as '[lower, upper]' (e.g. '[1.20, 1.80]'). None if not reported.",
          "title": "Confidence Interval 95"
        }
      },
      "required": [
        "phecode",
        "phenotype",
        "p_value"
      ],
      "title": "PheWASAssociation",
      "type": "object"
    },
    "PheWASVariantResult": {
      "description": "PheWAS associations for one rsID.",
      "properties": {
        "rsid": {
          "description": "dbSNP rsID queried (e.g. 'rs429358').",
          "title": "Rsid",
          "type": "string"
        },
        "associations": {
          "description": "PheWAS phenotype associations below p_value_threshold, sorted by p-value ascending. Empty if no associations pass the threshold.",
          "items": {
            "$ref": "#/$defs/PheWASAssociation"
          },
          "title": "Associations",
          "type": "array"
        }
      },
      "required": [
        "rsid"
      ],
      "title": "PheWASVariantResult",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.phewas_catalog``.",
  "properties": {
    "results": {
      "description": "PheWAS results per queried rsID (one entry per found rsID).",
      "items": {
        "$ref": "#/$defs/PheWASVariantResult"
      },
      "title": "Results",
      "type": "array"
    },
    "not_found": {
      "description": "rsIDs not found in the PheWAS Catalog (HTTP 404).",
      "items": {
        "type": "string"
      },
      "title": "Not Found",
      "type": "array"
    },
    "took_ms": {
      "description": "Wall-clock time for all upstream API calls.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "took_ms"
  ],
  "title": "ForgePheWASOut",
  "type": "object"
}

curl snippet

Replace $SCIDEX_JWT with a valid bearer token. Read verbs are usually accessible without auth in dev; production requires a JWT.

curl -sS -X POST '/api/scidex/forge/phewas_catalog' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "rsids": []
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.