TimeRangePhenotype

Bases: Phenotype

As the name implies, TimeRangePhenotype is designed for working with time ranges. If the input data has a start and an end date, use TimeRangePhenotype to identify other events (or patients) that occur within this time range. The most common use case of this is working with 'health insurance coverage' data i.e. on 'OBSERVATION_PERIOD' table. These tables have one or many rows per patient with the start of coverage and end of coverage i.e. domains compatible with TimeRangePhenotype require a START_DATE and an END_DATE column. At it's simplest, TimeRangePhenotype identifies patients who have their INDEX_DATE (or other anchor date of interest) within this time range. Additionally, a minimum or maximum number of days from the anchor date to the beginning/end of the time range can be defined. The returned Phenotype has the following interpretation:

DATE: If relative_time_range.when='before', then DATE is the beginning of the coverage period containing the anchor phenotype. If relative_time_range.when='after', then DATE is the end of the coverage period containing the anchor date. VALUE: Coverage (in days) relative to the anchor date. By convention, always non-negative.

There are two primary use cases for TimeRangePhenotype

1. Identify patients with some minimum duration of coverage prior to anchor_phenotype date e.g. "identify patients with 1 year of continuous coverage prior to index date"
2. Determine the date of loss to followup (right censoring) i.e. the duration of coverage after the anchor_phenotype event

Data for TimeRangePhenotype

This phenotype requires a table with PersonID and a coverage start date and end date. Depending on the datasource used, this information is a separate ObservationPeriod table or found in the PersonTable. Use an PhenexObservationPeriodTable to map required coverage start and end date columns. For tables with overlapping time ranges, use the CombineOverlappingPeriods derived table to combine time ranges into a single time range.

PersonID	startDate	endDate
1	2009-01-01	2010-01-01
2	2008-01-01	2010-01-02

One assumption that is made by TimeRangePhenotype is that there are NO overlapping coverage periods.

Parameters:

Name	Type	Description	Default
name	Optional[str]	The name of the phenotype.	'TIME_RANGE'
domain	Optional[str]	The domain of the phenotype. Default is 'observation_period'.	'OBSERVATION_PERIOD'
relative_time_range	Optional[RelativeTimeRangeFilter]	Filter returned persons based on the duration of coverage in days. The relative_time_range.anchor_phenotype defines the reference date with respect to calculate coverage. In typical applications, the anchor phenotype will be the entry criterion. The relative_time_range.when 'before', 'after'. If before, the return date is the start of the coverage period containing the anchor_phenotype. If after, the return date is the end of the coverage period containing the anchor_phenotype.	None

Example:

# make sure to create an entry phenotype, for example 'atrial fibrillation diagnosis'
entry_phenotype = CodelistPhenotype(...)
# one year continuous coverage prior to index
one_year_coverage = TimeRangePhenotype(
    relative_time_range = RelativeTimeRangeFilter(
        min_days=GreaterThanOrEqualTo(365),
        anchor_phenotype = entry_phenotype,
        when = 'before',
    ),
)
# determine the date of loss to followup
loss_to_followup = TimeRangePhenotype(
    relative_time_range = RelativeTimeRangeFilter(
        anchor_phenotype = entry_phenotype
        when = 'after',
    )
)

# determine the date when a drug was discontinued
drug_discontinuation = TimeRangePhenotype(
    relative_time_range = RelativeTimeRangeFilter(
        anchor_phenotype = entry_phenotype
        when = 'after',
    )
)

Source code in phenex/phenotypes/time_range_phenotype.py

