mcf_main.ModifiedCausalForest.sensitivity#

ModifiedCausalForest.sensitivity(train_df, predict_df, *, results, sens_cbgate=None, sens_bgate=False, sens_gate=False, sens_iate=None, sens_iate_se=False, sens_scenarios=('basic',), sens_cv_k=5, sens_replications=2, sens_reference_population=None)#

Compute simulation based sensitivity indicators.

Parameters:

  • train_df (DataFrame.) – Data with real outcomes, treatments, and covariates. Data will be transformed to compute sensitivity indicators.

  • predict_df (DataFrame or None) – Required argument. Prediction sample for sensitivity estimation. Previous IATE results supplied through results take precedence over this argument. Otherwise, a DataFrame supplied here is used; any other value makes the method use a copy of train_df. The selected sample must satisfy the input requirements of predict() for the enabled effects.

  • results (Dictionary or None) – Required keyword argument. Pass None when no previous prediction results are to be used. Otherwise, supply the output of predict(). If it contains an ‘iate_data_df’ DataFrame and ‘iate_names_dic’, that DataFrame replaces predict_df and enables IATE computation. Common-support trimming is then disabled for the placebo estimations, and original and placebo IATEs are compared when output is enabled. A result dictionary without IATEs does not affect the analysis.

  • sens_gate (Boolean (or None), optional) – Compute GATEs for sensitivity analysis. Automatically enabled if sens_bgate or sens_cbgate is True, even when sens_gate is False or None. Otherwise, only True enables GATEs. The default is False.

  • sens_bgate (Boolean (or None), optional) – Compute BGATEs for sensitivity analysis. Requires ‘p_bgate’ to be enabled on this instance; otherwise raises ValueError. Default (or None) is False.

  • sens_cbgate (Boolean (or None), optional) – Compute CBGATEs for sensitivity analysis. Requires ‘p_cbgate’ to be enabled on this instance; otherwise raises ValueError. Default (or None) is False.

  • sens_iate (Boolean (or None), optional) – Compute IATEs for sensitivity analysis. If results contains IATEs in ‘iate_data_df’ and their names in ‘iate_names_dic’, IATE computation is enabled even if sens_iate is False. Otherwise, IATEs are computed only if sens_iate is True. The default is None.

  • sens_iate_se (Boolean (or None), optional) – Compute Standard errors of IATEs for sensitivity analysis. Default (or None) is False.

  • sens_scenarios (String, list or tuple of strings (or None), optional) – Only the ‘basic’ scenario is supported. Pass ‘basic’ as a string or in a nonempty list or tuple. Other scenario names raise ValueError. This scenario draws placebo treatments using estimated treatment probabilities for observations in the selected reference population. Their outcomes remain unchanged, giving a scenario with no treatment effect. Default (or None) is (‘basic’,).

  • sens_cv_k (Integer or float (or None), optional) – Number of cross-fitting folds for estimating treatment probabilities used to simulate placebo treatments. None or values below 0.5 select 5 folds; otherwise, the value is rounded with Python’s round(). Use at least 2 folds and no more folds than the number of training observations remaining after data preparation. The default (or None) is 5.

  • sens_replications (Integer or float (or None), optional) – Number of placebo replications per sensitivity scenario. Each replication simulates new treatments, retrains the model and predicts the requested effects. None or values below 0.5 select 2 replications; otherwise, the value is rounded with Python’s round(). Choose a value that produces at least 1 replication. The default (or None) is 2.

  • sens_reference_population (Integer or float (or None), optional) – Treatment group in train_df used to construct the placebo training samples. Specify the treatment code after train_df has been recoded to consecutive integers starting at 0. For example, input values 1, 4 and 5 become 0, 1 and 2. Treatment probabilities are estimated using all retained training observations; placebo treatments are then simulated only for the selected group. The prediction sample is determined separately by predict_df and results. Default (or None) selects the largest treatment group after data preparation.

Returns:

results_avg – Dictionary keyed by sensitivity scenario. Currently, only ‘basic’ is supported; access its results as results_avg[‘basic’]. Each value has the structure of a result dictionary returned by predict(). ATEs and available GATE, BGATE and CBGATE estimates, including their differences, are averaged across replications. Their standard errors are also averaged arithmetically. If IATEs are computed, ‘iate_data_df’ contains averages across replications for observation identifiers present in every replication. Other entries are taken from the first replication.

Return type:

Dictionary

Raises:

NotImplementedError – If feature selection is enabled (‘fs_yes=True’) or treatments are continuous (‘gen_d_type’ is ‘continuous’).