Forge Tools human_cell_atlas

human_cell_atlas read

scidex.forge.human_cell_atlas

Query the Human Cell Atlas (CZ CellxGene Census) for single-cell RNA-seq expression data for a single gene across tissues and cell types. Accepts an HGNC gene symbol or Ensembl ID. Returns per-cell-type and per-tissue expression summaries — mean log(1+CPM), percent expressing, cell count — with optional tissue and cell_type substring filters. Distinguishes from cellxgene_expression (multi-gene dataset search) by targeting the HCA cell-type expression atlas for a single gene. Fully public REST API — no authentication required.

HTTP: POST /api/scidex/forge/human_cell_atlas

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.human_cell_atlas``.",
  "properties": {
    "gene_id": {
      "description": "Gene to query — either an HGNC symbol (e.g. ``TP53``, ``BRCA1``) or a bare Ensembl gene ID (e.g. ``ENSG00000141510``). Case-insensitive for symbol lookup.",
      "maxLength": 64,
      "minLength": 1,
      "title": "Gene Id",
      "type": "string"
    },
    "tissue": {
      "default": "",
      "description": "Optional case-insensitive substring filter applied client-side against the tissue label (e.g. ``blood``, ``liver``). Empty string returns all tissues.",
      "maxLength": 128,
      "title": "Tissue",
      "type": "string"
    },
    "cell_type": {
      "default": "",
      "description": "Optional case-insensitive substring filter applied client-side against the cell type label (e.g. ``T cell``, ``hepatocyte``). Empty string returns all cell types.",
      "maxLength": 128,
      "title": "Cell Type",
      "type": "string"
    },
    "organism": {
      "default": "Homo sapiens",
      "description": "Species to query. Default ``'Homo sapiens'``. Use ``'Mus musculus'`` for mouse. Other species raise a not_found error.",
      "maxLength": 128,
      "title": "Organism",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "description": "Maximum number of expression records to return (1–500, default 50).",
      "maximum": 500,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "gene_id"
  ],
  "title": "HumanCellAtlasIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "HCAExpressionRecord": {
      "description": "One expression summary record from the Human Cell Atlas.",
      "properties": {
        "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"
        },
        "mean_expression": {
          "default": 0,
          "description": "Mean expression (log(1+CPM)) across cells in this group.",
          "title": "Mean Expression",
          "type": "number"
        },
        "pct_expressing": {
          "default": 0,
          "description": "Fraction of cells with detectable expression (0.0–1.0).",
          "title": "Pct Expressing",
          "type": "number"
        },
        "cell_count": {
          "default": 0,
          "description": "Total cells in this cell-type/tissue group.",
          "title": "Cell Count",
          "type": "integer"
        },
        "dataset_id": {
          "default": "",
          "description": "Census snapshot identifier for the release queried. Stable within a Census version.",
          "title": "Dataset Id",
          "type": "string"
        },
        "donor_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Number of unique donors contributing cells. ``None`` — not exposed by the WMG v2 REST API.",
          "title": "Donor Count"
        }
      },
      "required": [
        "cell_type",
        "tissue"
      ],
      "title": "HCAExpressionRecord",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.human_cell_atlas``.",
  "properties": {
    "gene_id": {
      "description": "Echo of the queried gene_id input.",
      "title": "Gene Id",
      "type": "string"
    },
    "ensembl_gene_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Ensembl gene ID the query resolved to. ``None`` when the gene is not in the Census index.",
      "title": "Ensembl Gene Id"
    },
    "organism": {
      "description": "Organism queried.",
      "title": "Organism",
      "type": "string"
    },
    "snapshot_id": {
      "default": "",
      "description": "Census snapshot identifier returned by WMG.",
      "title": "Snapshot Id",
      "type": "string"
    },
    "returned": {
      "description": "Number of records in ``results``.",
      "title": "Returned",
      "type": "integer"
    },
    "results": {
      "items": {
        "$ref": "#/$defs/HCAExpressionRecord"
      },
      "title": "Results",
      "type": "array"
    },
    "took_ms": {
      "description": "Wall-clock time for all upstream API calls.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "gene_id",
    "organism",
    "returned",
    "took_ms"
  ],
  "title": "HumanCellAtlasOut",
  "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/human_cell_atlas' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "gene_id": ""
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.