Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

#
base module

Base classes and functions for grouping.

Class Grouper stores metadata related to grouping index. It can return, for example, the number of groups, the start indices of groups, and other information useful for reducing operations that utilize grouping. It also allows to dynamically enable/disable/modify groups and checks whether a certain operation is permitted.

## get_groups_and_index function

    get_groups_and_index(
        index,
        group_by,
        def_lvl_name='group'
    )

Return array of group indices pointing to the original index, and grouped index.

## group_by_to_index function

    group_by_to_index(
        index,
        group_by,
        def_lvl_name='group'
    )

Convert mapper `group_by` to `pd.Index`.

Note

Index and mapper must have the same length.

## Grouper class

    Grouper(
        index,
        group_by=None,
        def_lvl_name='group',
        allow_enable=True,
        allow_disable=True,
        allow_modify=True,
        **kwargs
    )

Class that exposes methods to group index.

`group_by` can be:

- boolean (False for no grouping, True for one group),
- integer (level by position),
- string (level by name),
- sequence of integers or strings that is shorter than `index` (multiple levels),
- any other sequence that has the same length as `index` (group per index).

Set `allow_enable` to False to prohibit grouping if Grouper.group_by is None. Set `allow_disable` to False to prohibit disabling of grouping if Grouper.group_by is not None. Set `allow_modify` to False to prohibit modifying groups (you can still change their labels).

All properties are read-only to enable caching.

Note

Columns must form monolithic groups for using `get_group_lens_nb`.

Note

This class is meant to be immutable. To change any attribute, use Configured.replace().

Superclasses

- Cacheable
- Chainable
- Comparable
- Configured
- HasSettings
- Pickleable
- Prettified

Inherited members

- Cacheable.get_ca_setup()
- Chainable.pipe()
- Configured.config
- Configured.copy()
- Configured.equals()
- Configured.get_writeable_attrs()
- Configured.prettify()
- Configured.rec_state
- Configured.replace()
- Configured.resolve_merge_kwargs()
- Configured.update_config()
- HasSettings.get_path_setting()
- HasSettings.get_path_settings()
- HasSettings.get_setting()
- HasSettings.get_settings()
- HasSettings.has_path_setting()
- HasSettings.has_path_settings()
- HasSettings.has_setting()
- HasSettings.has_settings()
- HasSettings.reset_settings()
- HasSettings.resolve_setting()
- HasSettings.resolve_settings_paths()
- HasSettings.set_settings()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()

### allow_disable property

Whether to allow disabling grouping.

### allow_enable property

Whether to allow enabling grouping.

### allow_modify property

Whether to allow changing groups.

### check_group_by method

    Grouper.check_group_by(
        group_by=None,
        allow_enable=None,
        allow_disable=None,
        allow_modify=None
    )

Check passed `group_by` object against restrictions.

### def_lvl_name property

Default level name.

### from_pd_group_by class method

    Grouper.from_pd_group_by(
        pd_group_by,
        **kwargs
    )

Build a Grouper instance from a pandas `GroupBy` object.

Indices are stored under `index` and group labels under `group_by`.

### get_group_count method

    Grouper.get_group_count(
        **kwargs
    )

Get number of groups.

### get_group_end_idxs method

    Grouper.get_group_end_idxs(
        **kwargs
    )

Get end index of each group as an array.

### get_group_lens method

    Grouper.get_group_lens(
        group_by=None,
        jitted=None,
        **kwargs
    )

See get_group_lens_nb.

### get_group_map method

    Grouper.get_group_map(
        group_by=None,
        jitted=None,
        **kwargs
    )

See get_group_map_nb.

### get_group_start_idxs method

    Grouper.get_group_start_idxs(
        **kwargs
    )

Get first index of each group as an array.

### get_grouped_index method

    Grouper.get_index(
        **kwargs
    )

Return grouped index.

### get_groups method

    Grouper.get_groups(
        **kwargs
    )

Return groups array.

### get_groups_and_index method

    Grouper.get_groups_and_index(
        group_by=None,
        **kwargs
    )

See get_groups_and_index().

### get_index method

    Grouper.get_index(
        **kwargs
    )

Return grouped index.

### get_stretched_index method

    Grouper.get_stretched_index(
        **kwargs
    )

Return stretched index.

### group_by property

Mapper for grouping.

### grouped_index property

Grouped index.

### index property

Original index.

### is_group_count_changed method

    Grouper.is_group_count_changed(
        group_by=None
    )

Check whether the number of groups has changed.

### is_grouped method

    Grouper.is_grouped(
        group_by=None
    )

Check whether index are grouped.

### is_grouping_changed method

    Grouper.is_grouping_changed(
        group_by=None
    )

Check whether grouping has changed in any way.

### is_grouping_disabled method

    Grouper.is_grouping_disabled(
        group_by=None
    )

Check whether grouping has been disabled.

### is_grouping_enabled method

    Grouper.is_grouping_enabled(
        group_by=None
    )

Check whether grouping has been enabled.

### is_grouping_modified method

    Grouper.is_grouping_modified(
        group_by=None
    )

Check whether grouping has been modified.

Doesn't care if grouping labels have been changed.

### is_sorted method

    Grouper.is_sorted(
        group_by=None,
        **kwargs
    )

Return whether groups are monolithic, sorted.

### resolve_group_by method

    Grouper.resolve_group_by(
        group_by=None,
        **kwargs
    )

Resolve `group_by` from either object variable or keyword argument.

### select_groups method

    Grouper.select_groups(
        group_idxs,
        jitted=None
    )

Select groups.

Returns indices and new group array. Automatically decides whether to use group lengths or group map.

### yield_group_idxs method

    Grouper.yield_group_idxs(
        **kwargs
    )

Yield indices of each group.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings