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', clust_alg='Leiden', metrics='sil_mean', opt_metric='sil_mean', opt_metric_dir='max', SS_weights='unitary', SS_exp_base=2.718282, n_subsamples=1, subsamples_pct_cells=100, seed=0, key_added='clusters', approx={'exact_size': True, 'run': False, 'size': 1000}, verbose=True, show_progress_bar=True, njobs=1)[source]
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.
(default (njobs) – sequence of values of the resolution parameter.
(default – sequence of values for the number of nearest neighbors.
(default – 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”).
(default – Whether to use a reduction (True) (highly recommended - accurate & much faster) or to use the direct matrix (False) for clustering.
(default – If reduction is TRUE, then specify which slot for the reduction to use.
(default – Clustering algorithm. Choose among: “Leiden” (default) or “Louvain”.
(default – 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”.
(default – A metric from metrics to use to optimize parameters for the clustering.
(default – Whether opt_metric is more optimal by maximizing (“max”) or by minimizing (“min”).
(default – Negative silhouette scores can be given more weight by exponentiation (“exp”). Otherwise, leave SS_weights as “unitary”.
(default – If SS_weights is set to “exp”, then set the base for exponentiation.
(default=1) (n_subsamples) – Number of subsamples per bootstrap.
(default – Percentage of cells sample at each bootstrap iteration. i.e. when 100, 100%, all cells are used).
(default – Random seed to use.
(default – Slot in obs to store the resulting clusters.
(default –
- A diciontary object containing three parameters to control subsampling and diffusion
”run”: True or False whether to use subsampling and diffusion. Default=False “size”: the number of cells to use in the subsampling. Default=1000. “exact_size”: whether to get the exact size “size” of subsampling (True) or be more inclusive during the representative subsampling (False, recommended).
(default – Include additional output with True. Alternative = False.
(default – Show a progress bar to visualize the progress of the algorithm.
(default – 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', clust_alg='Leiden', metrics='sil_mean', opt_metric='sil_mean', opt_metric_dir='max', SS_weights='unitary', SS_exp_base=2.718282, n_subsamples=1, subsamples_pct_cells=100, 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={'exact_size': True, 'run': False, 'size': 1000}, verbose=True, show_progress_bar=True, njobs=1)[source]
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.
(default (njobs) – edge values of the search space for the resolution parameter.
(default – edge values of the search space for the nearest neighbors parameter.
(default – 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”).
(default – Whether to use a reduction (True) (highly recommended - accurate & much faster) or to use the direct matrix (False) for clustering.
(default – If reduction is TRUE, then specify which slot for the reduction to use.
(default – Clustering algorithm. Choose among: “Leiden” (default) or “Louvain”.
(default – 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”.
(default – A metric from metrics to use to optimize parameters for the clustering.
(default – Whether opt_metric is more optimal by maximizing (“max”) or by minimizing (“min”).
(default – Negative silhouette scores can be given more weight by exponentiation (“exp”). Otherwise, leave SS_weights as “unitary”.
(default – If SS_weights is set to “exp”, then set the base for exponentiation.
(default=1) (n_subsamples) – Number of subsamples per bootstrap.
(default – Percentage of cells sample at each bootstrap iteration. i.e. when 100, 100%, all cells are used).
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.
(default – Random seed to use.
(default – Slot in obs to store the resulting clusters.
(default –
- A diciontary object containing three parameters to control subsampling and diffusion
”run”: True or False whether to use subsampling and diffusion. Default=False “size”: the number of cells to use in the subsampling. Default=1000. “exact_size”: whether to get the exact size “size” of subsampling (True) or be more inclusive during the representative subsampling (False, recommended).
(default – Include additional output with True. Alternative = False.
(default – Show a progress bar to visualize the progress of the algorithm.
(default – 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.