Verify sample sex annotation using sex-specific gene expression

Compares each sample's annotated sex against pseudobulk expression of sex-specific genes. Sex is called at the sample level (averaged across all cells in the donor), not per cell. This avoids false positives from single-cell dropout: a female cell may fail to capture XIST in any given sequencing run, but a truly male sample will have zero XIST across all cells.

Usage

CheckSex(
  seurat_object,
  sex_col = "sex",
  sample_col = "Sample",
  cell_type_col = NULL,
  species = NULL,
  female_genes = NULL,
  male_genes = NULL,
  assay = NULL,
  layer = "data",
  noise_floor = 0.05,
  output_dir = NULL,
  plot = TRUE
)

Arguments

seurat_object

A Seurat object.

sex_col

Character. Metadata column containing annotated sex. Accepted values: "F"/"M", "Female"/"Male", "female"/"male", "1"/"2". Default "sex".

sample_col

Character. Metadata column identifying donors/samples. Used for per-donor pseudobulk aggregation. NULL skips sample-level analysis and returns only per-cell scores for visualisation. Default "Sample".

cell_type_col

Character or NULL. When supplied, a per-cell-type pseudobulk table is computed in addition to the sample-level table — useful for distinguishing BMT/chimerism (cell-type-specific mismatch) from labeling errors (all cell types mismatched). Default NULL.

species

Character. "mouse", "human", or "zebrafish". Auto- detected from AnnotateFeatures() if previously run. Zebrafish has no universal sex-gene defaults — supply female_genes and male_genes.

female_genes

Character vector or NULL. Override default female marker genes. When NULL the package defaults are used (XIST/Tsix with automatic X-paralog fallback).

male_genes

Character vector or NULL. Override default male marker genes. When NULL the package defaults are used.

assay

Character or NULL. Assay to pull expression from. Defaults to DefaultAssay().

layer

Character. Layer within the assay. Default "data" (log-normalized counts). Falls back to "counts" automatically if "data" is not present (BPCells objects). Only ~4–8 sex genes are materialised into memory — near-instantaneous even on million-cell objects.

noise_floor

Numeric. Pseudobulk mean expression threshold that separates "completely absent" from "present" at the sample level. Default 0.05. Because this is applied to the sample mean (averaged over hundreds–thousands of cells), alignment-artifact signal from X–Y paralog multi-mapping (typically 0.001–0.01 in pseudobulk space) is well below this threshold, while true sex-gene expression (0.2–2.0) is well above. Raise to 0.1 if you see "Undetermined" on low-depth samples; lower to 0.02 for very high-depth data.

output_dir

Character or NULL. Directory for saved figures and CSV summary tables. Walks up from PrepObject() when NULL.

plot

Logical. Generate and save figures. Default TRUE.

Value

The input Seurat object with the following metadata columns added:

predicted_sex

Sample-level sex call ("Female" / "Male" / "Ambiguous" / "Undetermined"), propagated identically to all cells within each sample.

sex_score_f

Per-cell mean female-marker expression (for visualisation; not used for the mismatch decision).

sex_score_m

Per-cell mean male-marker expression.

sex_ratio

Per-cell log2(female_score + 0.01) / (male_score + 0.01). Positive = female signal, negative = male signal. Used for the continuous UMAP ratio plot.

sex_mismatch

Sample-level mismatch flag (TRUE/FALSE/NA), propagated to all cells in the sample. TRUE only when expected markers are completely absent and opposite markers are present.

Details

A sample is flagged only when both of the following hold:

1. The expected sex marker is completely absent at pseudobulk level (bulk mean ≤ noise_floor).

2. The opposite-sex marker is clearly present at pseudobulk level (bulk mean > noise_floor).

This strict two-condition rule avoids flags on:

• Dropout (expected marker absent but no opposite signal either).

• X–Y paralog multi-mapping artifacts: DDX3X/DDX3Y, KDM6A/UTY, and KDM5C/KDM5D share 70–85\ spurious Y-gene signal from misaligned X reads. At the pseudobulk level this artifact is tiny (scattered reads in a few cells) and stays well below noise_floor.

Female-scoring modes (auto-selected):

• Primary (XIST-based): uses XIST/Xist, the X-inactivation signal. Most specific when available.

• Fallback (X-paralog dosage): uses DDX3X, KDM6A, KDM5C (or mouse equivalents). Triggered when XIST/Tsix are absent from the panel (common when lncRNAs are filtered or targeted panels are used). In this mode mismatch is called using sample-level prediction rather than the noise_floor threshold, because X-paralogs are expressed in males at lower (not zero) levels.

When cell_type_col is supplied, a per-cell-type pseudobulk breakdown is also computed. A sample flagged only in specific cell types (e.g., immune cells) suggests BMT/chimerism; one flagged across all cell types suggests a labeling error.

See also

AnnotateFeatures()