cellink.tl.external.run_livi_association_testing

cellink.tl.external.run_livi_association_testing(inference_results, genotype_matrix, output_dir, *, method='LMM', kinship=None, genotype_pcs=None, covariates=None, fdr_threshold=0.05, fdr_method='Benjamini-Hochberg', quantile_norm=False, variance_threshold=None, variable_factors=None, output_file_prefix='livi', runner=None)

Run genetic association testing on LIVI donor embeddings.

Performs trans-eQTL-style testing between LIVI’s learned donor embeddings (D and/or V) and a genotype matrix, using either a linear mixed model (LMM / LIMIX) or TensorQTL.

Parameters:

• inference_results (dict) – Output of infer_livi(). Must contain at least one of "D_embedding" or "V_embedding".

• genotype_matrix (DonorData, str, or pd.DataFrame) – Genotype data. When a DonorData object is passed, dd.G.X is used as the donors × SNPs genotype matrix, and kinship / genotype_pcs are automatically extracted from dd.G.uns["kinship"] and dd.G.obsm["gPCs"] respectively (unless explicitly overridden). Alternatively, pass a TSV file path or a DataFrame directly.

• output_dir (str) – Directory where association result files are written.

• method ({"LMM", "TensorQTL"}) – Association testing method. "LMM" uses LIMIX with a kinship matrix for relatedness correction; "TensorQTL" is faster but does not support repeated-measures designs.

• kinship (str or pd.DataFrame, optional) – Donors × donors kinship / GRM matrix. Required for method="LMM". Auto-extracted from dd.G.uns["kinship"] when DonorData is passed.

• genotype_pcs (str or pd.DataFrame, optional) – Donors × PCs genotype principal-component matrix used as additional covariates. Auto-extracted from dd.G.obsm["gPCs"] when DonorData is passed.

• covariates (pd.DataFrame, optional) – Extra donor-level covariates (donors × covariates) passed alongside genotype PCs during testing.

• fdr_threshold (float) – FDR threshold for significance.

• fdr_method (str) – FDR-controlling procedure (e.g. "Benjamini-Hochberg").

• quantile_norm (bool) – Quantile-normalise LIVI embeddings before testing.

• variance_threshold (float, optional) – Only test D factors with variance ≥ this threshold.

• variable_factors (list of int, optional) – Explicit (zero-based) factor indices to test. Overrides variance_threshold.

• output_file_prefix (str) – Common prefix for output TSV files.

• runner (LIVIRunner, optional) – Runner instance. Uses the global runner when None.

Return type:

DataFrame | tuple[DataFrame, DataFrame | None]

Returns:

pd.DataFrame or tuple If only D (or only V) embeddings are present: a single DataFrame with association results. If both are present: a tuple (DxC_associations, V_associations).

Examples

Pass DonorData — genotype matrix, kinship, and gPCs are auto-extracted:

>>> assoc = cl.tl.external.run_livi_association_testing(
...     results,
...     genotype_matrix=dd,
...     output_dir="livi_assoc",
...     method="LMM",
... )

Or supply components explicitly:

>>> assoc = cl.tl.external.run_livi_association_testing(
...     results,
...     genotype_matrix="genotypes.tsv",
...     output_dir="livi_assoc",
...     method="LMM",
...     kinship="kinship.tsv",
...     genotype_pcs="gpcs.tsv",
... )