cellrank.models.GAM

class cellrank.models.GAM(adata, n_knots=6, spline_order=3, distribution='gamma', link='log', max_iter=2000, expectile=None, grid=None, spline_kwargs=mappingproxy({}), **kwargs)

Fit Generalized Additive Models (GAMs) using pygam.

Parameters:

• adata (AnnData) – Annotated data object.

• n_knots (int | None) – Number of knots.

• spline_order (int) – Order of the splines, e.g., \(3\) for cubic splines.

• distribution (Literal['normal', 'binomial', 'poisson', 'gamma', 'gaussian', 'inv_gauss']) – Name of the distribution. Available distributions can be found here.

• link (Literal['identity', 'logit', 'inverse', 'log', 'inv_squared']) – Name of the link function. Available link functions can be found here.

• max_iter (int) – Maximum number of iterations for optimization.

• expectile (float | None) – Expectile for ExpectileGAM. This forces the distribution to be 'normal' and link function to 'identity'. Must be in \((0, 1)\).

• grid (str | Mapping[str, Any] | None) – Whether to perform a grid search. Keys correspond to a parameter names and values to range to be searched. If 'default', use the default grid. If None, don’t perform a grid search.

• spline_kwargs (Mapping[str, Any]) – Keyword arguments for s().

• kwargs (Any) – Keyword arguments for the GAM.

Attributes table

adata	Annotated data object.
conf_int	Array of shape (n_samples, 2) containing the lower and upper bound of the confidence interval.
model	Underlying model.
prepared	Whether the model is prepared for fitting.
shape	Number of cells in adata.
signal	The Signal this model was prepared with, or None.
w	Filtered weights of shape (n_filtered_cells,) used for fitting.
w_all	Unfiltered weights of shape (n_cells,).
x	Filtered independent variables of shape (n_filtered_cells, 1) used for fitting.
x_all	Unfiltered independent variables of shape (n_cells, 1).
x_hat	Filtered independent variables used when calculating default confidence interval, usually same as x.
x_test	Independent variables of shape (n_samples, 1) used for prediction.
y	Filtered dependent variables of shape (n_filtered_cells, 1) used for fitting.
y_all	Unfiltered dependent variables of shape (n_cells, 1).
y_hat	Filtered dependent variables used when calculating default confidence interval, usually same as y.
y_test	Prediction values of shape (n_samples,) for x_test.

Methods table

confidence_interval([x_test])	Calculate the confidence interval.
copy()	Return a copy of self.
default_confidence_interval([x_test])	Calculate the confidence interval, if the underlying model has no method for it.
fit([x, y, w])	Fit the model.
plot([figsize, same_plot, hide_cells, perc, ...])	Plot the smoothed gene expression.
predict([x_test, key_added])	Run the prediction.
prepare([signal, lineage, time_key, ...])	Prepare the model to be ready for fitting.
read(fname[, adata, copy])	De-serialize self from a file.
write(fname[, write_adata])	Serialize self to a file using pickle.

Attributes

adata

GAM.adata

Annotated data object.

conf_int

GAM.conf_int

Array of shape (n_samples, 2) containing the lower and upper bound of the confidence interval.

model

GAM.model

Underlying model.

prepared

GAM.prepared

Whether the model is prepared for fitting.

shape

GAM.shape

Number of cells in adata.

signal

GAM.signal

The Signal this model was prepared with, or None.

w

GAM.w

Filtered weights of shape (n_filtered_cells,) used for fitting.

w_all

GAM.w_all

Unfiltered weights of shape (n_cells,).

x

GAM.x

Filtered independent variables of shape (n_filtered_cells, 1) used for fitting.

x_all

GAM.x_all

Unfiltered independent variables of shape (n_cells, 1).

x_hat

GAM.x_hat

Filtered independent variables used when calculating default confidence interval, usually same as x.

x_test

GAM.x_test

Independent variables of shape (n_samples, 1) used for prediction.

y

GAM.y

Filtered dependent variables of shape (n_filtered_cells, 1) used for fitting.

y_all

GAM.y_all

Unfiltered dependent variables of shape (n_cells, 1).

