scdynomics.ft_clf_explain

scdynomics.ft_clf_explain(clf_adata: anndata.AnnData = None, clf_adata_path: str = None, mod1_layer: str = None, mod2_layer: str = None, dataloader_worker: int = 10, token_dict_path: str = '../data/gene_dict/token_dict.json.gz', base_model_ckpt: str = None, tuned_model_ckpt: str = None, explain_sample_limit: int = None, sample_method: str = 'top', explain_batch_size: int = 1, explain_step: int = 100, outpath: str = None, accelerator: str = 'cpu', seed: int = 42, **kwargs) → pandas.DataFrame

Explain the fine-tuned classifier’s predictions using integrated gradients.

Parameters:

clf_adata: ad.AnnData (default: None)

The loaded AnnData object containing the dataset to be explained.

clf_adata_path: str (default: None)

The path to the AnnData file. Must provide either this or clf_adata.

mod1_layer: str (default: None)

The layer specifying the first modality to use.

mod2_layer: str (default: None)

The layer specifying the second modality to use.

dataloader_worker: int (default: 10)

Number of worker processes for data loading.

token_dict_path: str (default: "../data/gene_dict/token_dict.json.gz")

Path to the token dictionary file mapping genes to indices.

base_model_ckpt: str (default: None)

Path to the base pretrained foundation model checkpoint.

tuned_model_ckpt: str (default: None)

Path to the fine-tuned classifier checkpoint to be explained.

explain_sample_limit: int (default: None)

The maximum number of samples from the dataset to compute explanations for. If None, explains all samples in the query dataset.

sample_method: str (default: 'top')

The method used to sample cells for explanation. - ‘top’: Selects the top N samples with the highest predicted probability for their predicted class. - ‘distribution’: Sample the indices across the enitre distribution of the selected samples, ensuring coverage across confidence levels.

explain_batch_size: int (default: 1)

Batch size to use during the explanation generation.

explain_step: int (default: 100)

The number of interpolation steps to use for the integrated gradients approximation. Higher numbers provide better accuracy at the cost of computation time.

outpath: str (default: None)

File path to save the resulting explanations as a tab-separated text file.

accelerator: str (default: "cpu")

The accelerator to be used for training. It can be “auto”, “cuda”, “mps”, or “cpu”.

seed: int (default: 42)

The random seed for reproducibility during sampling.

kwargs: dict

Additional keyword arguments passed to the underlying explain method.

Returns: pd.DataFrame

A pandas DataFrame containing the computed feature attributions/explanations for the selected samples.