scFair

scFair is drop-in HVG selection for single-cell RNA-seq aimed at two problems every pipeline hits — plus an optional density population count:

Optional: estimate_n_populations reads a 3D density field after sc.pp.neighbors (how many populations, without sweeping Leiden resolution; works best up to ~20 well-separated populations).

Docs: Read the Docs.

What you need

• Python 3.10+ (tested 3.10–3.12)
• An AnnData object with raw integer counts in .X or layers["counts"]

Install

pip install scfair

First run

import scanpy as sc
import scfair as scf

# raw integer counts in .X or layers["counts"]
scf.pp.highly_variable_genes(adata)
# annotates adata.var["highly_variable"]; keep the full gene matrix
# (scanpy PCA uses that mask by default — no manual subset step)

sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.scale(adata, max_value=10)
sc.tl.pca(adata)
sc.pp.neighbors(adata)
sc.tl.leiden(adata, flavor="igraph", n_iterations=2, directed=False)

Default path: structure auto-n + same-rank append (cutoff buffer). Auto runs extra multi-seed graph builds and is slower than a fixed k — that is by design. A silent wrong list length is more expensive than the compute. Read adata.uns["scfair"]["hvg"]["auto_message"] for a one-line summary of the chosen base size. Use a fixed int only for a locked paper/protocol:

scf.pp.highly_variable_genes(adata, n_top_genes=2000)

Pure top-k (no buffer):

scf.pp.highly_variable_genes(adata, n_top_genes=2000, balance_method="none")

Population count without resolution sweep (after neighbors):

sc.pp.neighbors(adata)
est = scf.pp.estimate_n_populations(adata)
print(est.n_populations, est.confidence)

Status

0.8.0 (Beta). Import as import scfair as scf and use names in scfair.__all__ and scf.pp. See the API reference.

Next steps

1. Installation
2. Quickstart
3. Tutorial: PBMC 10k misclustered cells vs standard HVG
4. FAQ if something looks off

License

Software: Apache License 2.0.

Author

Zhao Li (李钊)
Email: leelieber@gmail.com