swotted package

Submodules

swotted.decomposition_contraints module

swotted.decomposition_contraints.nonnegative_projection(*var)

swotted.decomposition_contraints.normalization_constraint(*var)

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)

swotted.decomposition_contraints.sparsity_constraint(var)

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

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

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

swotted.loss_metrics module

class swotted.loss_metrics.Bernoulli

Bases: Loss

compute(X, Y)

class swotted.loss_metrics.Frobenius

Bases: Loss

compute(X, Y)

class swotted.loss_metrics.Loss

Bases: object

compute(X, Y)

class swotted.loss_metrics.Poisson

Bases: Loss

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

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

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

Bases: LightningModule

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

Return type:

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)

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

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

Bases: Module

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

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