---
title: "Score"
method: POST
path: "/api/markers/score"
tags: ["markers"]
---

# Score

`POST /api/markers/score`

## Query parameters

- `args` unknown, required
- `kwargs` unknown, required

## Request body

- ScoreClusterIn — Score one cluster's expression signature against the atlas. `cluster_zscores` is `{gene_symbol: cluster_vs_rest_zscore}` — one cluster's differential-expression z-score against all other cells. The recommended client recipe is scanpy's `rank_genes_groups(adata, groupby='leiden', method='wilcoxon')`, keeping only HVGs (~2k-5k genes, ~50 KB JSON). z > 0 = the gene is upregulated in this cluster vs rest; z < 0 = downregulated. Do NOT use "cluster mean of globally z-scored X" — that collapses to ≈ 0 for clusters that dominate the cohort (the cluster's cells ARE the population mean it's z-scored against). Cluster-vs-rest is the right baseline. The server scores each candidate as the L2-normalised inner product of the cluster's z-vector against a signed marker template (+spec for positive markers, -spec for negative markers, spec scoped to tissue + species + optional disease). The full atlas never leaves the server.
  - `cluster_zscores` object, required — Dict of {gene_symbol: cluster_vs_rest_zscore}. Typically the `scores` field of scanpy.tl.rank_genes_groups, restricted to HVGs. Both signs are used by the scorer.
  - `species` string, required
  - `tissue` string, nullable
  - `disease` string, nullable
  - `top_n` integer
  - `include_negative_markers` boolean

## Response `200`

Successful Response

- ScoreResponse
  - `n_genes_supplied` integer, required
  - `species` string, required
  - `tissue` string, nullable, required
  - `disease` string, nullable, required
  - `n_candidate_celltypes_scanned` integer, required
  - `n_rows_scanned` integer, required
  - `candidates` ScoreCandidateOut[], required
    - `rank` integer, required
    - `cell_name` string, required
    - `cl_id` string, nullable
    - `score` number, required
    - `score_raw` number, required
    - `n_positive_total` integer, required
    - `n_negative_total` integer, required
    - `n_positive_seen` integer, required
    - `n_negative_seen` integer, required
    - `template_l2` number, required
    - `top_supporting` MarkerHitOut[], required
      - `gene` string, required
      - `z` number, required
      - `polarity` string, required
      - `spec` number, required
      - `contribution` number, required
      - `n_pmid` integer, required
      - `pmids` string[], required
    - `top_conflicting` MarkerHitOut[], required
      - `gene` string, required
      - `z` number, required
      - `polarity` string, required
      - `spec` number, required
      - `contribution` number, required
      - `n_pmid` integer, required
      - `pmids` string[], required
    - `evidence_pmids` string[], required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/omicos/apis/omicos-server.md) · [All operations](https://skmtc.dev/omicos/apis/omicos-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omicos/omicos-server/revisions/a00b94573ffe/schema)