scdynomics.ft_kfold_classification

scdynomics.ft_kfold_classification(config_path: str, clf_adata_path: str, hvg_selection_mod: str = None, nHVGs: int = 2000, hvg_span: float = 0.3, hvg_flavor: str = 'seurat', mod1_layer: str = None, mod2_layer: str = None, obs_label: str = 'celltype', n_folds: int = 5, valid_fraction: float = 0.001, test_fraction: float = None, stratify_test: bool = False, stratify_valid: bool = True, dataloader_worker: int = 10, base_model_ckpt: str = None, unfreeze_embedder: bool = True, unfreeze_embedder_target: str = 'sgt', tuned_model_ckpt: str = None, test_ckpt: str = 'best', rand_ckpt_save_path: str = None, token_dict_path: str = '../data/gene_dict/token_dict.json.gz', default_root_dir: str = '../logs', save_callback_metrics: bool = True, save_label_dict: bool = True, seed: int = 42, ndevices: int = 1, accelerator: str = 'cpu') → tuple

Classification pipeline for multimodal or monomodal data with k-fold cross validation.

Parameters:

config_path: str

Path to the JSON configuration file containing model hyperparameters.

clf_adata_path: str

Path to the AnnData file containing the fine-tuning dataset.

hvg_selection_mod: str (default: None)

The modality layer to base Highly Variable Gene (HVG) selection on.

nHVGs: int (default: 2000)

Number of highly variable genes to select. If None, no subsetting is performed.

hvg_span: float (default: 0.3)

The fraction of data used for the loess fit during HVG selection.

hvg_flavor: str (default: "seurat")

The flavor of HVG selection to use (e.g., ‘seurat’, ‘cell_ranger’).

mod1_layer: str (default: None)

The key in adata.layers corresponding to the first modality.

mod2_layer: str (default: None)

The key in adata.layers corresponding to the second modality.

obs_label: str (default: "celltype")

The key in adata.obs that contains the classification target labels.

n_folds: int (default: 5)

The number of folds for cross-validation. If 1, performs a single train-test split.

valid_fraction: float (default: 0.001)

The fraction of data to allocate for validation in each fold.

test_fraction: float (default: None)

The fraction of data to allocate for testing (used if n_folds == 1).

stratify_test: bool (default: False)

Whether to stratify the test split based on class labels.

stratify_valid: bool (default: True)

Whether to stratify the validation split based on class labels.

dataloader_worker: int (default: 10)

Number of worker processes for data loading.

base_model_ckpt: str (default: None)

Path to the pretrained foundation model checkpoint.

unfreeze_embedder: bool (default: True)

Whether to unfreeze the initial embedding layers.

unfreeze_embedder_target: str (default: "sgt")

Which sub-embedding to unfreeze: "sgt" (gene-token / position embedding), "val" (value-bin embedding), or "all".

tuned_model_ckpt: str (default: None)

Path to an existing fine-tuned model checkpoint to resume training.

test_ckpt: str (default: "best")

The checkpoint to load before running the test suite (“best” or “last”).

rand_ckpt_save_path: str (default: None)

Path to save the randomly initialized model (if no base model is provided).

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

Path to the gene token dictionary.

default_root_dir: str (default: "../logs")

Directory to save training logs and checkpoints.

save_callback_metrics: bool (default: True)

Whether to save the accumulated training metrics to a JSON file.

save_label_dict: bool (default: True)

Whether to save the mapping between text labels and integer classes to a JSON file.

seed: int (default: 42)

Random seed for split reproducibility.

ndevices: int (default: 1)

Number of accelerator devices to use.

accelerator: str (default: "cpu")

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

Returns: tuple

trainer: pytorch_lightning.Trainer

The PyTorch Lightning trainer object from the final fold.

pretrainer: Masked_Pretrainer

The (partitioned) base model used for encoding.

classifier: FT_MLP_Classifier

The trained fine-tuning classifier model.

clf_data: Multimodal_Corpus

The loaded and processed multimodal dataset corpus.