class TimeRangePhenotype(Phenotype):
    """
    As the name implies, TimeRangePhenotype is designed for working with time ranges. If the input data has a start and an end date, use TimeRangePhenotype to identify other events (or patients) that occur within this time range. The most common use case of this is working with 'health insurance coverage' data i.e. on 'OBSERVATION_PERIOD' table. These tables have one or many rows per patient with the start of coverage and end of coverage i.e. domains compatible with TimeRangePhenotype require a START_DATE and an END_DATE column. At it's simplest, TimeRangePhenotype identifies patients who have their INDEX_DATE (or other anchor date of interest) within this time range. Additionally, a minimum or maximum number of days from the anchor date to the beginning/end of the time range can be defined. The returned Phenotype has the following interpretation:

    DATE: If relative_time_range.when='before', then DATE is the beginning of the coverage period containing the anchor phenotype. If relative_time_range.when='after', then DATE is the end of the coverage period containing the anchor date.
    VALUE: Coverage (in days) relative to the anchor date. By convention, always non-negative.

    There are two primary use cases for TimeRangePhenotype:
        1. Identify patients with some minimum duration of coverage prior to anchor_phenotype date e.g. "identify patients with 1 year of continuous coverage prior to index date"
        2. Determine the date of loss to followup (right censoring) i.e. the duration of coverage after the anchor_phenotype event

    ## Data for TimeRangePhenotype
    This phenotype requires a table with PersonID and a coverage start date and end date. Depending on the datasource used, this information is a separate ObservationPeriod table or found in the PersonTable. Use an PhenexObservationPeriodTable to map required coverage start and end date columns. For tables with overlapping time ranges, use the CombineOverlappingPeriods derived table to combine time ranges into a single time range.

    | PersonID    |   startDate          |   endDate          |
    |-------------|----------------------|--------------------|
    | 1           |   2009-01-01         |   2010-01-01       |
    | 2           |   2008-01-01         |   2010-01-02       |

    One assumption that is made by TimeRangePhenotype is that there are **NO overlapping coverage periods**.

    Parameters:
        name: The name of the phenotype.
        domain: The domain of the phenotype. Default is 'observation_period'.
        relative_time_range: Filter returned persons based on the duration of coverage in days. The relative_time_range.anchor_phenotype defines the reference date with respect to calculate coverage. In typical applications, the anchor phenotype will be the entry criterion. The relative_time_range.when 'before', 'after'. If before, the return date is the start of the coverage period containing the anchor_phenotype. If after, the return date is the end of the coverage period containing the anchor_phenotype.

    Example:
    ```python
    # make sure to create an entry phenotype, for example 'atrial fibrillation diagnosis'
    entry_phenotype = CodelistPhenotype(...)
    # one year continuous coverage prior to index
    one_year_coverage = TimeRangePhenotype(
        relative_time_range = RelativeTimeRangeFilter(
            min_days=GreaterThanOrEqualTo(365),
            anchor_phenotype = entry_phenotype,
            when = 'before',
        ),
    )
    # determine the date of loss to followup
    loss_to_followup = TimeRangePhenotype(
        relative_time_range = RelativeTimeRangeFilter(
            anchor_phenotype = entry_phenotype
            when = 'after',
        )
    )

    # determine the date when a drug was discontinued
    drug_discontinuation = TimeRangePhenotype(
        relative_time_range = RelativeTimeRangeFilter(
            anchor_phenotype = entry_phenotype
            when = 'after',
        )
    )
    ```
    """

    def __init__(
        self,
        name: Optional[str] = "TIME_RANGE",
        domain: Optional[str] = "OBSERVATION_PERIOD",
        relative_time_range: Optional["RelativeTimeRangeFilter"] = None,
        **kwargs
    ):
        super().__init__(name=name, **kwargs)
        self.domain = domain
        self.relative_time_range = relative_time_range
        if self.relative_time_range is not None:
            if self.relative_time_range.anchor_phenotype is not None:
                self.children.append(self.relative_time_range.anchor_phenotype)

    def _execute(self, tables: Dict[str, Table]) -> PhenotypeTable:
        table = tables[self.domain]
        table, reference_column = attach_anchor_and_get_reference_date(
            table, self.relative_time_range.anchor_phenotype
        )

        # Ensure that the observation period includes anchor date
        table = table.filter(
            (table.START_DATE <= reference_column)
            & (reference_column <= table.END_DATE)
        )

        if (
            self.relative_time_range is None
            or self.relative_time_range.when == "before"
        ):
            VALUE = reference_column.delta(table.START_DATE, "day")
            EVENT_DATE = table.START_DATE
        else:
            VALUE = table.END_DATE.delta(reference_column, "day")
            EVENT_DATE = table.END_DATE

        table = table.mutate(VALUE=VALUE, EVENT_DATE=EVENT_DATE)

        if self.relative_time_range is not None:
            value_filter = ValueFilter(
                min_value=self.relative_time_range.min_days,
                max_value=self.relative_time_range.max_days,
                column_name="VALUE",
            )
            ibis.options.interactive = True
            table = value_filter.filter(table)

        return table

namespaced_table property

A PhenotypeTable has generic column names 'person_id', 'boolean', 'event_date', and 'value'. The namespaced_table prepends 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