Metadata-Version: 2.1
Name: cvanmf
Version: 0.4.0
Summary: Bi-cross validation of NMF and signature generation and analysis
License: GNU General Public License v2.0
Author: Anthony Duncan
Requires-Python: >=3.10,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: kneed (>=0.8.5,<0.9.0)
Requires-Dist: marsilea (>=0.4.3,<0.5.0)
Requires-Dist: multimethod (>=1.12,<2.0)
Requires-Dist: pandas (>=2.1.4,<3.0.0)
Requires-Dist: plotnine (>=0.13,<0.14)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: scikit-bio (>=0.6.0,<0.7.0)
Requires-Dist: scikit-learn (>=1.3.2,<2.0.0)
Requires-Dist: scikit-posthocs (>=0.9.0,<0.10.0)
Requires-Dist: setuptools (>=69.1.1,<70.0.0)
Requires-Dist: tqdm (>=4.66.1,<5.0.0)
Description-Content-Type: text/markdown

# cvanmf
An implementation of bicrossvalidation for Non-negative Matrix Factorisation (NMF) rank selection, along with methods
for analysis and visualisation of NMF decomposition.

## Documentation
Documentation can be found at [readthedocs](https://cvanmf.readthedocs.io).

## Overview
NMF is an unsupervised machine learning techniques which provides a representation of a numeric input matrix $X$ as 
a mixture of $k$ of underlying parts. 
In this package we refer to each of these parts as a _signature_. 
Each signature can be described by how much each feature contributes to it.
For example, we can represent the abundance of bacteria in the human gut as a mixture of 5 signatures.

The number of signatures (or rank, $k$) has to specified when performing NMF, and selecting an appropriate value for 
$k$ is an important step.
We implement bicrossvalidation with Gabriel style holdouts.
Broadly speaking, this method holds out one block of the matrix ($A$) and makes an estimate of it ($A'$) using the 
remainder of the matrix.
How closely $A'$ resembles $A$ is used to identify and appropriate rank.

## Input
Any numeric matrix can be used as input, with samples on columns, and features on rows.
Each row should describe something similar, e.g. each is the abundance of a microbe, or abundance of a transcript.
A minimum of 2 samples is required.
When number of samples $n$ is close to the number of signatures $k$, signatures are likely to represent individual 
samples rather than broad patterns.
