medmodels.treatment_effect.estimate#

Estimators class for calculating treatment effect metrics.

Classes

`ContingencyTable`(...)	Contingency table for the treatment and control groups with/without outcome.
`Estimate`(treatment_effect)	Estimators class for calculating treatment effect metrics.
`SubjectIndices`	Dictionary with the patient ids of all contingency table groups.

class ContingencyTable(number_treated_outcome_true, number_treated_outcome_false, number_control_outcome_true, number_control_outcome_false)[source]#

Bases: object

Contingency table for the treatment and control groups with/without outcome.

__getitem__(key)[source]#

Returns the number of subjects in the given group.

Parameters:: key (Literal["treated_outcome_true", "treated_outcome_false", "control_outcome_true", "control_outcome_false"]) – The key to access the number of subjects in the treatment and control groups with and without the outcome.
Return type:: int
Returns:: int – Number of subject in the selected group.

__str__()[source]#

Returns a string representation of the ContingencyTable object.

The contingency table provides an overview of the number of subjects in the treatment and control groups with the outcome (true) and without the outcome (false). :rtype: str

Example

-----------------------------------
                Outcome
Group           True     False
-----------------------------------
Treated         2        1
Control         3        3
-----------------------------------

number_control_outcome_false: int#

number_control_outcome_true: int#

number_treated_outcome_false: int#

number_treated_outcome_true: int#

class Estimate(treatment_effect)[source]#

Bases: object

Estimators class for calculating treatment effect metrics.

absolute_risk_reduction(medrecord)[source]#

Calculates the absolute risk reduction (ARR).

AR (absolute risk) is a measure of the incidence of an event in each group. ARR, in turn, quantifies the difference in risk between the treatment and control groups. It is positive if the treatment reduces the risk, and negative if it increases the risk.

Parameters:

medrecord (MedRecord) – The MedRecord object containing the data.

Return type:

float

Returns:

float –

The calculated absolute risk reduction between the treatment and: control groups.

average_treatment_effect(medrecord, outcome_variable, reference='last')[source]#

Calculates the Average Treatment Effect (ATE).

It is calculated as the difference between the outcome means of the treated and control sets. A positive ATE indicates that the treatment increased the outcome, while a negative ATE suggests a decrease.

The ATE is computed as follows when the numbers of observations in treated and control sets are N and M, respectively:

Parameters:

medrecord (MedRecord) – An instance of the MedRecord class containing medical data.
outcome_variable (MedRecordAttribute) – The attribute in the edge that contains the outcome variable. It must be numeric and continuous.
reference (Literal["first", "last"], optional) – The reference point for the exposure time. Options include “first” and “last”. If “first”, the function returns the earliest exposure edge. If “last”, the function returns the latest exposure edge. Defaults to “last”.

Return type:

float

Returns:

float – The average treatment effect.

cohens_d(medrecord, outcome_variable, reference='last')[source]#

Calculates Cohen’s D, the standardized mean difference between two sets.

This measures the effect size of the difference between two outcome means. It’s applicable for any two sets but is recommended for sets of the same size. Cohen’s D indicates how many standard deviations the two groups differ by, with 1 standard deviation equal to 1 z-score.

A rule of thumb for interpreting Cohen’s D: - Small effect = ±0.2 - Medium effect = ±0.5 - Large effect = ±0.8

If the difference is negative, it indicates the mean in the treated group is lower than the control group.

This metric provides a dimensionless measure of effect size, facilitating the comparison across different studies and contexts.

Parameters:

medrecord (MedRecord) – An instance of the MedRecord class containing medical data.
outcome_variable (MedRecordAttribute) – The attribute in the edge that contains the outcome variable. It must be numeric and continuous.
reference (Literal["first", "last"], optional) – The reference point for the exposure time. Options include “first” and “last”. If “first”, the function returns the earliest exposure edge. If “last”, the function returns the latest exposure edge. Defaults to “last”.
add_correction (bool, optional) – Whether to apply a correction factor for small sample sizes. Defaults to False.

Return type:

float

Returns:

float – The Cohen’s D coefficient, representing the effect size.

confounding_bias(medrecord)[source]#

Calculates the confounding bias (CB).

The CB is used to assess the impact of potential confounders on the observed association between treatment and outcome. A confounder is a variable that influences both the dependent (outcome) and independent (treatment) variables, potentially biasing the study results.

Interpretation of CB: - CB = 1 indicates no confounding bias. - CB != 1 suggests the presence of confounding bias.

The method relies on the relative risk (RR) as an intermediary measure and adjusts the observed association for potential confounding effects. This adjustment helps in identifying whether the observed association might be influenced by factors other than the treatment.

Parameters:: medrecord (MedRecord) – The MedRecord object containing the data.
Return type:: float
Returns:: float – The calculated confounding bias.

hazard_ratio(medrecord)[source]#

Calculates the hazard ratio (HR).

HR is used to compare the hazard rates of two groups in survival analysis.

