API - methods#

found.methods.log1p(X)[source]#

matrix format aware log1p

Parameters:: X (TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array)) – input matrix
Returns:: TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array) – log(X + 1)

found.methods.scale_rs(X)[source]#

returns scaled version of input matrix with row-wise sums of 1

Parameters:: X (TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array)) – input matrix
Returns:: TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array) – scaled matrix

found.methods.scale_sd(X)[source]#

returns scaled version of input matrix with column-wise standard deviation of 1

Parameters:: X (TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array)) – input matrix
Returns:: TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array) – scaled matrix

found.methods.vst_shiftlog(X, overdispersion=0.05)[source]#

implements a variance stabilizing transform accounting for overdispersion, with size factors scaled to have a geometric mean of 1, as recommended in Ahlmann-Eltze et al..

Parameters:

X (TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array)) – input matrix
overdispersion (float) – overdispersion factor

Returns:

TypeVar(T, bound= ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array) – variance stabilized matrix

found.methods.run_pca(X, k, pre_pca_tf=<function <lambda>>, pca_args=None)[source]#

runs PCA as implemented in PCA using the ARPACK solver to provide PC-space embeddings for the input matrix. an optional callback can be provided to transform data prior to PCA (e.g. variance stabilizing transform, scaling, etc.).

note: PCA w/ ARPACK handles center-ing internally, so the provided transform should not center provided data.

Parameters:

X (ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array | csc_matrix | csr_matrix) – cell by gene matrix
k (int) – dimensionality of the PCA to run
pre_pca_tf (Callable[[ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array], ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array] | None) – optional callback to transform data matrix prior to PCA embedding, defaults to vst_shiftlog() followed by scale_sd()
pca_args (dict[str, Any] | None) – additional arguments to pass to PCA

Returns:

ndarray[tuple[int, int], dtype[floating]] – cell by k matrix representing cells in PC-space

found.methods.run_nmf(X, k, pre_nmf_tf=<function <lambda>>, nmf_args=None)[source]#

runs NMF (decomposition of X into w @ h) as implemented in NMF to provide NMF-cell-by-k-space coordinates for each cell.

note:

w refers to the cell by k matrix
h refers to the k by gene matrix

see NMF documentation for more details on meaning of arguments.

Parameters:

X (ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array | csc_matrix | csr_matrix) – cell by gene matrix
k (int) – k, specifying number of NMF components/programs
pre_nmf_tf (Callable[[ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array], ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array] | None) – optional callback to transform data matrix prior to NMF embedding, defaults to scale_rs() followed by scale_sd()
nmf_args (dict[str, Any] | None) – additional arguments to pass to NMF

Returns:

tuple[ndarray[tuple[int, int], dtype[floating]], ndarray[tuple[int, int], dtype[floating]]] – 2-tuple of:

cell by k matrix representing cells in NMF-cell-by-k-space (e.g. w)
gene by k matrix representing NMF-computed gene programs (e.g. h^T)

class found.methods.HasFitBinClass(*args, **kwargs)[source]#

found.methods.reg_logit(Z, V, logit_args=None)[source]#

runs a logistic regression to score cells as affected/unaffected by the condition.

Parameters:

Z (ndarray[tuple[int, int], dtype[floating]]) – cell by k matrix (where k is some number of dimensions)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
logit_args (dict[str, Any] | None) – additional arguments to pass to LogisticRegression (defaults: solver: "newton-cg", C: inf)

Returns:

tuple[ndarray[tuple[int], dtype[number]], LogisticRegression] – 2-tuple of:

1-d float array of probability scores generated by the fitted model
the fitted model object

found.methods.reg_svm(Z, V, svm_args=None)[source]#

runs a support vector machine classifier -based regression to score cells as affected/unaffected by the condition.

Parameters:

Z (ndarray[tuple[int, int], dtype[floating]]) – cell by k matrix (where k is some number of dimensions)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
svm_args (dict[str, Any] | None) – additional arguments to pass to SVC

Returns:

tuple[ndarray[tuple[int], dtype[number]], SVC] – 2-tuple of:

1-d float array of probability scores generated by the fitted model
the fitted model object

