TELF.factorization package

TELF.factorization package#

Subpackages#

Submodules#

TELF.factorization.NMFk module#

© 2022. Triad National Security, LLC. All rights reserved. This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

class TELF.factorization.NMFk.NMFk(n_perturbs=20, n_iters=100, epsilon=0.015, perturb_type='uniform', n_jobs=1, n_nodes=1, init='nnsvd', use_gpu=True, save_path='', save_output=True, collect_output=False, predict_k=False, predict_k_method='WH_sill', verbose=True, nmf_verbose=False, perturb_verbose=False, transpose=False, sill_thresh=0.8, nmf_func=None, nmf_method='nmf_fro_mu', clustering_method='kmeans', nmf_obj_params={}, clustering_obj_params={}, pruned=True, calculate_error=True, perturb_multiprocessing=False, consensus_mat=False, use_consensus_stopping=0, mask=None, calculate_pac=False, get_plot_data=False, simple_plot=True, k_search_method='linear', H_sill_thresh=None, factor_thresholding=None, factor_thresholding_H_regression=None, factor_thresholding_obj_params={}, factor_thresholding_H_regression_obj_params={}, device=-1)[source]#

Bases: object

NMFk is a Non-negative Matrix Factorization module with the capability to do automatic model determination.

Parameters:

  • n_perturbs (int, optional) – Number of bootstrap operations, or random matrices generated around the original matrix. The default is 20.

  • n_iters (int, optional) – Number of NMF iterations. The default is 100.

  • epsilon (float or tuple of two elements, optional) –

    Error amount for the random matrices generated around the original matrix. The default is 0.015.

    The default when perturb_type='bool' or perturb_type='boolean' is (epsilon, epsilon).

    epsilon is used when perturb_type='uniform' or perturb_type='bool' or perturb_type='boolean'.

    Note

    If perturb_type='bool' or perturb_type='boolean', use `epsilon=tuple()` where

    positive noise: flip 0s to 1s (additive noise), negative noise: flip 1s to 0s (subtractive noise).

  • perturb_type –

    Type of error sampling to perform for the bootstrap operation. The default is “uniform”.

    • perturb_type='uniform' will use uniform distribution for sampling.

    • perturb_type='poisson' will use Poission distribution for sampling.

    • perturb_type='bool' or perturb_type='boolean' will use Boolean perturbations.

n_jobsint, optional

Number of parallel jobs. Use -1 to use all available resources. The default is 1.

n_nodesint, optional

Number of HPC nodes. The default is 1.

initstr, optional

Initilization of matrices for NMF procedure. The default is “nnsvd”.

  • init='nnsvd' will use NNSVD for initilization.

  • init='random' will use random sampling for initilization.

use_gpubool, optional

If True, uses GPU for operations. The default is True.

save_pathstr, optional

Location to save output. The default is “”.

save_outputbool, optional

If True, saves the resulting latent factors and plots. The default is True.

collect_outputbool, optional

If True, collectes the resulting latent factors to be returned from fit() operation. The default is False.

predict_kbool, optional

If True, performs automatic prediction of the number of latent factors. The default is False.

Note

Even when predict_k=False, number of latent factors can be estimated using the figures saved in save_path.

predict_k_methodstr, optional

Method to use when performing automatic k prediction. Default is “WH_sill”.

  • predict_k_method='pvalue' will use L-Statistics with column-wise error for automatically estimating the number of latent factors.

  • predict_k_method='WH_sill' will use Silhouette scores from minimum of W and H latent factors for estimating the number of latent factors.

  • predict_k_method='W_sill' will use Silhouette scores from W latent factor for estimating the number of latent factors.

  • predict_k_method='H_sill' will use Silhouette scores from H latent factor for estimating the number of latent factors.

  • predict_k_method='sill' will default to predict_k_method='WH_sill'.

Warning

predict_k_method='pvalue' prediction will result in significantly longer processing time, altough it is more accurate! predict_k_method='WH_sill', on the other hand, will be much faster.

