diffsvg.pp.bin_obs#

diffsvg.pp.bin_obs(adata, anchor, condition, genes=None, n_bsplines=10, degree=3, n_bins=50, window_radius=None, layer=None, design_matrix='design_matrix', inplace=True, sample=None)#

Assign each cell a bin along anchor, bin every gene’s expression, and precompute the spline design matrices diffsvg.tl.setup_model needs.

This is the preprocessing step: it only bins/reshapes data (via bin_counts) and builds the (gene-independent) B-spline design matrices. It does not touch PyMC at all - diffsvg.tl.setup_model reads its output back off adata and defines the actual model.

Parameters:
adata

Annotated data matrix. adata.obsm["design_matrix"] must contain anchor (assumed to lie in [0, 1]) and condition (must have exactly two levels).

anchor

Column in adata.obsm["design_matrix"] giving the ordering coordinate (e.g. pseudotime, spatial distance) that the spline basis is built on.

condition

Column in adata.obsm["design_matrix"] giving the two groups to compare (e.g. control vs. treatment). Pass None for data without conditions: binning then runs along anchor only, and the result supports the condition-free models used by diffsvg.tl.fit_profiles/diffsvg.tl.one_vs_rest.

genes default: None

Genes to model. Defaults to all of adata.var_names.

n_bsplines default: 10

Number of B-spline basis functions used for both the anchor effect and its condition-interaction.

degree default: 3

Degree of the B-spline basis (3 = cubic).

n_bins default: 50

Number of bins spanning anchor in [0, 1]; the fitting/prediction grid has n_bins + 1 points. Every cell is also assigned to its nearest of these n_bins + 1 bin centers (see bin_assignment below).

window_radius default: None

Half-width of the averaging window used by bin_counts (independent of, and typically wider than, half a bin - a cell can contribute to several neighboring bins’ averages even though it is only ever assigned to one). Overlapping windows make neighbouring bins share cells, which the models treat as independent, so their uncertainty comes out too small. None bins every cell once, in its assigned bin, and records the cell counts and within-bin spread; the fitters then weight each bin by its cell count, so a binned fit matches a fit on the cells (needed for calibrated test="parallel" p-values). None is the default. With overlapping windows the rows are still weighted by how many cells they average (so a sparse edge window does not count as much as a full one), but neighbouring rows stay correlated and the p-values too small.

layer default: None

If given, use adata.layers[layer] instead of adata.X.

design_matrix default: 'design_matrix'

adata.obsm key of the design matrix. Defaults to "design_matrix".

sample default: None

Column in adata.obsm["design_matrix"] naming the biological replicate of every cell (e.g. donor, animal or organoid), for data with several replicates per condition. Each replicate must belong to one condition. Several sections of one donor are one replicate, so name the donor here, not the section. Bins are then built per replicate (one row per replicate and bin, contiguous: needs window_radius=None), and the fitters add a random level and a random curve per replicate, so that the condition curves are compared against the variation between replicates rather than between cells (see diffsvg.tl.fit_model).

inplace default: True

If True (default), write adata.obs[f"{anchor}_bin"] (each cell’s assigned bin index) and adata.uns["binned"] (everything diffsvg.tl.setup_model needs) and return None. If False, leave adata untouched and return the BinnedData instead.

Returns:

None or BinnedData