scFair

scFair selects highly variable genes (HVGs) for single-cell RNA-seq. It handles two choices most pipelines already make, plus an optional population count:

Optional: estimate_n_populations counts populations from a 3D density field after sc.pp.neighbors. It works best on well-separated data with up to about 20 populations.

Docs: Read the Docs.

What you need

• Python 3.10+ (tested 3.10–3.12)
• For the default seurat_v3 flavor, an AnnData object with raw integer counts in .X or layers["counts"]

Install

pip install scfair
# or: conda install -c conda-forge -c bioconda scfair

Details: installation guide.

First run

import scanpy as sc
import scfair as scf

# the default seurat_v3 flavor expects 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.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. Auto runs extra multi-seed graph builds and is slower than a fixed k. Read adata.uns["scfair"]["hvg"]["auto_message"] for a one-line summary of the chosen base size. Fixed length for a locked protocol:

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

Pure top-k (no append tail):

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

Population count after neighbors:

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

Status

0.10.1 (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. Tutorials
4. FAQ if something looks off

Citation

If you use scFair in published work, please cite the preprint:

Zhao Li, Aaron James, Shengxuan Li.
scFair: Geometry-Aware Gene Budgets and Same-Rank Extension for Highly Variable Gene Selection.
bioRxiv (2026). https://doi.org/10.64898/2026.08.08.743679

@article{li2026scfair,
  title   = {scFair: Geometry-Aware Gene Budgets and Same-Rank Extension for Highly Variable Gene Selection},
  author  = {Li, Zhao and James, Aaron and Li, Shengxuan},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.08.08.743679},
  url     = {https://www.biorxiv.org/content/10.64898/2026.08.08.743679v1},
}

For the software record, cite the Zenodo DOI. Pin the package version used in the analysis, for example scfair==0.10.1. See CITATION.cff.

License

Software: Apache License 2.0.

Author

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