Sc Filter

sc-filter

When to use

The user has reviewed sc-qc output and now wants to actually drop low-quality cells and lowly-detected genes — by per-cell thresholds (--min-genes, --max-genes, --max-mt-percent, --min-counts, --max-counts, --min-cells) or tissue-specific presets (--tissue brain / pbmc / etc.). This skill removes cells; it does not normalise, cluster, or annotate.

Use from a step

filtering = load_skill("sc-filter")
before = read_input("results/01_qc/intermediate/adata_qc.h5ad")
after = filtering.filter_cells(before, tissue="pbmc")
write_output(filtering.filter_summary(after), "tables/filter_summary.csv")
write_output(filtering.filter_stats_table(after), "tables/filter_stats.csv")
write_output(after, "intermediate/adata_filtered.h5ad")

Run doublet detection before filtering when doublets should be removed. In the next preprocessing step, call preprocess(after, apply_filters=False) to keep these cells and genes. A complete demo step is in examples/example_step.py.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

filter_cells(adata, *, min_genes: int=200, max_genes: int | None=None, min_counts: int | None=None, max_counts: int | None=None, max_mt_percent: float | None=20.0, min_cells: int=3, tissue: str | None=None, remove_doublets: bool=True, doublet_score_threshold: float=0.25)

Return a filtered copy of an AnnData, with counts and matrix contracts.

Existing QC columns are reused. Otherwise counts are selected from the input's counts layer, raw snapshot or X and missing QC metrics are computed. A normalized X with existing QC metrics is preserved. Doublet removal reads existing obs columns; it does not run doublet detection.

:param min_genes: Minimum detected genes per cell. Default 200. :param max_genes: Maximum detected genes per cell; None leaves it uncapped. :param min_counts: Minimum counts per cell; None disables this threshold. :param max_counts: Maximum counts per cell; None disables this threshold. :param max_mt_percent: Maximum mitochondrial percentage. Default 20.0; None disables the threshold. :param min_cells: Minimum retained cells expressing a gene. Default 3. :param tissue: Preset from tissue_presets(); overrides min_genes, max_genes and max_mt_percent. None uses the supplied thresholds. :param remove_doublets: Drop cells marked by predicted_doublet, or by doublet_score when the boolean column is absent. Default True. :param doublet_score_threshold: Score cutoff for the score-only case. Default 0.25. :returns: A new AnnData with retained cells and genes; run_info records effective thresholds, the count source and the filtering summary. :raises ValueError: Input requiring QC metrics has no count-like matrix.

run_info(adata, *, keep: bool=True) -> dict

Read the filtering record from the returned AnnData.

:param keep: False removes the record from uns; default True keeps it. :returns: summary, effective_params, input_contract and matrix_contract; an empty dict when filter_cells has not run. outliers_flagged counts existing outlier flags, which do not themselves remove cells.

filter_summary(adata) -> pd.DataFrame

Return retention counts and effective thresholds as metric/value rows.

:param adata: The result of filter_cells. :returns: A DataFrame matching the CLI's tables/filter_summary.csv.

filter_stats_table(adata) -> pd.DataFrame

Return metric/value rows for threshold removals and existing outlier flags.

Threshold counts can overlap. outliers_flagged is a count of flags, not removals. doublets_removed counts doublets remaining after QC thresholds.

retention_table(adata) -> pd.DataFrame

Return Cells and Genes rows with before/after counts from filter_cells.

filter_state_table(before, after) -> pd.DataFrame

Return QC metrics and Retained/Removed labels for every input cell.

Missing QC columns are calculated on a copy using filter_cells' input preparation. The index contains the original cell names.

tissue_presets() -> dict

Return copies of the shared QC presets, including their descriptions.

Each preset has min_genes, max_genes and max_mt (a percentage). These replace the corresponding filter_cells thresholds when tissue is set.

filter_figure(before, after)

Return a matplotlib Figure comparing cell and gene counts before and after filtering.

<!-- api:end -->