openavmkit.vertical_equity_study

Vertical equity analysis.

Implements :class:VerticalEquityStudy, which measures whether high-value parcels and low-value parcels are valued with the same accuracy — the "vertical equity" question. Computes PRD and PRB (with bootstrap confidence intervals) plus per-quantile median ratios.

Together with :mod:openavmkit.horizontal_equity_study and :mod:openavmkit.ratio_study, this module forms OpenAVMKit's IAAO-aligned equity analysis suite.

VerticalEquityStudy

VerticalEquityStudy(df_sales_in, field_sales, field_prediction, field_location, confidence_interval=0.95, iterations=10000, seed=777)

Perform vertical equity analysis and summarize the results.

Attributes:

Name	Type	Description
rows	int	Total number of rows in the input DataFrame.
confidence_interval	float	The confidence interval (e.g. 0.95 for 95% confidence)
prd	ConfidenceStat	The price-related differential, with confidence intervals
prb	ConfidenceStat	The price-related bias, with confidence intervals
quantiles	DataFrame	A dataframe containing the median ratio, with confidence intervals, of all ten price quantile tiers

Source code in openavmkit/vertical_equity_study.py

def __init__(
    self,
    df_sales_in: pd.DataFrame,
    field_sales: str,
    field_prediction: str,
    field_location: str,
    confidence_interval : float = 0.95,
    iterations: int = 10000,
    seed : int = 777
):
    df_sales = df_sales_in.copy()

    n = len(df_sales)
    self.rows = n
    self.confidence_interval = confidence_interval

    # Calculate PRD and PRB
    #----------------------

    predictions = df_sales[field_prediction].to_numpy()
    sales = df_sales[field_sales].to_numpy()

    results = calc_ratio_stats_bootstrap(predictions, sales, confidence_interval, iterations=iterations, seed=seed)
    self.prd = results["prd"]

    prb_point, prb_low, prb_high = calc_prb(predictions, sales, confidence_interval)

    self.prb = ConfidenceStat(prb_point, confidence_interval, prb_low, prb_high)

    # Calculate quantiles (directly from price)
    #------------------------------------------

    df_sales["quantile"] = _calc_quantiles(df_sales_in, field_sales)
    df = _assemble_quantile_df(df_sales, field_sales, field_prediction, confidence_interval, iterations, seed)
    self.quantiles = df
    # Calculate quantiles (grouped price)
    #------------------------------------------

    if field_location is not None and field_location in df_sales_in.columns:
        df_sales["quantile"] = _calc_grouped_quantiles(df_sales_in, field_sales, field_location)
        df = _assemble_quantile_df(df_sales, field_sales,  field_prediction, confidence_interval, iterations, seed)
        self.grouped_quantiles = df
    else:
        warnings.warn(f"VerticalEquityStudy: could not find location field, \"{field_location}\" in sales dataframe")
        self.grouped_quantiles = None