LifeTwin Simulation Language

LifeTwin Modelling Language

Data distribution section

These Python classes are critical for simulating and statistical behavior on our population attributes. The classes of this section are then represented in the tree in the next figure.

Attribute Transformations

This table outlines the Python classes designed for manipulating and sampling parameter values in a population model. The classes range from interfaces, like LimitValue, to more specialized classes, like Uniform and Normal, which inherit from Distribution.

Class	Inherits From	Description
`LimitValue`	–	An interface that mandates the implementation of a `sample()` method and a `contains_distribution()` method for value limitations.
`Clap`	`LimitValue`	Clamps a given source value within specified minimum and maximum bounds. Capable of sampling from nested `LimitValue` objects.
`Distribution`	`LimitValue`	An abstract class for generating samples from a distribution. Always returns true for `contains_distribution()`.
`Uniform`	`Distribution`	Generates samples from a uniform distribution given minimum and maximum bounds.
`Normal`	`Distribution`	Generates samples from a normal distribution specified by a mean and standard deviation.
`Normal95IC`	–	Utility function that returns a `Normal` object, whose mean and standard deviation are calculated based on 95% confidence intervals.
`LogNormal`	`Distribution`	Generates samples from a log-normal distribution specified by a mean and standard deviation.

Transformation section

This table describes the Python classes responsible for transformations on attributes. These classes provide utilities for a wide range of modifications, from simple value assignments (Set) to complex conditional transformations (OnSubset). These transformations are applied to the attributes and can introduce deterministic or stochastic changes.

Class	Inherits From	Description
`Transformation`	–	Interface necessary to implement attribute transformations. It requires subclasses to implement `apply()` and `contains_distribution()`.
`Set`	`Transformation`	Sets an attribute to a specific value.
`WithProbability`	`Transformation`	Applies a nested transformation with a given probability.
`Group`	`Transformation`	Applies a sequence of transformations to attributes.
`OnSubset`	`Transformation`	Conditionally applies a transformation based on a relational operator.
`Reduce`	`Transformation`	Decreases an attribute by a given value.
`ReduceByPercentage`	`Transformation`	Decreases an attribute by a given percentage.
`Increase`	`Transformation`	Increases an attribute by a given value.
`IncreaseByPercentage`	`Transformation`	Increases an attribute by a given percentage.
`RegressToValue`	`Transformation`	Adjusts an attribute towards a specific value by a percentage.

This table outlines a set of Python classes designed for implementing timedependent attribute transformations. These classes inherit from a base TimeDelta class and provide different strategies to apply transformations based on the passage of time. For instance, the Every class applies a transformation every n years, while the Once class triggers the transformation in a specific year

Class	Inherits From	Description
`Transformation`	–	Interface necessary to implement attribute transformations. It requires subclasses to implement `apply()` and `contains_distribution()`.
`Set`	`Transformation`	Sets an attribute to a specific value.
`WithProbability`	`Transformation`	Applies a nested transformation with a given probability.
`Group`	`Transformation`	Applies a sequence of transformations to attributes.
`OnSubset`	`Transformation`	Conditionally applies a transformation based on a relational operator.
`Reduce`	`Transformation`	Decreases an attribute by a given value.
`ReduceByPercentage`	`Transformation`	Decreases an attribute by a given percentage.
`Increase`	`Transformation`	Increases an attribute by a given value.
`IncreaseByPercentage`	`Transformation`	Increases an attribute by a given percentage.
`RegressToValue`	`Transformation`	Adjusts an attribute towards a specific value by a percentage.

This file contains classes and functions for implementing limit values, distributions, transformations, and time delta transformations. It includes functionality for sampling, containing distributions, applying transformations, and checking if a transformation should be applied in the current year. The classes and functions are designed to be easily extended and overridden for specific use cases.

