ScorePhenotype

Bases: ComputationGraphPhenotype

ScorePhenotype is a CompositePhenotype that performs arithmetic operations using the boolean column of its component phenotypes and populations the value column. It should be used for calculating medical scores such as CHADSVASC, HASBLED, etc.

--> 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
hypertension = Phenotype(Codelist('hypertension'))
hf = Phenotype(Codelist('chf'))
age_gt_45 = AgePhenotype(min_age=GreaterThan(45))

# Create the ScorePhenotype that defines a score which is 2*age + 1 if
# hypertension or chf are present, respectively. Notice that the boolean
# column of the component phenotypes are used for calculation and the value
# column is populated of the ScorePhenotype table.
pt = ScorePhenotype(
    expression = 2 * age_gt_45 + hypertension + chf,
)

Source code in phenex/phenotypes/computation_graph_phenotypes.py

class ScorePhenotype(ComputationGraphPhenotype):
    """
    ScorePhenotype is a CompositePhenotype that performs arithmetic operations using the **boolean** column of its component phenotypes and populations the **value** column. It should be used for calculating medical scores such as CHADSVASC, HASBLED, etc.

    --> 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
    hypertension = Phenotype(Codelist('hypertension'))
    hf = Phenotype(Codelist('chf'))
    age_gt_45 = AgePhenotype(min_age=GreaterThan(45))

    # Create the ScorePhenotype that defines a score which is 2*age + 1 if
    # hypertension or chf are present, respectively. Notice that the boolean
    # column of the component phenotypes are used for calculation and the value
    # column is populated of the ScorePhenotype table.
    pt = ScorePhenotype(
        expression = 2 * age_gt_45 + hypertension + chf,
    )
    ```
    """

    def __init__(
        self,
        expression: ComputationGraph,
        return_date: Union[str, Phenotype] = "first",
        name: str = None,
        **kwargs,
    ):
        super(ScorePhenotype, self).__init__(
            name=name,
            expression=expression,
            return_date=return_date,
            operate_on="boolean",
            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