one_to_many_pipeline

featminer.pipelines.one_to_many.one_to_many_pipeline

one_to_many_pipeline(
    *,
    df: DataFrame,
    target_col: str,
    aggregation_key: str,
    event_times: Collection[str] | None = None,
    prediction_time: str | None = None,
    cutoff_by: str | None = None,
    relative_time_columns: Collection[RelativeTime]
    | None = None,
    sampling_key: str | None = None,
    max_sampling_groups: int | None = None,
    max_cells_threshold: int = 100000000,
    candidate_screening: CandidateScreening | None = None,
    cat_features: Collection[str] | None = None,
    baseline_features: DataFrame | None = None,
    min_category_fraction: float = 0.01,
    selection: SelectionConfig | None = None,
    formulas: FormulaSet
    | Sequence[OneToManyFormula] = "basic",
    derived_columns: DerivedColumnsConfig = DEFAULT_DERIVED_COLUMNS,
    generate_report: bool = True,
    open_browser: bool = True,
    verbose: Literal[
        "off", "warning", "info", "debug"
    ] = "info",
) -> pd.DataFrame

Генерирует и отбирает агрегированные признаки по связанным строкам исторической таблицы. В результате возвращает по одной строке на каждый объект.

Параметры

Параметр	Описание
`df`	Исходная таблица, содержащая одну или несколько строк на каждый объект. Тип: `pd.DataFrame`По умолчанию: Обязательный
`target_col`	Колонка с бинарным таргетом. Значение должно быть одинаковым внутри одного объекта. Тип: `str`По умолчанию: Обязательный
`aggregation_key`	Колонка, по которой строки объединяются в объекты. Тип: `str`По умолчанию: Обязательный
`event_times`	Временные оси для time-aware формул. Могут включать известные заранее плановые даты из будущего. Тип: `Collection[str] \| None`По умолчанию: `None`
`prediction_time`	Момент построения прогноза. Используется как опорное время формул и включает point-in-time-фильтрацию. Тип: `str \| None`По умолчанию: `None`
`cutoff_by`	Колонка из `event_times`, определяющая доступность строки. Строки после `prediction_time` исключаются. При единственной временной оси определяется автоматически. Тип: `str \| None`По умолчанию: `None`
`relative_time_columns`	Числовые временные смещения с явно заданными единицами измерения. Тип: `Collection[RelativeTime] \| None`По умолчанию: `None`
`sampling_key`	Ключ, полные группы которого сохраняются при формировании подвыборки. По умолчанию используется `aggregation_key`. Тип: `str \| None`По умолчанию: `None`
`max_sampling_groups`	Максимальное число полных групп для отбора признаков. `None` не ограничивает количество групп. Тип: `int \| None`По умолчанию: `None`
`max_cells_threshold`	Максимальный размер входной таблицы `строки × колонки` до автоматического downsampling. Тип: `int`По умолчанию: `100_000_000`
`candidate_screening`	Необязательный быстрый предварительный отбор колонок и масок перед полным перебором. Тип: `CandidateScreening \| None`По умолчанию: `None`
`cat_features`	Колонки, которые нужно обрабатывать как категориальные. Если параметр не задан, категориальные колонки определяются по типам данных. Тип: `Collection[str] \| None`По умолчанию: `None`
`baseline_features`	Существующие числовые признаки. Учитываются при корреляционном отборе, чтобы новые признаки не дублировали их. Тип: `pd.DataFrame \| None`По умолчанию: `None`
`min_category_fraction`	Минимальная доля категории, необходимая для участия в генерации признаков. Тип: `float`По умолчанию: `0.01`
`selection`	Декларативная политика отбора. `None` включает `SelectionConfig.auc_with_mi_fallback()`; прежний отбор доступен через `SelectionConfig.auc()`. Все пороги основного отбора задаются внутри конфига. Тип: `SelectionConfig \| None`По умолчанию: `None`
`formulas`	Формулы для генерации: быстрый набор `"basic"`, дополнительный `"advanced"`, объединяющий их `"all"` или явная последовательность экземпляров формул (`Sequence[OneToManyFormula]`). Расширение набора может повысить качество ценой времени расчёта. Тип: `FormulaSet \| Sequence[OneToManyFormula]`По умолчанию: `"basic"`
`derived_columns`	Настройки производных колонок и условий (`DerivedColumnsConfig`). По умолчанию создаются дни между парами дат и условия по одной колонке; попарные разности и отношения выключены. Тип: `DerivedColumnsConfig`По умолчанию: `DEFAULT_DERIVED_COLUMNS`
`generate_report`	Формировать HTML-отчёт и воспроизводимый Python-код. Если `False`, отчёт не создаётся, а `open_browser` игнорируется. Тип: `bool`По умолчанию: `True`
`open_browser`	Открывать сформированный HTML-отчёт в браузере. Тип: `bool`По умолчанию: `True`
`verbose`	Уровень журналирования: `"off"`, `"warning"`, `"info"` или `"debug"`. Тип: `Literal['off', 'warning', 'info', 'debug']`По умолчанию: `"info"`