verbosebool, optional

If True, shows progress in each k. The default is True.

nmf_verbosebool, optional

If True, shows progress in each NMF operation. The default is False.

perturb_verbosebool, optional

If True, it shows progress in each perturbation. The default is False.

transposebool, optional

If True, transposes the input matrix before factorization. The default is False.

sill_threshfloat, optional

Threshold for the Silhouette score when performing automatic prediction of the number of latent factors. The default is 0.8.

nmf_funcobject, optional

If not None, and if nmf_method=func, used for passing NMF function. The default is None.

nmf_methodstr, optional

What NMF to use. The default is “nmf_fro_mu”.

  • nmf_method='nmf_fro_mu' will use NMF with Frobenious Norm.

  • nmf_method='nmf_kl_mu' will use NMF with Multiplicative Update rules with KL-Divergence.

  • nmf_method='func' will use the custom NMF function passed using the nmf_func parameter.

  • nmf_method='nmf_recommender' will use the Recommender NMF method for collaborative filtering.

  • nmf_method='wnmf' will use the Weighted NMF for missing value completion.

  • nmf_method='bnmf' will use the Boolean NMF for missing value completion on boolean matrix.

Note

When using nmf_method='nmf_recommender', RNMFk prediction method can be done using from TELF.factorization import RNMFk_predict.

Here RNMFk_predict(W, H, global_mean, bu, bi, u, i), W and H are the latent factors, global_mean, bu, and bi are the biases returned from nmf_recommender method.

Finally, u and i are the indices to perform prediction on.

Note

When using nmf_method='wnmf', pass nmf_obj_params={"WEIGHTS":P} where P is a matrix of size X and carries the weights for each item in X.

For example, here P can be used as a mask where 1s in P are the known entries, and 0s are the missing values in X that we want to predict (i.e. a recommender system).

Note that nmf_method='wnmf' does not support sparse matrices currently.

Note

When using nmf_method='bnmf', pass nmf_obj_params={"MASK":P} where P is a mask matrix of size X where 0s and 1s in P are the known and unknown locations in X.

0s in P are the places we would like to predict.

Note that nmf_method='bnmf' does not support sparse matrices currently.

When nmf_method='bnmf', perturb_type='bool' or perturb_type='boolean' is recommended to use. It will not set it automatically but raise warning if not used.

clustering_methodstr, optional

Clustering used on the W patterns. Default is “kmeans”. Options are “kmeans” and “bool” or “boolean”

nmf_obj_paramsdict, optional

Parameters used by NMF function. The default is {}.

clustering_obj_params: dict, optinal

Parameters used by custom clustering functions. The default is {}.

When nmf_method='bnmf', max_iters:int and distance:str can be passed here. distance can be 'hamming', 'FN', or 'FP'. Default is hamming.

For all nmf methods passed in nmf_method, max_iters can also be passed.

prunedbool, optional

When True, removes columns and rows from the input matrix that has only 0 values. The default is True.

