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.

Return type:

AnnData

Parameters:

adataad.AnnData

AnnData object containing the data matrix and metadata.

feature_namestr

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_boundfloat, 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_boundfloat, 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:

ad.AnnData

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}".

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.