swotted package

Submodules

swotted.decomposition_contraints module

SWoTTeD Module: decomposition constraints

swotted.decomposition_contraints.nonnegative_projection(*var)

Transform a tensor by replacing the negative values by zeros.

Inplace transformation of the var parameter.

Args:

var: collection of tensors or tensor

swotted.decomposition_contraints.normalization_constraint(*var)

Transform a tensor by replacing the negative values by zeros and values greater than 1 by ones.

Inplace transformation of the var parameter.

Args:

var: collection of tensors or tensor

swotted.decomposition_contraints.phenotypeSuccession_constraint(Wk, Tw)
Parameters:

Wk (torch.Tensor) – A 3rd order tensor of size \(K * rank * (T-Tw+1)\)

swotted.decomposition_contraints.phenotype_uniqueness(Ph)

Evaluate the redundancy between phenotypes. The larger, the more redundant are the phenotypes. It computes the sum of pairwise cosines-similarity (dot products) between phenotypes.

Args:

Ph: collection of phenotypes (2D tensors)

Returns:

float: constraint value

swotted.decomposition_contraints.sparsity_constraint(var)

Sparcity constraint (L1 metric) for a tensor var. The lower the better.

Args:

var (torch.tensor): a tensor

Returns:

float: constraint value

swotted.fastswotted module

This module implements the FastSWoTTeD reconstruction of tensors based on the temporal convolution of the temporal phenotypes with a pathways.

This fast implementation decomposes collection of pathway all having the same length.

class swotted.fastswotted.SlidingWindowConv(dist=<swotted.loss_metrics.Loss object>)

Bases: Module

Torch module that defines the convolution of phenotypes with the pathway matrix

forward(X: Tensor, W: Tensor, Ph: Tensor, padding: bool = None) → float
Parameters:

  • X (torch.Tensor) – a 3rd-order tensor of size \(K * N * Tp\), where \(N\) is the number of drugs and \(Tp\) is the time of the patients’ stays

  • Ph (torch.Tensor) – phenotypes of size \(R * N * \omega\), where \(R\) is the number of phenotypes and \(\omega\) the length of the temporal window

  • W (torch.Tensor) – assignement tensor of size \(K * R * Tp\) for all patients

loss(Xp: Tensor, Wp: Tensor, Ph: Tensor) → float
Parameters:

  • Xp (torch.Tensor) – a 2nd-order tensor of size \(N * Tp\), where \(N\) is the number of drugs and \(Tp\) is the time of the patient’s stay

  • Ph (torch.Tensor) – phenotypes of size \(R * N * \omega\), where \(R\) is the number of phenotypes and \(\omega\) the length of the temporal window

  • Wp (torch.Tensor) – assignement tensor of size \(R * Tp\) for patient \(p\)

reconstruct(W: Tensor, Ph: Tensor) → Tensor

Reconstruction function based on a convolution operator

Parameters:

  • W (torch.Tensor) – Pathway containing all occurrences of the phenotypes

  • Ph (torch.Tensor) – Description of the phenotypes

Returns:

The reconstructed pathway that combines all occurrences of the phenotypes along time.

Return type:

torch.Tensor

setMetric(dist)

Setter for the metric property

Parameters:

  • dist (Loss) – Selection of one loss metric used to evaluate the quality of the reconstruction

  • See

  • ---

  • loss_metric.py

class swotted.fastswotted.fastSWoTTeDDataset(dataset: Tensor)

Bases: Dataset

Implementation of a dataset class for FastSwotted.

The dataset uses a 3D tensors with dimensions \(K * N * T\) where \(K\) is the number of individuals, \(N\) the number of features and \(T\) the shared duration.

FastSwotted requires the pathways to be of same length.

class swotted.fastswotted.fastSWoTTeDModule(*args: Any, **kwargs: Any)

Bases: LightningModule

Warning

The fastSwottedModule has to be used with a fastSwottedTrainer. This trainer ensures the initialisation of the internal \(W\) and \(O\) tensors, when the dataset is known.

Warning

The phenotypes that are discovered by this module have to be flipped to correspond to the correct temporal order!

swotted = fastSwottedModule()
...
swotted.fit()
...
Ph = swotted.Ph
Ph = Ph.flip(2)
configure_optimizers()

Parent override.

forecast(X: Tensor) → Tensor

This function forecasts the next time step using the trained phenotypes. This function can be used only with the parameter \(\omega\geq 2\) (twl>=2) (phenotypes with more than two instant).

This function makes a projection of the data with the phenotypes of the model.

For computational efficiency, the time dimension of \(X\) is reduced to \(\omega\), and then is extended \(\omega-1\) time steps on the right with empty values.

Parameters:

X ((torch.Tensor)) – tensor of dimension \(K* N* T\) with \(T\) to decompose according to the phenotype of the model.

Returns:

A tensor of dimension \(K * N\) that is the forecast of the next time step of \(X\).

