Skip to main content

Package to visualise component-based decomposition models such as PCA and PARAFAC

Project description

Tests Coverage Documentation Status

TLVis is a Python package for visualising component-based decomposition models like PARAFAC and PCA.


The documentation is available on ReadTheDocs and includes


TLVis supports Python 3.7 or above (it may also work with Python 3.6, though that is not officially supported).

Installation requires matplotlib, numpy, pandas, scipy, statsmodels and xarray.


To install the latest stable release of TLVis and its dependencies, run:

pip install tlvis

There is also functionality to create improved QQ-plots with Pingoiun. However, this is disabled by default due to the restrictive GPL lisence. To enable this possibility, you must manually install Pingoiun.

To install the latest development version of TLVis, you can either clone this repo or run

pip install git+


import tlvis
import matplotlib.pyplot as plt
from tensorly.decomposition import parafac

def fit_parafac(dataset, num_components, num_inits):
    model_candidates = [
        parafac(, num_components, init="random", random_state=i)
        for i in range(num_inits)
    model = tlvis.multimodel_evaluation.get_model_with_lowest_error(
        model_candidates, dataset
    return tlvis.postprocessing.postprocess(model, dataset)

data =
cp_tensor = fit_parafac(data, 3, num_inits=3)
Loading Aminoacids dataset from:
Bro, R, PARAFAC: Tutorial and applications, Chemometrics and Intelligent Laboratory Systems, 1997, 38, 149-171
An example figure showing the component vectors of a three component PARAFAC model fitted to a fluoresence spectroscopy dataset.

This example uses TensorLy to fit five three-component PARAFAC models to the data. Then it uses TLVis to:

  1. Select the model that gave the lowest reconstruction error,

  2. normalise the component vectors, storing their magnitude in a separate weight-vector,

  3. permute the components in descending weight (i.e. signal strength) order,

  4. flip the components so they point in a logical direction compared to the data,

  5. convert the factor matrices into Pandas DataFrames with logical indices,

  6. and plot the components using matplotlib.

All these steps are described in the API documentation with references to the literature.


The test suite requires an additional set of dependencies. To install these, run

pip install tlvis[test]


pip install -e .[test]

inside your local copy of the TLVis repository.

The tests can be run by calling pytest with no additional arguments. All doctests are ran by default and a coverage summary will be printed on the screen. To generate a coverage report, run coverage html.


Contributions are welcome to TLVis, see the contribution guidelines.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

TLVis-0.0.3.tar.gz (632.8 kB view hashes)

Uploaded source

Built Distribution

TLVis-0.0.3-py2.py3-none-any.whl (701.6 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page