Package: tensorsignatures
TensorSignatures is a tensor factorisation framework for mutational signature analysis, which in contrast to other methods, deciphers mutational processes not only in terms of mutational spectra, but also assess their properties with respect to various genomic variables, allows the inclusion of different mutation types and integrates a robust noise model toperform the inference.TensorSignatures is a young project and breaking changes are to be expected. We keep a changelog and it will have possible breakage clearly documented.Quick installTensorSignatures makes use of the TensorFlow 1.5.x framework requiring the user to install a separate package to enable GPU support, i.e.tensorflow-gpuinstead oftensorflow. We highly recommend to install TensorSignatures into an environment with tensorflow-gpu, as the tensor computations greatly benefit from GPU-acceleration.Via GitHubTo 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$gitclonehttps://github.com/gerstung-lab/tensorsignatures.git&&cdtensorsignaturesThen, create a new virtual environment and install all dependencies. If you have access to a GPU with cuda support userequirements-gpu.txtinstead ofrequirements.txt.$python-mvenvenv$sourceenv/bin/activate$pipinstall--upgradepipsetuptoolswheel&&pipinstall-rrequirements.txtFinally, install TensorSignatures.$pythonsetup.pyinstallVia PypiTo installtensorsignaturesvia Pypi simply type$pipinstalltensorsignaturesinto your shell.Via docker (& jupyter)To run TensorSignatures within a docker environment, clone the repository$gitclonehttps://github.com/gerstung-lab/tensorsignatures.git$cdtensorsignaturesand spin up the container usingdocker-compose$docker-composeup--buildThis spins up a jupyter server including notebooks with tutorials onhttp://localhost:8889.Free software: MIT licenseDocumentation:https://tensorsignatures.readthedocs.io.Getting startedStep 1: Data preparationRunning 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.Preparing input data using dockerWe provide a docker image that contains allRandbioconductordependencies to create the variant tensor and the other mutation type matrix. To use it, pull the image from docker. Note that the image is approximately 5 GB large.$dockerpullsagar87/tensorsignatures-data:latestTo use the image switch into the folder containing your VCF data. Then run image using the following command and supply the VCF files as well as the name of thehdf5output file (must be the last argument) as arguments.$dockerrun-v$PWD:/usr/src/appsagar87/tensorsignatures-data<vcf1.vcf><vcf2.vcf>...<vcfn.vcf><output.h5>Then continue with Step 2.Preparing input data using a custom installationMake sure you haveR3.4.x(!) and the packagesVariantAnnotationandrhdf5installed. You can install them, if necessary, by executing$Rscript-e"source('https://bioconductor.org/biocLite.R'); biocLite('VariantAnnotation')"and$Rscript-e"source('https://bioconductor.org/biocLite.R'); biocLite('rhdf5')"from your command line.To get started, download the following files and place them in the same directory:Constants.RData(containsGRangesobjects that annotate transcription/replication orientation, nucleosomal and epigenetic states)mutations.R(all required functions to partiton SNVs, MNVs and indels)processVcf.R(loadsvcffiles and creates the SNV count tensor, MNV and indel count matrix; eventually needs custom modification to make the script run on your vcfs.)genome.zip.To obtain the SNV count tensor and the matrices containing other mutation types, executeprocessVcf.Rand pass the VCF files you want to convert, as well as a name for an outputhdf5file as command line arguments, e.g.$RscriptprocessVcf.R<vcf1.vcf><vcf2.vcf>...<vcfn.vcf><output.h5>In case of errors please check wether you have correctly specified paths in line 6-8. Also, take a look at thereadVcfSavefunction and adjust it when it fails.Step 2: Computing trinucleotide normalisationTensorSignatures 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 thehd5file from Step 1 as well as the path for the output file as positional arguments to the programme.$tensorsignaturesprep<output.h5><tsdata.h5>Step 3: Run TensorSignaturesThere are two ways to run TensorSignatures using either therefitoption, which fits the exposures of a set of pre-defined signatures extracted from the PCAWG cohort to a your dataset, or via thetrainsubroutine, 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--verboserefittsData.h5refit.pkl-nTo run a denovo extraction use$tensorsignatures--verbosetraintsData.h5denovo.pkl<rank>-k<size>-n-ep<epochs>whererankspecifies the decomposition rank,sizecontrols the dispersion of the model, andepochsthe 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. thedeltavalue 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.FeaturesRuntensorsignatureson your dataset using theTensorSignatureclass provided by the package or via the command line tool.Compute percentile based bootstrap confidence intervals for inferred parameters.Basic plotting tools to visualize tensor signatures and inferred parametersCreditsHarald Vöhringer and Moritz GerstungHistory0.5.0 (2020-08-25)updated installation and quick start guidadded/updated tutorials to the documentationadded tutorial jupyter notebooksadded new docker image to install R pipeline required to format input dataExperiment class reads hdf5 files with “r” flagData class provides tensor factors directly via a, b and m attributes0.4.1 (2019-07-29)modified reshape of normalisation constant to enable tissue specific normalisations0.4.0 (2019-11-25)added subroutine prep which adds the normalization constant to a hdf5 input file of tensorsignaturesadded subroutine refit which refits a set of predefined signatures to mew datasetupdated README.rstfixed issue with package data0.3.0 (2019-10-03)various fixesdesign changesfixed setup.py0.1.0 (2019-08-21)First release on PyPI.