y_hat

GAM.y_hat

Filtered dependent variables used when calculating default confidence interval, usually same as y.

y_test

GAM.y_test

Prediction values of shape (n_samples,) for x_test.

Methods

confidence_interval

GAM.confidence_interval(x_test=None, **kwargs)

Calculate the confidence interval.

Parameters:

• x_test (ndarray | None) – Array of shape (n_samples,) used for confidence interval calculation. If None, use x_test.

• kwargs (Any) – Keyword arguments for underlying model’s confidence method or for default_confidence_interval().

Return type:

ndarray

Returns:

: Returns self and updates the following fields:

copy

GAM.copy()

Return a copy of self.

Return type:

BaseModel

default_confidence_interval

GAM.default_confidence_interval(x_test=None, **kwargs)

Calculate the confidence interval, if the underlying model has no method for it.

This formula is taken from [DeSalvo, 1970], eq. 5.

Parameters:

• x_test (ndarray | None) – Array of shape (n_samples,) used for confidence interval calculation. If None, use x_test.

• kwargs (Any) – Keyword arguments for underlying model’s confidence method or for default_confidence_interval().

Return type:

ndarray

Returns:

: Returns self and updates the following fields:

Also updates the following fields:

• x_hat - Filtered independent variables used when calculating default confidence interval, usually same as x.

• y_hat - Filtered dependent variables used when calculating default confidence interval, usually same as y.

fit

GAM.fit(x=None, y=None, w=None, **kwargs)

Fit the model.

Parameters:

• x (ndarray | None) – Independent variables, array of shape (n_samples, 1). If None, use x.

• y (ndarray | None) – Dependent variables, array of shape (n_samples, 1). If None, use y.

• w (ndarray | None) – Optional weights of x, array of shape (n_samples,). If None, use w.

• kwargs (Any) – Keyword arguments for underlying model’s fitting function.

Return type:

GAM

Returns:

: Fits the model and returns self.

plot

GAM.plot(figsize=(8, 5), same_plot=False, hide_cells=False, perc=None, fate_prob_cmap=<matplotlib.colors.ListedColormap object>, cell_color=None, lineage_color='black', alpha=0.8, lineage_alpha=0.2, title=None, size=15, lw=2, cbar=True, margins=0.015, xlabel='pseudotime', ylabel='expression', conf_int=True, lineage_probability=False, lineage_probability_conf_int=False, lineage_probability_color=None, obs_legend_loc='best', dpi=None, fig=None, ax=None, return_fig=False, save=None, **kwargs)

Plot the smoothed gene expression.

Parameters:

• figsize (tuple[float, float]) – Size of the figure.

• same_plot (bool) – Whether to plot all trends in the same plot.

• hide_cells (bool) – Whether to hide the cells.

• perc (tuple[float, float]) – Percentile by which to clip the fate probabilities.

• fate_prob_cmap (ListedColormap) – Colormap to use when coloring in the fate probabilities.

• cell_color (str | None) – Key in obs or var_names used for coloring the cells.

• lineage_color (str) – Color for the lineage.

• alpha (float) – Alpha value in \([0, 1]\) for the transparency of cells.

• lineage_alpha (float) – Alpha value in \([0, 1]\) for the transparency lineage confidence intervals.

• title (str | None) – Title of the plot.

• size (int) – Size of the points.

• lw (float) – Line width for the smoothed values.

• cbar (bool) – Whether to show the colorbar.

• margins (float) – Margins around the plot.

• xlabel (str) – Label on the x-axis.

• ylabel (str) – Label on the y-axis.

• conf_int (bool) – Whether to show the confidence interval.

• lineage_probability (bool) – Whether to show smoothed lineage probability as a dashed line. Note that this will require 1 additional model fit.

• lineage_probability_conf_int (bool | float) – Whether to compute and show smoothed lineage probability confidence interval.

• lineage_probability_color (str | None) – Color to use when plotting the smoothed lineage_probability. If None, it’s the same as lineage_color. Only used when show_lineage_probability = True.

• obs_legend_loc (str | None) – Location of the legend when cell_color corresponds to a categorical variable.

