Forge Tools ensembl_xref

ensembl_xref read

scidex.forge.ensembl_xref

Resolve a gene symbol to its canonical Ensembl gene id and, optionally, list orthologs across target species. Bridges cross-species KG entities via Ensembl's homology graph.

HTTP: POST /api/scidex/forge/ensembl_xref

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.ensembl_xref``.",
  "properties": {
    "gene_symbol": {
      "description": "Gene symbol to resolve. Human (``BDNF``, ``APOE``) and non-human (``Bdnf``, ``Apoe``) casing both work — Ensembl normalises internally.",
      "maxLength": 30,
      "minLength": 1,
      "title": "Gene Symbol",
      "type": "string"
    },
    "species": {
      "default": "homo_sapiens",
      "description": "Source species Ensembl slug. Defaults to ``homo_sapiens``. Lowercase ``genus_species`` form; subspecies allowed.",
      "maxLength": 64,
      "title": "Species",
      "type": "string"
    },
    "include_orthologs": {
      "default": true,
      "description": "When ``True`` (default), also fetch orthologs across ``target_species``. Set to ``False`` to skip the homology call entirely (saves one round-trip when only the gene id is needed).",
      "title": "Include Orthologs",
      "type": "boolean"
    },
    "target_species": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of target species slugs to constrain the ortholog query. ``None`` means Ensembl returns orthologs across all species. Ignored when ``include_orthologs`` is ``False``.",
      "title": "Target Species"
    }
  },
  "required": [
    "gene_symbol"
  ],
  "title": "EnsemblXrefIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "OrthologRow": {
      "description": "One ortholog row in the response.",
      "properties": {
        "species": {
          "description": "Ensembl species slug for the ortholog.",
          "title": "Species",
          "type": "string"
        },
        "gene_symbol": {
          "description": "Native gene symbol of the ortholog.",
          "title": "Gene Symbol",
          "type": "string"
        },
        "ensembl_gene_id": {
          "description": "Ensembl gene id of the ortholog.",
          "title": "Ensembl Gene Id",
          "type": "string"
        },
        "homology_type": {
          "description": "Ensembl homology type — ``ortholog_one2one``, ``ortholog_one2many``, ``ortholog_many2many``, ``within_species_paralog``, or ``other_paralog``.",
          "title": "Homology Type",
          "type": "string"
        }
      },
      "required": [
        "species",
        "gene_symbol",
        "ensembl_gene_id",
        "homology_type"
      ],
      "title": "OrthologRow",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.ensembl_xref``.",
  "properties": {
    "gene_symbol": {
      "description": "Echo of the queried gene symbol.",
      "title": "Gene Symbol",
      "type": "string"
    },
    "species": {
      "description": "Echo of the queried source species.",
      "title": "Species",
      "type": "string"
    },
    "ensembl_gene_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical Ensembl gene id for the source species. ``None`` when the gene has no Ensembl mapping.",
      "title": "Ensembl Gene Id"
    },
    "ensembl_transcript_ids": {
      "description": "Ensembl transcript ids for the source gene.",
      "items": {
        "type": "string"
      },
      "title": "Ensembl Transcript Ids",
      "type": "array"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Ensembl's free-text gene description, when present.",
      "title": "Description"
    },
    "orthologs": {
      "description": "Orthologs across requested target species. Empty when ``include_orthologs`` is ``False`` or the gene has no ortholog records in Ensembl.",
      "items": {
        "$ref": "#/$defs/OrthologRow"
      },
      "title": "Orthologs",
      "type": "array"
    },
    "returned_orthologs": {
      "default": 0,
      "description": "Length of ``orthologs``.",
      "title": "Returned Orthologs",
      "type": "integer"
    },
    "took_ms": {
      "description": "Wall-clock time for the upstream calls.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "gene_symbol",
    "species",
    "took_ms"
  ],
  "title": "EnsemblXrefResponse",
  "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/ensembl_xref' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "gene_symbol": ""
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.