optpolicy_main.OptimalPolicy.winners_losers#

OptimalPolicy.winners_losers(data_df: pandas.DataFrame, welfare_df: pandas.DataFrame, *, welfare_reference_df=None, outpath: str | Path | None = None, title: str = '') → dict#

Compare the winners and loser.

Cluster observations by their welfare change relative to the reference allocation. Only welfare changes enter the clustering; policy scores and decision, protected and materially relevant variables are used to describe the resulting groups. Actual and reference welfare, and their differences, must be numeric and finite. Invalid values raise ValueError before a cluster-label column is added to data_df. For varying welfare changes, try 2 through min(8, n - 1, u) clusters, where n is the number of observations and u the number of distinct changes. Merge clusters containing fewer than 1% of observations with their nearest remaining cluster, then select the candidate with the highest valid average silhouette score. The retained number of clusters can be smaller. Varying changes require at least three observations. A ValueError is raised if no candidate clustering has a valid silhouette score.

Parameters:

  • data_df (Dataframe) – Variables used for descriptions.

  • welfare_df (DataFrame) – Welfare under the allocation being evaluated. Must contain exactly one column and the same number of observations as data_df, in the same row order. Rows are matched by position.

  • welfare_reference_df (DataFrame (or None), optional) – Welfare under the reference allocation. If supplied, must contain exactly one column and match the number and row order of observations in data_df and welfare_df. The default is None, which uses zero reference welfare for every observation.

  • outpath (String or Path (or None), optional) – Directory for this call’s text output. An explicit directory is created if needed and used with the configured text-file basenames. None reuses the instance’s configured text-file paths. The default is None.

  • title (String, optional) – Title used in the statistics. The default is ‘’.

Returns:

results_dict – Contains the results. This dictionary has the following structure: ‘data_plus_cluster_number_df’ : DataFrame

data_df with a cluster-label column named 'Welfare_change_cluster_<welfare>_minus_<reference>'. <welfare> and <reference> are the column names from welfare_df and welfare_reference_df; the reference name is 'zero' when welfare_reference_df is None. Labels start at 0 and increase with the cluster’s mean welfare change. If welfare changes are constant, every observation receives label 0. The supplied data_df is modified in place.

’outpath’Path or None

Supplied directory converted to Path, or the existing self.gen_cfg.outpath when outpath is None. Assigned to self.gen_cfg.outpath on successful return. Can be None when welfare changes do not vary and no output directory is configured.

Return type:

Dictionary.

Notes

Clustering descriptions are written to both text output files, even when gen_output_type is 0. Initialize with _int_with_output=True to configure the required text-file paths. An explicit outpath also needs their configured filenames. If welfare changes do not vary, the method returns before writing text. With outpath=None, this case can also run with output disabled.