found.methods.reg_lsvm(Z, V, lsvm_args=None)[source]#

runs a linear kernel support vector machine classifier -based regression to score cells as affected/unaffected by the condition.

Parameters:

Z (ndarray[tuple[int, int], dtype[floating]]) – cell by k matrix (where k is some number of dimensions)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
lsvm_args (dict[str, Any] | None) – additional arguments to pass to LinearSVC

Returns:

tuple[ndarray[tuple[int], dtype[number]], LinearSVC] – 2-tuple of:

1-d float array of probability scores generated by the fitted model
the fitted model object

found.methods.reg_gp(Z, V, gp_args=None)[source]#

runs a Gaussian process classifier -based regression to score cells as affected/unaffected by the condition.

Parameters:

Z (ndarray[tuple[int, int], dtype[floating]]) – cell by k matrix (where k is some number of dimensions)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
gp_args (dict[str, Any] | None) – additional arguments to pass to GaussianProcessClassifier

Returns:

tuple[ndarray[tuple[int], dtype[number]], GaussianProcessClassifier] – 2-tuple of:

1-d float array of probability scores generated by the fitted model
the fitted model object

found.methods.reg_rf(Z, V, rf_args=None)[source]#

runs a random forest classifier -based regression to score cells as affected/unaffected by the condition.

Parameters:

Z (ndarray[tuple[int, int], dtype[floating]]) – cell by k matrix (where k is some number of dimensions)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
rf_args (dict[str, Any] | None) – additional arguments to pass to RandomForestClassifier

Returns:

tuple[ndarray[tuple[int], dtype[number]], RandomForestClassifier] – 2-tuple of:

1-d float array of probability scores generated by the fitted model
the fitted model object

found.methods.bin_kmeans(Y, V, kmeans_args=None)[source]#

runs k-means based clustering to binarize continuous scores into boolean labels.

Parameters:

Y (ndarray[tuple[int], dtype[number]]) – 1-d float array of condition scores (p_hat)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
kmeans_args (dict[str, Any] | None) – additional arguments to pass to KMeans (defaults: n_init: "auto")

Returns:

ndarray[tuple[int], dtype[bool]] – 1-d boolean array of adjusted condition labels (False corresponds to control, True to case)

found.methods.bin_gmm(Y, V, gmm_args=None)[source]#

runs gaussian mixture modeling based clustering to binarize continuous scores into boolean labels.

Parameters:

Y (ndarray[tuple[int], dtype[number]]) – 1-d float array of condition scores (p_hat)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
gmm_args (dict[str, Any] | None) – additional arguments to pass to GaussianMixture

Returns:

ndarray[tuple[int], dtype[bool]] – 1-d boolean array of adjusted condition labels (False corresponds to control, True to case)

found.methods.score_deg(X, W, lfc_cutoff=1.5, sig_cutoff=0.05)[source]#

implements a heuristic to score label adjustment based on number of DEGs produced by new labels.

Parameters:

