Repository navigation
Releases
xcell 0.5.0
- Fixed: the analysis record's report start could only move forward. Start report here set the report to begin after the last recorded step, so pressing it in a finished session left every step outside the report, greyed out, with no way back short of Clear, and an export then wrote an empty document. Each step now has Start here, which begins the report at that step; Include all steps puts every step back; a Report starts here marker shows the boundary; the old button is renamed Report new steps only; and an export whose report covers none of the recorded steps is refused with that explanation rather than written empty.
PUT /api/record/report_start {index}.
xcell 0.4.0
- Add menu replaces Draw, and text labels on embeddings (toolbar → Add). The toolbar's Draw button is now Add, its menu grouped as Shape (Lasso, Polygon), Line (Pencil, Smooth Curve, Segmented Line) and Text. In Text mode a click on the plot places a label and a click on a label opens an editor for its text (multi-line), size, color, bold, italic, alignment, rotation, and an optional background box with color and opacity; a drag moves it. Positions are in the embedding's data coordinates (sizes in screen pixels), so labels stay on their cells under pan and zoom and travel with Adjust's rotate, flip and quilt moves (only the anchor moves; labels stay upright). A label belongs to the embedding and column pair it was placed on, is stored per dataset in
uns['xcell_text_annotations_json'], and is restored on load, so exports carry it; deleting a cell subset with its derived embeddings drops the labels on them. The next label starts in the last one's style.GET/POST /api/text_annotations. Labels are not yet drawn into snapshots or the Figures system. Design note:docs/superpowers/specs/2026-10-30-add-menu-pca-hits-obs-manager-design.md. - PCA Loadings: gene-set hits (Analyze → Cells → PCA Loadings). A gene field above the loadings table (comma, semicolon, space or newline separated; or filled from a Gene Panel set, up and down genes together, via From gene set…) marks each listed gene that appears in a PC's displayed top-N positive or negative list: accent chip in the list, an accent bar on the row, and a Hits column as
total (pos+/neg−). Matching ignores case, so a human-cased set still hits mouse symbols. Order PCs: Most gene-set hits sorts by total hits, ties and zero-hit PCs by PC number; the checked PCs for a PC subset are keyed by PC number, so reordering does not change them. A summary line gives how many of the genes appear in the top N of at least one PC and how many PCs have hits, and a muted line lists the genes in no displayed list (they may load just below the top N). Computed in the browser over the table as shown (lib/pcaLoadingHits.ts); no backend change. The gene field clears on a dataset switch and survives a PCA re-run. - .obs manager (Cells panel →
⚙ .obs). A table of every.obscolumn with its kind (categorical, boolean, integer, float, string, other), pandas dtype, unique and missing counts, and a preview: the three most frequent values, or min · median · max over the finite values. Sort by name, type, unique or missing; filter by name and by kind. The colour-by column, saved-subset membership columns, tool prefixes (UCell_,leiden,subset_, …) and stored palettes are marked. Tick columns, shift-click for a range or tick all shown, then Delete (one recorded step; the confirm dialog names any saved subset that goes with its column, and colour palettes go too) or Export (TSV with cell ids, through the existing annotations export). Per column: Rename (moves<col>_colors; refuses a taken name and a saved subset's column), Duplicate, and Convert to categorical, string (missing stays missing), numeric (refused with a count and an example of a value that does not parse) or boolean (columns with at most two values and none missing; true/false, yes/no, 1/0 read themselves, otherwise you pick which value is True). Every operation drops a converted column's palette, refreshes the schema and the Cells panel, and has acodegenentry that replays it exactly in the notebook export.GET /api/obs/columns,POST /api/obs/delete_columns,/api/obs/rename_column,/api/obs/duplicate_column,/api/obs/convert_column(column names in the body, so a name containing/works). Note that AnnData stores string columns as categoricals when writing h5ad, so a conversion to string lasts only for the session. - Filter Cells: mitochondrial fraction, and cutoffs at ± k MAD (Analyze → Preprocess → Filter Cells). A third histogram shows each cell's percentage of counts from mitochondrial genes, with draggable Min/Max % mito cutoffs bound to two new thresholds (
min_pct_mt,max_pct_mt). Mitochondrial means a boolean.var['mt']column when one exists, else gene names startingmt-in either case; the panel says which and how many, and says so when neither applies. Each histogram has a ± MAD box: typing k places both cutoffs at median ± k × MAD (unscaled, as in scipy and the sc-best-practices QC chapter) on the axis as drawn — the log axis for counts and genes, linear for the percentage — and a cutoff that would fall outside the data is left unset. The box is a shortcut, not a parameter: it fills the same thresholds the lines and the inputs set, and clears itself when one is changed by hand. The notebook export reproduces a mitochondrial threshold as the same per-cell percentage over the recorded gene set, since scanpy'sfilter_cellshas no such option.GET /api/scanpy/filter_cells/qcaddspct_mtandmt_source. - Filter Genes: threshold histograms (Analyze → Preprocess → Filter Genes). The same panel as Filter Cells, per gene: total counts and cells expressing, with draggable cutoffs for Min/Max counts and Min cells / Max cells and a live count of the genes that pass. The cells chart is drawn in cells while Min cells stays a percentage of the dataset; a dragged cutoff converts through the same rounding the request uses, so the line shows the count scanpy will be given.
GET /api/scanpy/filter_genes/qc. - Exclude Genes: patterns preset by species (Analyze → Preprocess → Exclude Genes). When the gene names say human, the pattern field opens as
^MT-, ^ENS, ^RPS, ^RPL, ^LINCinstead of the mouse^mt-, ^Gm\d+, ^Rps, ^Rpl. Only the stock default is replaced: a value from the user config, or an edit, stays. - Heatmap: order cells by similarity (Heatmap → Configure → Cell Ordering, and the expression-heatmap figure). By similarity (clustered) lays the columns out in dendrogram leaf order of an average-linkage clustering of the cells on the selected genes, each gene scaled to its own range so none dominates the distance, before the cells are binned; Category, then similarity does the same inside each category block. Above 5,000 cells (
heatmap.SIMILARITY_EXACT_MAX_CELLS) the cells are first collapsed to 500 k-means centroids, the centroids are clustered, and each centroid's cells are laid out along the axis to the next one; the footer says cells clustered via centroids when that happened (about 4 s at 60k cells × 30 genes). The response carriescell_ordering_method(exact,centroids, or null for the other orderings). A figure whose default ordering is Category, then similarity but has no column degrades to By similarity; an explicit one is refused (400), like the other category orderings. - Heatmap: order genes by similarity (Heatmap → Configure → Gene Ordering, and the expression-heatmap figure). By similarity (clustered) lays the rows out in dendrogram leaf order of an average-linkage clustering of each gene's normalised profile, so genes with the same shape sit together; inside each gene set when sets are shown, like By peak position. An unknown ordering is now refused (400) rather than silently drawn as provided.
xcell 0.3.0
-
CNV inference and clone calling (Analyze → Cells → CNV inference). An inferCNV-style analysis for tumor data: log expression relative to reference (normal) cells you tick from a categorical column, clipped at ±3, averaged in windows of 100 genes every 10 along each chromosome, centred per cell, with inferCNV's dynamic noise threshold. Clones come from Leiden on the CNV profile or Ward linkage cut into a fixed number, named by rising CNV burden (
clone_1is the quietest); the result table shows each clone's size, burden, share of the reference cells and dominant input group. Gene positions come from shipped GENCODE tables (human GRCh38, mouse GRCm39,backend/xcell/data/gene_positions_*.tsv.gz, built bybuild_gene_positions.py) matched by Ensembl ID or symbol, or from two.varcolumns. Writesobsm['X_<key>'], a registered per-chromosome score matrixX_<key>_chrom,<key>_scoreand<key>_clone(unassignedoutside the cell mask), anduns['xcell_cnv'][key]. With several reference categories a gene within the range of their means counts as normal (infercnvpy's bounds rule); X and Y are excluded by default. Hierarchical clustering is refused above 20,000 cells.- CNV heatmap figure (new figure kind
cnv_heatmap): cells binned within each group, or one mean row per group, × genome windows with chromosome separators, diverging colours, PNG export. Heatmap figure… in the modal saves one grouped by clone. - Pure
xcell/cnv.py(no new dependencies);prepare_cnvbackground task;GET /api/cnv/status,POST /api/cnv,GET /api/cnv/results;codegenentry so the notebook export replays it. - Benchmarked against copy-number truth (
docs/measurements/2026-10-13-cnv-benchmark.md, harness inbackend/benchmarks/cnv/): the SNU601 and NUGC4 gastric lines with scWGS, the MM199 myeloma and BCC06 carcinoma samples with WES, a four-patient BCC mix for clone recovery and a PBMC diploid control, from Schmid et al. 2025 (Nat Commun). Four changes came out of it: clones are called on the un-thresholded window matrix (patient ARI 0.40 → 0.98), the expression floor drops from 0.1 to 0.02 mean log expression (max F1 up on every dataset), the Leiden resolution default is 0.5 (1.0 cut 9k cells into 24 clones), a reference category needs 50 cells to set the multi-reference bounds (a 44-cell doublet cluster erased every per-cell event in MM199: tumor-vs-normal AUROC 0.46 → 0.92), and immunoglobulin / TCR / MHC genes are excluded by default. Profile accuracy matches or beats infercnvpy on all four truth sets.
- CNV heatmap figure (new figure kind
-
A developmental GO slim, shipped as curated bundles (Genes → Sets → Import). Four new bundles beside the signaling pathways: Developmental GO slim, coarse and fine, each for mouse and human. The coarse bundle is 32 sets, one per major developmental process or organ system on two axes — mechanism (pattern specification, cell fate commitment, stem cell maintenance, gastrulation, blastocyst, epithelial morphogenesis, mesenchyme, migration, proliferation, growth, developmental apoptosis, the signaling pathways, ECM, adhesion, chromatin) and anatomy (nervous, neural crest, circulatory, hemopoiesis, skeletal, muscle, renal, respiratory, digestive, gland, epidermis, sensory, craniofacial, reproductive, limb, placenta, connective tissue) — sized for enrichment (30 to 2,296 mouse genes). The fine bundle nests 200 narrower terms under those as folders (chondrocyte differentiation under skeletal; left/right pattern formation under pattern specification; canonical and non-canonical Wnt, BMP, TGF-β, activin, nodal, Notch, FGF, Hedgehog, retinoic acid, Hippo, ephrin, EGF, PDGF, VEGF and IGF under signaling), sized for scoring cells (1 to 694 genes; 25 terms have fewer than 20 mouse genes and are kept for enrichment). A set is the GO term's annotated genes with descendants included, the same closure as the GO library; by GO's convention regulation of annotations do not propagate, so Ptch1 and Hhip are absent from the Hedgehog set and Dkk1 from Wnt unless annotated to the pathway itself. Human sets come from goa_human directly, not by ortholog mapping. The table is
backend/xcell/data/dev_goslim.tsv(cross=xmarks a fine term placed under a coarse term it does not descend from in GO: osteoblast differentiation under skeletal, liver under digestive) andbuild_dev_goslim.pyregenerates the bundles from it, refusing a wrong, obsolete or misnamed id, an unflagged cross-link, or a duplicate, and printing every size and each sibling pair with Jaccard above 0.5 (somitogenesis ~ somite development 0.82, mesonephros ~ ureteric bud 0.93 are the closest). Built from GO releases/2026-07-26 and the 2026-01-05 GAFs.docs/dev-goslim.mdrecords the derivation for users of the lists: source files and versions, the closure rule and what it excludes, the carve parameters (carve_dev_goslim_candidates.py, 40–350 mouse genes, Jaccard < 0.5, 14 per root), every curation decision, the 32 coarse terms with their sizes, the known redundancies and gaps, and how to regenerate. Design note:docs/superpowers/specs/2026-10-08-dev-goslim-design.md; 30 backend tests. -
GO slims as importable libraries (Genes → Sets → Library → Gene Ontology). The Gene Ontology source now lists, beside GO annotations, three slim libraries: the GO Consortium's generic slim (140 terms), the Alliance of Genome Resources AGR slim (53 terms) for human and mouse, and MGI's mouse slim (45 terms) for mouse. A slim is a
subset:tag on terms inside go-basic.obo, so each library is built from the ontology and GAF already on disk — one set per slim term with ancestors included and no size cap (the ~2,000-gene terms are the point of a slim) — and only downloads the two files if they are not there; refetching GO annotations is still what refreshes them. MGI's own GO-slim page defines its categories with OR/EXCLUDING combinations that, as the page says, standard tools cannot apply, so the mouse slim here is the one MGI distributes through GO. On mouse the generic slim gives 133 sets (7 of its terms have no annotated mouse gene). Catalogues that are code rather than a download (GO, MGI GXD, OmniPath) are no longer served from the cached catalogue file, which would have hidden a library added in a newer build for up to the 7-day TTL.go_semantic.slim_sets; 7 backend tests.