acdc_py package

Submodules

acdc_py.GS module

acdc_py.GS.GS(adata, res_vector=array([0.1, 0.3, 0.5, 0.7, 0.9, 1.1, 1.3, 1.5, 1.7, 1.9]), NN_vector=array([11, 21, 31, 41, 51, 61, 71, 81, 91, 101]), dist_slot=None, use_reduction=True, reduction_slot='X_pca', metrics='sil_mean', opt_metric='sil_mean', opt_metric_dir='max', cluster_labels=None, cluster_name=None, seed=0, key_added='clusters', approx_size=None, verbose=True, show_progress_bar=True, batch_size=1000, njobs=1)

A tool for the optimization-based unsupervised clustering of large-scale data. Grid Search (GS) allows for deterministic optimization of several variables—Nearest Neighbors and resolution–with several objective functions—e.g. Silhouette Score. An approximation method we call subsampling and diffusion is included to allow fast and accurate clustering of hundreds of thousands of cells.

Parameters:

• adata – An anndata object containing a gene expression signature in adata.X and gene expression counts in adata.raw.X.

• res_vector (default: np.arange(0.1, 2, 0.2)) – sequence of values of the resolution parameter.

• NN_vector (default: np.arange(11, 102, 10)) – sequence of values for the number of nearest neighbors.

• dist_slot (default: None) – Slot in adata.obsp where a pre-generated distance matrix computed across all cells is stored in adata for use in construction of NN. (Default = None, i.e. distance matrix will be automatically computed as a correlation distance and stored in “corr_dist”).

• use_reduction (default: True) – Whether to use a reduction (True) (highly recommended - accurate & much faster) or to use the direct matrix (False) for clustering.

• reduction_slot (default: "X_pca") – If reduction is TRUE, then specify which slot for the reduction to use.

• metrics (default: "sil_mean") – A metric or a list of metrics to be computed at each iteration of the GridSearch. Possible metrics to use include “sil_mean”, “sil_mean_median”, “tot_sil_neg”, “lowest_sil_clust”, “max_sil_clust”, “ch” and “db”.

• opt_metric (default: "sil_mean") – A metric from metrics to use to optimize parameters for the clustering.

• opt_metric_dir (default: "max") – Whether opt_metric is more optimal by maximizing (“max”) or by minimizing (“min”).

• cluster_labels (default: None) – A column in adata.obs with a set of cluster labels containing a cluster to subcluster. Specify the cluster with the cluster_name parameter.

• cluster_name (default: None) – A cluster from cluster_labels to subcluster. When None, cluster whole dataset.

• seed (default: 0) – Random seed to use.

• key_added (default: "clusters") – Slot in obs to store the resulting clusters.

• approx_size (default: None) – When set to a positive integer, instead of running GS on the entire dataset, perform GS on a subsample and diffuse those results. This will lead to an approximation of the optimal solution for cases where the dataset is too large to perform GS on due to time or memory constraints.

• verbose (default: True) – Include additional output with True. Alternative = False.

• show_progress_bar (default: True) – Show a progress bar to visualize the progress of the algorithm.

• batch_size (default: 1000) – The size of each batch. Larger batches result in more memory usage. If None, use the whole dataset instead of batches.

• njobs (default: 1) – Paralleization option that allows users to speed up runtime.

Returns:

• A object of (class:~anndata.Anndata containing a clustering vector)

• ”clusters” in the .obs slot and a dictionary “GS_results_dict” with

• information on the run in the .uns slot.

acdc_py.SA module

acdc_py.SA.SA(adata, res_range=[0.1, 1.9], NN_range=[11, 101], dist_slot=None, use_reduction=True, reduction_slot='X_pca', metrics='sil_mean', opt_metric='sil_mean', opt_metric_dir='max', cluster_labels=None, cluster_name=None, maxiter=20, initial_temp=5230, restart_temp_ratio=2e-05, visit=2.62, accept=-5.0, maxfun=10000000.0, seed=0, key_added='clusters', approx_size=None, verbose=True, show_progress_bar=True, batch_size=1000, njobs=1)

A tool for the optimization-based unsupervised clustering of large-scale data. Simulated Annealing (SA) allows for stochastic optimization of several variables—Nearest Neighbors and resolution–with several objective functions—e.g. Silhouette Score. An approximation method we call subsampling and diffusion is included to allow fast and accurate clustering of hundreds of thousands of cells.

Parameters:

• adata – An anndata object containing a gene expression signature in adata.X and gene expression counts in adata.raw.X.

• res_range (default: [0.1, 1.9]) – edge values of the search space for the resolution parameter.

• NN_range (default: [11, 101]) – edge values of the search space for the nearest neighbors parameter.

