scmkl.create_adata

  1import numpy as np
  2import anndata as ad
  3import scipy
  4import pandas as pd
  5import gc
  6import warnings
  7
  8
  9def filter_features(feature_names: np.ndarray, group_dict: dict):
 10    """
 11    Function to remove features only in feature names or group_dict.
 12    Any features not included in group_dict will be removed from the
 13    matrix. Also puts the features in the same relative order (of 
 14    included features)
 15    
 16    Parameters
 17    ----------
 18    feature_names : np.ndarray
 19        Numpy array of corresponding feature names.
 20
 21    group_dict : dict
 22        Dictionary containing feature grouping information.
 23                 Example: {geneset: np.array(gene_1, gene_2, ..., 
 24                 gene_n)}
 25    Returns
 26    -------
 27    feature_names : np.ndarray
 28        Numpy array of corresponding feature names from group_dict.
 29
 30    group_dict : dict
 31        Dictionary containing features overlapping input grouping 
 32        information and full feature names.
 33    """
 34    group_features = set()
 35    feature_set = set(feature_names)
 36
 37    # Store all objects in dictionary in set
 38    for group in group_dict.keys():
 39        group_features.update(set(group_dict[group]))
 40
 41        # Finds intersection between group features and features in data
 42        # Converts to nd.array and sorts to preserve order of feature names
 43        group_feats = list(feature_set.intersection(set(group_dict[group])))
 44        group_dict[group] = np.sort(np.array(group_feats))
 45
 46    # Only keeping groupings that have at least two features
 47    group_dict = {group : group_dict[group] for group in group_dict.keys()
 48                  if len(group_dict[group]) > 1}
 49
 50    group_features = np.array(list(group_features.intersection(feature_set)))
 51
 52    return group_features, group_dict
 53
 54
 55def multi_class_split(y: np.ndarray, seed_obj: np.random._generator.Generator, 
 56                      class_threshold: str | int | None=None, 
 57                      train_ratio: float=0.8):
 58    """
 59    Function for calculating the training and testing cell positions 
 60    for multiclass data sets.
 61
 62    Parameters
 63    ----------
 64    y : array_like
 65        Should be an iterable object cooresponding to samples in 
 66        `ad.AnnData` object.
 67
 68    seed_obj : np.random._generator.Generator
 69        Seed used to randomly sample and split data.
 70
 71    train_ratio : float
 72        Ratio of number of training samples to entire data set. 
 73        Note: if a threshold is applied, the ratio training samples 
 74        may decrease depending on class balance and `class_threshold`
 75        parameter.
 76
 77    class_threshold : str | int
 78        If is type `int`, classes with more samples than 
 79        class_threshold will be sampled. If `'median'`, 
 80        samples will be sampled to the median number of samples per 
 81        class.
 82
 83    Returns
 84    -------
 85    train_indices : np.ndarray
 86        Indices for training samples.
 87
 88    test_indices : np.ndarray
 89        Indices for testing samples.
 90    """
 91    uniq_labels = np.unique(y)
 92
 93    # Finding indices for each cell class
 94    class_positions = {class_ : np.where(y == class_)[0] 
 95                       for class_ in uniq_labels}
 96    
 97    # Capturing training indices while maintaining original class proportions
 98    train_samples = {class_ : seed_obj.choice(class_positions[class_], 
 99                                              int(len(class_positions[class_])
100                                                  * train_ratio), 
101                                              replace = False)
102                        for class_ in class_positions.keys()}
103    
104    # Capturing testing indices while maintaining original class proportions
105    test_samples = {class_ : np.setdiff1d(class_positions[class_], 
106                                          train_samples[class_])
107                    for class_ in class_positions.keys()}
108    
109    # Applying threshold for samples per class
110    if class_threshold == 'median':
111        cells_per_class = [len(values) for values in train_samples.values()]
112        class_threshold = int(np.median(cells_per_class))
113
114    if isinstance(class_threshold, int):
115        # Down sample to class_threshold
116        for class_ in train_samples.keys():
117            if len(train_samples[class_]) > class_threshold:
118                train_samples[class_] = seed_obj.choice(train_samples[class_], 
119                                                        class_threshold)
120            
121    train_indices = np.array([idx for class_ in train_samples.keys()
122                                  for idx in train_samples[class_]])
123    
124    test_indices = np.array([idx for class_ in test_samples.keys()
125                                 for idx in test_samples[class_]])
126    
127    return train_indices, test_indices
128
129
130def binary_split(y: np.ndarray, train_indices: np.ndarray | None=None, 
131                  train_ratio: float=0.8,
132                  seed_obj: np.random._generator.Generator=np.random.default_rng(100)):
133    """
134    Function to calculate training and testing indices for given 
135    dataset. If train indices are given, it will calculate the test 
136    indices. If train_indices == None, then it calculates both indices, 
137    preserving the ratio of each label in y
138
139    Parameters
140    ----------
141    y : np.ndarray
142        Numpy array of cell labels. Can have any number of classes 
143        for this function.
144
145    train_indices : np.ndarray | None
146        Optional array of pre-determined training indices
147
148    train_ratio : float
149        Decimal value ratio of features in training/testing sets
150
151    seed_obj : np.random._generator.Generator
152        Numpy random state used for random processes. Can be 
153        specified for reproducubility or set by default.
154    
155    
156    Returns
157    -------
158    train_indices : np.ndarray
159        Array of indices of training cells.
160
161    test_indices : np.ndarray:
162        Array of indices of testing cells.
163    """
164    # If train indices aren't provided
165    if train_indices is None:
166
167        unique_labels = np.unique(y)
168        train_indices = []
169
170        for label in unique_labels:
171
172            # Find indices of each unique label
173            label_indices = np.where(y == label)[0]
174
175            # Sample these indices according to train ratio
176            n = int(len(label_indices) * train_ratio)
177            train_label_indices = seed_obj.choice(label_indices, n, 
178                                                  replace = False)
179            train_indices.extend(train_label_indices)
180    else:
181        assert len(train_indices) <= len(y), ("More train indices than there "
182                                              "are samples")
183
184    train_indices = np.array(train_indices)
185
186    # Test indices are the indices not in the train_indices
187    test_indices = np.setdiff1d(np.arange(len(y)), train_indices, 
188                                assume_unique = True)
189
190    return train_indices, test_indices
191
192
193def get_median_size(adata: ad.AnnData, other_factor: float=1.5):
194    """
195    Returns the median size of training plus testing samples per cell 
196    type. Used to calculate D for multiclass runs.
197
198    Parameters
199    ----------
200    adata : ad.AnnData
201        An ad.AnnData object with `test_indices` in `.uns` keys and 
202        `labels` in `.obs` keys.
203
204    Returns
205    -------
206    median_size : int
207        The median size of training plus testing samples across cell 
208        types. 
209    """
210    n_test = adata.uns['test_indices'].shape[0]
211
212    _, n_cts = np.unique(adata.obs['labels'][adata.uns['train_indices']], 
213                         return_counts=True)
214    sizes = [n_test + (other_factor*count) for count in n_cts]
215
216    return np.median(sizes)
217 
218
219def calculate_d(num_samples : int):
220    """
221    This function calculates the optimal number of dimensions for 
222    performance. See https://doi.org/10.48550/arXiv.1806.09178 for more
223    information.
224
225    Parameters
226    ----------
227    num_samples : int
228        The number of samples in the data set including both training
229        and testing sets.
230
231    Returns
232    -------
233    d : int
234        The optimal number of dimensions to run scMKL with the given 
235        data set.
236
237    Examples
238    --------
239    >>> raw_counts = scipy.sparse.load_npz('MCF7_counts.npz')
240    >>>
241    >>> num_cells = raw_counts.shape[0]
242    >>> d = scmkl.calculate_d(num_cells)
243    >>> d
244    161
245    """
246    d = int(np.sqrt(num_samples)*np.log(np.log(num_samples)))
247
248    return int(np.max([d, 100]))
249
250
251def get_optimal_d(adata: ad.AnnData, D: int | None, allow_multiclass: bool, 
252                  other_factor: float=1.5):
253    """
254    Takes the ad.AnnData object and input D. If D is type `int`, D will 
255    be return. If D is `None` and `allow_multiclass is False`, 
256    `scmkl.calculate_d(adata.shape[0])` will be returned. Else, median 
257    size of training and testing will be calculated and 
258    `scmkl.calculate_d(median_size)` will be returned.
259
260    Parameters
261    ----------
262    adata : ad.AnnData
263        An ad.AnnData object with `test_indices` in `.uns` keys and 
264        `labels` in `.obs` keys.
265    
266    D : int | None
267        The D provided as an `int` or `None` if optimal D should be 
268        calculated.
269
270    allow_multiclass : bool
271        Should be `False` if labels are binary. Else, should be `True` 
272        indicating there are more than two classes.
273
274    Returns
275    -------
276    d : int
277        Either the input or calculated optimal d for the experiment. 
278    """
279    if D is not None:    
280        assert isinstance(D, int) and D > 0, 'D must be a positive integer.'
281        return D
282    
283    if allow_multiclass:
284        size = get_median_size(adata, other_factor)
285    else:
286        size = adata.shape[0]
287
288    return calculate_d(size)
289        
290
291def sort_samples(train_indices, test_indices):
292    """
293    Ensures that samples in adata obj are all training, then all 
294    testing.
295
296    Parameters
297    ----------
298    train_indices : np.ndarray
299        Indices in ad.AnnData object for training.
300    
301    test_indices : np.ndarray
302        Indices in ad.AnnData object for testing.
303
304    Returns
305    -------
306    sort_idc : np.ndarray
307        Ordered indices that will sort ad.AnnData object as all 
308        training samples, then all testing.
309
310    train_indices : np.ndarray
311        The new training indices given the new index order, `sort_idc`.
312
313    test_indices : np.ndarray
314        The new testing indices given the new index order, `sort_idc`.
315    """
316    sort_idc = np.concatenate([train_indices, test_indices])
317
318    train_indices = np.arange(0, train_indices.shape[0])
319    test_indices = np.arange(train_indices.shape[0], 
320                             train_indices.shape[0] + test_indices.shape[0])
321    
322    return sort_idc, train_indices, test_indices
323
324
325def create_adata(X: scipy.sparse._csc.csc_matrix | np.ndarray | pd.DataFrame, 
326                 feature_names: np.ndarray, cell_labels: np.ndarray, 
327                 group_dict: dict, obs_names: None | np.ndarray=None, 
328                 scale_data: bool=True, transform_data: bool=False, 
329                 split_data: np.ndarray | None=None, D: int | None=None, 
330                 remove_features: bool=True, train_ratio: float=0.8, 
331                 distance_metric: str='euclidean', kernel_type: str='Gaussian', 
332                 random_state: int=1, allow_multiclass: bool = False, 
333                 class_threshold: str | int | None = None,
334                 reduction: str | None = None, tfidf: bool = False, 
335                 other_factor: float=1.5):
336    """
337    Function to create an AnnData object to carry all relevant 
338    information going forward.
339
340    Parameters
341    ----------
342    X : scipy.sparse.csc_matrix | np.ndarray | pd.DataFrame
343        A data matrix of cells by features (sparse array 
344        recommended for large datasets).
345
346    feature_names : np.ndarray
347        Array of feature names corresponding with the features 
348        in `X`.
349
350    cell_labels : np.ndarray
351        A numpy array of cell phenotypes corresponding with 
352        the cells in `X`.
353
354    group_dict : dict 
355        Dictionary containing feature grouping information (i.e. 
356        `{geneset1: np.array([gene_1, gene_2, ..., gene_n]), geneset2: 
357        np.array([...]), ...}`.
358
359    obs_names : None | np.ndarray
360        The cell names corresponding to `X` to be assigned to output 
361        object `.obs_names` attribute.
362
363    scale_data : bool  
364        If `True`, data matrix is log transformed and standard 
365        scaled. Default is `True`.
366
367    transform_data : bool
368        If `True`, data will be log1p transformed (recommended for 
369        counts data). Default is `False`.   
370    
371    split_data : None | np.ndarray
372        If `None`, data will be split stratified by cell labels. 
373        Else, is an array of precalculated train/test split 
374        corresponding to samples. Can include labels for entire
375        dataset to benchmark performance or for only training
376        data to classify unknown cell types (i.e. `np.array(['train', 
377        'test', ..., 'train'])`.
378
379    D : int 
380        Number of Random Fourier Features used to calculate Z. 
381        Should be a positive integer. Higher values of D will 
382        increase classification accuracy at the cost of computation 
383        time. If set to `None`, will be calculated given number of 
384        samples. 
385    
386    remove_features : bool
387        If `True`, will remove features from `X` and `feature_names` 
388        not in `group_dict` and remove features from groupings not in 
389        `feature_names`.
390
391    train_ratio : float
392        Ratio of number of training samples to entire data set. Note:
393        if a threshold is applied, the ratio training samples may 
394        decrease depending on class balance and `class_threshold`
395        parameter if `allow_multiclass = True`.
396
397    distance_metric : str
398        The pairwise distance metric used to estimate sigma. Must
399        be one of the options used in `scipy.spatial.distance.cdist`.
400
401    kernel_type : str
402        The approximated kernel function used to calculate Zs.
403        Must be one of `'Gaussian'`, `'Laplacian'`, or `'Cauchy'`.
404
405    random_state : int
406        Integer random_state used to set the seed for 
407        reproducibilty.
408
409    allow_multiclass : bool
410        If `False`, will ensure that cell labels are binary.
411
412    class_threshold : str | int
413        Number of samples allowed in the training data for each cell
414        class in the training data. If `'median'`, the median number 
415        of cells per cell class will be the threshold for number of 
416        samples per class.
417
418    reduction: str | None
419        Choose which dimension reduction technique to perform on 
420        features within a group. 'svd' will run 
421        `sklearn.decomposition.TruncatedSVD`, 'linear' will multiply 
422        by an array of 1s down to 50 dimensions. 'pca' will replace 
423        each group values with 50 PCs from principal component 
424        analysis.
425        
426    tfidf: bool
427        Whether to calculate TFIDF transformation on peaks within 
428        groupings.
429        
430    Returns
431    -------
432    adata : ad.AnnData
433        AnnData with the following attributes and keys:
434
435        `adata.X` (array_like):
436            Data matrix.
437    
438        `adata.var_names` (array_like): 
439            Feature names corresponding to `adata.X`.
440
441        `adata.obs['labels']` (array_like):
442            cell classes/phenotypes from `cell_labels`.
443
444        `adata.uns['train_indices']` (array_like):
445            Indices for training data. 
446
447        `adata.uns['test_indices']` (array_like)
448            Indices for testing data.
449
450        `adata.uns['group_dict']` (dict):
451            Grouping information.
452
453        `adata.uns['seed_obj']` (np.random._generator.Generator): 
454            Seed object with seed equal to 100 * `random_state`.
455
456        `adata.uns['D']` (int):
457            Number of dimensions to scMKL with.
458
459        `adata.uns['scale_data']` (bool):
460            Whether or not data is scaled.
461
462        `adata.uns['transform_data']` (bool):
463            Whether or not data is log1p transformed.
464
465        `adata.uns['distance_metric']` (str): 
466            Distance metric as given.
467    
468        `adata.uns['kernel_type']` (str): 
469            Kernel function as given.
470
471        `adata.uns['svd']` (bool): 
472            Whether to calculate SVD reduction.
473
474        `adata.uns['tfidf']` (bool): 
475            Whether to calculate TF-IDF per grouping.
476
477    Examples
478    --------
479    >>> data_mat = scipy.sparse.load_npz('MCF7_RNA_matrix.npz')
480    >>> gene_names = np.load('MCF7_gene_names.pkl', allow_pickle = True)
481    >>> group_dict = np.load('hallmark_genesets.pkl', 
482    >>>                      allow_pickle = True)
483    >>> 
484    >>> adata = scmkl.create_adata(X = data_mat, 
485    ...                            feature_names = gene_names, 
486    ...                            group_dict = group_dict)
487    >>> adata
488    AnnData object with n_obs × n_vars = 1000 × 4341
489    obs: 'labels'
490    uns: 'group_dict', 'seed_obj', 'scale_data', 'D', 'kernel_type', 
491    'distance_metric', 'train_indices', 'test_indices'
492    """
493
494    assert X.shape[1] == len(feature_names), ("Different number of features "
495                                              "in X than feature names.")
496    
497    if not allow_multiclass:
498        assert len(np.unique(cell_labels)) == 2, ("cell_labels must contain "
499                                                  "2 classes.")
500
501    kernel_options = ['gaussian', 'laplacian', 'cauchy']
502    assert kernel_type.lower() in kernel_options, ("Given kernel type not "
503                                                   "implemented. Gaussian, "
504                                                   "Laplacian, and Cauchy "
505                                                   "are the acceptable "
506                                                   "types.")
507
508    # Create adata object and add column names
509    adata = ad.AnnData(X)
510    adata.var_names = feature_names
511
512    if isinstance(obs_names, (np.ndarray)):
513        adata.obs_names = obs_names
514
515    filtered_feature_names, group_dict = filter_features(feature_names, 
516                                                          group_dict)
517    
518    # Ensuring that there are common features between feature_names and groups
519    overlap_err = ("No common features between feature names and grouping "
520                   "dict. Check grouping.")
521    assert len(filtered_feature_names) > 0, overlap_err
522
523    if remove_features:
524        warnings.filterwarnings('ignore', category = ad.ImplicitModificationWarning)
525        adata = adata[:, filtered_feature_names]
526    
527    gc.collect()
528
529    # Add metadata to adata object
530    adata.uns['group_dict'] = group_dict
531    adata.uns['seed_obj'] = np.random.default_rng(100*random_state)
532    adata.uns['scale_data'] = scale_data
533    adata.uns['transform_data'] = transform_data
534    adata.uns['kernel_type'] = kernel_type
535    adata.uns['distance_metric'] = distance_metric
536    adata.uns['reduction'] = reduction if isinstance(reduction, str) else 'None'
537    adata.uns['tfidf'] = tfidf
538
539    if (split_data is None):
540        assert X.shape[0] == len(cell_labels), ("Different number of cells "
541                                                "than labels")
542        adata.obs['labels'] = cell_labels
543
544        if (allow_multiclass == False):
545            split = binary_split(cell_labels, 
546                                  seed_obj = adata.uns['seed_obj'],
547                                  train_ratio = train_ratio)
548            train_indices, test_indices = split
549
550        elif (allow_multiclass == True):
551            split = multi_class_split(cell_labels, 
552                                       seed_obj = adata.uns['seed_obj'], 
553                                       class_threshold = class_threshold,
554                                       train_ratio = train_ratio)
555            train_indices, test_indices = split
556
557        adata.uns['labeled_test'] = True
558
559    else:
560        sd_err_message = "`split_data` argument must be of type np.ndarray"
561        assert isinstance(split_data, np.ndarray), sd_err_message
562        x_eq_labs = X.shape[0] == len(cell_labels)
563        train_eq_labs = X.shape[0] == len(cell_labels)
564        assert x_eq_labs or train_eq_labs, ("Must give labels for all cells "
565                                            "or only for training cells")
566        
567        train_indices = np.where(split_data == 'train')[0]
568        test_indices = np.where(split_data == 'test')[0]
569
570        if len(cell_labels) == len(train_indices):
571
572            padded_cell_labels = np.zeros((X.shape[0])).astype('object')
573            padded_cell_labels[train_indices] = cell_labels
574            padded_cell_labels[test_indices] = 'padded_test_label'
575
576            adata.obs['labels'] = padded_cell_labels
577            adata.uns['labeled_test'] = False
578
579        elif len(cell_labels) == len(split_data):
580            adata.obs['labels'] = cell_labels
581            adata.uns['labeled_test'] = True
582
583    # Ensuring all train samples are first in adata object followed by test
584    sort_idx, train_indices, test_indices = sort_samples(train_indices, 
585                                                         test_indices)
586
587    adata = adata[sort_idx]
588
589    if not isinstance(obs_names, (np.ndarray)):
590        adata.obs = adata.obs.reset_index(drop=True)
591        adata.obs.index = adata.obs.index.astype('O')
592
593    adata.uns['train_indices'] = train_indices
594    adata.uns['test_indices'] = test_indices
595
596    adata.uns['D'] = get_optimal_d(adata, D, allow_multiclass, other_factor)
597
598    if not scale_data:
599        print("WARNING: Data will not be scaled. "
600              "To change this behavior, set scale_data to True")
601    if not transform_data:
602        print("WARNING: Data will not be transformed."
603              "To change this behavior, set transform_data to True")
604
605    return adata
606
607
608def format_adata(adata: ad.AnnData | str, cell_labels: np.ndarray | str, 
609                 group_dict: dict | str, use_raw: bool=False, 
610                 scale_data: bool=True, transform_data: bool=False, 
611                 split_data: np.ndarray | None=None, D: int | None=None, 
612                 remove_features: bool=True, train_ratio: float=0.8, 
613                 distance_metric: str='euclidean', kernel_type: str='Gaussian', 
614                 random_state: int=1, allow_multiclass: bool = False, 
615                 class_threshold: str | int | None=None, 
616                 reduction: str | None = None, tfidf: bool = False):
617    """
618    Function to format an `ad.AnnData` object to carry all relevant 
619    information going forward. `adata.obs_names` will be retained.
620
621    **NOTE: Information not needed for running `scmkl` will be 
622    removed.**
623
624    Parameters
625    ----------
626    adata : ad.AnnData
627        Object with data for `scmkl` to be applied to. Only requirment 
628        is that `.var_names` is correct and data matrix is in `adata.X` 
629        or `adata.raw.X`. A h5ad file can be provided as a `str` and it 
630        will be read in.
631
632    cell_labels : np.ndarray | str
633        If type `str`, the labels for `scmkl` to learn are captured 
634        from `adata.obs['cell_labels']`. Else, a `np.ndarray` of cell 
635        phenotypes corresponding with the cells in `adata.X`.
636
637    group_dict : dict | str
638        Dictionary containing feature grouping information (i.e. 
639        `{geneset1: np.array([gene_1, gene_2, ..., gene_n]), geneset2: 
640        np.array([...]), ...}`. A pickle file can be provided as a `str` 
641        and it will be read in.
642
643    obs_names : None | np.ndarray
644        The cell names corresponding to `X` to be assigned to output 
645        object `.obs_names` attribute.
646
647    use_raw : bool
648        If `False`, will use `adata.X` to create new `adata`. Else, 
649        will use `adata.raw.X`.
650
651    scale_data : bool  
652        If `True`, data matrix is log transformed and standard 
653        scaled. 
654
655    transform_data : bool
656        If `True`, data will be log1p transformed (recommended for 
657        counts data). Default is `False`. 
658        
659    split_data : None | np.ndarray
660        If `None`, data will be split stratified by cell labels. 
661        Else, is an array of precalculated train/test split 
662        corresponding to samples. Can include labels for entire
663        dataset to benchmark performance or for only training
664        data to classify unknown cell types (i.e. `np.array(['train', 
665        'test', ..., 'train'])`.
666
667    D : int 
668        Number of Random Fourier Features used to calculate Z. 
669        Should be a positive integer. Higher values of D will 
670        increase classification accuracy at the cost of computation 
671        time. If set to `None`, will be calculated given number of 
672        samples. 
673    
674    remove_features : bool
675        If `True`, will remove features from `X` and `feature_names` 
676        not in `group_dict` and remove features from groupings not in 
677        `feature_names`.
678
679    train_ratio : float
680        Ratio of number of training samples to entire data set. Note:
681        if a threshold is applied, the ratio training samples may 
682        decrease depending on class balance and `class_threshold`
683        parameter if `allow_multiclass = True`.
684
685    distance_metric : str
686        The pairwise distance metric used to estimate sigma. Must
687        be one of the options used in `scipy.spatial.distance.cdist`.
688
689    kernel_type : str
690        The approximated kernel function used to calculate Zs.
691        Must be one of `'Gaussian'`, `'Laplacian'`, or `'Cauchy'`.
692
693    random_state : int
694        Integer random_state used to set the seed for 
695        reproducibilty.
696
697    allow_multiclass : bool
698        If `False`, will ensure that cell labels are binary.
699
700    class_threshold : str | int
701        Number of samples allowed in the training data for each cell
702        class in the training data. If `'median'`, the median number 
703        of cells per cell class will be the threshold for number of 
704        samples per class.
705
706    reduction: str | None
707        Choose which dimension reduction technique to perform on 
708        features within a group. 'svd' will run 
709        `sklearn.decomposition.TruncatedSVD`, 'linear' will multiply 
710        by an array of 1s down to 50 dimensions.
711        
712    tfidf: bool
713        Whether to calculate TFIDF transformation on peaks within 
714        groupings.
715        
716    Returns
717    -------
718    adata : ad.AnnData
719        AnnData with the following attributes and keys:
720
721        `adata.X` (array_like):
722            Data matrix.
723    
724        `adata.var_names` (array_like): 
725            Feature names corresponding to `adata.X`.
726
727        `adata.obs['labels']` (array_like):
728            cell classes/phenotypes from `cell_labels`.
729
730        `adata.uns['train_indices']` (array_like):
731            Indices for training data. 
732
733        `adata.uns['test_indices']` (array_like)
734            Indices for testing data.
735
736        `adata.uns['group_dict']` (dict):
737            Grouping information.
738
739        `adata.uns['seed_obj']` (np.random._generator.Generator): 
740            Seed object with seed equal to 100 * `random_state`.
741
742        `adata.uns['D']` (int):
743            Number of dimensions to scMKL with.
744
745        `adata.uns['scale_data']` (bool):
746            Whether or not data is scaled.
747
748        `adata.uns['transform_data']` (bool):
749            Whether or not data is log1p transformed.
750
751        `adata.uns['distance_metric']` (str): 
752            Distance metric as given.
753    
754        `adata.uns['kernel_type']` (str): 
755            Kernel function as given.
756
757        `adata.uns['svd']` (bool): 
758            Whether to calculate SVD reduction.
759
760        `adata.uns['tfidf']` (bool): 
761            Whether to calculate TF-IDF per grouping.
762
763    Examples
764    --------
765    >>> adata = ad.read_h5ad('MCF7_rna.h5ad')
766    >>> group_dict = np.load('hallmark_genesets.pkl', 
767    >>>                      allow_pickle = True)
768    >>> 
769    >>> 
770    >>> # The labels in adata.obs we want to learn are 'celltypes'
771    >>> adata = scmkl.format_adata(adata, 'celltypes', 
772    ...                            group_dict)
773    >>> adata
774    AnnData object with n_obs × n_vars = 1000 × 4341
775    obs: 'labels'
776    uns: 'group_dict', 'seed_obj', 'scale_data', 'D', 'kernel_type', 
777    'distance_metric', 'train_indices', 'test_indices'
778    """
779    if str == type(adata):
780        adata = ad.read_h5ad(adata)
781
782    if str == type(group_dict):
783        group_dict = np.load(group_dict, allow_pickle=True)
784        
785    if str == type(cell_labels):
786        err_msg = f"{cell_labels} is not in `adata.obs`"
787        assert cell_labels in adata.obs.keys(), err_msg
788        cell_labels = adata.obs[cell_labels].to_numpy()
789    
790    if use_raw:
791        assert adata.raw, "`adata.raw` is empty, set `use_raw` to `False`"
792        X = adata.raw.X
793    else:
794        X = adata.X
795
796    adata = create_adata(X, adata.var_names.to_numpy().copy(), cell_labels, 
797                         group_dict, adata.obs_names.to_numpy().copy(), 
798                         scale_data, transform_data, split_data, D, remove_features, 
799                         train_ratio, distance_metric, kernel_type, 
800                         random_state, allow_multiclass, class_threshold, 
801                         reduction, tfidf)
802
803    return adata