Return type:

torch.Tensor

forward(X: Tensor) → Tensor

This forward function makes the decomposition of the tensor X. It contains an optimisation stage to find the best decomposition. The optimisation does not modifies the phenotypes of the model.

Parameters:

X ((torch.Tensor)) – tensor of dimension \(K * N * T\) to decompose according to the phenotype of the model

Returns:

A tensor of dimension \(K * R * (T-\omega)\) that is the decomposition of X according to the \(R\) phenotypes of the model

Return type:

torch.Tensor

phenotypeNonSuccession_loss(Wk: Tensor, Tw: Tensor)

Definition of a loss that pushes the decomposition to add the description in phenotypes preferably to in the pathways.

Parameters:

Wk (torch.Tensor) – A 3rd order tensor of size \(K * R * (T-\omega+1)\)

predict_step(batch, batch_idx, dataloader_idx=0) → float

Parent override.

reorderPhenotypes(gen_pheno: Tensor, Wk: Tensor = None, tw: int = 2) → Tensor

This function outputs reordered internal phenotypes and pathways.

Parameters:

  • gen_pheno ((torch.Tensor)) – generated phenotypes of size \(R * N * \omega\), where \(R\) is the number of phenotypes, \(N\) is the number of drugs and \(\omega\) is the length of the temporal window

  • Wk ((torch.Tensor)) – pathway to reorder. If None, the function uses the internal pathways

  • tw ((int)) – windows size (\(\omega\))

Returns:

A pair (rPh,rW) with reordered phenotypes (aligned at best with gen_pheno) and the corresponding reodering of the pathways

Return type:

torch.Tensor

test_step(batch, batch_idx) → float
training_step(batch, idx)

Parent override.

validation_step(batch, batch_idx)

Parent override.

*This function has not been tested*

class swotted.fastswotted.fastSWoTTeDTrainer(*args: Any, **kwargs: Any)

Bases: Trainer

Trainer for fast-SWoTTeD

This class redefines the lightning trainer to take into account the specificity of the training procedure in tensor decomposition.

fit(model: fastSWoTTeDModule, train_dataloaders, val_dataloaders=None, datamodule=None, ckpt_path=None)

swotted.loss_metrics module

This module contains the alternative losses that can be used in tensor decomposition tasks.

class swotted.loss_metrics.Bernoulli

Bases: Loss

Frobenius loss to be used with data assuming a bernoulli distribution of their values (discrete values).

compute(X, Y)
class swotted.loss_metrics.Frobenius

Bases: Loss

Frobenius loss to be used with data assuming a gaussian distribution of their values.

compute(X, Y)
class swotted.loss_metrics.Loss

Bases: object

Difference loss

compute(X, Y)
class swotted.loss_metrics.Poisson

Bases: Loss

Frobenius loss to be used with data assuming a Poisson distribution of their values (counting attribute).

compute(X, Y)

swotted.slidingWindow_model module

Sliding Windows reconstruction module

This module implements the SWoTTeD reconstruction of tensors based on the temporal convolution of the temporal phenotypes with a pathways.

Example

from model.slidingWindow_model import SlidingWindow
from model.loss_metrics import Bernoulli
import torch

Ph = torch.rand( (5,10,3) ) # generation of 5 phenotypes with 10 features and 3 timestamps
Wp = torch.rand( (5,12) )   # generation of a pathway describing the occurrences of the 5 phenotypes across time

sw=SlidingWindow()
sw.setMetric(Bernoulli())

Yp=sw.reconstruct(Wp,Ph)
class swotted.slidingWindow_model.SlidingWindow(*args, **kwargs)

Bases: Module

Torch module for the computation of the reconstruction error by sliding phenotypes.

forward(X, W, Ph, padding=None)

Evaluation of the SWoTTeD reconstruction loss for a collection of patients (see reconstruct method).

Parameters:

  • Xp (list[torch.Tensor]) – A 3nd-order tensor of size \(K* N * Tp\), where \(K\) is the number of patients, \(N\) is the number of drugs and \(Tp\) is the time of the patient’s stay

  • Ph (torch.Tensor) – Phenotypes of size \(R * N * \omega\), where \(R\) is the number of phenotypes and \(\omega\) the length of the temporal window

  • Wp (list[torch.Tensor]) – Assignement tensor of size \(K* R * Tp\) for patient \(p\)

  • padding (None, bool or tuple) – If padding is True then the loss is evaluated on the interval \([\omega, L-\omega]\) of the pathway. If padding is a tuple (a,b), then the loss is evaluated on the interval \([a, L-b]\). Default is None (no padding)

Returns:

The SWoTTeD reconstruction loss of a collection of patients, that is the sum of the losses for all patients.

Return type:

float

loss(Xp, Wp, Ph, padding=None)

Evaluation of the SWoTTeD reconstruction loss (see reconstruct method).

