[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M76EVRKJ9K2WZZQTYS74RFN4":3,"skill-same:01M76EVRKJ9K2WZZQTYS74RFN4":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M76EVRKJ9K2WZZQTYS74RFN4","spatial-mapping-tangram",null,"Tangram (tangram-sc) mapping of scRNA-seq onto spatial transcriptomics (Visium, Slide-seq, MERFISH, Xenium), one skill for every Tangram task: marker training genes, cells\u002Fclusters\u002Fconstrained mode, per-spot cell type proportions, held-out gene validation (training scores, compare_spatial_geneexp, AUC, k-fold CV), imputation of unmeasured or dropout genes (project_genes; gimVI alternative), and Visium deconvolution into segmented nuclei with the tissue image (squidpy watershed, target_count, deconvolve_cell_annotations). Task-specific routes follow the main workflow. For probabilistic spot abundances with uncertainty use spatial-transcriptomics-deconvolution-cell2location.","bg-szy\u002FTOP-SKILLS","bg-szy","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F106576190?v=4","01M73A4E8KPV67SFXRY8XZGNBX","ShuZhiyong","01M73A4E96MQ294MHM74TZBVQD",6,"CC-BY-4.0","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fawesome-skills\u002Fspatial-mapping-tangram\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: \"spatial-mapping-tangram\"\ndescription: \"Tangram (tangram-sc) mapping of scRNA-seq onto spatial transcriptomics (Visium, Slide-seq, MERFISH, Xenium), one skill for every Tangram task: marker training genes, cells\u002Fclusters\u002Fconstrained mode, per-spot cell type proportions, held-out gene validation (training scores, compare_spatial_geneexp, AUC, k-fold CV), imputation of unmeasured or dropout genes (project_genes; gimVI alternative), and Visium deconvolution into segmented nuclei with the tissue image (squidpy watershed, target_count, deconvolve_cell_annotations). Task-specific routes follow the main workflow. For probabilistic spot abundances with uncertainty use spatial-transcriptomics-deconvolution-cell2location.\"\nlicense: \"CC-BY-4.0\"\n---\n\n# Spatial Mapping with Tangram\n\n## Overview\n\nTangram fits a cell-by-spot probability matrix so that the expression of the\nmapped single cells reproduces the spatial expression of shared training\ngenes. Every Tangram task starts from that matrix: per-spot cell type\nproportions, predicted expression of genes the panel did not measure, and,\nwith a histology image, a cell type for every segmented nucleus. The mapping\nalways converges to something, so this skill validates it on genes held out\nof training before any result is reported. The reference must come from the\nsame tissue and state as the section and share informative genes with it.\n\n| Task | Route |\n|---|---|\n| Cell type proportions per spot \u002F labels on single-cell-resolution data | Workflow Steps 1-7 |\n| Predict unmeasured or dropout-affected genes | Steps 1-6, then Route: Gene Imputation |\n| One cell type per segmented nucleus (Visium + full-resolution image) | Route: Nuclei Deconvolution (replaces Step 1, then Steps 2-3, Nucleus 2-4, Step 6) |\n| Deeper quality checks (k-fold CV, cells vs clusters, seed stability) | After Step 6, Route: Advanced Validation |\n\nAll routes are in `## Task Routes` below the Workflow.\n\n## When to Use\n\n- Placing scRNA-seq cell types onto a Visium, Slide-seq, MERFISH or Xenium section\n- Getting per-spot cell type proportions without a histology image\n- Showing the spatial pattern of genes a targeted panel did not measure, or that Visium lost to dropout\n- Labelling every segmented nucleus in a Visium spot when the full-resolution image is available\n- Deciding whether a Tangram mapping is good enough to report, from held-out genes\n- Mapping one reference onto several sections for a consistent comparison\n- Use `spatial-transcriptomics-deconvolution-cell2location` instead when you need posterior uncertainty for spot abundances\n- For label transfer on Xenium\u002FMERFISH as the primary annotation, use `spatial-transcriptomics-cell-type-annotation` (Tangram labels are a second opinion)\n\n## Prerequisites\n\n- **Spatial data**: AnnData with `obsm[\"spatial\"]` (Visium: Step 1 of\n  `spatial-transcriptomics-deconvolution-cell2location`; Xenium: Step 1 of\n  `spatial-transcriptomics-cell-type-annotation`)\n- **Reference**: scRNA-seq with a cell type column, tissue- and state-matched\n  (search\u002Fdownload: Steps 3-4 of `spatial-transcriptomics-cell-type-annotation`,\n  with `GENES = None` and `MAX_PER_TYPE = 300` - markers are ranked over every gene)\n- **Python packages**: `tangram-sc`, `squidpy`, `scanpy`. They are not\n  pre-installed; `tangram-sc` pulls PyTorch, whose Linux wheel brings CUDA\n  libraries (several GB). The first install takes minutes; say so to the user\n  before starting.\n- **Compute**: CPU works. `mode=\"cells\"` holds a reference-cells x spots\n  matrix plus optimiser state (roughly 16 bytes per entry): ~2 GB for 30k cells\n  x 5k spots, but tens of GB for single-cell-resolution sections with 100k+\n  cells. Use `mode=\"clusters\"` or subsample there (Step 4 prints the estimate).\n\n```bash\n# Install only what `import` reports missing. `--pypi` keeps the env's scanpy\u002Fnumba\n# stack; a conda add can swap it and bare pip can shadow it.\npixi add --pypi squidpy scanpy tangram-sc\n```\n\n## Pre-flight Interview\n\n```yaml\ndecisions:\n  - id: D1\n    param: TASK\n    kind: required\n    source: user\n    ask: \"What should the mapping give you: cell type proportions per spot (or labels per cell), predicted expression of genes the panel did not measure, or a cell type for every nucleus seen in the tissue image?\"\n    default: \"cell type proportions\"\n\n  - id: D2\n    param: referenceSource\n    kind: required\n    source: user\n    ask: \"Do you have a scRNA\u002FsnRNA-seq reference from the same tissue and state (h5ad with a cell type column), or should I search public data (CELLxGENE)?\"\n    default: null\n\n  - id: D3\n    param: CELL_TYPE_KEY\n    kind: required\n    source: data\n    depends_on: [D2]\n    ask: \"Which column of the reference holds the cell types to map?\"\n    default: null\n\n  - id: D4\n    param: MODE\n    kind: required\n    source: user\n    depends_on: [D1]\n    ask: \"Do the reference and the spatial section come from the same specimen (or a biological replicate), or from different samples\u002Fstudies?\"\n    default: \"clusters when from different samples or when the Step 4 memory estimate exceeds the sandbox; cells otherwise; constrained for the nucleus task\"\n\n  - id: D5\n    param: density_prior\n    kind: required\n    source: data\n    depends_on: [D1]\n    ask: \"This section looks like \u003Cspot data \u002F single-cell-resolution data>: weight each location by its RNA count, or treat every location as one cell?\"\n    default: \"per-spot total counts on spot data; uniform on single-cell-resolution data; nucleus counts for the nucleus task\"\n\n  - id: D6\n    param: TARGETS\n    kind: required\n    source: user\n    depends_on: [D1]\n    skip_if: \"TASK is not gene imputation\"\n    ask: \"Which genes or gene signatures do you want predicted on the tissue?\"\n    default: null\n\n  - id: D7\n    param: STAIN\n    kind: required\n    source: data\n    depends_on: [D1]\n    skip_if: \"TASK is not the nucleus task\"\n    ask: \"Is the full-resolution image H&E (dark nuclei) or fluorescent DAPI (bright nuclei)?\"\n    default: null\n\n  - id: D8\n    param: N_MARKERS\n    kind: optional\n    source: user\n    ask: \"How many top marker genes per cell type should drive the mapping?\"\n    default: \"100 per type\"\n\n  - id: D9\n    param: num_epochs\n    kind: optional\n    source: user\n    ask: \"How many training epochs?\"\n    default: \"500 (1000 in constrained mode)\"\n\n  - id: D10\n    param: DEVICE\n    kind: never_ask\n    source: data\n    reason: \"Picks CUDA when present, otherwise CPU; changes runtime only\"\n```\n\nAsk D1, D2 and D4 together. D3 and D5 follow from inspecting the files: offer\nthe reference's `obs` columns that look like cell type labels, and state the\nplatform the coordinates suggest. If no column groups the reference cells,\nstop and ask; never map on clusters you computed yourself without saying so.\n\n## Workflow\n\n1. Load spatial data and reference\n2. Normalise and keep the raw-count density prior\n3. Select training genes and run `tg.pp_adatas`\n4. Map cells to space\n5. Project cell type annotations\n6. Validate on training and held-out genes\n7. Plot and save\n\n### Step 1: Load Data\n\nThe demo uses the Tangram tutorial data (mouse cortex Visium + scRNA-seq);\nsquidpy downloads it on first use and caches it.\n\n```python\nimport numpy as np\nimport pandas as pd\nimport scanpy as sc\nimport squidpy as sq\nimport tangram as tg\n\nUSE_DEMO = True\nif USE_DEMO:\n    adata_sp = sq.datasets.visium_fluo_adata_crop()\n    adata_sp = adata_sp[adata_sp.obs[\"cluster\"].isin([f\"Cortex_{i}\" for i in range(1, 5)])].copy()\n    adata_sc = sq.datasets.sc_mouse_cortex()\n    CELL_TYPE_KEY = \"cell_subclass\"\nelse:\n    adata_sp = sc.read_h5ad(\"spatial.h5ad\")      # obsm[\"spatial\"] required\n    adata_sc = sc.read_h5ad(\"reference.h5ad\")\n    CELL_TYPE_KEY = \"cell_type\"                  # D3\n\nprint(adata_sp)\nprint(adata_sc.obs[CELL_TYPE_KEY].value_counts())\nshared = adata_sc.var_names.str.lower().intersection(adata_sp.var_names.str.lower())\nprint(f\"shared genes: {len(shared)}\")\n```\n\nFor the nucleus task use Nucleus 1 (Task Routes) instead of this step.\n\n### Step 2: Normalise, Keep the Density Prior\n\nUse the same normalisation on both sides. `tg.pp_adatas` computes its\n`rna_count_based` prior from `adata_sp.X`, which `normalize_total` flattens, so\ntake the per-spot total from raw counts first.\n\n```python\ndef is_raw_counts(ad):\n    x = ad.X[: min(500, ad.n_obs)]\n    x = x.toarray() if hasattr(x, \"toarray\") else np.asarray(x)\n    return np.allclose(x, np.round(x)) and x.max() > 20\n\nSINGLE_CELL_RESOLUTION = False                   # D5: True for Xenium\u002FMERFISH\u002FCosMx\nif SINGLE_CELL_RESOLUTION:\n    density_prior = np.full(adata_sp.n_obs, 1 \u002F adata_sp.n_obs)\nelse:\n    if \"total_counts\" in adata_sp.obs:\n        totals = adata_sp.obs[\"total_counts\"].to_numpy(dtype=float)\n    else:\n        totals = np.asarray(adata_sp.X.sum(1)).ravel().astype(float)   # raw if X is raw\n    density_prior = totals \u002F totals.sum()\nadata_sp.obs[\"density_prior\"] = density_prior      # reused by validation \u002F re-mapping\n\nfor ad in (adata_sc, adata_sp):\n    if is_raw_counts(ad):\n        ad.layers[\"counts\"] = ad.X.copy()\n        sc.pp.normalize_total(ad)\n        sc.pp.log1p(ad)\n\n# rank_genes_groups needs >= 2 cells per group; tiny types cannot be placed reliably anyway\nkeep = adata_sc.obs[CELL_TYPE_KEY].map(adata_sc.obs[CELL_TYPE_KEY].value_counts()) >= 10\nadata_sc = adata_sc[keep].copy()\nadata_sc.obs[CELL_TYPE_KEY] = adata_sc.obs[CELL_TYPE_KEY].astype(\"category\").cat.remove_unused_categories()\n```\n\n### Step 3: Training Genes\n\nTop markers per cell type, stratified across types (the Tangram authors\nsuggest ~1k unique markers). Genes not used for training stay available as\nheld-out genes for Step 6; with `genes=None` every shared gene trains and\nnothing is left to validate on.\n\n```python\nN_MARKERS = 100                                   # D8\nsc.tl.rank_genes_groups(adata_sc, groupby=CELL_TYPE_KEY, use_raw=False, method=\"wilcoxon\")\nmarkers_df = pd.DataFrame(adata_sc.uns[\"rank_genes_groups\"][\"names\"]).iloc[:N_MARKERS, :]\nmarkers = list(np.unique(markers_df.melt().value.values))\n\ntg.pp_adatas(adata_sc, adata_sp, genes=markers)   # lowercases var_names in both objects\nprint(f\"training genes: {len(adata_sc.uns['training_genes'])}; \"\n      f\"overlap genes: {len(adata_sc.uns['overlap_genes'])}\")\n```\n\nFewer than ~100 training genes makes the mapping unstable; raise `N_MARKERS` or\ncheck gene symbol formats (Ensembl IDs vs symbols, human vs mouse case). From\nhere on, gene names are lowercase. For the nucleus task, continue with\nNucleus 2-4 (Task Routes), then return to Step 6.\n\n### Step 4: Map Cells to Space\n\n`mode=\"cells\"` maps every cell (needed for per-cell placement and the\nconstrained mode); `mode=\"clusters\"` maps cell type averages, is far cheaper,\nand is the safer choice when the reference comes from a different sample.\n\n```python\nimport torch\n\nMODE = \"cells\"                                    # D4: or \"clusters\"\nCLUSTER_LABEL = CELL_TYPE_KEY if MODE == \"clusters\" else None\nDEVICE = \"cuda:0\" if torch.cuda.is_available() else \"cpu\"\n\nn_rows = adata_sc.obs[CELL_TYPE_KEY].nunique() if MODE == \"clusters\" else adata_sc.n_obs\nprint(f\"rough memory for the map + optimiser: {n_rows * adata_sp.n_obs * 16 \u002F 1e9:.1f} GB\")\n\nkwargs = dict(mode=MODE, density_prior=density_prior, num_epochs=500,   # D9\n              device=DEVICE, random_state=0)\nif CLUSTER_LABEL:\n    kwargs[\"cluster_label\"] = CLUSTER_LABEL\n\nad_map = tg.map_cells_to_space(adata_sc, adata_sp, **kwargs)\ntrain_df = ad_map.uns[\"train_genes_df\"]\nprint(ad_map)                                     # cells (or clusters) x spots\nprint(f\"mean training score: {train_df['train_score'].mean():.3f}\")\n```\n\nIf the estimate exceeds ~12 GB on the 16 GB sandbox, switch to `clusters`\nor subsample the reference per cell type before mapping.\n\n### Step 5: Project Cell Type Annotations\n\n`tangram_ct_pred` holds the mapped probability mass per type and spot; divide\nby the row sum for proportions.\n\n```python\ntg.project_cell_annotations(ad_map, adata_sp, annotation=CELL_TYPE_KEY)\nct = adata_sp.obsm[\"tangram_ct_pred\"]\nprop = ct.div(ct.sum(axis=1), axis=0)\nadata_sp.obs[\"tangram_top_type\"] = prop.idxmax(axis=1).astype(\"category\")\nadata_sp.obs[\"tangram_top_frac\"] = prop.max(axis=1)\n\nprint(prop.mean().sort_values(ascending=False).head(10))\nprint(f\"spots where the top type is \u003C 50%: {(adata_sp.obs['tangram_top_frac'] \u003C 0.5).mean():.0%}\")\n```\n\nOn spot data (Visium) report proportions; `tangram_top_type` is a summary, not\nthe identity of the spot.\n\n### Step 6: Validate on Training and Held-out Genes\n\nTraining scores show the fit; only held-out genes show whether the mapping\ngeneralises. Low scores on genes sparse in space (high `sparsity_sp`) are\ndropout; low scores on well-detected genes point to a reference mismatch.\n\n```python\nimport matplotlib.pyplot as plt\n\ntg.plot_training_scores(ad_map, bins=20, alpha=0.5)   # score; vs sc \u002F sp sparsity; vs difference\nplt.savefig(\"tangram_training_scores.png\", dpi=150, bbox_inches=\"tight\")\n\nad_ge = tg.project_genes(ad_map, adata_sc, cluster_label=CLUSTER_LABEL)   # spots x all reference genes\ndf_all = tg.compare_spatial_geneexp(ad_ge, adata_sp, adata_sc)\ndf_all.to_csv(\"tangram_gene_scores.csv\")\ntrain = df_all[df_all[\"is_training\"]]\ntest = df_all[~df_all[\"is_training\"]]\nprint(f\"training genes: {len(train)}, mean score {train['score'].mean():.3f}\")\nprint(f\"held-out genes: {len(test)}, mean score {test['score'].mean():.3f}\")\n```\n\n`tg.eval_metric` fits held-out score against spatial sparsity; its AUC is the\nmain quality number. Plot from its coordinates (`tg.plot_auc` calls seaborn\nwith positional arguments, which recent seaborn rejects):\n\n```python\nmetrics, ((pol_xs, pol_ys), (xs, ys)) = tg.eval_metric(df_all)\nprint({k: round(float(v), 3) for k, v in metrics.items()})\nfig, ax = plt.subplots(figsize=(5, 4))\nax.scatter(xs, ys, s=8, alpha=0.5); ax.plot(pol_xs, pol_ys, c=\"r\")\nax.set(xlim=(0, 1), ylim=(0, 1), xlabel=\"score (held-out genes)\", ylabel=\"spatial sparsity\",\n       title=f\"AUC = {metrics['auc_score']:.3f}\")\nplt.savefig(\"tangram_auc.png\", dpi=150, bbox_inches=\"tight\")\n```\n\nEach projected cell type should also follow a held-out marker the training\ncould not have forced:\n\n```python\nchecks = {\"Oligo\": \"mobp\", \"Astro\": \"aqp4\"}       # cell type -> lowercase marker; fill for the tissue\ntraining = set(adata_sp.uns[\"training_genes\"])\nfor t, g in checks.items():\n    if t in prop and g in adata_sp.var_names:\n        x = adata_sp[:, g].X\n        x = np.asarray(x.todense()).ravel() if hasattr(x, \"todense\") else np.asarray(x).ravel()\n        tag = \"training\" if g in training else \"held-out\"\n        print(f\"{t} vs {g} ({tag}): r = {np.corrcoef(prop[t], x)[0, 1]:.2f}\")\n```\n\n| Number | Good | Usable with care | Poor - do not report as a finding |\n|---|---|---|---|\n| Mean training score | > 0.7 | 0.5-0.7 | \u003C 0.5 |\n| Held-out AUC | > 0.6 | 0.4-0.6 | \u003C 0.4 |\n| Held-out marker r | clearly positive | weak | ~0 or negative |\n\nA large train-test gap means the mapping memorised the markers: broaden the\nmarker set, use `mode=\"clusters\"`, or set `lambda_r` > 0. Report these numbers\nnext to every map or imputed gene.\n\n### Step 7: Plot and Save\n\n```python\nxy = adata_sp.obsm[\"spatial\"]\ntop = prop.mean().nlargest(6).index\nfig, axes = plt.subplots(2, 3, figsize=(15, 10))\nfor ax, t in zip(axes.flat, top):\n    s = ax.scatter(xy[:, 0], xy[:, 1], c=prop[t], s=12, cmap=\"viridis\", vmin=0)\n    ax.set_title(t); ax.invert_yaxis(); ax.set_aspect(\"equal\"); ax.axis(\"off\")\n    fig.colorbar(s, ax=ax, shrink=0.6)\nplt.tight_layout(); plt.savefig(\"tangram_celltype_maps.png\", dpi=150)\n\nprop.to_csv(\"tangram_celltype_proportions.csv\")\nad_map.write_h5ad(\"tangram_mapping.h5ad\", compression=\"gzip\")\nadata_sc.write_h5ad(\"tangram_sc_prep.h5ad\", compression=\"gzip\")\nadata_sp.write_h5ad(\"tangram_spatial.h5ad\", compression=\"gzip\")\n```\n\nCheck each map against biology the user expects (for the demo: L2\u002F3 IT\nneurons in the upper cortical layers, L6 types deep). The three h5ad files let\nthe reference routes resume without re-mapping.\n\n## Task Routes\n\nEach route continues the Workflow session (same variable names). Only the calls\nthat differ from the Workflow, or that fail silently when written another way,\nare shown; plotting and saving follow Step 7.\n\n### Route: Gene Imputation (Tangram, gimVI)\n\nPredicts genes the panel did not measure, or measured with heavy dropout, by\nprojecting reference expression through the mapping. A projected gene reflects\nwhere the mapped cells sit, not a new measurement: report every imputed map as\na prediction, next to the held-out score from Step 6. Start after Step 6\n(`ad_ge`, `df_all`), mapped with a marker subset so held-out genes exist.\n\n1. **Targets (D6)**: lowercase names (after `pp_adatas`); a gene absent or\n   near-zero in the reference cannot be imputed. Genes dense in the reference\n   but sparse in space (dropout) gain the most.\n2. **Trust table**: there is no ground truth for unmeasured genes; the held-out\n   score is the proxy, and a gene expressed in \u003C ~5% of reference cells gives a\n   noisy map.\n3. **Plot measured vs projected**: `tg.plot_genes_sc(genes, adata_measured=adata_sp,\n   adata_predicted=ad_ge, perc=0.02)` needs `uns[\"spatial\"]`; otherwise scatter on\n   `obsm[\"spatial\"]` copied below.\n4. **Store** predictions in `obsm`, never in `X`, so later steps cannot mistake\n   them for counts.\n\n```python\nTARGETS = [\"foxp3\", \"cd8a\", \"gfap\", \"mbp\"]                      # D6\nin_sc = [g for g in TARGETS if g in adata_sc.var_names]\nad_ge.obsm[\"spatial\"] = adata_sp[ad_ge.obs_names].obsm[\"spatial\"]\n\ndetect_sc = pd.Series(np.asarray((adata_sc.X > 0).mean(0)).ravel(), index=adata_sc.var_names)\ntrust = pd.DataFrame({\n    \"measured_in_spatial\": [g in adata_sp.var_names for g in in_sc],\n    \"heldout_score\": [df_all[\"score\"].get(g, np.nan) for g in in_sc],\n    \"frac_cells_expressing_sc\": [detect_sc[g] for g in in_sc],\n}, index=in_sc)\ntrust.to_csv(\"imputation_trust.csv\")\nprint(f\"held-out median score: {df_all.loc[~df_all['is_training'], 'score'].median():.3f}\")\n\nkeep = [g for g in in_sc if g not in adata_sp.var_names]       # imputed-only genes\nx = ad_ge[:, keep].X\nadata_sp.obsm[\"imputed_tangram\"] = pd.DataFrame(x.toarray() if hasattr(x, \"toarray\") else x,\n                                                index=ad_ge.obs_names, columns=keep)\nad_ge.write_h5ad(\"tangram_projected_genes.h5ad\", compression=\"gzip\")\n```\n\n- **Signature score**: `sc.tl.score_genes(ad_ge, genes, score_name=\"signature_score\")`\n  on the projected genes; it marks where cells expressing the signature in the\n  reference were placed.\n- **Spatially structured imputed genes**: `sq.gr.spatial_neighbors(ad_ge, coord_type=\"generic\")`\n  then `sq.gr.spatial_autocorr(ad_ge, mode=\"moran\", genes=unmeasured)`. High\n  Moran's I often mirrors the layout of the expressing cell type; check that\n  before calling it a finding.\n\n**gimVI (count-based second opinion, targeted panels)**: install\n`pixi add --pypi \"scvi-tools\u003C1.6\"` (gimVI leaves scvi-tools in v1.6). Both\nobjects need raw counts, and the spatial genes must be a subset of the reference\ngenes. Hold out ~1\u002F5 of the panel genes, train on the rest, and report the\nheld-out Spearman correlation before trusting the imputed genes.\n\n```python\nfrom scvi.external import GIMVI\n\nGIMVI.setup_anndata(seq)                       # reference counts, all genes\nGIMVI.setup_anndata(st_train)                  # spatial counts without the held-out genes\nmodel = GIMVI(seq, st_train)\nmodel.train(max_epochs=200)\n_, imputed = model.get_imputed_values(normalized=True)   # spatial cells x reference genes\n```\n\n### Route: Nuclei Deconvolution with Histology (constrained mode)\n\nCounts nuclei per Visium spot from the image, then asks Tangram\n(`mode=\"constrained\"`) to select exactly that many reference cells, so every\nsegmented nucleus gets a cell type. Segmentation quality bounds the result.\nNeeds the Space Ranger folder and the **full-resolution** image given to Space\nRanger (`tissue_hires_image.png` is too small to segment). Without it use\n`spatial-transcriptomics-deconvolution-cell2location`.\n\nOrder: Nucleus 1 replaces Step 1, then Steps 2-3, Nucleus 2-4, and Step 6 on\nthe constrained map (`CLUSTER_LABEL = None`).\n\n#### Nucleus 1: Load Data and Image\n\n```python\nVISIUM_DIR = \"path\u002Fto\u002Fspaceranger_outs\"\nadata_sp = sq.read.visium(VISIUM_DIR)                     # obsm[\"spatial\"] in full-res pixels\nadata_sp.var_names_make_unique()\nlibrary_id = list(adata_sp.uns[\"spatial\"])[0]\nimg = sq.im.ImageContainer(\"path\u002Fto\u002Ffullres_image.tif\", layer=\"image\", library_id=library_id)\nadata_sc = sc.read_h5ad(\"reference.h5ad\")\nCELL_TYPE_KEY, STAIN = \"cell_type\", \"he\"                  # D7: \"he\" or \"fluorescent\"\n# count_cell_annotations indexes obs[annotation][k] positionally; newer pandas rejects integer keys\nadata_sc.obs_names = [str(i) for i in range(adata_sc.n_obs)]\n```\n\nDemo: `sq.datasets.visium_fluo_adata_crop()`, `sq.datasets.visium_fluo_image_crop()`\n(DAPI in channel 0, `STAIN = \"fluorescent\"`) and `sq.datasets.sc_mouse_cortex()`.\n\n#### Nucleus 2: Segment and Count Nuclei\n\nFluorescent nuclei are bright; H&E nuclei are dark (`geq=False`). Tangram reads\n`obsm[\"image_features\"]`, not squidpy's default `img_features`.\n\n```python\nif STAIN == \"fluorescent\":\n    sq.im.process(img, layer=\"image\", method=\"smooth\")\n    sq.im.segment(img, layer=\"image_smooth\", method=\"watershed\", channel=0)\nelse:\n    sq.im.process(img, layer=\"image\", method=\"gray\")\n    sq.im.process(img, layer=\"image_gray\", method=\"smooth\")\n    sq.im.segment(img, layer=\"image_gray_smooth\", method=\"watershed\", channel=0, geq=False)\n\nsq.im.calculate_image_features(\n    adata_sp, img, layer=\"image\", features=\"segmentation\", key_added=\"image_features\",\n    features_kwargs={\"segmentation\": {\"label_layer\": \"segmented_watershed\", \"props\": [\"label\", \"centroid\"]}},\n    mask_circle=True)\nadata_sp.obs[\"cell_count\"] = adata_sp.obsm[\"image_features\"][\"segmentation_label\"]\nprint(adata_sp.obs[\"cell_count\"].describe(), (adata_sp.obs[\"cell_count\"] == 0).sum())\n```\n\nInspect a crop of `img[\"image\"]` next to `img[\"segmented_watershed\"]` before\ngoing on. Merged clumps or fragments: pass `thresh=` to `sq.im.segment` or\nchange `sigma=` in `sq.im.process`. Visium spots usually hold ~1-10 nuclei in\nbrain, more in dense tissue; many zero-count spots inside tissue mean failed\nsegmentation.\n\n#### Nucleus 3: Constrained Mapping\n\nThe nucleus counts replace the Step 2 density prior; `target_count` is the total\nnumber of nuclei, and `obs[\"F_out\"]` is each reference cell's selection\nprobability. The reference needs more cells than `target_count`.\n\n```python\ncounts = adata_sp.obs[\"cell_count\"].to_numpy(dtype=float)\nad_map = tg.map_cells_to_space(adata_sc, adata_sp, mode=\"constrained\",\n                               target_count=int(counts.sum()), density_prior=counts \u002F counts.sum(),\n                               num_epochs=1000, device=DEVICE, random_state=0)\nprint(f\"selected (F_out > 0.5): {(ad_map.obs['F_out'] > 0.5).sum()} of {int(counts.sum())}\")\n```\n\n#### Nucleus 4: One Cell Type per Nucleus\n\n`tg.project_cell_annotations` in tangram-sc 1.0.4 ignores `F_out`, so build the\nper-spot prediction from selected cells only; `count_cell_annotations` already\napplies the filter.\n\n```python\nsel = (ad_map.obs[\"F_out\"] > 0.5).to_numpy()\nonehot = pd.get_dummies(ad_map.obs.loc[sel, CELL_TYPE_KEY]).astype(float)\nadata_sp.obsm[\"tangram_ct_pred\"] = pd.DataFrame(ad_map.X[sel].T @ onehot.to_numpy(),\n                                                index=ad_map.var_names, columns=onehot.columns)\ntg.create_segment_cell_df(adata_sp)\ntg.count_cell_annotations(ad_map, adata_sc, adata_sp, annotation=CELL_TYPE_KEY)\nadata_segment = tg.deconvolve_cell_annotations(adata_sp)        # one row per nucleus, obs[\"cluster\"]\nadata_segment.obsm[\"spatial\"] = adata_segment.obs[[\"x\", \"y\"]].to_numpy(float)\nadata_sp.obsm[\"tangram_ct_count\"].drop(columns=[\"centroids\"]).to_csv(\"tangram_ct_count_per_spot.csv\")\nadata_segment.obs[[\"x\", \"y\", \"cluster\"]].to_csv(\"tangram_segment_celltypes.csv\")\n```\n\nNucleus and spot coordinate ranges must overlap; if they look swapped, swap the\ncolumns of `adata_segment.obsm[\"spatial\"]`. Per-spot counts can be compared with\ncell2location by correlating proportions per type over shared spots; large\ndisagreements usually trace back to segmentation. The per-nucleus table works\nlike single-cell-resolution data for `sq.gr.nhood_enrichment(adata_segment,\ncluster_key=\"cluster\")`, but carries labels, not its own expression.\n\n### Route: Advanced Validation (k-fold CV, mode, seeds)\n\nRun after Step 6 when its numbers are borderline, when choosing a mode, or\nbefore a result goes into a report. Each check re-maps; on CPU use `clusters`\nmode and fewer epochs, and report the settings. `PRIOR =\nadata_sp.obs[\"density_prior\"].to_numpy()` (saved in Step 2).\n\n- **k-fold gene CV**: withhold each fold of training genes through\n  `cv_train_genes` and score the withheld fold. `tg.cross_val` calls `np.float`\n  (removed in NumPy >= 1.24) and defaults to `device=\"cuda:0\"`; use the loop.\n- **Cells vs clusters**: compare held-out score and AUC (`tg.eval_metric(d)[0][\"auc_score\"]`),\n  never training scores, which always favour `cells`.\n- **Seed stability**: re-map with seeds 0-2, project annotations, correlate each\n  type's proportions between runs; r \u003C ~0.8 means that type's map is not stable.\n- **Genes the reference explains badly**: held-out genes with `sparsity_sp \u003C 0.5`\n  and `score \u003C 0.3` are not dropout; tumour, stress or tissue-specific genes among\n  them point to a reference from the wrong state or tissue.\n\n```python\nK, EPOCHS = 5, 300\ngenes = np.array(adata_sc.uns[\"training_genes\"])\nfolds = np.array_split(np.random.default_rng(0).permutation(genes), K)\nrows = []\nfor i, held in enumerate(folds):\n    m = tg.map_cells_to_space(adata_sc, adata_sp, cv_train_genes=[g for g in genes if g not in set(held)],\n                              mode=\"clusters\", cluster_label=CELL_TYPE_KEY, density_prior=PRIOR,\n                              num_epochs=EPOCHS, device=DEVICE, random_state=0, verbose=False)\n    ge = tg.project_genes(m, adata_sc, cluster_label=CELL_TYPE_KEY)\n    rows.append({\"fold\": i, \"test_score\": tg.compare_spatial_geneexp(ge, adata_sp, genes=list(held))[\"score\"].mean()})\ncv = pd.DataFrame(rows); cv.to_csv(\"tangram_cv.csv\", index=False)\nprint(cv[\"test_score\"].mean())\n```\n\n## Key Parameters\n\n| Parameter | Default | Effect |\n|---|---|---|\n| Reference choice | from the user | Same tissue and state; the most consequential choice |\n| `N_MARKERS` | 100 per type | Training gene count; more genes = more constraint, but noisy genes hurt |\n| `mode` | `\"cells\"` | `\"clusters\"` is faster and smoother, cannot give per-cell placement; `\"constrained\"` selects `target_count` cells |\n| `num_epochs` | 500 | 500-1000; check the score has plateaued in `training_history` |\n| `density_prior` | raw-count based | `\"uniform\"` on single-cell-resolution data; array must sum to 1 |\n| `lambda_r` | 0 | Entropy regulariser; > 0 makes each cell's placement more peaked |\n| AUC threshold | > 0.6 good \u002F \u003C 0.4 poor | Generalisation to held-out genes (Step 6) |\n| `TARGETS` | from the user (D6) | Genes to impute; must be expressed in the reference |\n| `cluster_label` (`project_genes`) | same as mapping | Mismatch raises an obs-index error |\n| Held-out fraction (gimVI) | 1\u002F5 of panel | Genes withheld to score imputation |\n| `max_epochs` (gimVI) | 200 | Lower for a quick CPU run; report it |\n| `normalized` (gimVI) | True | Compare against library-size-normalised counts |\n| `STAIN` \u002F `geq` | from the image (D7) | Bright (fluorescent) vs dark (H&E) nuclei |\n| `thresh` (`sq.im.segment`) | Otsu | Nucleus threshold; drives every count |\n| `mask_circle` | True | Count only nuclei inside the round spot |\n| `F_out` threshold | 0.5 | Probability for a reference cell to count as selected |\n| `K` (CV folds) | 5 | More folds = smaller held-out sets, more runs |\n| `EPOCHS` (CV) | 300 | Shorter than the main run to save time; report it |\n| Seeds | 0, 1, 2 | Number of re-mappings for the stability check |\n| Seed stability cutoff | r ~0.8 | Below it, the type's map is not stable |\n| Poorly explained gene filter | `sparsity_sp \u003C 0.5`, score \u003C 0.3 | Separates reference mismatch from dropout |\n\n## Common Recipes\n\n### Recipe: One Reference, Several Sections\n\nMap each section separately with the same training genes, then compare mean\ncompositions. `clusters` mode keeps it fast:\n\n```python\nsections = {\"S1\": \"s1.h5ad\", \"S2\": \"s2.h5ad\"}\nprops = {}\nfor name, path in sections.items():\n    sp = sc.read_h5ad(path)\n    totals = np.asarray(sp.X.sum(1)).ravel().astype(float)       # raw counts before normalising\n    if is_raw_counts(sp):\n        sc.pp.normalize_total(sp); sc.pp.log1p(sp)\n    ref = adata_sc.copy()\n    tg.pp_adatas(ref, sp, genes=list(adata_sc.uns[\"training_genes\"]))\n    m = tg.map_cells_to_space(ref, sp, mode=\"clusters\", cluster_label=CELL_TYPE_KEY,\n                              density_prior=totals \u002F totals.sum(), num_epochs=500, device=DEVICE, random_state=0)\n    tg.project_cell_annotations(m, sp, annotation=CELL_TYPE_KEY)\n    ct_s = sp.obsm[\"tangram_ct_pred\"]\n    props[name] = ct_s.div(ct_s.sum(axis=1), axis=0)\nsummary = pd.DataFrame({k: v.mean() for k, v in props.items()}).round(3)\nsummary.to_csv(\"tangram_composition_by_section.csv\")\nprint(summary)\n```\n\n### Recipe: Label Cells on Single-Cell-Resolution Data\n\nOn Xenium or MERFISH each spatial observation is one cell, so the top\nprojected type is a per-cell label. Compare it with an existing annotation\nrather than replacing it:\n\n```python\nadata_sp.obs[\"tangram_label\"] = prop.idxmax(axis=1).astype(\"category\")\nadata_sp.obs[\"tangram_conf\"] = prop.max(axis=1)\nif \"cell_type\" in adata_sp.obs:\n    agree = pd.crosstab(adata_sp.obs[\"cell_type\"], adata_sp.obs[\"tangram_label\"], normalize=\"index\")\n    agree.round(2).to_csv(\"tangram_vs_annotation.csv\")\n    print(agree.max(axis=1).round(2).sort_values())      # low values = the two methods disagree\n```\n\n### Recipe: Where Each Reference Cell Lands\n\nIn `cells` mode, each reference cell's expected position and how sharply it\nis placed (low entropy = one clear location):\n\n```python\nP = np.asarray(ad_map.X, dtype=float)\nP = P \u002F P.sum(axis=1, keepdims=True)                      # cells x spots, rows sum to 1\nadata_sc.obsm[\"tangram_xy\"] = P @ adata_sp.obsm[\"spatial\"]\nadata_sc.obs[\"placement_entropy\"] = -(P * np.log(P + 1e-12)).sum(axis=1)\nprint(adata_sc.obs.groupby(CELL_TYPE_KEY, observed=True)[\"placement_entropy\"].median()\n      .sort_values().round(2))\n```\n\nTypes with high entropy are spread evenly and their spatial pattern carries\nlittle information.\n\n### Recipe: One-Row Quality Summary for the Report\n\n```python\nsummary = pd.DataFrame([{\n    \"mode\": MODE,\n    \"n_training_genes\": int(df_all[\"is_training\"].sum()),\n    \"n_heldout_genes\": int((~df_all[\"is_training\"]).sum()),\n    \"mean_train_score\": round(train[\"score\"].mean(), 3),\n    \"mean_heldout_score\": round(test[\"score\"].mean(), 3),\n    \"auc_heldout\": round(float(metrics[\"auc_score\"]), 3),\n}])\nsummary[\"verdict\"] = np.where(summary[\"auc_heldout\"] > 0.6, \"good\",\n                              np.where(summary[\"auc_heldout\"] >= 0.4, \"moderate\", \"poor\"))\nsummary.to_csv(\"tangram_validation_summary.csv\", index=False)\nprint(summary.T)\n```\n\n## Expected Outputs\n\n- `tangram_mapping.h5ad` - cell (or cluster) x spot probability matrix; `uns[\"train_genes_df\"]`\n- `tangram_sc_prep.h5ad`, `tangram_spatial.h5ad` - preprocessed inputs; spatial has `obs[\"density_prior\"]`, `obsm[\"tangram_ct_pred\"]`, `obs[\"tangram_top_type\"]`\n- `tangram_celltype_proportions.csv`, `tangram_celltype_maps.png` - per-spot proportions and maps\n- `tangram_training_scores.png`, `tangram_gene_scores.csv`, `tangram_auc.png` - validation (Step 6)\n- `tangram_validation_summary.csv` - one-row summary with a verdict (recipe)\n- Gene Imputation: `tangram_projected_genes.h5ad` (spots x reference genes), `imputation_trust.csv`, imputed-only genes in `adata_sp.obsm[\"imputed_tangram\"]`\n- Nuclei Deconvolution: `tangram_ct_count_per_spot.csv` (cell type counts per spot), `tangram_segment_celltypes.csv` (every nucleus with coordinates and type)\n- Advanced Validation: `tangram_cv.csv` (per-fold held-out scores)\n\n## Troubleshooting\n\n| Problem | Cause | Fix |\n|---|---|---|\n| `AssertionError` on `training_genes` \u002F `overlap_genes` | `pp_adatas` not run on these exact objects | Re-run Step 3 right before mapping; load the saved `tangram_*.h5ad`, not the raw files |\n| Very few training genes | Symbol mismatch (Ensembl IDs, species) | Map IDs to symbols; `pp_adatas` already lowercases |\n| CUDA\u002FCPU out of memory, or very slow | Too many cells in `mode=\"cells\"` | Subsample the reference per type, or use `mode=\"clusters\"` |\n| One type dominates every spot | Reference lacks the tissue's major types or wrong state | Choose a better-matched reference |\n| `ValueError: A cluster_label must be specified` | `mode=\"clusters\"` without label | Pass `cluster_label=CELL_TYPE_KEY` |\n| `The two AnnDatas need to have same obs index` | Clusters-mode map projected without `cluster_label` | Pass `cluster_label=CLUSTER_LABEL` to `project_genes` |\n| `Invalid input for density_prior` | List instead of array, or does not sum to 1 | Pass a numpy array normalised to sum 1 |\n| No held-out genes \u002F `eval_metric` fails | `pp_adatas(genes=None)` used all genes | Re-run Step 3 with a marker subset |\n| `TypeError` in `tg.plot_auc` | seaborn >= 0.12 positional args | Plot from `eval_metric` coordinates (Step 6) |\n| Gene names lowercase afterwards | `pp_adatas` default `gene_to_lowercase=True` | Expected; use lowercase names downstream |\n| Target gene missing | Not in reference, or uppercase name | Use lowercase names; pick a reference that measures it |\n| `sc.pl.spatial` fails on projected data | Projected AnnData lacks `uns[\"spatial\"]` | Scatter on `obsm[\"spatial\"]` (Gene Imputation route) |\n| Projected map mirrors one cell type's layout | Gene restricted to that type in the reference | Expected; state it, it is not independent evidence |\n| `spatial genes needs to be subset of seq genes` | Panel genes absent from the reference, or case differs | Harmonise symbols; drop panel genes the reference lacks |\n| gimVI `ImportError`\u002F`AttributeError` | gimVI moved out of scvi-tools | `pixi add --pypi \"scvi-tools\u003C1.6\"` |\n| `Missing parameter ... Run sqidpy.im.calculate_image_features` | Features stored under `img_features` | Pass `key_added=\"image_features\"` (Nucleus 2) |\n| `KeyError: 'tangram_ct_pred'` in `deconvolve_cell_annotations` | Annotation not projected | Run the `tangram_ct_pred` block of Nucleus 4 first |\n| Almost all spots have 0 nuclei | Low-res image, or wrong polarity | Use the full-res image; switch `geq` \u002F stain branch |\n| Counts far too high | Over-segmentation of texture | Raise `thresh` or smoothing `sigma` |\n| `ValueError` about `target_count` | Missing or zero count | Check `cell_count` sum > 0 |\n| `KeyError` \u002F `FutureWarning` on integer key in `count_cell_annotations` | Non-string reference `obs_names` | String `obs_names` (Nucleus 1) before `pp_adatas` |\n| Image and spots misaligned | Image is not the one Space Ranger used, or wrong scale | Use the Space Ranger input image at full resolution |\n\n## Bundled Resources\n\nMerged from four former Tangram skills: `spatial-mapping-tangram` (Steps 1-5, 7,\nrecipes), `spatial-mapping-validation` (Step 6, summary recipe, Route: Advanced\nValidation), `scrna-spatial-gene-imputation` (Route: Gene Imputation) and\n`spatial-transcriptomics-deconvolution-tangram` (Route: Nuclei Deconvolution).\nDuplicated loading, normalisation and `pp_adatas` code was kept once (Steps 1-3).\n\n## Related Skills\n\n- `spatial-transcriptomics-deconvolution-cell2location` - probabilistic spot deconvolution alternative\n- `spatial-transcriptomics-cell-type-annotation` - reference search\u002Fdownload; labels for single-cell-resolution data\n- `spatial-panel-design` - choose panel genes so imputation is less needed\n- `spatial-transcriptomics-analysis-squidpy` - squidpy image and neighbourhood analysis\n- `spatial-transcriptomics-cell-cell-communication` - interactions between the mapped types\n\n## References\n\n- Biancalani et al. (2021) Tangram, Nature Methods: https:\u002F\u002Fdoi.org\u002F10.1038\u002Fs41592-021-01264-7\n- Tangram source and tutorials: https:\u002F\u002Fgithub.com\u002Fbroadinstitute\u002FTangram\n- Tangram documentation: https:\u002F\u002Ftangram-sc.readthedocs.io\u002F\n- squidpy + Tangram tutorial (demo data used here): https:\u002F\u002Fsquidpy.readthedocs.io\u002Fen\u002Fstable\u002Fnotebooks\u002Ftutorials\u002Ftutorial_tangram.html\n","# Spatial Mapping with Tangram\n\n## Overview\n\nTangram fits a cell-by-spot probability matrix so that the expression of the\nmapped single cells reproduces the spatial expression of shared training\ngenes. Every Tangram task starts from that matrix: per-spot cell type\nproportions, predicted expression of genes the panel did not measure, and,\nwith a histology image, a cell type for every segmented nucleus. The mapping\nalways converges to something, so this skill validates it on genes held out\nof training before any result is reported. The reference must come from the\nsame tissue and state as the section and share informative genes with it.\n\n| Task | Route |\n|---|---|\n| Cell type proportions per spot \u002F labels on single-cell-resolution data | Workflow Steps 1-7 |\n| Predict unmeasured or dropout-affected genes | Steps 1-6, then Route: Gene Imputation |\n| One cell type per segmented nucleus (Visium + full-resolution image) | Route: Nuclei Deconvolution (replaces Step 1, then Steps 2-3, Nucleus 2-4, Step 6) |\n| Deeper quality checks (k-fold CV, cells vs clusters, seed stability) | After Step 6, Route: Advanced Validation |\n\nAll routes are in `## Task Routes` below the Workflow.\n\n## When to Use\n\n- Placing scRNA-seq cell types onto a Visium, Slide-seq, MERFISH or Xenium section\n- Getting per-spot cell type proportions without a histology image\n- Showing the spatial pattern of genes a targeted panel did not measure, or that Visium lost to dropout\n- Labelling every segmented nucleus in a Visium spot when the full-resolution image is available\n- Deciding whether a Tangram mapping is good enough to report, from held-out genes\n- Mapping one reference onto several sections for a consistent comparison\n- Use `spatial-transcriptomics-deconvolution-cell2location` instead when you need posterior uncertainty for spot abundances\n- For label transfer on Xenium\u002FMERFISH as the primary annotation, use `spatial-transcriptomics-cell-type-annotation` (Tangram labels are a second opinion)\n\n## Prerequisites\n\n- **Spatial data**: AnnData with `obsm[\"spatial\"]` (Visium: Step 1 of\n  `spatial-transcriptomics-deconvolution-cell2location`; Xenium: Step 1 of\n  `spatial-transcriptomics-cell-type-annotation`)\n- **Reference**: scRNA-seq with a cell type column, tissue- and state-matched\n  (search\u002Fdownload: Steps 3-4 of `spatial-transcriptomics-cell-type-annotation`,\n  with `GENES = None` and `MAX_PER_TYPE = 300` - markers are ranked over every gene)\n- **Python packages**: `tangram-sc`, `squidpy`, `scanpy`. They are not\n  pre-installed; `tangram-sc` pulls PyTorch, whose Linux wheel brings CUDA\n  libraries (several GB). The first install takes minutes; say so to the user\n  before starting.\n- **Compute**: CPU works. `mode=\"cells\"` holds a reference-cells x spots\n  matrix plus optimiser state (roughly 16 bytes per entry): ~2 GB for 30k cells\n  x 5k spots, but tens of GB for single-cell-resolution sections with 100k+\n  cells. Use `mode=\"clusters\"` or subsample there (Step 4 prints the estimate).\n\n```bash\n# Install only what `import` reports missing. `--pypi` keeps the env's scanpy\u002Fnumba\n# stack; a conda add can swap it and bare pip can shadow it.\npixi add --pypi squidpy scanpy tangram-sc\n```\n\n## Pre-flight Interview\n\n```yaml\ndecisions:\n  - id: D1\n    param: TASK\n    kind: required\n    source: user\n    ask: \"What should the mapping give you: cell type proportions per spot (or labels per cell), predicted expression of genes the panel did not measure, or a cell type for every nucleus seen in the tissue image?\"\n    default: \"cell type proportions\"\n\n  - id: D2\n    param: referenceSource\n    kind: required\n    source: user\n    ask: \"Do you have a scRNA\u002FsnRNA-seq reference from the same tissue and state (h5ad with a cell type column), or should I search public data (CELLxGENE)?\"\n    default: null\n\n  - id: D3\n    param: CELL_TYPE_KEY\n    kind: required\n    source: data\n    depends_on: [D2]\n    ask: \"Which column of the reference holds the cell types to map?\"\n    default: null\n\n  - id: D4\n    param: MODE\n    kind: required\n    source: user\n    depends_on: [D1]\n    ask: \"Do the reference and the spatial section come from the same specimen (or a biological replicate), or from different samples\u002Fstudies?\"\n    default: \"clusters when from different samples or when the Step 4 memory estimate exceeds the sandbox; cells otherwise; constrained for the nucleus task\"\n\n  - id: D5\n    param: density_prior\n    kind: required\n    source: data\n    depends_on: [D1]\n    ask: \"This section looks like \u003Cspot data \u002F single-cell-resolution data>: weight each location by its RNA count, or treat every location as one cell?\"\n    default: \"per-spot total counts on spot data; uniform on single-cell-resolution data; nucleus counts for the nucleus task\"\n\n  - id: D6\n    param: TARGETS\n    kind: required\n    source: user\n    depends_on: [D1]\n    skip_if: \"TASK is not gene imputation\"\n    ask: \"Which genes or gene signatures do you want predicted on the tissue?\"\n    default: null\n\n  - id: D7\n    param: STAIN\n    kind: required\n    source: data\n    depends_on: [D1]\n    skip_if: \"TASK is not the nucleus task\"\n    ask: \"Is the full-resolution image H&E (dark nuclei) or fluorescent DAPI (bright nuclei)?\"\n    default: null\n\n  - id: D8\n    param: N_MARKERS\n    kind: optional\n    source: user\n    ask: \"How many top marker genes per cell type should drive the mapping?\"\n    default: \"100 per type\"\n\n  - id: D9\n    param: num_epochs\n    kind: optional\n    source: user\n    ask: \"How many training epochs?\"\n    default: \"500 (1000 in constrained mode)\"\n\n  - id: D10\n    param: DEVICE\n    kind: never_ask\n    source: data\n    reason: \"Picks CUDA when present, otherwise CPU; changes runtime only\"\n```\n\nAsk D1, D2 and D4 together. D3 and D5 follow from inspecting the files: offer\nthe reference's `obs` columns that look like cell type labels, and state the\nplatform the coordinates suggest. If no column groups the reference cells,\nstop and ask; never map on clusters you computed yourself without saying so.\n\n## Workflow\n\n1. Load spatial data and reference\n2. Normalise and keep the raw-count density prior\n3. Select training genes and run `tg.pp_adatas`\n4. Map cells to space\n5. Project cell type annotations\n6. Validate on training and held-out genes\n7. Plot and save\n\n### Step 1: Load Data\n\nThe demo uses the Tangram tutorial data (mouse cortex Visium + scRNA-seq);\nsquidpy downloads it on first use and caches it.\n\n```python\nimport numpy as np\nimport pandas as pd\nimport scanpy as sc\nimport squidpy as sq\nimport tangram as tg\n\nUSE_DEMO = True\nif USE_DEMO:\n    adata_sp = sq.datasets.visium_fluo_adata_crop()\n    adata_sp = adata_sp[adata_sp.obs[\"cluster\"].isin([f\"Cortex_{i}\" for i in range(1, 5)])].copy()\n    adata_sc = sq.datasets.sc_mouse_cortex()\n    CELL_TYPE_KEY = \"cell_subclass\"\nelse:\n    adata_sp = sc.read_h5ad(\"spatial.h5ad\")      # obsm[\"spatial\"] required\n    adata_sc = sc.read_h5ad(\"reference.h5ad\")\n    CELL_TYPE_KEY = \"cell_type\"                  # D3\n\nprint(adata_sp)\nprint(adata_sc.obs[CELL_TYPE_KEY].value_counts())\nshared = adata_sc.var_names.str.lower().intersection(adata_sp.var_names.str.lower())\nprint(f\"shared genes: {len(shared)}\")\n```\n\nFor the nucleus task use Nucleus 1 (Task Routes) instead of this step.\n\n### Step 2: Normalise, Keep the Density Prior\n\nUse the same normalisation on both sides. `tg.pp_adatas` computes its\n`rna_count_based` prior from `adata_sp.X`, which `normalize_total` flattens, so\ntake the per-spot total from raw counts first.\n\n```python\ndef is_raw_counts(ad):\n    x = ad.X[: min(500, ad.n_obs)]\n    x = x.toarray() if hasattr(x, \"toarray\") else np.asarray(x)\n    return np.allclose(x, np.round(x)) and x.max() > 20\n\nSINGLE_CELL_RESOLUTION = False                   # D5: True for Xenium\u002FMERFISH\u002FCosMx\nif SINGLE_CELL_RESOLUTION:\n    density_prior = np.full(adata_sp.n_obs, 1 \u002F adata_sp.n_obs)\nelse:\n    if \"total_counts\" in adata_sp.obs:\n        totals = adata_sp.obs[\"total_counts\"].to_numpy(dtype=float)\n    else:\n        totals = np.asarray(adata_sp.X.sum(1)).ravel().astype(float)   # raw if X is raw\n    density_prior = totals \u002F totals.sum()\nadata_sp.obs[\"density_prior\"] = density_prior      # reused by validation \u002F re-mapping\n\nfor ad in (adata_sc, adata_sp):\n    if is_raw_counts(ad):\n        ad.layers[\"counts\"] = ad.X.copy()\n        sc.pp.normalize_total(ad)\n        sc.pp.log1p(ad)\n\n# rank_genes_groups needs >= 2 cells per group; tiny types cannot be placed reliably anyway\nkeep = adata_sc.obs[CELL_TYPE_KEY].map(adata_sc.obs[CELL_TYPE_KEY].value_counts()) >= 10\nadata_sc = adata_sc[keep].copy()\nadata_sc.obs[CELL_TYPE_KEY] = adata_sc.obs[CELL_TYPE_KEY].astype(\"category\").cat.remove_unused_categories()\n```\n\n### Step 3: Training Genes\n\nTop markers per cell type, stratified across types (the Tangram authors\nsuggest ~1k unique markers). Genes not used for training stay available as\nheld-out genes for Step 6; with `genes=None` every shared gene trains and\nnothing is left to validate on.\n\n```python\nN_MARKERS = 100                                   # D8\nsc.tl.rank_genes_groups(adata_sc, groupby=CELL_TYPE_KEY, use_raw=False, method=\"wilcoxon\")\nmarkers_df = pd.DataFrame(adata_sc.uns[\"rank_genes_groups\"][\"names\"]).iloc[:N_MARKERS, :]\nmarkers = list(np.unique(markers_df.melt().value.values))\n\ntg.pp_adatas(adata_sc, adata_sp, genes=markers)   # lowercases var_names in both objects\nprint(f\"training genes: {len(adata_sc.uns['training_genes'])}; \"\n      f\"overlap genes: {len(adata_sc.uns['overlap_genes'])}\")\n```\n\nFewer than ~100 training genes makes the mapping unstable; raise `N_MARKERS` or\ncheck gene symbol formats (Ensembl IDs vs symbols, human vs mouse case). From\nhere on, gene names are lowercase. For the nucleus task, continue with\nNucleus 2-4 (Task Routes), then return to Step 6.\n\n### Step 4: Map Cells to Space\n\n`mode=\"cells\"` maps every cell (needed for per-cell placement and the\nconstrained mode); `mode=\"clusters\"` maps cell type averages, is far cheaper,\nand is the safer choice when the reference comes from a different sample.\n\n```python\nimport torch\n\nMODE = \"cells\"                                    # D4: or \"clusters\"\nCLUSTER_LABEL = CELL_TYPE_KEY if MODE == \"clusters\" else None\nDEVICE = \"cuda:0\" if torch.cuda.is_available() else \"cpu\"\n\nn_rows = adata_sc.obs[CELL_TYPE_KEY].nunique() if MODE == \"clusters\" else adata_sc.n_obs\nprint(f\"rough memory for the map + optimiser: {n_rows * adata_sp.n_obs * 16 \u002F 1e9:.1f} GB\")\n\nkwargs = dict(mode=MODE, density_prior=density_prior, num_epochs=500,   # D9\n              device=DEVICE, random_state=0)\nif CLUSTER_LABEL:\n    kwargs[\"cluster_label\"] = CLUSTER_LABEL\n\nad_map = tg.map_cells_to_space(adata_sc, adata_sp, **kwargs)\ntrain_df = ad_map.uns[\"train_genes_df\"]\nprint(ad_map)                                     # cells (or clusters) x spots\nprint(f\"mean training score: {train_df['train_score'].mean():.3f}\")\n```\n\nIf the estimate exceeds ~12 GB on the 16 GB sandbox, switch to `clusters`\nor subsample the reference per cell type before mapping.\n\n### Step 5: Project Cell Type Annotations\n\n`tangram_ct_pred` holds the mapped probability mass per type and spot; divide\nby the row sum for proportions.\n\n```python\ntg.project_cell_annotations(ad_map, adata_sp, annotation=CELL_TYPE_KEY)\nct = adata_sp.obsm[\"tangram_ct_pred\"]\nprop = ct.div(ct.sum(axis=1), axis=0)\nadata_sp.obs[\"tangram_top_type\"] = prop.idxmax(axis=1).astype(\"category\")\nadata_sp.obs[\"tangram_top_frac\"] = prop.max(axis=1)\n\nprint(prop.mean().sort_values(ascending=False).head(10))\nprint(f\"spots where the top type is \u003C 50%: {(adata_sp.obs['tangram_top_frac'] \u003C 0.5).mean():.0%}\")\n```\n\nOn spot data (Visium) report proportions; `tangram_top_type` is a summary, not\nthe identity of the spot.\n\n### Step 6: Validate on Training and Held-out Genes\n\nTraining scores show the fit; only held-out genes show whether the mapping\ngeneralises. Low scores on genes sparse in space (high `sparsity_sp`) are\ndropout; low scores on well-detected genes point to a reference mismatch.\n\n```python\nimport matplotlib.pyplot as plt\n\ntg.plot_training_scores(ad_map, bins=20, alpha=0.5)   # score; vs sc \u002F sp sparsity; vs difference\nplt.savefig(\"tangram_training_scores.png\", dpi=150, bbox_inches=\"tight\")\n\nad_ge = tg.project_genes(ad_map, adata_sc, cluster_label=CLUSTER_LABEL)   # spots x all reference genes\ndf_all = tg.compare_spatial_geneexp(ad_ge, adata_sp, adata_sc)\ndf_all.to_csv(\"tangram_gene_scores.csv\")\ntrain = df_all[df_all[\"is_training\"]]\ntest = df_all[~df_all[\"is_training\"]]\nprint(f\"training genes: {len(train)}, mean score {train['score'].mean():.3f}\")\nprint(f\"held-out genes: {len(test)}, mean score {test['score'].mean():.3f}\")\n```\n\n`tg.eval_metric` fits held-out score against spatial sparsity; its AUC is the\nmain quality number. Plot from its coordinates (`tg.plot_auc` calls seaborn\nwith positional arguments, which recent seaborn rejects):\n\n```python\nmetrics, ((pol_xs, pol_ys), (xs, ys)) = tg.eval_metric(df_all)\nprint({k: round(float(v), 3) for k, v in metrics.items()})\nfig, ax = plt.subplots(figsize=(5, 4))\nax.scatter(xs, ys, s=8, alpha=0.5); ax.plot(pol_xs, pol_ys, c=\"r\")\nax.set(xlim=(0, 1), ylim=(0, 1), xlabel=\"score (held-out genes)\", ylabel=\"spatial sparsity\",\n       title=f\"AUC = {metrics['auc_score']:.3f}\")\nplt.savefig(\"tangram_auc.png\", dpi=150, bbox_inches=\"tight\")\n```\n\nEach projected cell type should also follow a held-out marker the training\ncould not have forced:\n\n```python\nchecks = {\"Oligo\": \"mobp\", \"Astro\": \"aqp4\"}       # cell type -> lowercase marker; fill for the tissue\ntraining = set(adata_sp.uns[\"training_genes\"])\nfor t, g in checks.items():\n    if t in prop and g in adata_sp.var_names:\n        x = adata_sp[:, g].X\n        x = np.asarray(x.todense()).ravel() if hasattr(x, \"todense\") else np.asarray(x).ravel()\n        tag = \"training\" if g in training else \"held-out\"\n        print(f\"{t} vs {g} ({tag}): r = {np.corrcoef(prop[t], x)[0, 1]:.2f}\")\n```\n\n| Number | Good | Usable with care | Poor - do not report as a finding |\n|---|---|---|---|\n| Mean training score | > 0.7 | 0.5-0.7 | \u003C 0.5 |\n| Held-out AUC | > 0.6 | 0.4-0.6 | \u003C 0.4 |\n| Held-out marker r | clearly positive | weak | ~0 or negative |\n\nA large train-test gap means the mapping memorised the markers: broaden the\nmarker set, use `mode=\"clusters\"`, or set `lambda_r` > 0. Report these numbers\nnext to every map or imputed gene.\n\n### Step 7: Plot and Save\n\n```python\nxy = adata_sp.obsm[\"spatial\"]\ntop = prop.mean().nlargest(6).index\nfig, axes = plt.subplots(2, 3, figsize=(15, 10))\nfor ax, t in zip(axes.flat, top):\n    s = ax.scatter(xy[:, 0], xy[:, 1], c=prop[t], s=12, cmap=\"viridis\", vmin=0)\n    ax.set_title(t); ax.invert_yaxis(); ax.set_aspect(\"equal\"); ax.axis(\"off\")\n    fig.colorbar(s, ax=ax, shrink=0.6)\nplt.tight_layout(); plt.savefig(\"tangram_celltype_maps.png\", dpi=150)\n\nprop.to_csv(\"tangram_celltype_proportions.csv\")\nad_map.write_h5ad(\"tangram_mapping.h5ad\", compression=\"gzip\")\nadata_sc.write_h5ad(\"tangram_sc_prep.h5ad\", compression=\"gzip\")\nadata_sp.write_h5ad(\"tangram_spatial.h5ad\", compression=\"gzip\")\n```\n\nCheck each map against biology the user expects (for the demo: L2\u002F3 IT\nneurons in the upper cortical layers, L6 types deep). The three h5ad files let\nthe reference routes resume without re-mapping.\n\n## Task Routes\n\nEach route continues the Workflow session (same variable names). Only the calls\nthat differ from the Workflow, or that fail silently when written another way,\nare shown; plotting and saving follow Step 7.\n\n### Route: Gene Imputation (Tangram, gimVI)\n\nPredicts genes the panel did not measure, or measured with heavy dropout, by\nprojecting reference expression through the mapping. A projected gene reflects\nwhere the mapped cells sit, not a new measurement: report every imputed map as\na prediction, next to the held-out score from Step 6. Start after Step 6\n(`ad_ge`, `df_all`), mapped with a marker subset so held-out genes exist.\n\n1. **Targets (D6)**: lowercase names (after `pp_adatas`); a gene absent or\n   near-zero in the reference cannot be imputed. Genes dense in the reference\n   but sparse in space (dropout) gain the most.\n2. **Trust table**: there is no ground truth for unmeasured genes; the held-out\n   score is the proxy, and a gene expressed in \u003C ~5% of reference cells gives a\n   noisy map.\n3. **Plot measured vs projected**: `tg.plot_genes_sc(genes, adata_measured=adata_sp,\n   adata_predicted=ad_ge, perc=0.02)` needs `uns[\"spatial\"]`; otherwise scatter on\n   `obsm[\"spatial\"]` copied below.\n4. **Store** predictions in `obsm`, never in `X`, so later steps cannot mistake\n   them for counts.\n\n```python\nTARGETS = [\"foxp3\", \"cd8a\", \"gfap\", \"mbp\"]                      # D6\nin_sc = [g for g in TARGETS if g in adata_sc.var_names]\nad_ge.obsm[\"spatial\"] = adata_sp[ad_ge.obs_names].obsm[\"spatial\"]\n\ndetect_sc = pd.Series(np.asarray((adata_sc.X > 0).mean(0)).ravel(), index=adata_sc.var_names)\ntrust = pd.DataFrame({\n    \"measured_in_spatial\": [g in adata_sp.var_names for g in in_sc],\n    \"heldout_score\": [df_all[\"score\"].get(g, np.nan) for g in in_sc],\n    \"frac_cells_expressing_sc\": [detect_sc[g] for g in in_sc],\n}, index=in_sc)\ntrust.to_csv(\"imputation_trust.csv\")\nprint(f\"held-out median score: {df_all.loc[~df_all['is_training'], 'score'].median():.3f}\")\n\nkeep = [g for g in in_sc if g not in adata_sp.var_names]       # imputed-only genes\nx = ad_ge[:, keep].X\nadata_sp.obsm[\"imputed_tangram\"] = pd.DataFrame(x.toarray() if hasattr(x, \"toarray\") else x,\n                                                index=ad_ge.obs_names, columns=keep)\nad_ge.write_h5ad(\"tangram_projected_genes.h5ad\", compression=\"gzip\")\n```\n\n- **Signature score**: `sc.tl.score_genes(ad_ge, genes, score_name=\"signature_score\")`\n  on the projected genes; it marks where cells expressing the signature in the\n  reference were placed.\n- **Spatially structured imputed genes**: `sq.gr.spatial_neighbors(ad_ge, coord_type=\"generic\")`\n  then `sq.gr.spatial_autocorr(ad_ge, mode=\"moran\", genes=unmeasured)`. High\n  Moran's I often mirrors the layout of the expressing cell type; check that\n  before calling it a finding.\n\n**gimVI (count-based second opinion, targeted panels)**: install\n`pixi add --pypi \"scvi-tools\u003C1.6\"` (gimVI leaves scvi-tools in v1.6). Both\nobjects need raw counts, and the spatial genes must be a subset of the reference\ngenes. Hold out ~1\u002F5 of the panel genes, train on the rest, and report the\nheld-out Spearman correlation before trusting the imputed genes.\n\n```python\nfrom scvi.external import GIMVI\n\nGIMVI.setup_anndata(seq)                       # reference counts, all genes\nGIMVI.setup_anndata(st_train)                  # spatial counts without the held-out genes\nmodel = GIMVI(seq, st_train)\nmodel.train(max_epochs=200)\n_, imputed = model.get_imputed_values(normalized=True)   # spatial cells x reference genes\n```\n\n### Route: Nuclei Deconvolution with Histology (constrained mode)\n\nCounts nuclei per Visium spot from the image, then asks Tangram\n(`mode=\"constrained\"`) to select exactly that many reference cells, so every\nsegmented nucleus gets a cell type. Segmentation quality bounds the result.\nNeeds the Space Ranger folder and the **full-resolution** image given to Space\nRanger (`tissue_hires_image.png` is too small to segment). Without it use\n`spatial-transcriptomics-deconvolution-cell2location`.\n\nOrder: Nucleus 1 replaces Step 1, then Steps 2-3, Nucleus 2-4, and Step 6 on\nthe constrained map (`CLUSTER_LABEL = None`).\n\n#### Nucleus 1: Load Data and Image\n\n```python\nVISIUM_DIR = \"path\u002Fto\u002Fspaceranger_outs\"\nadata_sp = sq.read.visium(VISIUM_DIR)                     # obsm[\"spatial\"] in full-res pixels\nadata_sp.var_names_make_unique()\nlibrary_id = list(adata_sp.uns[\"spatial\"])[0]\nimg = sq.im.ImageContainer(\"path\u002Fto\u002Ffullres_image.tif\", layer=\"image\", library_id=library_id)\nadata_sc = sc.read_h5ad(\"reference.h5ad\")\nCELL_TYPE_KEY, STAIN = \"cell_type\", \"he\"                  # D7: \"he\" or \"fluorescent\"\n# count_cell_annotations indexes obs[annotation][k] positionally; newer pandas rejects integer keys\nadata_sc.obs_names = [str(i) for i in range(adata_sc.n_obs)]\n```\n\nDemo: `sq.datasets.visium_fluo_adata_crop()`, `sq.datasets.visium_fluo_image_crop()`\n(DAPI in channel 0, `STAIN = \"fluorescent\"`) and `sq.datasets.sc_mouse_cortex()`.\n\n#### Nucleus 2: Segment and Count Nuclei\n\nFluorescent nuclei are bright; H&E nuclei are dark (`geq=False`). Tangram reads\n`obsm[\"image_features\"]`, not squidpy's default `img_features`.\n\n```python\nif STAIN == \"fluorescent\":\n    sq.im.process(img, layer=\"image\", method=\"smooth\")\n    sq.im.segment(img, layer=\"image_smooth\", method=\"watershed\", channel=0)\nelse:\n    sq.im.process(img, layer=\"image\", method=\"gray\")\n    sq.im.process(img, layer=\"image_gray\", method=\"smooth\")\n    sq.im.segment(img, layer=\"image_gray_smooth\", method=\"watershed\", channel=0, geq=False)\n\nsq.im.calculate_image_features(\n    adata_sp, img, layer=\"image\", features=\"segmentation\", key_added=\"image_features\",\n    features_kwargs={\"segmentation\": {\"label_layer\": \"segmented_watershed\", \"props\": [\"label\", \"centroid\"]}},\n    mask_circle=True)\nadata_sp.obs[\"cell_count\"] = adata_sp.obsm[\"image_features\"][\"segmentation_label\"]\nprint(adata_sp.obs[\"cell_count\"].describe(), (adata_sp.obs[\"cell_count\"] == 0).sum())\n```\n\nInspect a crop of `img[\"image\"]` next to `img[\"segmented_watershed\"]` before\ngoing on. Merged clumps or fragments: pass `thresh=` to `sq.im.segment` or\nchange `sigma=` in `sq.im.process`. Visium spots usually hold ~1-10 nuclei in\nbrain, more in dense tissue; many zero-count spots inside tissue mean failed\nsegmentation.\n\n#### Nucleus 3: Constrained Mapping\n\nThe nucleus counts replace the Step 2 density prior; `target_count` is the total\nnumber of nuclei, and `obs[\"F_out\"]` is each reference cell's selection\nprobability. The reference needs more cells than `target_count`.\n\n```python\ncounts = adata_sp.obs[\"cell_count\"].to_numpy(dtype=float)\nad_map = tg.map_cells_to_space(adata_sc, adata_sp, mode=\"constrained\",\n                               target_count=int(counts.sum()), density_prior=counts \u002F counts.sum(),\n                               num_epochs=1000, device=DEVICE, random_state=0)\nprint(f\"selected (F_out > 0.5): {(ad_map.obs['F_out'] > 0.5).sum()} of {int(counts.sum())}\")\n```\n\n#### Nucleus 4: One Cell Type per Nucleus\n\n`tg.project_cell_annotations` in tangram-sc 1.0.4 ignores `F_out`, so build the\nper-spot prediction from selected cells only; `count_cell_annotations` already\napplies the filter.\n\n```python\nsel = (ad_map.obs[\"F_out\"] > 0.5).to_numpy()\nonehot = pd.get_dummies(ad_map.obs.loc[sel, CELL_TYPE_KEY]).astype(float)\nadata_sp.obsm[\"tangram_ct_pred\"] = pd.DataFrame(ad_map.X[sel].T @ onehot.to_numpy(),\n                                                index=ad_map.var_names, columns=onehot.columns)\ntg.create_segment_cell_df(adata_sp)\ntg.count_cell_annotations(ad_map, adata_sc, adata_sp, annotation=CELL_TYPE_KEY)\nadata_segment = tg.deconvolve_cell_annotations(adata_sp)        # one row per nucleus, obs[\"cluster\"]\nadata_segment.obsm[\"spatial\"] = adata_segment.obs[[\"x\", \"y\"]].to_numpy(float)\nadata_sp.obsm[\"tangram_ct_count\"].drop(columns=[\"centroids\"]).to_csv(\"tangram_ct_count_per_spot.csv\")\nadata_segment.obs[[\"x\", \"y\", \"cluster\"]].to_csv(\"tangram_segment_celltypes.csv\")\n```\n\nNucleus and spot coordinate ranges must overlap; if they look swapped, swap the\ncolumns of `adata_segment.obsm[\"spatial\"]`. Per-spot counts can be compared with\ncell2location by correlating proportions per type over shared spots; large\ndisagreements usually trace back to segmentation. The per-nucleus table works\nlike single-cell-resolution data for `sq.gr.nhood_enrichment(adata_segment,\ncluster_key=\"cluster\")`, but carries labels, not its own expression.\n\n### Route: Advanced Validation (k-fold CV, mode, seeds)\n\nRun after Step 6 when its numbers are borderline, when choosing a mode, or\nbefore a result goes into a report. Each check re-maps; on CPU use `clusters`\nmode and fewer epochs, and report the settings. `PRIOR =\nadata_sp.obs[\"density_prior\"].to_numpy()` (saved in Step 2).\n\n- **k-fold gene CV**: withhold each fold of training genes through\n  `cv_train_genes` and score the withheld fold. `tg.cross_val` calls `np.float`\n  (removed in NumPy >= 1.24) and defaults to `device=\"cuda:0\"`; use the loop.\n- **Cells vs clusters**: compare held-out score and AUC (`tg.eval_metric(d)[0][\"auc_score\"]`),\n  never training scores, which always favour `cells`.\n- **Seed stability**: re-map with seeds 0-2, project annotations, correlate each\n  type's proportions between runs; r \u003C ~0.8 means that type's map is not stable.\n- **Genes the reference explains badly**: held-out genes with `sparsity_sp \u003C 0.5`\n  and `score \u003C 0.3` are not dropout; tumour, stress or tissue-specific genes among\n  them point to a reference from the wrong state or tissue.\n\n```python\nK, EPOCHS = 5, 300\ngenes = np.array(adata_sc.uns[\"training_genes\"])\nfolds = np.array_split(np.random.default_rng(0).permutation(genes), K)\nrows = []\nfor i, held in enumerate(folds):\n    m = tg.map_cells_to_space(adata_sc, adata_sp, cv_train_genes=[g for g in genes if g not in set(held)],\n                              mode=\"clusters\", cluster_label=CELL_TYPE_KEY, density_prior=PRIOR,\n                              num_epochs=EPOCHS, device=DEVICE, random_state=0, verbose=False)\n    ge = tg.project_genes(m, adata_sc, cluster_label=CELL_TYPE_KEY)\n    rows.append({\"fold\": i, \"test_score\": tg.compare_spatial_geneexp(ge, adata_sp, genes=list(held))[\"score\"].mean()})\ncv = pd.DataFrame(rows); cv.to_csv(\"tangram_cv.csv\", index=False)\nprint(cv[\"test_score\"].mean())\n```\n\n## Key Parameters\n\n| Parameter | Default | Effect |\n|---|---|---|\n| Reference choice | from the user | Same tissue and state; the most consequential choice |\n| `N_MARKERS` | 100 per type | Training gene count; more genes = more constraint, but noisy genes hurt |\n| `mode` | `\"cells\"` | `\"clusters\"` is faster and smoother, cannot give per-cell placement; `\"constrained\"` selects `target_count` cells |\n| `num_epochs` | 500 | 500-1000; check the score has plateaued in `training_history` |\n| `density_prior` | raw-count based | `\"uniform\"` on single-cell-resolution data; array must sum to 1 |\n| `lambda_r` | 0 | Entropy regulariser; > 0 makes each cell's placement more peaked |\n| AUC threshold | > 0.6 good \u002F \u003C 0.4 poor | Generalisation to held-out genes (Step 6) |\n| `TARGETS` | from the user (D6) | Genes to impute; must be expressed in the reference |\n| `cluster_label` (`project_genes`) | same as mapping | Mismatch raises an obs-index error |\n| Held-out fraction (gimVI) | 1\u002F5 of panel | Genes withheld to score imputation |\n| `max_epochs` (gimVI) | 200 | Lower for a quick CPU run; report it |\n| `normalized` (gimVI) | True | Compare against library-size-normalised counts |\n| `STAIN` \u002F `geq` | from the image (D7) | Bright (fluorescent) vs dark (H&E) nuclei |\n| `thresh` (`sq.im.segment`) | Otsu | Nucleus threshold; drives every count |\n| `mask_circle` | True | Count only nuclei inside the round spot |\n| `F_out` threshold | 0.5 | Probability for a reference cell to count as selected |\n| `K` (CV folds) | 5 | More folds = smaller held-out sets, more runs |\n| `EPOCHS` (CV) | 300 | Shorter than the main run to save time; report it |\n| Seeds | 0, 1, 2 | Number of re-mappings for the stability check |\n| Seed stability cutoff | r ~0.8 | Below it, the type's map is not stable |\n| Poorly explained gene filter | `sparsity_sp \u003C 0.5`, score \u003C 0.3 | Separates reference mismatch from dropout |\n\n## Common Recipes\n\n### Recipe: One Reference, Several Sections\n\nMap each section separately with the same training genes, then compare mean\ncompositions. `clusters` mode keeps it fast:\n\n```python\nsections = {\"S1\": \"s1.h5ad\", \"S2\": \"s2.h5ad\"}\nprops = {}\nfor name, path in sections.items():\n    sp = sc.read_h5ad(path)\n    totals = np.asarray(sp.X.sum(1)).ravel().astype(float)       # raw counts before normalising\n    if is_raw_counts(sp):\n        sc.pp.normalize_total(sp); sc.pp.log1p(sp)\n    ref = adata_sc.copy()\n    tg.pp_adatas(ref, sp, genes=list(adata_sc.uns[\"training_genes\"]))\n    m = tg.map_cells_to_space(ref, sp, mode=\"clusters\", cluster_label=CELL_TYPE_KEY,\n                              density_prior=totals \u002F totals.sum(), num_epochs=500, device=DEVICE, random_state=0)\n    tg.project_cell_annotations(m, sp, annotation=CELL_TYPE_KEY)\n    ct_s = sp.obsm[\"tangram_ct_pred\"]\n    props[name] = ct_s.div(ct_s.sum(axis=1), axis=0)\nsummary = pd.DataFrame({k: v.mean() for k, v in props.items()}).round(3)\nsummary.to_csv(\"tangram_composition_by_section.csv\")\nprint(summary)\n```\n\n### Recipe: Label Cells on Single-Cell-Resolution Data\n\nOn Xenium or MERFISH each spatial observation is one cell, so the top\nprojected type is a per-cell label. Compare it with an existing annotation\nrather than replacing it:\n\n```python\nadata_sp.obs[\"tangram_label\"] = prop.idxmax(axis=1).astype(\"category\")\nadata_sp.obs[\"tangram_conf\"] = prop.max(axis=1)\nif \"cell_type\" in adata_sp.obs:\n    agree = pd.crosstab(adata_sp.obs[\"cell_type\"], adata_sp.obs[\"tangram_label\"], normalize=\"index\")\n    agree.round(2).to_csv(\"tangram_vs_annotation.csv\")\n    print(agree.max(axis=1).round(2).sort_values())      # low values = the two methods disagree\n```\n\n### Recipe: Where Each Reference Cell Lands\n\nIn `cells` mode, each reference cell's expected position and how sharply it\nis placed (low entropy = one clear location):\n\n```python\nP = np.asarray(ad_map.X, dtype=float)\nP = P \u002F P.sum(axis=1, keepdims=True)                      # cells x spots, rows sum to 1\nadata_sc.obsm[\"tangram_xy\"] = P @ adata_sp.obsm[\"spatial\"]\nadata_sc.obs[\"placement_entropy\"] = -(P * np.log(P + 1e-12)).sum(axis=1)\nprint(adata_sc.obs.groupby(CELL_TYPE_KEY, observed=True)[\"placement_entropy\"].median()\n      .sort_values().round(2))\n```\n\nTypes with high entropy are spread evenly and their spatial pattern carries\nlittle information.\n\n### Recipe: One-Row Quality Summary for the Report\n\n```python\nsummary = pd.DataFrame([{\n    \"mode\": MODE,\n    \"n_training_genes\": int(df_all[\"is_training\"].sum()),\n    \"n_heldout_genes\": int((~df_all[\"is_training\"]).sum()),\n    \"mean_train_score\": round(train[\"score\"].mean(), 3),\n    \"mean_heldout_score\": round(test[\"score\"].mean(), 3),\n    \"auc_heldout\": round(float(metrics[\"auc_score\"]), 3),\n}])\nsummary[\"verdict\"] = np.where(summary[\"auc_heldout\"] > 0.6, \"good\",\n                              np.where(summary[\"auc_heldout\"] >= 0.4, \"moderate\", \"poor\"))\nsummary.to_csv(\"tangram_validation_summary.csv\", index=False)\nprint(summary.T)\n```\n\n## Expected Outputs\n\n- `tangram_mapping.h5ad` - cell (or cluster) x spot probability matrix; `uns[\"train_genes_df\"]`\n- `tangram_sc_prep.h5ad`, `tangram_spatial.h5ad` - preprocessed inputs; spatial has `obs[\"density_prior\"]`, `obsm[\"tangram_ct_pred\"]`, `obs[\"tangram_top_type\"]`\n- `tangram_celltype_proportions.csv`, `tangram_celltype_maps.png` - per-spot proportions and maps\n- `tangram_training_scores.png`, `tangram_gene_scores.csv`, `tangram_auc.png` - validation (Step 6)\n- `tangram_validation_summary.csv` - one-row summary with a verdict (recipe)\n- Gene Imputation: `tangram_projected_genes.h5ad` (spots x reference genes), `imputation_trust.csv`, imputed-only genes in `adata_sp.obsm[\"imputed_tangram\"]`\n- Nuclei Deconvolution: `tangram_ct_count_per_spot.csv` (cell type counts per spot), `tangram_segment_celltypes.csv` (every nucleus with coordinates and type)\n- Advanced Validation: `tangram_cv.csv` (per-fold held-out scores)\n\n## Troubleshooting\n\n| Problem | Cause | Fix |\n|---|---|---|\n| `AssertionError` on `training_genes` \u002F `overlap_genes` | `pp_adatas` not run on these exact objects | Re-run Step 3 right before mapping; load the saved `tangram_*.h5ad`, not the raw files |\n| Very few training genes | Symbol mismatch (Ensembl IDs, species) | Map IDs to symbols; `pp_adatas` already lowercases |\n| CUDA\u002FCPU out of memory, or very slow | Too many cells in `mode=\"cells\"` | Subsample the reference per type, or use `mode=\"clusters\"` |\n| One type dominates every spot | Reference lacks the tissue's major types or wrong state | Choose a better-matched reference |\n| `ValueError: A cluster_label must be specified` | `mode=\"clusters\"` without label | Pass `cluster_label=CELL_TYPE_KEY` |\n| `The two AnnDatas need to have same obs index` | Clusters-mode map projected without `cluster_label` | Pass `cluster_label=CLUSTER_LABEL` to `project_genes` |\n| `Invalid input for density_prior` | List instead of array, or does not sum to 1 | Pass a numpy array normalised to sum 1 |\n| No held-out genes \u002F `eval_metric` fails | `pp_adatas(genes=None)` used all genes | Re-run Step 3 with a marker subset |\n| `TypeError` in `tg.plot_auc` | seaborn >= 0.12 positional args | Plot from `eval_metric` coordinates (Step 6) |\n| Gene names lowercase afterwards | `pp_adatas` default `gene_to_lowercase=True` | Expected; use lowercase names downstream |\n| Target gene missing | Not in reference, or uppercase name | Use lowercase names; pick a reference that measures it |\n| `sc.pl.spatial` fails on projected data | Projected AnnData lacks `uns[\"spatial\"]` | Scatter on `obsm[\"spatial\"]` (Gene Imputation route) |\n| Projected map mirrors one cell type's layout | Gene restricted to that type in the reference | Expected; state it, it is not independent evidence |\n| `spatial genes needs to be subset of seq genes` | Panel genes absent from the reference, or case differs | Harmonise symbols; drop panel genes the reference lacks |\n| gimVI `ImportError`\u002F`AttributeError` | gimVI moved out of scvi-tools | `pixi add --pypi \"scvi-tools\u003C1.6\"` |\n| `Missing parameter ... Run sqidpy.im.calculate_image_features` | Features stored under `img_features` | Pass `key_added=\"image_features\"` (Nucleus 2) |\n| `KeyError: 'tangram_ct_pred'` in `deconvolve_cell_annotations` | Annotation not projected | Run the `tangram_ct_pred` block of Nucleus 4 first |\n| Almost all spots have 0 nuclei | Low-res image, or wrong polarity | Use the full-res image; switch `geq` \u002F stain branch |\n| Counts far too high | Over-segmentation of texture | Raise `thresh` or smoothing `sigma` |\n| `ValueError` about `target_count` | Missing or zero count | Check `cell_count` sum > 0 |\n| `KeyError` \u002F `FutureWarning` on integer key in `count_cell_annotations` | Non-string reference `obs_names` | String `obs_names` (Nucleus 1) before `pp_adatas` |\n| Image and spots misaligned | Image is not the one Space Ranger used, or wrong scale | Use the Space Ranger input image at full resolution |\n\n## Bundled Resources\n\nMerged from four former Tangram skills: `spatial-mapping-tangram` (Steps 1-5, 7,\nrecipes), `spatial-mapping-validation` (Step 6, summary recipe, Route: Advanced\nValidation), `scrna-spatial-gene-imputation` (Route: Gene Imputation) and\n`spatial-transcriptomics-deconvolution-tangram` (Route: Nuclei Deconvolution).\nDuplicated loading, normalisation and `pp_adatas` code was kept once (Steps 1-3).\n\n## Related Skills\n\n- `spatial-transcriptomics-deconvolution-cell2location` - probabilistic spot deconvolution alternative\n- `spatial-transcriptomics-cell-type-annotation` - reference search\u002Fdownload; labels for single-cell-resolution data\n- `spatial-panel-design` - choose panel genes so imputation is less needed\n- `spatial-transcriptomics-analysis-squidpy` - squidpy image and neighbourhood analysis\n- `spatial-transcriptomics-cell-cell-communication` - interactions between the mapped types\n\n## References\n\n- Biancalani et al. (2021) Tangram, Nature Methods: https:\u002F\u002Fdoi.org\u002F10.1038\u002Fs41592-021-01264-7\n- Tangram source and tutorials: https:\u002F\u002Fgithub.com\u002Fbroadinstitute\u002FTangram\n- Tangram documentation: https:\u002F\u002Ftangram-sc.readthedocs.io\u002F\n- squidpy + Tangram tutorial (demo data used here): https:\u002F\u002Fsquidpy.readthedocs.io\u002Fen\u002Fstable\u002Fnotebooks\u002Ftutorials\u002Ftutorial_tangram.html\n",{"name":5,"license":15,"description":7},"master","fd76f882a04e445e899d5cfb2732f2105ea054ee","skills\u002Fawesome-skills\u002Fspatial-mapping-tangram",0,"https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS","https:\u002F\u002Fbg-szy.github.io\u002FTOP-SKILLS\u002F","https:\u002F\u002Fgithub.com\u002Fbg-szy","https:\u002F\u002Fwww.ecust.edu.cn\u002F","a student of East China University of Science and Technology","2026-11-15 03:38:02",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add bg-szy\u002FTOP-SKILLS --skill spatial-mapping-tangram",{"tool":40,"command":41},"bunx","bunx skills add bg-szy\u002FTOP-SKILLS --skill spatial-mapping-tangram",{"tool":43,"command":44},"pnpm","pnpm dlx skills add bg-szy\u002FTOP-SKILLS --skill spatial-mapping-tangram","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fawesome-skills\u002Fspatial-mapping-tangram\u002FSKILL.md",true,[],[49,58,65,72,79,86],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":57},"01M7DXW9N826PKXK174PVW3038","serpmaven","Scrape Google search results (SERP) to JSON with SERP Maven (serpmaven) - a real Chrome browser on a residential proxy with sticky sessions. Run it as a CLI, a Python library, a local HTTP search API (`serve`), an MCP server or a Docker image; set the proxy login, workers, pages and cost tracking. Use when the user wants Google results, rank tracking, a self-hosted SERP API, or live Google search for an AI agent.","MIT","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Fserpmaven\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":57},"01M7DXVHSTWDV65475QEQ915M7","revnu-landing-page-audit","Find out why a landing page isn't turning visitors into signups, demos or sales. Audits one page against what the ad, post or search that sends people there promised, then checks the first screen, proof, call to action, friction and mobile. Returns at most 7 prioritized fixes, plus what is fine and what could not be checked; rewrites specific lines and fixes the page in the repo when asked. Never promises a conversion lift. Works without a Revnu account. Use when the user says or asks: \"audit my landing page\", \"why isn't this page converting\", \"review my homepage\", \"my ads get clicks but no signups\", \"people bounce from the pricing page\", \"CRO review\", \"improve conversion rate\", \"is my hero section clear\", \"roast my landing page\", \"rewrite my headline\", \"what's wrong with this page\", \"landing page feedback\", \"make the signup page convert better\". Not for SEO or AI-search audits, page speed engineering on its own, or building a new page from scratch.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-landing-page-audit\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":57},"01M7DXV8X2D7B3VTD4HHYYHTGR","revnu-growth-context","Write down once who buys, what they're stuck on, what it costs, what proof you have and what you've already tried, so every growth task starts from facts instead of a questionnaire. Creates or updates .agents\u002Frevnu-growth.md from the repo, the live site and the user, and imports an existing product-marketing.md. Use when the user says \"set up our marketing context\", \"who is our ideal customer\", \"write our ICP\", \"describe the product for marketing\", \"positioning doc\", \"what's our brand voice\", \"remember this about our customers\", \"log what we tried\", \"what have we learned from marketing\", \"we changed pricing, update the context\", \"update our growth notes\", \"summarize the business for the agent\", \"import my product-marketing.md\", \"start a growth doc\", or before a first marketing, SEO, outreach or launch task when no context file exists. Works without a Revnu account.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-growth-context\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":57},"01M7DXV0DGJ1G0A60PAHC6J3C5","revnu-get-listed","Get onto the third-party pages AI answers and search cite when buyers ask for the best tool in your category: \"best X\" roundups, directories, review sites, GitHub awesome lists, community threads and comparison pages. Finds which ones are cited, ranks them by fit and effort, and drafts each submission, PR or pitch by the target's own rules. Use when the user says \"get us listed\", \"which directories should we submit to\", \"how do we get into best-of lists\", \"why does ChatGPT recommend competitors and not us\", \"get mentioned in AI answers\", \"submit to awesome lists\", \"get on G2\", \"where are our competitors listed\", \"pitch listicle authors\", \"find backlink opportunities\", \"launch directories\", \"get into roundups\", \"Product Hunt alternatives\", \"where should we be listed\", \"get cited by Perplexity\". Never submits, pays or posts without a yes. Works without a Revnu account.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-get-listed\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":57},"01M7DXTSPMGT9D6DSS0HP9BSTA","revnu-ai-readiness-audit","Audit whether your website gives ChatGPT, Perplexity, Claude, Gemini and Google's AI Overviews something worth quoting, and fix the pages that don't. Use when the user says or asks \"is my site ready for AI search\", \"audit my site for AI answers\", \"AEO audit\", \"GEO audit\", \"why doesn't ChatGPT quote our pricing\", \"make our pages citable by AI\", \"do I need llms.txt\", \"does schema help with ChatGPT\", \"check our structured data\", \"is our content visible without JavaScript\", \"AI SEO audit\", \"optimize our homepage for AI answers\", \"LLM SEO check\", \"why does AI get our product wrong\", \"fix our site for AI Overviews\". Checks fetchability and indexability, answers in the raw HTML, entity facts, schema (including JS-injected markup), headings, dates and llms.txt, then gives at most 10 prioritised fixes and edits the repo when asked. Works without a Revnu account.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-ai-readiness-audit\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":57},"01M7DXSZHCVTRS620GC3S97JZV","proxy-troubleshooting","Diagnose residential proxy failures, with NodeMaven's gateway as the reference - 407 with correct credentials, 406, 410, 500, a connection that hangs, ERR_TUNNEL_CONNECTION_FAILED in a browser, Playwright or Puppeteer ignoring proxy credentials, a sticky session that changes IP, geo-targeting that is silently ignored, passwords with special characters, and unexpected traffic from headless Chrome. Use when a proxy connection fails, returns the wrong location, or costs more traffic than expected.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Fproxy-troubleshooting\u002FSKILL.md",[],[]]