pace.pace_model#

pace.pace_model(counts, x=None, y=None, cell_type=None, image=None, *, genes=None, types=None, h_bio=30.0, h_tech=5.0, eps=None, condition=None, condition_name='condition', condition_levels=None, min_effective=30.0, within_image=True, kernel_per_image=False, homotypic_fraction=0.5, ambient_mode='cache', n_iter=32, min_iter=12, chunk_size=128, n_threads=1, verbose=False, spatial_key='spatial', layer=None)[source]#

Fit the PACE model, without the reporting layers.

The equivalent of paceModel(). Takes either a cells-by-genes count matrix with coordinates and labels, or an AnnData, in which case the coordinates come from obsm[spatial_key] and the labels from obs[cell_type]. pace_fit() runs this and the three reporting stages.

Parameters:

  • counts – Sparse cells by genes counts. Note the orientation: AnnData.X is already cells by genes, but a SpatialExperiment assay is the other way round.

  • x – Cell coordinates, in the same units as the bandwidths.

  • y – Cell coordinates, in the same units as the bandwidths.

  • cell_type – One label per cell.

  • types – The cell types, in the order they should index the random-effect rows. Note that R builds its formula by pasting the names together, without backticks, so a name that is not a syntactic R name (“T-NK”, “CD8+”, “arm 2”) fails there outright. Such a panel fits here but has no R counterpart to be compared against. None sorts the observed labels, which is Python’s byte order and NOT R’s: R sorts under LC_COLLATE, so a label set mixing cases orders differently (“epithelial” sorts before “T-NK” in R, after it here). The fit is equivariant under a permutation of types, so the science is unchanged, but the row order is not, and the two stop being bit-identical. Pass the types explicitly to match a given R fit.

  • image – One label per cell, or None for a single image.

  • kernel_per_image – Whether to build neighbourhoods within each image rather than over all cells at once. False, matching R: a cohort whose images are fields of view of one section wants the global search. Set it True when the images are separate samples. The contamination field is always per-image regardless, as it is in R.

  • spatial_key – Only used when the first argument is an AnnData: which obsm key holds the coordinates, and which layer holds the counts (None for X).

  • layer – Only used when the first argument is an AnnData: which obsm key holds the coordinates, and which layer holds the counts (None for X).

  • ambient_mode – “cache” (default) materialises the whole cells-by-genes ambient product, as R’s default does. “stream” keeps only the weight matrix and recomputes each chunk’s columns from it, which is what lets a full transcriptome panel fit in memory: on a million cells by five thousand genes the cached product alone is several GB. The numbers are the same either way, since cache mode forms its product with the same routine and the two differ only in chunking.

  • condition – One label per cell, or – when the first argument is an AnnData – the name of the obs column holding them, whose name then becomes the prefix of the condition’s terms. Given one, the model gains a condition main effect in the fixed design and a condition-by-neighbour interaction in the random-effect block, which is the responder layer: ~ 1 + condition * (types), as in R.

  • condition_name – The name the condition’s terms are built from, so a two-level condition called “Responder” with levels PD and PR gives the term ResponderPR. In R this is the colData column name; here it has to be passed, because an array has no name. fit_anndata() uses the obs key.

  • condition_levels –

    The levels in order. The first is the reference and is dropped, as R’s default treatment contrasts drop it.

    This is NOT the same caveat as types, and the difference matters. A permutation of types relabels the output and leaves the science alone. The condition’s first level is the arm everything else is contrasted against, so it decides what the baseline neighbour slopes mean and which way the interaction points. R picks it with levels(factor(…)) under LC_COLLATE; leaving this None picks it by byte order, and the two disagree on labels as ordinary as {“Responder”, “non-responder”}, where the fitted slopes then differ by 2 rather than being reordered. Leaving it None warns for that reason.

Return type:

PaceFit