Forge Tools ensembl_regulatory

ensembl_regulatory read

scidex.forge.ensembl_regulatory

Query the Ensembl Regulatory Build for regulatory features (promoters, enhancers, open chromatin, CTCF binding sites) overlapping a gene or genomic region. Integrates ENCODE, Roadmap Epigenomics, and Blueprint data, pre-mapped to Ensembl gene coordinates. Input: Ensembl gene ID (e.g. ENSG00000012048 for BRCA1) or genomic region (e.g. 17:41196312-41277500), species (default: human), feature_types filter (promoter/enhancer/ctcf/open_chromatin/all), activity filter (active/inactive/any), and limit. Distinct from forge_encode_epigenomics (raw ENCODE experiments) and forge_jaspar_tfbs (TF binding motif PWMs). REST API: https://rest.ensembl.org/ — free, no auth required.

HTTP: POST /api/scidex/forge/ensembl_regulatory

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_regulatory``.",
  "properties": {
    "gene_id": {
      "anyOf": [
        {
          "maxLength": 30,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Ensembl gene ID to query (e.g. ``ENSG00000012048`` for BRCA1). Mutually exclusive with ``region``; exactly one is required.",
      "title": "Gene Id"
    },
    "region": {
      "anyOf": [
        {
          "maxLength": 100,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Genomic region in ``chr:start-end`` format (e.g. ``17:41196312-41277500``). Mutually exclusive with ``gene_id``.",
      "title": "Region"
    },
    "species": {
      "default": "human",
      "description": "Species — common name (``human``, ``mouse``) or Ensembl slug (``homo_sapiens``, ``mus_musculus``). Defaults to ``human``. Required for region queries; ignored for gene_id queries (species is inferred from the Ensembl gene ID).",
      "maxLength": 64,
      "title": "Species",
      "type": "string"
    },
    "feature_types": {
      "description": "List of feature types to include. Supported values: ``all``, ``promoter``, ``enhancer``, ``ctcf``, ``open_chromatin``, ``tf_binding``. ``all`` (default) returns all feature types.",
      "items": {
        "type": "string"
      },
      "title": "Feature Types",
      "type": "array"
    },
    "activity": {
      "default": "active",
      "description": "Activity filter. ``active`` (default) returns features with ACTIVE or unset activity; ``inactive`` returns INACTIVE/POISED/REPRESSED; ``any`` applies no filter.",
      "enum": [
        "active",
        "inactive",
        "any"
      ],
      "title": "Activity",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "description": "Maximum number of regulatory features to return (default 50, max 500).",
      "maximum": 500,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "ForgeEnsemblRegulatoryIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "RegulatoryFeature": {
      "description": "One regulatory feature from the Ensembl Regulatory Build.",
      "properties": {
        "id": {
          "description": "Ensembl Regulatory Build ID (ENSR...).",
          "title": "Id",
          "type": "string"
        },
        "feature_type": {
          "description": "Regulatory feature type: Promoter, Enhancer, CTCF Binding Site, TF Binding Site, Open Chromatin, Promoter Flanking Region.",
          "title": "Feature Type",
          "type": "string"
        },
        "chromosome": {
          "description": "Chromosome / sequence region name.",
          "title": "Chromosome",
          "type": "string"
        },
        "start": {
          "description": "Genomic start coordinate (1-based, inclusive).",
          "title": "Start",
          "type": "integer"
        },
        "end": {
          "description": "Genomic end coordinate (1-based, inclusive).",
          "title": "End",
          "type": "integer"
        },
        "strand": {
          "default": 0,
          "description": "Strand: 1 (forward), -1 (reverse), 0 (unstranded).",
          "title": "Strand",
          "type": "integer"
        },
        "activity": {
          "default": "",
          "description": "Activity state from Ensembl Regulatory Build (e.g. ACTIVE, INACTIVE, POISED, REPRESSED, NA).",
          "title": "Activity",
          "type": "string"
        },
        "cell_type": {
          "default": "",
          "description": "Cell type or tissue context for the activity annotation.",
          "title": "Cell Type",
          "type": "string"
        },
        "description": {
          "default": "",
          "description": "Free-text description when available.",
          "title": "Description",
          "type": "string"
        }
      },
      "required": [
        "id",
        "feature_type",
        "chromosome",
        "start",
        "end"
      ],
      "title": "RegulatoryFeature",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.ensembl_regulatory``.",
  "properties": {
    "query": {
      "description": "The gene ID or region that was queried.",
      "title": "Query",
      "type": "string"
    },
    "species": {
      "description": "Ensembl species slug used for the query.",
      "title": "Species",
      "type": "string"
    },
    "results": {
      "description": "Regulatory features matching the query and filters.",
      "items": {
        "$ref": "#/$defs/RegulatoryFeature"
      },
      "title": "Results",
      "type": "array"
    },
    "total_found": {
      "default": 0,
      "description": "Number of features returned after filtering.",
      "title": "Total Found",
      "type": "integer"
    },
    "not_found": {
      "default": false,
      "description": "True when no features matched the query and filters.",
      "title": "Not Found",
      "type": "boolean"
    },
    "source": {
      "default": "Ensembl Regulatory Build",
      "description": "Data source: 'Ensembl Regulatory Build'.",
      "title": "Source",
      "type": "string"
    },
    "took_ms": {
      "default": 0,
      "description": "Wall-clock time in milliseconds for the upstream call.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "query",
    "species"
  ],
  "title": "ForgeEnsemblRegulatoryOut",
  "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_regulatory' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.