opendvp.tl.filter_by_abs_value

filter_by_abs_value(adata, feature_name, lower_bound=None, upper_bound=None, mode='absolute')

Filter cells in an AnnData object by a range of values for a specified feature.

This function creates a boolean mask for each cell based on a feature’s value, using either absolute thresholds or quantile-based thresholds. The feature can be a marker from adata.X or a continuous variable from adata.obs. Cells with feature values within the specified lower and upper bounds (inclusive) will pass the filter.

Parameters:

• adata (anndata.AnnData) – AnnData object containing the data matrix and metadata.

• feature_name (str) – Name of the feature to filter on. The function will automatically determine if this feature is a marker in adata.var_names or a continuous variable in adata.obs. If found in both, a ValueError will be raised.

• lower_bound (float, int, or None, default None) – The lower threshold for filtering. If None, no lower bound is applied. If mode is ‘absolute’, this is the direct value. If mode is ‘quantile’, this is the quantile (0 <= value <= 1).

• upper_bound (float, int, or None, default None) – The upper threshold for filtering. If None, no upper bound is applied. If mode is ‘absolute’, this is the direct value. If mode is ‘quantile’, this is the quantile (0 <= value <= 1).

• mode ({'absolute', 'quantile'}, default 'absolute') – Determines how lower_bound and upper_bound are interpreted: ‘absolute’: Bounds are direct numerical values. ‘quantile’: Bounds are quantiles (e.g., 0.25 for 25th percentile).

Returns:

A copy of the input AnnData with a new boolean column in .obs indicating which cells passed the filter. The new column name will be f"{feature_name}_filtered_by_{mode}".

Return type:

anndata.AnnData

Raises:

ValueError – If feature_name is not found in adata.var_names or adata.obs.columns, if feature_name is found in both, if bounds are invalid, or if the adata.obs column is not numeric when used for filtering.