adaptive.generate_targeted_samples

generate_targeted_samples(
    df,
    input_cols,
    outcome_col,
    n_new_per_fix=10,
    failed_data=None,
    distance_threshold=0.05,
    max_gap_ratio=MAX_GAP_RATIO,
    min_r2_score=MIN_R2_SCORE,
    max_avg_cv=MAX_AVG_CV,
    max_max_cv=MAX_MAX_CV,
    max_allowed_vif=MAX_ALLOWED_VIF,
    seed=None,
)

Active Learning Engine: Generates new samples based on diagnostic failures.

It consumes the results table from sample_sufficiency. - If Input Coverage fails -> Triggers _fill_gaps (Exploration). - If Model Fit or Bootstrap fails -> Triggers _sample_uncertainty (Exploitation). - A Collinearity Check failure cannot be fixed by adding samples (it is a property of how the inputs are related), so it is reported rather than sampled. Any such failures are listed in result.attrs["unresolved"], so a caller can tell “nothing left to fix” apart from “cannot fix by sampling”.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Current simulation data.	required
input_cols	List[str]	Input variable names.	required
outcome_col	str	Outcome variable name.	required
n_new_per_fix	int	Number of samples to generate per detected issue.	10
failed_data	Optional[pd.DataFrame]	Graveyard of inputs that crashed the solver.	None
distance_threshold	float	Minimum normalized distance to maintain from failed points.	0.05
max_gap_ratio	float	Largest allowed coverage gap, as a fraction of each input’s range.	MAX_GAP_RATIO
min_r2_score	float	Minimum cross-validated R² for the model-fit check.	MIN_R2_SCORE
max_avg_cv	float	Maximum average bootstrap spread (relative to the response std).	MAX_AVG_CV
max_max_cv	float	Maximum bootstrap spread at any probe point.	MAX_MAX_CV
max_allowed_vif	float	Maximum Variance Inflation Factor for the collinearity check.	MAX_ALLOWED_VIF
seed	int	Seed for the candidate samplers, for reproducible runs.	None

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: New recommended samples.

Examples

import numpy as np
import pandas as pd
# 1. Setup data with a massive gap in 'Length' (0-1, then 9-10)
length = np.r_[np.linspace(0.1, 0.9, 6), np.linspace(9.1, 9.9, 6)]
df = pd.DataFrame({'Length': length, 'Signal': 2 * length})

# 2. Ask for new samples to fix the gap
new_pts = generate_targeted_samples(
    df=df,
    input_cols=['Length'],
    outcome_col='Signal',
    n_new_per_fix=2
)
print(new_pts)
#    Length Refinement_Reason
# 0     5.4      Gap in Length
# 1     3.2      Gap in Length