## apply_multi_component_map()


Apply a single MultiComponentMap with regex and catch-all support.


Usage

``` python
apply_multi_component_map(
    df,
    multi_component_map,
    verbose=False,
)
```


Rules are evaluated by priority so that results do not depend on the stored order of the value maps: explicit (literal) tuples first, then regex tuples, then any pure catch-all (`"regex:.*"` for every component) last. The first matching rule wins. Patterns prefixed with `"regex:"` must match the full stringified value (`Series.str.fullmatch`).

Rows with a missing value (NaN/None) in any source column remain unmapped: they are never matched by any rule (including the catch-all) and yield NaN in the target column.

Only the first target column is used; multi-target MultiComponentMaps are not supported.


## Parameters


`df: pd.DataFrame`  
Source data.

`multi_component_map: px.model.map.MultiComponentMap`  
MultiComponentMap with source columns, target column, and values.

`verbose: bool = ``False`  
If True, log progress at INFO level (DEBUG otherwise). Unmapped-value warnings are always logged at WARNING level.


## Returns


`pd.DataFrame`  
DataFrame with the target column added or overwritten.