Выбор формул

В API используется параметр formulas. Он принимает строковый пресет "basic", "advanced" или "all", а также явную последовательность экземпляров формул. По умолчанию используется "basic".

Выбор готового набора:

# Быстрый базовый набор используется по умолчанию.
features = one_to_many_pipeline(..., formulas="basic")

# Только дополнительные формулы.
features = one_to_many_pipeline(..., formulas="advanced")

# Базовые и дополнительные формулы вместе.
features = one_to_many_pipeline(..., formulas="all")

Если выбранной формуле не хватает временной конфигурации, pipeline выводит warning с именами таких формул, пропускает их и продолжает расчёт. Без event_times не запускаются формулы, которым нужен порядок событий. При календарных Date-осях без prediction_time пропускаются формулы, которые считают значения относительно момента прогноза. First и Last при этом продолжают работать, а RelativeTime использует нулевую точку прогноза.

Набор	Формулы
`basic`	`Fraction`, `Count`, `Max`, `Sum`, `Mean`, `Min`, `Nunique`, `Std`, `First`, `Last`
`advanced`	`NumMax`, `NumMin`, `Kurtosis`, `Skew`, `Mode`, `EventRange`, `FirstCategory`, `LastCategory`, `IntervalMax`, `IntervalMean`, `IntervalMin`, `IntervalStd`, `Trend`, `TimeSinceFirstMaximum`, `TimeSinceFirstMinimum`, `TimeSinceLastMaximum`, `TimeSinceLastMinimum`, `Quantile`, `Slope`, `Ewa`, `EwaFraction`, `Ews`, `EwsCount`, `EwmaTrend`, `WindowSum`, `WindowCount`, `WindowFraction`, `WindowMean`, `WindowMax`, `WindowMin`, `WindowStd`
`all`	`basic` + `advanced`

Можно собрать собственный набор:

from featminer import one_to_many_pipeline
from featminer.formulas import Count, Ews, Quantile, Slope, WindowSum

FORMULAS = (
    Count(),
    WindowSum(days=7),
    WindowSum(days=30),
    WindowSum(days=90),
    Ews(half_life_days=7),
    Ews(half_life_days=30),
    Quantile(q=0.33),
    Quantile(q=0.8),
    Slope(last_k=10),
    Slope(last_k=100),
)

features = one_to_many_pipeline(
    df=transactions,
    aggregation_key="client_id",
    target_col="target",
    event_times=("event_date",),
    prediction_time="prediction_date",
    formulas=FORMULAS,
)

Формулы без числовых параметров тоже передаются экземплярами: Count(), Mean(), EventRange(), IntervalMean() и так далее.

Готовый набор можно расширить явно:

from featminer.formulas import EventRange, WindowSum
from featminer.formulas.sets import BASIC_FORMULAS

FORMULAS = (
    *BASIC_FORMULAS,
    EventRange(),
    WindowSum(days=14),
    WindowSum(days=60),
)

Time-series формулы участвуют в генерации только при наличии event_times.

Производные колонки

Параметр derived_columns управляет арифметическими колонками, которые создаются до применения формул:

from featminer import DerivedColumnsConfig, one_to_many_pipeline

features = one_to_many_pipeline(
    df=transactions,
    aggregation_key="client_id",
    target_col="target",
    derived_columns=DerivedColumnsConfig(
        days_between=True,
        differences=True,
        ratios=False,
        conditions=True,
        max_condition_columns=1,
    ),
)

Параметры `DerivedColumnsConfig`

Параметр	Тип	По умолчанию	Описание
`days_between`	`bool`	`True`	Создавать разности в днях между всеми парами календарных дат.
`differences`	`bool`	`False`	Создавать попарные разности совместимых числовых колонок.
`ratios`	`bool`	`False`	Создавать безопасные попарные отношения совместимых числовых колонок.
`conditions`	`bool`	`True`	Разрешать условные признаки, рассчитанные только по строкам, соответствующим категориальным условиям. `False` сохраняет обычные агрегаты без фильтрации.
`max_condition_columns`	`int`	`1`	Максимальное число колонок в одном условии. Значение `2`, например, разрешает условие `status="active" and channel="web"`.

Значения по умолчанию сохраняют базовый режим:

DerivedColumnsConfig(
    days_between=True,
    differences=False,
    ratios=False,
    conditions=True,
    max_condition_columns=1,
)

conditions=False отключает условные признаки, но сохраняет обычные агрегаты без фильтрации. max_condition_columns задаёт максимальное число колонок в одном условии.

Подробнее о временных параметрах: Защита от утечки из будущего.

Подробнее о выборе AUC или корреляции Пирсона: Конфигурация отбора признаков.

Справочник формул

Полный список формул содержит описания, математические формулы, параметры, значения в стандартных наборах, обработку пропусков и примеры.