• dist_slot (default: None) – Slot in adata.obsp where a pre-generated distance matrix computed across all cells is stored in adata for use in construction of NN. (Default = None, i.e. distance matrix will be automatically computed as a correlation distance and stored in “corr_dist”).

• use_reduction (default: True) – Whether to use a reduction (True) (highly recommended - accurate & much faster) or to use the direct matrix (False) for clustering.

• reduction_slot (default: "X_pca") – If reduction is TRUE, then specify which slot for the reduction to use.

• metrics (default: "sil_mean") – A metric or a list of metrics to be computed at each iteration of the GridSearch. Possible metrics to use include “sil_mean”, “sil_mean_median”, “tot_sil_neg”, “lowest_sil_clust”, “max_sil_clust”, “ch” and “db”.

• opt_metric (default: "sil_mean") – A metric from metrics to use to optimize parameters for the clustering.

• opt_metric_dir (default: "max") – Whether opt_metric is more optimal by maximizing (“max”) or by minimizing (“min”).

• cluster_labels (default: None) – A column in adata.obs with a set of cluster labels containing a cluster to subcluster. Specify the cluster with the cluster_name parameter.

• cluster_name (default: None) – A cluster from cluster_labels to subcluster. When None, cluster whole dataset.

• maxiter (: default: 20) – The maximum number of global search iterations. If None, value is 1000.

• minimizer_kwargs (dict, optional) – Extra keyword arguments to be passed to the local minimizer (minimize). Some important options could be: method for the minimizer method to use and args for objective function additional arguments.

• initial_temp (float, optional) – The initial temperature, use higher values to facilitates a wider search of the energy landscape, allowing dual_annealing to escape local minima that it is trapped in. Default value is 5230. Range is (0.01, 5.e4].

• restart_temp_ratio (float, optional) – During the annealing process, temperature is decreasing, when it reaches initial_temp * restart_temp_ratio, the reannealing process is triggered. Default value of the ratio is 2e-5. Range is (0, 1).

• visit (float, optional) – Parameter for visiting distribution. Default value is 2.62. Higher values give the visiting distribution a heavier tail, this makes the algorithm jump to a more distant region. The value range is (1, 3].

• accept (float, optional) – Parameter for acceptance distribution. It is used to control the probability of acceptance. The lower the acceptance parameter, the smaller the probability of acceptance. Default value is -5.0 with a range (-1e4, -5].

• maxfun (int, optional) – Soft limit for the number of objective function calls. If the algorithm is in the middle of a local search, this number will be exceeded, the algorithm will stop just after the local search is done. Default value is 1e7.

• seed (default: 0) – Random seed to use.

• key_added (default: "clusters") – Slot in obs to store the resulting clusters.

• approx_size (default: None) – When set to a positive integer, instead of running GS on the entire dataset, perform GS on a subsample and diffuse those results. This will lead to an approximation of the optimal solution for cases where the dataset is too large to perform GS on due to time or memory constraints.

• verbose (default: True) – Include additional output with True. Alternative = False.

• show_progress_bar (default: True) – Show a progress bar to visualize the progress of the algorithm.

• batch_size (default: 1000) – The size of each batch. Larger batches result in more memory usage. If None, use the whole dataset instead of batches.

• njobs (default: 1) – Paralleization option that allows users to speed up runtime.

Returns:

• A object of (class:~anndata.Anndata containing a clustering vector)

• ”clusters” in the .obs slot and a dictionary “GS_results_dict” with

• information on the run in the .uns slot.

acdc_py.config module

acdc_py.config.set_SS_bootstraps(n_subsamples=1, subsamples_pct_cells=100)

n_subsamplesdefault: 1

Number of subsamples per bootstrap.

subsamples_pct_cellsdefault: 100

Percentage of cells sample at each bootstrap iteration. i.e. when 100, 100%, all cells are used).

acdc_py.config.set_SS_weights(SS_weights='unitary', SS_exp_base=2.718282)

SS_weightsdefault: “unitary”

Negative silhouette scores can be given more weight by exponentiation (“exp”). Otherwise, leave SS_weights as “unitary”.

SS_exp_basedefault: 2.718282.

If SS_weights is set to “exp”, then set the base for exponentiation.

acdc_py.config.set_clust_alg(clust_alg='Leiden')

clust_alg : default: “Leiden” Clustering algorithm. Choose among: “Leiden” (default) or “Louvain”.

acdc_py.config.set_corr_distance_dtype(dtype=<class 'numpy.int16'>)

dtype : default: np.int16 Data type used to represent the distance values. np.int16 (default) is a compromise between smaller memory size while not reducing information so much as to affect clustering. dtypes include np.int8, np.int16 (default) np.int32, np.int64, np.float16, np.float32, and np.float64.

acdc_py.get_opt module

acdc_py.pl module

acdc_py.pp module

acdc_py.tl module

Module contents