Metadata-Version: 1.2
Name: nmf-torch
Version: 0.1.1
Summary: A PyTorch implementation on Non-negative Matrix Factorization.
Home-page: https://github.com/lilab-bcb/nmf-torch
Author: Yiming Yang, Bo Li
Author-email: cumulus-support@googlegroups.com
License: UNKNOWN
Description: ==============
        NMF-Torch
        ==============
        
        |PyPI| |Python| |License|
        
        .. |PyPI| image:: https://img.shields.io/pypi/v/nmf-torch.svg
           :target: https://pypi.org/project/nmf-torch
        
        .. |Python| image:: https://img.shields.io/pypi/pyversions/nmf-torch
           :target: https://pypi.org/project/nmf-torch
        
        .. |License| image:: https://img.shields.io/github/license/lilab-bcb/nmf-torch
           :target: https://github.com/lilab-bcb/nmf-torch/blob/main/LICENSE
        
        A PyTorch implementation on Non-negative Matrix Factorization.
        
        Installation
        ^^^^^^^^^^^^^
        
        This package is published on PyPI::
        
        	pip install nmf-torch
        
        
        Usage
        ^^^^^^^^
        
        NMF
        ######
        
        Given a non-negative numeric matrix ``X`` of shape M-by-N (M is number of samples, N number of features) in either numpy array or torch tensor structure, run the following code::
        
        	from nmf import run_nmf
        	H, W, err = run_nmf(X, n_components=20)
        
        will decompose ``X`` into two new non-negative matrices:
        
        - ``H`` of shape (M, 20), representing the transformed coordinates of samples regarding the 20 components;
        - ``W`` of shape (20, N), representing the composition of each component in terms of features;
        
        along with the loss between ``X`` and its approximation ``H*W``.
        
        Advanced Settings
        ++++++++++++++++++
        
        By default, ``run_nmf`` function uses the batch HALS solver for NMF decomposition. In total, there are other solvers available in NMF-torch:
        
        - **HALS**: Hierarchical Alternative Least Squares (`[Kimura et al., 2015]`_). The default.
        - **MU**: Multiplicative Update. Set ``algo='mu'`` in ``run_nmf`` function.
        - **BPP**: Alternative non-negative least squares with Block Principal Pivoting method (`[Kim & Park, 2011]`_). Set ``algo='bpp'`` in ``run_nmf`` function.
        
        Besides, each solver has two modes: batch and online.
        The online mode is a modified version which is scalable for input matrix of a large number of samples.
        You can set ``mode='online'`` in ``run_nmf`` function to switch to use the online mode.
        
        The default beta loss is Frobenius (L2) distance, which is the most commonly used.
        By changing ``beta_loss`` parameter in ``run_nmf`` function,
        users can specify other beta loss metrics:
        
        - **KL divergence**: ``beta_loss='kullback-leibler'`` or ``beta_loss=1.0``;
        - **Itakura-Saito divergence**: ``beta_loss='itakura-saito'`` or ``beta_loss=0``;
        - Or any non-negative float number.
        
        Notice that since online mode only works for L2 loss, if you specify other beta loss, ``run_nmf`` will automatically switch back to batch mode.
        
        For the other parameters in ``run_nmf`` function, please type ``help(run_nmf)`` in your Python interpreter to view.
        
        ------------
        
        Data Integration using Integrative NMF (iNMF)
        ################################################
        
        In this case, we have a list of ``k`` batches, with their corresponding non-negative numeric matrices to be integrated.
        Let ``X`` be such a list, and all matrices in ``X`` have the same number of features,
        i.e. each X\ :sub:`i` in ``X`` has shape (|M_i|, N), where |M_i| is number of samples in batch i, and N is number of features.
        
        The following code::
        
        	from nmf import integrative_nmf
        	H, W, V, err = integrative_nmf(X, n_components=20)
        
        will perform iNMF, which results in the following non-negative matrices:
        
        - ``H``: List of matrices of shape (|M_i|, 20), each of which represents the transformed coordinates of samples regarding components of the corresponding batch;
        - ``W`` of shape (20, N), representing the common composition (shared information) across the given batches in terms of features;
        - ``V``: List of matrices of the same shape (20, N), each of which represents the batch-specific composition in terms of features of the corresponding batch,
        
        along with the overall L2 loss between |X_i| and its approximation |H_i| \* (W + |V_i|) for each batch i.
        
        Advanced Settings
        ++++++++++++++++++
        
        Similarly as in ``run_nmf`` function above, ``integrative_nmf`` provides 2 modes (batch and online) and 3 solvers: HALS, MU, and BPP.
        By default, batch HALS is used. You can switch to other solvers and modes by specifying ``algo`` and ``mode`` parameters.
        
        There is another important parameter ``lam`` for the coefficient for regularization terms, with default value ``5.0``.
        If set to ``0``, then no regularization will be applied.
        
        Notice that only L2 loss is accepted in iNMF.
        
        For the other parameters in ``integrative_nmf`` function, please type ``help(integrative_nmf)`` in your Python interpreter to view.
        
        .. |M_i| replace:: M\ :sub:`i`
        .. |X_i| replace:: X\ :sub:`i`
        .. |H_i| replace:: H\ :sub:`i`
        .. |V_i| replace:: V\ :sub:`i`
        .. _[Kimura et al., 2015]: http://proceedings.mlr.press/v39/kimura14.pdf
        .. _[Kim & Park, 2011]: https://www.cc.gatech.edu/~hpark/papers/SISC_082117RR_Kim_Park.pdf
        
Keywords: matrix factorization
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: ~=3.6
