Transform-Invariant Non-Negative Matrix Factorization
A comprehensive Python package for Non-Negative Matrix Factorization (NMF) with a focus on learning transform-invariant representations.
The packages supports multiple optimization backends and can be easily extended to handle application-specific types of transforms.
A general introduction to Non-Negative Matrix Factorization and the purpose of this package can be found on the corresponding GitHub Pages.
For using this package, you will need Python version 3.7 (or higher).
The package is available via PyPI.
Installation is easiest using pip:
pip install tnmf
Demos and Examples
The package comes with a streamlit demo and a number of examples that demonstrate the capabilities of the TNMF model.
They provide a good starting point for your own experiments.
Without requiring any installation, the demo is accessible via streamlit sharing.
Once the package is installed, the demo and the examples can be conveniently executed locally using the
- To execute the demo, run
- A specific example can be executed by calling
tnmf example <example_name>.
To show the list of available examples, type
tnmf example --help.
Copyright (c) 2021 Merck KGaA, Darmstadt, Germany
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The full text of the license can be found in the file LICENSE in the repository root directory.
Working with the Code
To checkout the code and set up a working environment with all required Python packages, execute the following commands:
git checkout https://github.com/emdgroup/tnmf.git ./tnmf cd tmnf python3 -m virtualenv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt
Now, you should be able to execute the unit tests by calling
pytest to verify that the code is running as expected.
Before creating a pull request, you should always try to ensure that the automated code quality and unit tests do not fail.
This section explains how to run them locally to understand and fix potential issues.
Code Style and Quality
flake8 pylint tnmf
In order for a pull request to be accaptable, no errors may be reported here.
Debugging potential failures from the command line might be cumbersome.
Most Python IDEs, however, also support
pytest natively in their debugger.
Again, for a pull request to be acceptable, no failures may be reported here.
coverage run coverage report
This will output a concise table with an overview of python files that are not fully covered with unit tests along with the line numbers of code that has not been executed.
A more detailed, interactive report can be created using
Then, you can open the file
htmlcov/index.html in a web browser of your choice to navigate through code annotated with coverage data.
Required overall coverage to is configured in setup.cfg, under the key
fail_under in section
Building the Documentation
To build the documentation locally, change into the doc subdirectory and run
Then, the documentation resides at