Parameters:

medrecord (MedRecord) – The MedRecord object containing the data.

Return type:

float

Returns:

float – The calculated hazard ratio between the treatment and control groups.

Raises:

ValueError – Raises Error if the required groups are not present in the MedRecord (patients, treatments, outcomes).
ValueError – If there are no subjects in the group of treated with no outcome, in the one of controls with outcome or in the one of controls with no outcome, an error is raised. This would result in division by zero errors.
ValueError – If the control hazard rate is zero, cannot calculate HR.

hedges_g(medrecord, outcome_variable, reference='last')[source]#

Calculates Hedges’ g, the unbiased effect size estimate.

Hedges’ g is a corrected version of Cohen’s d that provides an unbiased estimate of the effect size, especially important when sample sizes are small (under 50).

The correction factor is applied regardless of the sample size.

Parameters:

medrecord (MedRecord) – An instance of the MedRecord class containing medical data.
outcome_variable (MedRecordAttribute) – The attribute in the edge that contains the outcome variable. It must be numeric and continuous.
reference (Literal["first", "last"], optional) – The reference point for the exposure time. Options include “first” and “last”. If “first”, the function returns the earliest exposure edge. If “last”, the function returns the latest exposure edge. Defaults to “last”.
add_correction (bool, optional) – Whether to apply a correction factor for small sample sizes. Defaults to False.

Return type:

float

Returns:

float – The Hedges’ g coefficient, representing the effect size.

number_needed_to_treat(medrecord)[source]#

Calculates the number needed to treat (NNT) to prevent one extra bad outcome.

NNT is derived from the absolute risk reduction (ARR) and provides an estimate of the number of patients that need to be treated to prevent one additional bad outcome.

Parameters:

medrecord (MedRecord) – The MedRecord object containing the data.

Return type:

float

Returns:

float – The calculated number needed to treat between the treatment and control groups.

Raises:

ValueError – Raises Error if the required groups are not present in the MedRecord (patients, treatments, outcomes).
ValueError – If there are no subjects in the group of treated with no outcome, in the one of controls with outcome or in the one of controls with no outcome, an error is raised. This would result in division by zero errors.
ValueError – If the ARR is zero, cannot calculate NNT.

odds_ratio(medrecord)[source]#

Calculates the odds ratio (OR).

The OR quantifies the association between exposure to a treatment and the occurrence of an outcome.

OR compares the odds of an event occurring in the treatment group to the odds in the control group, providing insight into the strength of the association between the treatment and the outcome.

Interpretation of the odds ratio: - OR = 1 indicates no difference in odds between the two groups. - OR > 1 suggests the event is more likely in the treatment group. - OR < 1 suggests the event is less likely in the treatment group.

Parameters:: medrecord (MedRecord) – The MedRecord object containing the data.
Return type:: float
Returns:: float – The calculated odds ratio between the treatment and control groups.

relative_risk(medrecord)[source]#

Calculates the relative risk (RR) of an event.

RR is a key measure in epidemiological studies for estimating the likelihood of an event in one group relative to another, in this case, the treatment group compared to the control group.

The interpretation of RR is as follows: - RR = 1 indicates no difference in risk between the two groups. - RR > 1 indicates a higher risk in the treatment group. - RR < 1 indicates a lower risk in the treatment group.

Parameters:

medrecord (MedRecord) – The MedRecord object containing the data.

Return type:

float

Returns:

float –

The calculated relative risk between the treatment and control: groups.

subject_counts(medrecord)[source]#

Overview of how many subjects are in which group from the contingency table.

Returns a contingency table object with the number of subjects in the treatment and control groups with and without the outcome.

Parameters:

medrecord (MedRecord) – The MedRecord object containing the data.

Return type:

ContingencyTable

Returns:

ContingencyTable –

The contingency table object containing the number of: subjects in the treatment and control groups with and without the outcome.

subject_indices(medrecord)[source]#

Overview of which subjects are in which group from the contingency table.

Returns a dictionary with the patient ids of all contingency table groups, i.e., the treated group with and without the outcome, and the control group with and without the outcome.

Parameters:

medrecord (MedRecord) – The MedRecord object containing the data.

Return type:

SubjectIndices

Returns:

SubjectIndices –

Dictionary with the patient ids of true and false subjects: in the treatment and control groups, respectively.

class SubjectIndices[source]#

Bases: TypedDict

Dictionary with the patient ids of all contingency table groups.

clear() → None. Remove all items from D.#

control_outcome_false: Set[Union[str, int]]#

control_outcome_true: Set[Union[str, int]]#

copy() → a shallow copy of D#

fromkeys(value=None, /)#: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#

keys() → a set-like object providing a view on D's keys#

pop(k[, d]) → v, remove specified key and return the corresponding value.#: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

treated_outcome_false: Set[Union[str, int]]#

treated_outcome_true: Set[Union[str, int]]#

update([E, ]**F) → None. Update D from dict/iterable E and F.#: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values#