class transformations.After(year: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation in the years after the specified year. The ‘apply_this_year’ method returns True if the transformation should be applied in the years after the specified year, otherwise returns False. Additionally, it prints the comparison details.

apply_this_year(delta_years): Returns True if the transformation should be applied in the years after the specified year, otherwise returns False. Additionally, it prints the comparison details.

transformation: Transformation

year: int

class transformations.Always(transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation every year. The ‘apply_this_year’ method always returns True, indicating that the transformation should be applied every year.

apply_this_year(delta_years): Always returns True, indicating that the transformation should be applied every year.

transformation: Transformation

class transformations.Before(year: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation in the years before the specified year. The ‘apply_this_year’ method returns True if the transformation should be applied in the years before the specified year, otherwise returns False.

apply_this_year(delta_years): Returns True if the transformation should be applied in the years before the specified year, otherwise returns False.

transformation: Transformation

year: int

class transformations.BeforeAndThen(year: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation in the current year or any year before the specified year. The ‘apply_this_year’ method returns True if the transformation should be applied in the current year or any year before the specified year, otherwise returns False.

apply_this_year(delta_years): Returns True if the transformation should be applied in the current year or any year before the specified year, otherwise returns False.

transformation: Transformation

year: int

Bases: LimitValue

This class represents a limit value with minimum and maximum constraints. It also includes a source value. The ‘sample’ method returns a value from the source, ensuring it falls within the specified minimum and maximum limits. The ‘contains_distribution’ method returns True if the distribution is contained within the minimum and maximum limits, otherwise returns False.

contains_distribution(): Returns True if the distribution is contained within the minimum and maximum limits, otherwise returns False.

max: int | float | LimitValue

min: int | float | LimitValue

sample(): Returns the sampled value from the source, ensuring it falls within the specified minimum and maximum limits.

source: int | float | LimitValue

class transformations.Distribution

Bases: LimitValue

This class represents a distribution within the limits. The ‘contains_distribution’ method always returns True, indicating that the distribution is contained within the limits.

contains_distribution(): Returns True, indicating that the distribution is contained within the limits.

class transformations.Every(years: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation every ‘n’ years. The ‘apply_this_year’ method returns True if the transformation should be applied in the current year based on the specified number of years, otherwise returns False.

apply_this_year(delta_years): Returns True if the transformation should be applied in the current year based on the specified number of years, otherwise returns False.

transformation: Transformation

years: int

class transformations.Group(transformations: list[Transformation])

Bases: Transformation

This class represents a group of transformations that are applied to the attributes. The ‘apply’ method applies each transformation in the list to the attributes and returns the updated attributes. The ‘contains_distribution’ method returns True if any of the transformations contain a distribution, otherwise returns False.

apply(attributes, delta_years): Applies each transformation in the list to the attributes and returns the updated attributes.

contains_distribution(): Returns True if any of the transformations contain a distribution, otherwise returns False.

transformations: list[Transformation]

class transformations.Increase(id: int | str | OMOPId, value: int | float | LimitValue)

Bases: Transformation

This class represents an increase transformation, which adds the value to the attribute associated with the ID. The ‘apply’ method adds the value to the attribute associated with the ID and returns the updated attributes. The ‘contains_distribution’ method returns True if the value contains a distribution, otherwise returns False.

apply(attributes, delta_years): Adds the value to the attribute associated with the ID and returns the updated attributes.

contains_distribution(): Returns True if the value contains a distribution, otherwise returns False.

id: int | str | OMOPId

value: int | float | LimitValue

class transformations.IncreaseByPercentage(id: int | str | OMOPId, percentage: int | float | LimitValue)

Bases: Transformation

This class represents an increase by percentage transformation, which increases the attribute value by a certain percentage. The ‘apply’ method increases the attribute value by a certain percentage and returns the updated attributes. The ‘contains_distribution’ method returns True if the percentage contains a distribution, otherwise returns False.

apply(attributes, delta_years): Increases the attribute value by a certain percentage and returns the updated attributes.

contains_distribution(): Returns True if the percentage contains a distribution, otherwise returns False.

id: int | str | OMOPId

percentage: int | float | LimitValue

class transformations.LimitValue

Bases: ABC

This class is an abstract base class for implementing limit value functionality. It contains abstract methods ‘sample’ and ‘contains_distribution’ which must be implemented by subclasses. These methods do not contain any implementation and should be overridden in the derived classes.

abstract contains_distribution(): This is an abstract method that should be implemented by subclasses. It does not contain any implementation and should be overridden in the derived classes.

abstract sample(): This is an abstract method that should be implemented by subclasses. It does not contain any implementation and should be overridden in the derived classes.

class transformations.LogNormal(mean: int | float, std: int | float)

Bases: Distribution

This class represents a log-normal distribution with the specified mean and standard deviation. The ‘sample’ method returns a randomly sampled value from a log-normal distribution with the specified mean and standard deviation.

mean: int | float

sample(): Returns a randomly sampled value from a log-normal distribution with the specified mean and standard deviation.

std: int | float

class transformations.Normal(mean: int | float, std: int | float)

Bases: Distribution

This class represents a normal distribution with the specified mean and standard deviation. The ‘sample’ method returns a randomly sampled value from a normal distribution with the specified mean and standard deviation.

mean: int | float

sample(): Returns a randomly sampled value from a normal distribution with the specified mean and standard deviation.

std: int | float

transformations.Normal95IC(min, max): Returns a normal distribution with a mean and standard deviation calculated from the given minimum and maximum values, representing a 95% confidence interval.

class transformations.OnRange(start: int, end: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation within the specified range of years. The ‘apply_this_year’ method returns True if the transformation should be applied within the specified range of years, otherwise returns False.

apply_this_year(delta_years): Returns True if the transformation should be applied within the specified range of years, otherwise returns False.

end: int

start: int

transformation: Transformation

class transformations.OnSubset(id: int | str | OMOPId, value: int | float, operator: str, transformation: Transformation)

Bases: Transformation

This class represents a transformation that is applied to the attributes based on the comparison result between the specified attribute and value. The ‘apply’ method applies the transformation to the attributes based on the comparison result between the specified attribute and value, and returns the updated attributes. If the comparison operator is invalid, a ValueError is raised. The ‘contains_distribution’ method returns True if the transformation contains a distribution, otherwise returns False.

apply(attributes, delta_years): Applies the transformation to the attributes based on the comparison result between the specified attribute and value, and returns the updated attributes. If the comparison operator is invalid, a ValueError is raised.

contains_distribution(): Returns True if the transformation contains a distribution, otherwise returns False.

id: int | str | OMOPId

operator: str

transformation: Transformation

value: int | float

class transformations.Once(year: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation once in a specific year. The ‘apply_this_year’ method returns True if the transformation should be applied in the current year based on the specified year, otherwise returns False.

apply_this_year(delta_years): Returns True if the transformation should be applied in the current year based on the specified year, otherwise returns False.

transformation: Transformation

year: int

class transformations.Reduce(id: int | str | OMOPId, value: int | float | LimitValue)

Bases: Transformation

This class represents a reduction transformation, which subtracts the value associated with the ID from the attributes. The ‘apply’ method subtracts the value associated with the ID from the attributes and returns the updated attributes. The ‘contains_distribution’ method returns True if the value contains a distribution, otherwise returns False.

apply(attributes, delta_years): Subtracts the value associated with the ID from the attributes and returns the updated attributes.

contains_distribution(): Returns True if the value contains a distribution, otherwise returns False.

id: int | str | OMOPId

value: int | float | LimitValue

class transformations.ReduceByPercentage(id: int | str | OMOPId, percentage: int | float | LimitValue)

Bases: Transformation

This class represents a reduction by percentage transformation, which reduces the attribute value by a certain percentage. The ‘apply’ method reduces the attribute value by a certain percentage and returns the updated attributes. The ‘contains_distribution’ method returns True if the percentage contains a distribution, otherwise returns False.

apply(attributes, delta_years): Reduces the attribute value by a certain percentage and returns the updated attributes.

contains_distribution(): Returns True if the percentage contains a distribution, otherwise returns False.

id: int | str | OMOPId

percentage: int | float | LimitValue

Bases: Transformation

This class represents a regression to value transformation, which adjusts the attribute value based on the specified value and percentage, ensuring it does not exceed the value. The ‘apply’ method adjusts the attribute value based on the specified value and percentage, ensuring it does not exceed the value, and returns the updated attributes. Additionally, it prints the regression details. The ‘contains_distribution’ method returns True if either the value or the percentage contains a distribution, otherwise returns False.

apply(attributes, delta_years): Adjusts the attribute value based on the specified value and percentage, ensuring it does not exceed the value, and returns the updated attributes. Additionally, it prints the regression details.

contains_distribution(): Returns True if either the value or the percentage contains a distribution, otherwise returns False.

id: int | str | OMOPId

percentage: int | float | LimitValue

value: int | float | LimitValue

class transformations.Set(id: int | str | OMOPId, value: int | float | LimitValue)

Bases: Transformation

This class represents a set transformation, which updates the attributes with the value associated with the ID. The ‘apply’ method updates the attributes with the value associated with the ID, and returns the updated attributes. The ‘contains_distribution’ method returns True if the value contains a distribution, otherwise returns False.

apply(attributes, delta_years): Updates the attributes with the value associated with the ID, and returns the updated attributes.

contains_distribution(): Returns True if the value contains a distribution, otherwise returns False.

id: int | str | OMOPId

value: int | float | LimitValue

class transformations.ThenOnwards(year: int, transformation: Transformation)

Bases: TimeDelta

This class represents a time delta transformation that applies the specified transformation from a specific year onwards. The ‘apply_this_year’ method returns True if the transformation should be applied in the current year or any year after the specified year, otherwise returns False.

apply_this_year(delta_years): Returns True if the transformation should be applied in the current year or any year after the specified year, otherwise returns False.

transformation: Transformation

year: int

class transformations.TimeDelta

Bases: Transformation

This class represents a time delta transformation, which applies the transformation to the attributes if it should be applied in the current year. The ‘apply’ method applies the transformation to the attributes if it should be applied in the current year, and returns the updated attributes. The ‘contains_distribution’ method returns True if the transformation contains a distribution, otherwise returns False.

apply(attributes, delta_years): Applies the transformation to the attributes if it should be applied in the current year, and returns the updated attributes.

abstract apply_this_year(delta_years): This is an abstract method that should be implemented by subclasses. It does not contain any implementation and should be overridden in the derived classes.

contains_distribution(): Returns True if the transformation contains a distribution, otherwise returns False.

class transformations.Transformation

Bases: ABC

This class is an abstract base class for implementing transformations. It contains abstract methods ‘apply’ and ‘contains_distribution’ which must be implemented by subclasses. These methods do not contain any implementation and should be overridden in the derived classes.

abstract apply(attributes, delta_years): This is an abstract method that should be implemented by subclasses. It does not contain any implementation and should be overridden in the derived classes.

abstract contains_distribution(): This is an abstract method that should be implemented by subclasses. It does not contain any implementation and should be overridden in the derived classes.

class transformations.Uniform(min: int | float, max: int | float)

Bases: Distribution

This class represents a uniform distribution within the specified minimum and maximum limits. The ‘sample’ method returns a randomly sampled value within the specified limits.

max: int | float

min: int | float

sample(): Returns a randomly sampled value within the specified minimum and maximum limits.

class transformations.WithProbability(probability: float | LimitValue, transformation: Transformation)

Bases: Transformation

This class represents a transformation with a certain probability of application. The ‘apply’ method applies the transformation to the attributes with a certain probability and returns the updated attributes. The ‘contains_distribution’ method returns True if either the probability or the transformation contains a distribution, otherwise returns False.

apply(attributes, delta_years): Applies the transformation to the attributes with a certain probability and returns the updated attributes.

contains_distribution(): Returns True if either the probability or the transformation contains a distribution, otherwise returns False.

probability: float | LimitValue

transformation: Transformation

transformations.get_as_id(value: int | str | OMOPId): Returns the input value as an OMOPId object if it is not already, otherwise returns the input value.

transformations.get_id_value(value: int | str | OMOPId): Returns the ID value if the input is an OMOPId object, otherwise returns the input value.

transformations.get_value(value: int | float | LimitValue): Returns the sampled value if the input is a LimitValue object, otherwise returns the input value.