Parameters:

  • Xp (torch.Tensor) – A 2nd-order tensor of size \(N * Tp\), where \(N\) is the number of drugs and \(Tp\) is the time of the patient’s stay

  • Ph (torch.Tensor) – Phenotypes of size \(R * N * \omega\), where \(R\) is the number of phenotypes and \(\omega\) the length of the temporal window

  • Wp (torch.Tensor) – Assignement tensor of size \(R * Tp\) for patient \(p\)

  • padding (None, bool or tuple) – If padding is True then the loss is evaluated on the interval \([\omega, L-\omega]\) of the pathway. If padding is a tuple (a,b), then the loss is evaluated on the interval \([a, L-b]\). Default is None (no padding)

Returns:

the SWoTTeD reconstruction loss of one patient.

Return type:

float

reconstruct(Wp, Ph)

Implementation of the SWoTTeD reconstruction scheme (convolutional reconstruction).

Notes

The function does not ensure that the output values belongs to [0,1]

Parameters:

  • Ph (torch.Tensor) – Phenotypes of size \(R * N * \omega\), where \(R\) is the number of phenotypes and \(\omega\) the length of the temporal window

  • Wp (torch.Tensor) – Assignement tensor of size \(R * (Tp-\omega+1)\) for patient \(p\)

Returns:

the SWoTTeD reconstruction of a pathway from \(Wp\) and \(Ph\).

Return type:

torch.Tensor

setMetric(dist=<swotted.loss_metrics.Loss object>)

Define the loss used to evaluate the tensor reconstruction.

Parameters:

dist (Loss) – one of the loss metric available in the loss_metric module.

swotted.swotted module

The SWoTTeD module

class swotted.swotted.swottedModule(*args: Any, **kwargs: Any)

Bases: LightningModule

SwoTTeD module (lightning module)

configure_optimizers()

Parent override.

forecast(X)

This function forecasts the next time step using the trained phenotypes. This function can be used only with the parameter \($\omega\geq 2\) (twl>=2) (phenotypes with more than two instant).

This function makes a projection of the data with the phenotypes of the model.

For computational efficiency, the time dimension of \(X\) is reduced to \(\omega\), and then is extended \(\omega-1\) time steps on the right with empty values.

Parameters:

X (torch.Tensor) – tensor of dimension \(K* N* T\) with \(T\) to decompose according to the phenotype of the model.

Returns:

A tensor of dimension \(K* N\) that is the forecast of the next time step of \(X\).

Return type:

torch.Tensor

forward(X)

This forward function makes the decomposition of the tensor X. It contains an optimisation stage to find the best decomposition. The optimisation does not modifies the phenotypes of the model.

Parameters:

X (torch.Tensor) – tensor of dimension \(K * N * T\) to decompose according to the phenotype of the model

Returns:

A tensor of dimension \(K * R * (T-Tw)\) that is the decomposition of X according to the \(R\) phenotypes of the model

Return type:

torch.Tensor

predict_step(batch, batch_idx, dataloader_idx=0)

Parent override.

reorderPhenotypes(gen_pheno, Wk=None, tw=2)

This function outputs reordered internal phenotypes and pathways.

Parameters:

  • gen_pheno (torch.Tensor) – generated phenotypes of size \(R x N x Tw\), where \(R\) is the number of phenotypes, \(N\) is the number of drugs and \(Tw\) is the length of the temporal window

  • Wk (torch.Tensor) – pathway to reorder, if None, it uses the internal pathways

  • tw (int) – windows size

Returns:

  • A pair \((rPh,rW)\) with reordered phenotypes (aligned at best with gen_pheno) and the

  • corresponding reodering of the pathways

test_step(batch, batch_idx)

test step

training_step(batch, idx)

Parent override.

validation_step(batch, batch_idx)

Parent override.

*This function has not been tested*

class swotted.swotted.swottedTrainer(*args: Any, **kwargs: Any)

Bases: Trainer

fit(model: swottedModule, train_dataloaders, val_dataloaders=None, datamodule=None, ckpt_path=None)

swotted.temporal_regularization module

Temporal regularization module

class swotted.temporal_regularization.TemporalDependency(rank, nlayers, nhidden, dropout)

Bases: Module

Torch Module to implement the temporal regularization losses This module is based on a LSTM.

forward(Ws, device)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

init_hidden(batch_sz)
init_weights()
loss(input, target)

swotted.utils module

SWoTTeD utiles (datasets)

class swotted.utils.Subset(dataset, indices)

Bases: Dataset

swotted.utils.success_rate(base, result)
Parameters:

  • base (torch.Tensor) – phenotypes, pathways or patients matrices

  • result (torch.Tensor) – tensor with the same shape as base

swotted.utils.transform3DTensorTo4D(dataset, twl)

Module contents

SWoTTeD Module

@author: Hana Sebia and Thomas Guyet @date: 2023 @institution: Inria