Skip to content

MESQUAL Pandas Util xs_df

xs_df 

xs_df(df: DataFrame, keys: Hashable | list[Hashable], axis: Axis = 0, level: Hashable = None) -> DataFrame

Extract cross-section from MultiIndex DataFrame with support for multiple keys.

This function provides a flexible interface to pandas .xs() method with enhanced functionality for MESQUAL's MultiIndex data structures. It supports both single and multiple key selection, making it particularly useful for energy systems analysis where data often has complex hierarchical structures.

Parameters:

Name Type Description Default
df DataFrame

Input DataFrame with MultiIndex (either on index or columns).

 required
keys Hashable | list[Hashable]

Single key or list of keys to select from the specified level. For single keys, uses pandas .xs() method with drop_level=True. For multiple keys, uses .isin() for efficient selection.

 required
axis Axis

Axis to operate on. Can be 0/'index'/'rows' for index operations or 1/'columns' for column operations. Defaults to 0.

 0
level Hashable

Name or position of the MultiIndex level to select from. Must be specified for MultiIndex operations.

 None

Returns:

Type Description
DataFrame

DataFrame with cross-section data. For single keys, the specified level
DataFrame

is dropped. For multiple keys, the level is preserved.

Examples:

Single dataset selection from MESQUAL multi-scenario data:

>>> multi_scenario_prices = study.scen.fetch('buses_t.marginal_price')
>>> base_prices = xs_df(multi_scenario_prices, 'base', level='dataset')

Multiple scenario selection:

>>> scenarios = ['base', 'high_renewable', 'low_cost']
>>> selected_data = xs_df(multi_scenario_prices, scenarios, level='dataset')

Column-wise selection for specific buses:

>>> bus_names = ['Bus_1', 'Bus_2', 'Bus_3']
>>> selected_buses = xs_df(price_data, bus_names, axis='columns', level='Bus')
Source code in submodules/mesqual/mesqual/utils/pandas_utils/xs_df.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def xs_df(
        df: pd.DataFrame,
        keys: Hashable | list[Hashable],
        axis: Axis = 0,
        level: Hashable = None,
) -> pd.DataFrame:
    """Extract cross-section from MultiIndex DataFrame with support for multiple keys.

    This function provides a flexible interface to pandas .xs() method with enhanced
    functionality for MESQUAL's MultiIndex data structures. It supports both single
    and multiple key selection, making it particularly useful for energy systems
    analysis where data often has complex hierarchical structures.

    Args:
        df: Input DataFrame with MultiIndex (either on index or columns).
        keys: Single key or list of keys to select from the specified level.
            For single keys, uses pandas .xs() method with drop_level=True.
            For multiple keys, uses .isin() for efficient selection.
        axis: Axis to operate on. Can be 0/'index'/'rows' for index operations
            or 1/'columns' for column operations. Defaults to 0.
        level: Name or position of the MultiIndex level to select from.
            Must be specified for MultiIndex operations.

    Returns:
        DataFrame with cross-section data. For single keys, the specified level
        is dropped. For multiple keys, the level is preserved.

    Examples:
        Single dataset selection from MESQUAL multi-scenario data:
        >>> multi_scenario_prices = study.scen.fetch('buses_t.marginal_price')
        >>> base_prices = xs_df(multi_scenario_prices, 'base', level='dataset')

        Multiple scenario selection:
        >>> scenarios = ['base', 'high_renewable', 'low_cost']
        >>> selected_data = xs_df(multi_scenario_prices, scenarios, level='dataset')

        Column-wise selection for specific buses:
        >>> bus_names = ['Bus_1', 'Bus_2', 'Bus_3']
        >>> selected_buses = xs_df(price_data, bus_names, axis='columns', level='Bus')
    """
    if isinstance(keys, list):
        if axis in [0, 'index', 'rows']:
            return df.iloc[df.index.get_level_values(level).isin(keys)]
        return df.iloc[:, df.columns.get_level_values(level).isin(keys)]
    return df.xs(keys, level=level, axis=axis, drop_level=True)