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:
- 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:
- 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:
- 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)\)
- 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:
- 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
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:
- 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:
- 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:
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:
- 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:
- 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_weights()
- loss(input, target)
swotted.utils module
- 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