X (ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array) – input cell by gene matrix
W (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of adjusted condition labels (True corresponds to case, False to control)
lfc_cutoff (float) – threshold log2 fold change value for a gene to be considered a DEG
sig_cutoff (float) – threshold Bonferroni-corrected Mann-Whitney U-test p value for a gene to be considered a DEG

Returns:

integer – number of DEGs (as determined by a Bonferroni-corrected Mann-Whitney U-test p value of less than sig_cutoff and an absolute log2 fold change of more than lfc_cutoff)

found.methods.score_deg2(X, V, W, score_weight_vsctl=1.0, lfc_cutoff=1.5, sig_cutoff=0.05)[source]#

implements a heuristic to score label adjustment based on number of DEGs produced by new labels using two comparisons. specifically two comparisons are run, and the return value is a weighted difference of:

case cells labeled affected vs case cells labeled unaffected (amount should be as large as possible)
control cells vs case cells labeled unaffected (amount should be as small as possible)

Parameters:

X (ndarray[tuple[int, int], dtype[floating]] | ndarray[tuple[int, int], dtype[integer]] | csr_array | csc_array) – input cell by gene matrix
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
W (ndarray[tuple[int], dtype[bool]]) – boolean array of adjusted condition labels (False corresponds to control, True to case)
score_weight_vsctl (float) – weight given to number of DEGs in second comparison
lfc_cutoff (float) – threshold log2 fold change value for a gene to be considered a DEG
sig_cutoff (float) – threshold Bonferroni-corrected Mann-Whitney U-test p value for a gene to be considered a DEG

Returns:

Integral – number of DEGs in first comparison - score_weight_vsctl * number of DEGs in second comparison

found.methods.score_ks_diff(Y, V, W, score_weight_vsctl=1.0)[source]#

implements a heuristic to score label adjustment based on the distribution difference (using the Kolmogorov-Smirnov statistic) between p_hat values. specifically two comparisons are run, and the return value is a weighted difference of:

case cells labeled affected vs case cells labeled unaffected (difference should be as large as possible)
control cells vs case cells labeled unaffected (difference should be as small as possible)

Parameters:

Y (ndarray[tuple[int], dtype[number]]) – 1-d float array of condition scores (p_hat)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
W (ndarray[tuple[int], dtype[bool]]) – boolean array of adjusted condition labels (False corresponds to control, True to case)
score_weight_vsctl (float) – weight given to KS stat of the second comparison

Returns:

int | float | floating | integer – KS stat of first comparison - score_weight_vsctl * KS stat of second comparison

found.methods.symm_kl_div(lhs, rhs)[source]#

implements a symmetrized version of Kullback-Leibler (KL) divergence, by returning the sum of the KL divergence from lhs to rhs and from rhs to lhs. this symmetrized statistic is also known as the Jeffreys divergence.

Parameters:

lhs (ndarray[tuple[int], dtype[number]]) – 1-d N-length vector of probability values
rhs (ndarray[tuple[int], dtype[number]]) – 1-d N-length vector of probability values

Returns:

int | float | floating | integer – KL divergence of lhs to rhs + KL divergence of rhs to lhs

found.methods.score_dist_diff(Y, V, W, distance_fn=<function wasserstein_distance>, score_weight_vsctl=1.0)[source]#

implements a heuristic to score label adjustment based on the distribution difference between p_hat values. specifically two comparisons are run, and the return value is a weighted difference of:

case cells labeled affected vs case cells labeled unaffected (difference should be as large as possible)
control cells vs case cells labeled unaffected (difference should be as small as possible)

Parameters:

Y (ndarray[tuple[int], dtype[number]]) – 1-d float array of condition scores (p_hat)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
W (ndarray[tuple[int], dtype[bool]]) – boolean array of adjusted condition labels (False corresponds to control, True to case)
distance_fn (Callable[[ndarray[tuple[int], dtype[number]], ndarray[tuple[int], dtype[number]]], int | float | floating | integer]) – distance function used to calculate distribution difference between p_hat values (defaults to earth’s mover distance, as computed by wasserstein_distance())
score_weight_vsctl (float) – weight given to result of second comparison

Returns:

int | float | floating | integer – statistic from first comparison - score_weight_vsctl * statistic from second comparison

found.methods.score_null_dist(Y, V, pipeline_algo, n_iters=10, distance_fn=<function wasserstein_distance>, **kwargs)[source]#

implements a heuristic to score label adjustment based on a distance metric between p_hat values generated by the pipeline and an approximation of null-distributed p_hat values (generated by re-running the pipeline regression step given randomly permuted condition labels).

Parameters:

Y (ndarray[tuple[int], dtype[number]]) – 1-d float array of condition scores (p_hat)
V (ndarray[tuple[int], dtype[bool]]) – 1-d boolean array of condition labels (False corresponds to control, True to case)
pipeline_algo (Pipeline) – pipeline class used to generate outputs
n_iters (int) – number of iterations to run random sampling procedure over, returning average of all iterations
distance_fn (Callable[[ndarray[tuple[int], dtype[number]], ndarray[tuple[int], dtype[number]]], int | float | floating | integer]) – distance metric to use between “null” Y values and pipeline outputs (defaults to earth’s mover distance, as computed by wasserstein_distance())

Returns:

int | float | floating | integer – distance between pipeline generated p_hat values and p_hat values yielded by re-running regression on randomly permuted condition labels