Vocabulary

Methods

CellRef2 is a harmonized human lung and airway single-cell reference constructed with the scALABLE framework in AltAnalyze3. It defines 86 transcriptionally distinct cell states across 15 studies and 27 disease categories. The associated differential index represents 4,494,899 cells from 591 samples.

Reference construction

Seventeen human lung and airway scRNA-seq or snRNA-seq datasets contributed to the candidate reference. MarkerFinder was performed on all author-annotated cell populations to define unique marker genes per cluster. ICGS3, which uses non-negative matrix factorization, was applied within datasets requiring unsupervised cell-state discovery. ICGS-integrate then compared cluster marker sets in a fixed priority order. Candidate clusters required at least three unique markers at Pearson r > 0.3; a cluster was considered redundant when at least 12 of its top 60 markers overlapped an earlier population at a Benjamini-Hochberg false-discovery rate of 0.05 or less.

The reference priority was: Human Lung Cell Atlas; LungMAP Human Lung CellRef v1.1 (Guo 2023 NatCommun); Sun 2026 LungMAP; the TGEN interstitial lung disease collection; Zhang 2026 NatGenet; the UPenn pediatric and postnatal collection represented by Morrisey 2026 LungMAP, Mellors 2025 JCIInsight and Guo 2023 NatCommun; and Deutsch 2026 LungMAP. Unsupervised candidates were evaluated after these annotated references in the following order: UPenn pediatric development, Basil 2022 Nature, Natri 2024 NatGenet, Adams 2020 SciAdv, the combined Perl 2026 LungMAP, Uehara 2023 NatCommun and Guo 2023 NatCommun collection, Guo 2023 AJRCCM, Jaiswal 2026 CellGenom, Sun 2026 LungMAP, Olatoke 2023 SciAdv and Wang 2020 eLife.

All 717 input clusters were also tested by hypergeometric enrichment against 331 published LungMAP Cell Nomenclature and CellCards marker panels. This evidence restored five candidates removed during automated redundancy filtering; a Langerhans candidate was added separately. Final annotation considered unique markers, GO-Elite BioMarkers enrichment, centroid similarity and the CellCards evidence. Each of the final 86 states was mapped to a CellCards term, using a broader term when no exact term was available, and assigned a standardized name and Cell Ontology term. LungMAP Cell Nomenclature identifiers were recorded where available.

Reclassification and final reference

Ninety-two candidate states were reclassified in two rounds with cellHarmony using the UPenn source collection assembled by the Morrisey laboratory. This collection comprised 978,892 scRNA-seq cells from 83 unique donors in 120 libraries: Morrisey 2026 LungMAP contributed 523,972 cells from 54 donors, Guo 2023 NatCommun contributed 354,570 cells from 24 donors and Mellors 2025 JCIInsight contributed 100,350 cells from 6 donors; one donor was represented in two study records. The collection contained 628,702 cells from 80 10x 3′ v3 libraries and 350,190 cells from 40 10x 3′ v2 libraries.

The 83 donors comprised 59 normal controls and 24 donors with COPD, LAM, CLAD-associated or cGVHD-associated bronchiolitis obliterans syndrome, idiopathic pulmonary fibrosis, pulmonary veno-occlusive disease, systemic juvenile idiopathic arthritis-associated lung disease, Hermansky-Pudlak syndrome, bleomycin-associated interstitial lung disease or other interstitial lung disease. The final v7 reference was constructed exclusively from this UPenn collection. Up to 500 cells per retained cell state were selected by cellHarmony alignment score.

Five candidate states were excluded because they lacked sufficient unique marker support after projection. The Preterminal bronchiolar secretory candidate was also excluded because it was not consistently separable from AT2 cells across datasets. The resulting reference contains 40,383 cells across 86 cell states and 35,049 genes. Author annotations from each input study were compared with the final assignments as a validation step.

Workflow