• dpi (int) – Dots per inch.

• fig (Figure) – Figure to use. If None, create a new one.

• ax (Axes) – Ax to use. If None, create a new one.

• return_fig (bool) – If True, return the figure object.

• save (str | None) – Filename where to save the plot. If None, just shows the plots.

• kwargs (Any) – Keyword arguments for legend().

Return type:

Figure | None

Returns:

: Nothing, just plots the figure. Optionally saves it based on save.

predict

GAM.predict(x_test=None, key_added='_x_test', **kwargs)

Run the prediction.

Parameters:

• x_test (ndarray | None) – Array of shape (n_samples,) used for prediction. If None, use x_test.

• key_added (str | None) – Attribute name where to save the x_test for later use. If None, don’t save it.

• kwargs (Any) – Keyword arguments for underlying model’s prediction method.

Return type:

ndarray

Returns:

: Returns and updates the following fields:

prepare

GAM.prepare(signal=<object object>, lineage=<object object>, time_key=<object object>, backward=False, time_range=None, data_key=<object object>, use_raw=<object object>, threshold=None, weight_threshold=(0.01, 0.01), filter_cells=None, n_test_points=200, *, gene=<object object>)

Prepare the model to be ready for fitting.

Parameters:

• signal (str | Signal) –

  The observation-aligned quantity to fit along the trajectory. Either a Signal (Gene, Obs or Obsm) or, as a shorthand, a gene name in var_names (equivalent to Gene).

  Added in version 2.3.

• lineage (str | None) – Name of the lineage. If None, all weights will be set to \(1\).

• time_key (str) – Key in obs where the pseudotime is stored.

• backward (bool) – Direction of the process.

• time_range (float | tuple[float, float] | None) –

  Specify start and end times:

  • tuple - it specifies the minimum and maximum pseudotime. Both values can be None, in which case the minimum is the earliest pseudotime and the maximum is automatically determined.

  • float - it specifies the maximum pseudotime.

• data_key (str | None) –

  Deprecated since version 2.4: Pass a Signal via signal instead, e.g. Gene(name, layer=...) or Obs(name).

• use_raw (bool) –

  Deprecated since version 2.4: Pass Gene(name, use_raw=True) via signal instead.

• gene (str | Signal) –

  Deprecated since version 2.4: Renamed to signal, which also accepts Signal objects.

• threshold (float | None) – Consider only cells with weights > threshold when estimating the test endpoint. If None, use the median of the weights.

• weight_threshold (float | tuple[float, float]) – Set all weights below weight_threshold to weight_threshold if a float, or to the second value, if a tuple.

• filter_cells (float | None) – Filter out all cells with expression values lower than this threshold.

• n_test_points (int) – Number of test points. If None, use the original points based on threshold.

Return type:

BaseModel

Returns:

: Nothing, just updates the following fields:

• x - Filtered independent variables of shape (n_filtered_cells, 1) used for fitting.

• y - Filtered dependent variables of shape (n_filtered_cells, 1) used for fitting.

• w - Filtered weights of shape (n_filtered_cells,) used for fitting.

• x_all - Unfiltered independent variables of shape (n_cells, 1).

• y_all - Unfiltered dependent variables of shape (n_cells, 1).

• w_all - Unfiltered weights of shape (n_cells,).

• x_test - Independent variables of shape (n_samples, 1) used for prediction.

• prepared - Whether the model is prepared for fitting.

read

static GAM.read(fname, adata=None, copy=False)

De-serialize self from a file.

Parameters:

• fname (str | Path) – Path from which to read the object.

• adata (AnnData | None) – AnnData object to assign to the saved object. Only used when the saved object has adata and it was saved without it.

• copy (bool) – Whether to copy adata before assigning it. If adata is a view, it is always copied.

Return type:

IOMixin

Returns:

: The de-serialized object.

write

GAM.write(fname, write_adata=True)

Serialize self to a file using pickle.

Parameters:

• fname (str | Path) – Path where to save the object.

• write_adata (bool) – Whether to save adata object.

Return type:

None

Returns:

: Nothing, just writes itself to a file.