Forge Tools cellxgene_expression

cellxgene_expression read

scidex.forge.cellxgene_expression

Query the CellxGene Census (Chan Zuckerberg Initiative) for single-cell RNA-seq expression data via the WMG v2 REST API. Returns per-cell-type and per-tissue expression summaries — mean log(1+CPM), percent detected, cell count — from millions of cells across hundreds of datasets. Complements bulk expression tools (GTEx, GEO, HPA) with single-cell resolution. Supports multi-gene queries batched into a single Census request. Fully public REST API — no authentication required.

HTTP: POST /api/scidex/forge/cellxgene_expression

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.cellxgene_expression``.",
  "properties": {
    "gene_symbols": {
      "description": "HGNC gene symbols to query (e.g. ``['TP53', 'BRCA1']``). All symbols are batched into a single WMG Census query.",
      "items": {
        "type": "string"
      },
      "title": "Gene Symbols",
      "type": "array"
    },
    "cell_types": {
      "description": "Optional cell-type labels to filter by (e.g. ``['T cell', 'hepatocyte']``). Applied client-side after the API response. Empty list returns all cell types.",
      "items": {
        "type": "string"
      },
      "title": "Cell Types",
      "type": "array"
    },
    "tissues": {
      "description": "Optional tissue labels to filter by (e.g. ``['blood', 'liver']``). Applied client-side after the API response. Empty list returns all tissues.",
      "items": {
        "type": "string"
      },
      "title": "Tissues",
      "type": "array"
    },
    "species": {
      "default": "Homo sapiens",
      "description": "Species filter. Default ``'Homo sapiens'``. Use ``'Mus musculus'`` for mouse. Other species raise a ToolError.",
      "maxLength": 128,
      "title": "Species",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of expression records to return across all genes (1–500, default 20).",
      "maximum": 500,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "gene_symbols"
  ],
  "title": "ForgeCellxGeneIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "CellxGeneRecord": {
      "description": "One expression summary record from the CellxGene Census.",
      "properties": {
        "gene_symbol": {
          "description": "HGNC gene symbol queried.",
          "title": "Gene Symbol",
          "type": "string"
        },
        "cell_type": {
          "description": "Cell type label (e.g. ``T cell``, ``hepatocyte``).",
          "title": "Cell Type",
          "type": "string"
        },
        "tissue": {
          "description": "Tissue label (e.g. ``blood``, ``liver``).",
          "title": "Tissue",
          "type": "string"
        },
        "expression_mean": {
          "default": 0,
          "description": "Mean expression (log(1+CPM)) across cells in this group.",
          "title": "Expression Mean",
          "type": "number"
        },
        "expression_pct_detected": {
          "default": 0,
          "description": "Fraction of cells with detectable expression (0.0–1.0).",
          "title": "Expression Pct Detected",
          "type": "number"
        },
        "dataset_count": {
          "default": 0,
          "description": "Number of datasets contributing (not available from WMG v2; always 0).",
          "title": "Dataset Count",
          "type": "integer"
        },
        "cell_count": {
          "default": 0,
          "description": "Total cells in this cell-type/tissue group.",
          "title": "Cell Count",
          "type": "integer"
        }
      },
      "required": [
        "gene_symbol",
        "cell_type",
        "tissue"
      ],
      "title": "CellxGeneRecord",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.cellxgene_expression``.",
  "properties": {
    "expressions": {
      "description": "Expression records, capped at ``limit``.",
      "items": {
        "$ref": "#/$defs/CellxGeneRecord"
      },
      "title": "Expressions",
      "type": "array"
    },
    "total_returned": {
      "default": 0,
      "description": "Length of ``expressions`` (after filtering and limit).",
      "title": "Total Returned",
      "type": "integer"
    },
    "genes_queried": {
      "description": "Echo of the queried gene symbols.",
      "items": {
        "type": "string"
      },
      "title": "Genes Queried",
      "type": "array"
    },
    "took_ms": {
      "description": "Wall-clock time for all upstream API calls.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "took_ms"
  ],
  "title": "ForgeCellxGeneOut",
  "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/cellxgene_expression' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "gene_symbols": []
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.