tensorsignatures 0.5.0

Via GitHub

To obtain the most recent version of TensorSignatures, we recommend to download the repository directly from GitHub and to install the package into a virtual environment. To get started, clone the repository by executing the following commands in your terminal

$ git clone https://github.com/gerstung-lab/tensorsignatures.git && cd tensorsignatures

Then, create a new virtual environment and install all dependencies. If you have access to a GPU with cuda support use requirements-gpu.txt instead of requirements.txt.

$ python -m venv env
$ source env/bin/activate
$ pip install --upgrade pip setuptools wheel && pip install -r requirements.txt

Finally, install TensorSignatures.

$ python setup.py install

Via Pypi

To install tensorsignatures via Pypi simply type

$ pip install tensorsignatures

into your shell.

Via docker (& jupyter)

To run TensorSignatures within a docker environment, clone the repository

$ git clone https://github.com/gerstung-lab/tensorsignatures.git
$ cd tensorsignatures

and spin up the container using docker-compose

$ docker-compose up --build

This spins up a jupyter server including notebooks with tutorials on http://localhost:8889.

• Free software: MIT license

• Documentation: https://tensorsignatures.readthedocs.io.

Step 1: Data preparation

Running TensorSignatures involves three steps: preparing the input data, i.e. creating the mutation count tensor as well as the mutation count matrix, computing a trinucleotide normalisation to account for differences in the nucleotide composition of different genomic regions, and running TensorSignatures.

$ docker pull sagar87/tensorsignatures-data:latest

$ docker run -v $PWD:/usr/src/app sagar87/tensorsignatures-data <vcf1.vcf> <vcf2.vcf> ... <vcfn.vcf> <output.h5>

$ Rscript -e "source('https://bioconductor.org/biocLite.R'); biocLite('VariantAnnotation')"

$ Rscript -e "source('https://bioconductor.org/biocLite.R'); biocLite('rhdf5')"

$ Rscript processVcf.R <vcf1.vcf> <vcf2.vcf> ... <vcfn.vcf> <output.h5>

Step 2: Computing trinucleotide normalisation

TensorSignatures requires a trinucleotide normalisation constant to account for differences in the nucleotide composition of genomic states. To compute it, invoke the prep sub routine of TensorSignatures and pass the hd5 file from Step 1 as well as the path for the output file as positional arguments to the programme.

$ tensorsignatures prep <output.h5> <tsdata.h5>

Step 3: Run TensorSignatures

There are two ways to run TensorSignatures using either the refit option, which fits the exposures of a set of pre-defined signatures extracted from the PCAWG cohort to a your dataset, or via the train subroutine, that performs a denovo extraction of tensor signatures. Refitting tensor signatures is computationally fast but does not allow to discover new signatures, while extracting new signatures from scratch is computationally intensive (GPU required) and requires ideally larger numbers of samples. For most use cases, with a small number of samples, we advice to use the refit option:

$ tensorsignatures --verbose refit tsData.h5 refit.pkl -n

To run a denovo extraction use

$ tensorsignatures --verbose train tsData.h5 denovo.pkl <rank> -k <size> -n -ep <epochs>

where rank specifies the decomposition rank, size controls the dispersion of the model, and epochs the number of desired epochs to fit the model. TensorSignatures outputs value of the objective function (log likelihood) that is minimised during training as well as the change of the objective during an epoch interval (delta). When deciding on the number of epochs to train the model ensure that it is sufficiently large such that the objective function converges, i.e. the delta value is close to, or fluctuates around zero. For more information on how to run TensorSignatures in a practical setting see the documentation. Running TensorSignatures will yield a pickle dump which can subsequently inspected using the tensorsignatures package.

0.5.0 (2020-08-25)

• updated installation and quick start guid

• added/updated tutorials to the documentation

• added tutorial jupyter notebooks

• added new docker image to install R pipeline required to format input data

• Experiment class reads hdf5 files with “r” flag

• Data class provides tensor factors directly via a, b and m attributes

0.4.1 (2019-07-29)

• modified reshape of normalisation constant to enable tissue specific normalisations

0.4.0 (2019-11-25)

• added subroutine prep which adds the normalization constant to a hdf5 input file of tensorsignatures

• added subroutine refit which refits a set of predefined signatures to mew dataset

• updated README.rst

• fixed issue with package data

0.3.0 (2019-10-03)

• various fixes

• design changes

• fixed setup.py

0.1.0 (2019-08-21)

• First release on PyPI.