ArithmeticPhenotype

Bases: ComputationGraphPhenotype

ArithmeticPhenotype is a composite phenotype that performs arithmetic operations using the value column of its component phenotypes and populations the value column. It should be used for calculating values such as BMI, GFR or converting units. --> See the comparison table of CompositePhenotype classes

Parameters:

Name	Type	Description	Default
expression	ComputationGraph	The arithmetic expression to be evaluated composed of phenotypes combined by python arithmetic operations.	required
return_date	Union[str, Phenotype]	The date to be returned for the phenotype. Can be "first", "last", or a Phenotype object.	'first'
name	str	The name of the phenotype.	None

Attributes:

Name	Type	Description
table	PhenotypeTable	The resulting phenotype table after filtering (None until execute is called)

Example:

# Create component phenotypes individually
height = MeasurementPhenotype(Codelist('height'))
weight = MeasurementPhenotype(Codelist('weight'))

# Create the ArithmeticPhenotype that defines the BMI score
bmi = ArithmeticPhenotype(
    expression = weight / height**2,
)

Source code in phenex/phenotypes/computation_graph_phenotypes.py

class ArithmeticPhenotype(ComputationGraphPhenotype):
    """
    ArithmeticPhenotype is a composite phenotype that performs arithmetic operations using the **value** column of its component phenotypes and populations the **value** column. It should be used for calculating values such as BMI, GFR or converting units.
    --> See the comparison table of CompositePhenotype classes

    Parameters:
        expression: The arithmetic expression to be evaluated composed of phenotypes combined by python arithmetic operations.
        return_date: The date to be returned for the phenotype. Can be "first", "last", or a Phenotype object.
        name: The name of the phenotype.

    Attributes:
        table (PhenotypeTable): The resulting phenotype table after filtering (None until execute is called)

    Example:
    ```python
    # Create component phenotypes individually
    height = MeasurementPhenotype(Codelist('height'))
    weight = MeasurementPhenotype(Codelist('weight'))

    # Create the ArithmeticPhenotype that defines the BMI score
    bmi = ArithmeticPhenotype(
        expression = weight / height**2,
    )
    ```
    """

    def __init__(
        self,
        expression: ComputationGraph,
        return_date: Union[str, Phenotype] = "first",
        name: str = None,
        **kwargs,
    ):
        super(ArithmeticPhenotype, self).__init__(
            name=name,
            expression=expression,
            return_date=return_date,
            operate_on="value",
            populate="value",
        )

namespaced_table property

A PhenotypeTable has generic column names 'person_id', 'boolean', 'event_date', and 'value'. The namespaced_table appends the phenotype name to all of these columns. This is useful when joining multiple phenotype tables together.

Returns:

Name	Type	Description
table	Table	The namespaced table for the current phenotype.

execute(tables)

Executes the phenotype computation for the current object and its children. This method recursively iterates over the children of the current object and calls their execute method if their table attribute is None.

Parameters:

Name	Type	Description	Default
tables	Dict[str, PhenexTable]	A dictionary mapping table names to PhenexTable objects. See phenex.mappers.DomainsDictionary.get_mapped_tables().	required

Returns:

Name	Type	Description
table	PhenotypeTable	The resulting phenotype table containing the required columns. The PhenotypeTable will contain the columns: PERSON_ID, EVENT_DATE, VALUE. DATE is determined by the return_date parameter. VALUE is different for each phenotype. For example, AgePhenotype will return the age in the VALUE column. A MeasurementPhenotype will return the observed value for the measurement. See the specific phenotype of interest to understand more.

Source code in phenex/phenotypes/phenotype.py

def execute(self, tables: Dict[str, Table]) -> PhenotypeTable:
    """
    Executes the phenotype computation for the current object and its children. This method recursively iterates over the children of the current object and calls their execute method if their table attribute is None.

    Args:
        tables (Dict[str, PhenexTable]): A dictionary mapping table names to PhenexTable objects. See phenex.mappers.DomainsDictionary.get_mapped_tables().

    Returns:
        table (PhenotypeTable): The resulting phenotype table containing the required columns. The PhenotypeTable will contain the columns: PERSON_ID, EVENT_DATE, VALUE. DATE is determined by the return_date parameter. VALUE is different for each phenotype. For example, AgePhenotype will return the age in the VALUE column. A MeasurementPhenotype will return the observed value for the measurement. See the specific phenotype of interest to understand more.
    """
    logger.info(f"Phenotype '{self.name}': executing...")
    for child in self.children:
        if child.table is None:
            logger.debug(
                f"Phenotype {self.name}: executing child phenotype '{child.name}'..."
            )
            child.execute(tables)
        else:
            logger.debug(
                f"Phenotype {self.name}: skipping already computed child phenotype '{child.name}'."
            )

    table = self._execute(tables).mutate(BOOLEAN=True)

    if not set(PHENOTYPE_TABLE_COLUMNS) <= set(table.columns):
        raise ValueError(
            f"Phenotype {self.name} must return columns {PHENOTYPE_TABLE_COLUMNS}. Found {table.columns}."
        )

    self.table = table.select(PHENOTYPE_TABLE_COLUMNS)
    # for some reason, having NULL datatype screws up writing the table to disk; here we make explicit cast
    if type(self.table.schema()["VALUE"]) == ibis.expr.datatypes.core.Null:
        self.table = self.table.cast({"VALUE": "float64"})

    assert is_phenex_phenotype_table(self.table)
    logger.info(f"Phenotype '{self.name}': execution completed.")
    return self.table