Warning

  • If after pruning decomposition is not possible (for example if the number of samples left is 1, or K range is empty based on the rule k < min(X.shape), fit() will return None.

calculate_errorbool, optional

When True, calculates the relative reconstruction error. The default is True.

Warning

If calculate_error=True, it will result in longer processing time.

perturb_multiprocessingbool, optional

If perturb_multiprocessing=True, it will make parallel computation over each perturbation. Default is perturb_multiprocessing=False.

When perturb_multiprocessing=False, which is default, parallelization is done over each K (rank).

consensus_matbool, optional

When True, computes the Consensus Matrices for each k. The default is False.

use_consensus_stoppingstr, optional

When not 0, uses Consensus matrices criteria for early stopping of NMF factorization. The default is 0.

masknp.ndarray, optional

Numpy array that points out the locations in input matrix that should be masked during factorization. The default is None.

calculate_pacbool, optional

When True, calculates the PAC score for H matrix stability. The default is False.

get_plot_databool, optional

When True, collectes the data used in plotting each intermidiate k factorization. The default is False.

simple_plotbool, optional

When True, creates a simple plot for each intermidiate k factorization which hides the statistics such as average and maximum Silhouette scores. The default is True.

k_search_methodstr, optional

Which approach to use when searching for the rank or k. The default is “linear”.

  • k_search_method='linear' will linearly visit each K given in Ks hyper-parameter of the fit() function.

  • k_search_method='bst_post' will perform post-order binary search. When an ideal rank is found, determined by the selected predict_k_method, all lower ranks are pruned from the search space.

  • k_search_method='bst_pre' will perform pre-order binary search. When an ideal rank is found, determined by the selected predict_k_method, all lower ranks are pruned from the search space.

  • k_search_method='bst_in' will perform in-order binary search. When an ideal rank is found, determined by the selected predict_k_method, all lower ranks are pruned from the search space.

H_sill_threshfloat, optional

Setting for removing higher ranks from the search space.

When searching for the optimal rank with binary search using k_search='bst_post' or k_search='bst_pre', this hyper-parameter can be used to cut off higher ranks from search space.

The cut-off of higher ranks from the search space is based on threshold for H silhouette. When a H silhouette below H_sill_thresh is found for a given rank or K, all higher ranks are removed from the search space.

If H_sill_thresh=None, it is not used. The default is None.

factor_thresholdingstr, optional

If not None, W and H factors are thresholded using a thresholding method specified to be boolean. Default is None.

Options are WH_thresh and coord_desc_thresh and otsu_thresh and kmeans_thresh.

If nmf_method='bnmf', factor_thresholding='otsu_thresh' is used by default.

factor_thresholding_H_regressionstr, optional

If not None, H factor is thresholded using a thresholding method specified to be boolean. Default is None.

Options are coord_desc_thresh, otsu_thresh, and kmeans_thresh.

If nmf_method='bnmf', factor_thresholding='kmeans_thresh' is used by default.

factor_thresholding_obj_paramsdict, optional

Extra settings used for the thresholding used in factor_thresholding. Default is {}.

For factor_thresholding='coord_desc_thresh', options include max_iter:int, wt, and ht.

For factor_thresholding='WH_thresh', options include npoint.

factor_thresholding_H_regression_obj_paramsdict, optional

Extra settings used for the thresholding used in factor_thresholding_H_regression. Default is {}.

For factor_thresholding='coord_desc_thresh', options include max_iter:int, wt, and ht.

For factor_thresholding='WH_thresh', options include npoint.

deviceint or list, optional

CUDA device or list of CUDA devices (GPUs) to use. Default is -1.

When device is a positive integer such as device=0 it will use the given GPU with the id.

When device is -1, it will use all devices.

When device is a list of devices, it will use those devices.

If device is negative integer other than -1, it will use number if GPUs minues the device + 1.

Return type:

None.

fit(X, Ks, name='NMFk', note='')[source]#

Factorize the input matrix X for the each given K value in Ks.

Parameters:

  • X (np.ndarray or scipy.sparse._csr.csr_matrix matrix) – Input matrix to be factorized.

  • Ks (list) –

    List of K values to factorize the input matrix.

    Example: Ks=range(1, 10, 1).

  • name (str, optional) – Name of the experiment. Default is “NMFk”.

  • note (str, optional) – Note for the experiment used in logs. Default is “”.

Returns:

results – Resulting dict can include all the latent factors, plotting data, predicted latent factors, time took for factorization, and predicted k value depending on the settings specified.

  • If get_plot_data=True, results will include field for plot_data.

  • If predict_k=True, results will include field for k_predict. This is an intiger for the automatically estimated number of latent factors.

  • If predict_k=True and collect_output=True, results will include fields for W and H which are the latent factors in type of np.ndarray.

  • results will always include a field for time, that gives the total compute time.

Return type:

dict

TELF.factorization.RESCALk module#

© 2022. Triad National Security, LLC. All rights reserved. This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

class TELF.factorization.RESCALk.RESCALk(n_perturbs=20, n_iters=100, epsilon=0.015, perturb_type='uniform', n_jobs=1, n_nodes=1, init='nnsvd', use_gpu=True, save_path='', save_output=True, verbose=True, rescal_verbose=False, perturb_verbose=False, rescal_func=None, rescal_method='rescal_fro_mu', rescal_obj_params={}, pruned=False, calculate_error=False, perturb_multiprocessing=False, get_plot_data=False, simple_plot=True)[source]#

Bases: object

RESCALk is a RESCAL module with the capability to do automatic model determination.

Parameters:

  • n_perturbs (int, optional) – Number of bootstrap operations, or random matrices generated around the original matrix. The default is 20.

  • n_iters (int, optional) – Number of RESCAL iterations. The default is 100.

  • epsilon (float, optional) –

    Error amount for the random matrices generated around the original matrix. The default is 0.015.

    epsilon is used when perturb_type='uniform'.

  • perturb_type (str, optional) –

    Type of error sampling to perform for the bootstrap operation. The default is “uniform”.

    • perturb_type='uniform' will use uniform distribution for sampling.

    • perturb_type='poisson' will use Poission distribution for sampling.

  • n_jobs (int, optional) – Number of parallel jobs. Use -1 to use all available resources. The default is 1.

  • n_nodes (int, optional) – Number of HPC nodes. The default is 1.

  • init (str, optional) –

    Initilization of matrices for RESCAL procedure. The default is “nnsvd”.

    • init='nnsvd' will use NNSVD for initilization.

    • init='random' will use random sampling for initilization.

  • use_gpu (bool, optional) – If True, uses GPU for operations. The default is True.

  • save_path (str, optional) – Location to save output. The default is “”.

  • save_output (bool, optional) – If True, saves the resulting latent factors and plots. The default is True.

  • verbose (bool, optional) – If True, shows progress in each k. The default is True.

  • rescal_verbose (bool, optional) – If True, shows progress in each RESCAL operation. The default is False.

  • perturb_verbose (bool, optional) – If True, it shows progress in each perturbation. The default is False.

  • rescal_func (object, optional) – If not None, and if rescal_method=func, used for passing RESCAL function. The default is None.

  • rescal_method (str, optional) –

    What RESCAL to use. The default is “rescal_fro_mu”.

    • rescal_method='rescal_fro_mu' will use RESCAL with Frobenious Norm.

rescal_obj_paramsdict, optional

Parameters used by RESCAL function. The default is {}.

prunedbool, optional

When True, removes columns and rows from the input matrix that has only 0 values. The default is False.

Warning

Pruning is not implemented for RESCALk yet.

calculate_errorbool, optional

When True, calculates the relative reconstruction error. The default is False.

Warning

If calculate_error=True, it will result in longer processing time.

perturb_multiprocessingbool, optional

If perturb_multiprocessing=True, it will make parallel computation over each perturbation. Default is perturb_multiprocessing=False.

When perturb_multiprocessing=False, which is default, parallelization is done over each K (rank).

get_plot_databool, optional

When True, collectes the data used in plotting each intermidiate k factorization. The default is False.

simple_plotbool, optional

When True, creates a simple plot for each intermidiate k factorization which hides the statistics such as average and maximum Silhouette scores. The default is True.

Return type:

None.

fit(X, Ks, name='RESCALk', note='')[source]#

Factorize the input matrix X for the each given K value in Ks.

Parameters:

  • X (list of symmetric np.ndarray or list of symmetric scipy.sparse._csr.csr_matrix matrix) – Input matrix to be factorized.

  • Ks (list) –

    List of K values to factorize the input matrix.

    Example: Ks=range(1, 10, 1).

  • name (str, optional) – Name of the experiment. Default is “RESCALk”.

  • note (str, optional) – Note for the experiment used in logs. Default is “”.

Returns:

results – Resulting dict can include all the latent factors, plotting data, predicted latent factors, time took for factorization, and predicted k value depending on the settings specified.

  • If get_plot_data=True, results will include field for plot_data.

  • results will always include a field for time, that gives the total compute time.

Return type:

dict

TELF.factorization.TriNMFk module#

© 2022. Triad National Security, LLC. All rights reserved. This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

class TELF.factorization.TriNMFk.TriNMFk(experiment_name='TriNMFk', nmfk_params={}, save_path='TriNMFk', nmf_verbose=False, use_gpu=False, n_jobs=-1, mask=None, use_consensus_stopping=0, alpha=(0, 0), n_iters=100, n_inits=10, pruned=True, transpose=False, verbose=True)[source]#

Bases: object

TriNMFk is a Non-negative Matrix Factorization module with the capability to do automatic model determination for both estimating the number of latent patterns (Wk) and clusters (Hk).

Parameters:

  • experiment_name (str, optional) – Name used for the experiment. Default is “TriNMFk”.

  • nmfk_params (str, optional) – Parameters for NMFk. See documentation for NMFk for the options.

  • save_path (str, optional) – Used for save location when NMFk fit is not performed first, and TriNMFk fit is done.

  • nmf_verbose (bool, optional) – If True, shows progress in each NMF operation. The default is False.

  • use_gpu (bool, optional) – If True, uses GPU for operations. The default is True.

  • n_jobs (int, optional) – Number of parallel jobs. Use -1 to use all available resources. The default is 1.

  • mask (np.ndarray, optional) – Numpy array that points out the locations in input matrix that should be masked during factorization. The default is None.

  • use_consensus_stopping (str, optional) – When not 0, uses Consensus matrices criteria for early stopping of NMF factorization. The default is 0.

  • alpha (tupl, optional) – Error rate used in bootstrap operation. Default is (0, 0).

  • n_iters (int, optional) – Number of NMF iterations. The default is 100.

  • n_inits (int, optional) – Number of matrix initilization for the bootstrap operation. The default is 10.

  • pruned (bool, optional) – When True, removes columns and rows from the input matrix that has only 0 values. The default is True.

  • transpose (bool, optional) – If True, transposes the input matrix before factorization. The default is False.

  • verbose (bool, optional) – If True, shows progress in each k. The default is False.

Return type:

None.

fit_nmfk(X, Ks, note='')[source]#

Factorize the input matrix X for the each given K value in Ks.

Parameters:

  • X (np.ndarray or scipy.sparse._csr.csr_matrix matrix) – Input matrix to be factorized.

  • Ks (list) –

    List of K values to factorize the input matrix.

    Example: Ks=range(1, 10, 1).

  • name (str, optional) – Name of the experiment. Default is “NMFk”.

  • note (str, optional) – Note for the experiment used in logs. Default is “”.

Returns:

results – Resulting dict can include all the latent factors, plotting data, predicted latent factors, time took for factorization, and predicted k value depending on the settings specified in nmfk_params.

  • If get_plot_data=True, results will include field for plot_data.

  • If predict_k=True, results will include field for k_predict. This is an intiger for the automatically estimated number of latent factors.

  • If predict_k=True and collect_output=True, results will include fields for W and H which are the latent factors in type of np.ndarray.

  • results will always include a field for time, that gives the total compute time.

Return type:

dict

fit_tri_nmfk(X, k1k2: tuple)[source]#

Factorize the input matrix X.

after applying fit_nmfk() to select the Wk and Hk, to factorize the given matrix with k1k2=(Wk, Hk).

Parameters:

  • X (np.ndarray or scipy.sparse._csr.csr_matrix matrix) – Input matrix to be factorized.

  • k1k2 (tuple) – Tuple of Wk (number of latent patterns) and Hk (number of latent clusters), to factorize the matrix X to. Example: Ks=range(4,3).

Returns:

results – Resulting dict will include latent patterns W, H, and mixing matrix S along with the error from each n_inits.

Return type:

dict

Module contents#