The analysis used ICGS3 for unsupervised cell state detection by non-negative matrix factorization, MarkerFinder for markers and centroids, ICGS-integrate for staged redundancy testing, GO-Elite for annotation from marker enrichment, HOPACH for lineage ordering, cellHarmony-align for cell state assignment, UMAP-approximate for placement on the reference embedding, metacell-random for aggregation, rna2adt, rna2lipid and rna2grn for modality imputation, fastComm for receptor-ligand communication, and cellHarmony-differential for testing. Exact commands and parameters are provided in the downloadable notebook.

For rna2grn, an Elastic Net model was trained separately for each transcription- factor-to-gene edge using ChromLinker predictions. These predictions were generated from IPF and control lung-biopsy 10x Multiome profiles containing paired single-nucleus RNA-seq and ATAC-seq (GSE286182), analyzed with scALABLE and ChromLinker. Training retained the 50 highest-scoring edges per transcription factor and cell type. The rna2lipid models were trained on matched LungMAP human bulk RNA-seq and lipidomics measurements.

Metadata harmonization

Study metadata were mapped to the CELLxGENE schema and extended with harmonized lung-specific clinical and technical fields. Library, sample and donor identifiers were linked in side tables, and expression-derived sex assignments were compared with recorded metadata before missing values were imputed. The released metadata contain 654 libraries from 556 samples and 514 donors.

Metacells and controlled-access data

Open-study metacells contain 7–20 cells from one cell state and one biological sample. For the controlled-access Zhang 2026 NatGenet COPD cohort, 83,416 metacells were provided across 178 de-identified meta-samples. Each metacell contains 10, 15 or 20 nuclei from one cell state and two or three metadata-matched donors. Continuous clinical covariates—including age, BMI, FEV1 percent predicted, FEV1/FVC, DLCO, smoking pack-years and GOLD score—are cell-count- weighted across the contributing donors. Categorical covariates, including disease status, sex and smoking status, are provided as matched-pool summaries. Donor identifiers and the underlying mixture weights are not released.

Differential analysis

Differential results were computed from both sample-level pseudobulks and metacells, with pseudobulk used when sample counts supported it. Pseudobulk comparisons used a moderated t test with fixed variance shrinkage of 0.2 toward the median feature variance. Metacell comparisons used the Wilcoxon rank-sum test and were capped at 100 metacells per cell state per contrast arm; this unit was used when either arm contained fewer than five samples. The controlled-access COPD cohort was tested with donor-level pseudobulks, not metacells.

Analyses required at least three replicates per group and used Benjamini-Hochberg adjustment with a false-discovery threshold of 0.1. A 1.2-fold minimum was applied to RNA; no fold-change minimum was applied to ADT, lipid, gene-regulatory-network or ligand-receptor features.

Test statistics were calculated for all features. Benjamini-Hochberg correction was restricted to features with expression above 0.1 in at least two replicates. Features outside this detection set retain their fold change and raw p value and receive an adjusted p value of 1.0.

The interface distinguishes measured RNA from model-derived features. The rna2adt prediction model was trained on denoised antibody-derived tag measurements from the Deutsch 2026 LungMAP CITE-seq study. ADT abundance, lipid species, regulatory edges and transcription-factor activity were inferred from transcriptomic profiles.

Downloads

• Study information — One row per contributing study: title, description, abstract, accession, LungMAP identifier, PMID, DOI and every link out. 17 rows, 30 columns.
• Harmonized library metadata — One row per sequencing library, harmonized onto the CELLxGENE schema with the clinical and technical fields that schema omits. 654 rows, 68 columns.
• Cell state to CellCards and Cell Nomenclature mapping — One row per CellRef2 cell state: long name, short name, superclass, CellCards term, Cell Ontology term, LungMAP LMCC identifier and the Cell Nomenclature aliases. 86 rows, 9 columns.
• AltAnalyze3 command reference (Jupyter notebook) — Every AltAnalyze3 entry point that built CellRef2 and its differential index, in run order, with the parameters each stage used. 42 cells.

Every cell state name, study acronym and disease label in these tables was compared against the served LungMAP.net database and matched, so the names in the downloads and the names the site reports are one set.

The Single-Cell Matrix Service provides single-cell count matrices in which controlled-access metadata are masked, together with metacell count matrices carrying assigned metadata.