Package: tnmf
Transform-Invariant Non-Negative Matrix FactorizationA comprehensive Python package forNon-Negative Matrix Factorization (NMF)with a focus on learningtransform-invariant representations.The packages supports multiple optimization backends and can be easily extended to handle application-specific types of transforms.General IntroductionA general introduction to Non-Negative Matrix Factorization and the purpose of this package can be found on the correspondingGitHub Pages.InstallationFor using this package, you will need Python version 3.7 (or higher).
The package is available viaPyPI.Installation is easiest using pip:pip install tnmfDemos and ExamplesThe package comes with astreamlitdemo and a number of examples that demonstrate the capabilities of the TNMF model.
They provide a good starting point for your own experiments.Online DemoWithout requiring any installation, the demo is accessible viastreamlit sharing.Local ExecutionOnce the package is installed, the demo and the examples can be conveniently executed locally using thetnmfcommand:To execute the demo, runtnmf demo.A specific example can be executed by callingtnmf example <example_name>.To show the list of available examples, typetnmf example --help.LicenseCopyright (c) 2021 Merck KGaA, Darmstadt, GermanyLicensed 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 athttp://www.apache.org/licenses/LICENSE-2.0Unless 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 fileLICENSEin the repository root directory.Usage and CitationIf you use this software, please cite us using the information in CITATION.cff.ContributingContributions to the package are always welcome and can be submitted via a pull request.
Please note, that you have to agree to theContributor License Agreementto contribute.Working with the CodeTo 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.txtNow, you should be able to execute the unit tests by callingpytestto verify that the code is running as expected.Pull RequestsBefore 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 QualityCode style and quality are checked usingflake8andpylint.
To execute them, change into therepository root directory, run the following commands and inspect their output:flake8
pylint tnmfIn order for a pull request to be accaptable, no errors may be reported here.Unit TestsAutomated unit tests reside inside the foldertnmf/tests. They can be executed viapytestby changing into therepository root directoryand runningpytestDebugging potential failures from the command line might be cumbersome.
Most Python IDEs, however, also supportpytestnatively in their debugger.
Again, for a pull request to be acceptable, no failures may be reported here.Code CoverageCode coverage in the unit tests is measured usingcoverage.
A coverage report can be created locally from therepository root directoryviacoverage run
coverage combine
coverage reportThis 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 usingcoverage htmlThen, you can open the filehtmlcov/index.htmlin a web browser of your choice to navigate through code annotated with coverage data.
Required overall coverage to is configured insetup.cfg, under the keyfail_underin section[coverage:report].Building the DocumentationTo build the documentation locally, change into thedoc subdirectoryand runmake html.
Then, the documentation resides atdoc\_build\html\index.html.