PitaSeries

`flatbread.accessors.series.PitaSeries`

Bases: PitaDisplayMixin

Tabulation methods for Series, registered as s.pita.

All methods return a new Series or DataFrame, leaving the original unmodified. Methods can be chained.

`add_agg(aggfunc, label=None, ignore_keys=None, _fill='')`

Add aggregate to a Series.

Parameters:

Name	Type	Description	Default
`aggfunc`	`str \| Callable`	Function to use for aggregating the data.	required
`label`	`str \| None`	Label for the aggregated row. Default None.	`None`
`ignore_keys`	`str \| list[str] \| None`	Keys of rows to ignore when aggregating.	`None`

Returns:

Type	Description
`pd.Series:`	Series with aggregated row added.

Examples:

>>> s.pita.add_agg('mean')
>>> s.pita.add_agg(lambda x: x.max() - x.min(), label='range')

`add_subagg(aggfunc, level=0, label=None, include_level_name=False, ignore_keys=None, skip_single_rows=True, _fill='')`

Add aggregates of specified levels to a Series.

Parameters:

Name	Type	Description	Default
`aggfunc`	`str \| Callable`	Function to use for aggregating the data.	required
`level`	`Level \| list[Level]`	Level(s) to aggregate with func. Default 0.	`0`
`label`	`str \| None`	Label for the aggregated rows. Default None.	`None`
`include_level_name`	`bool`	Whether to add level name to subtotal label.	`False`
`ignore_keys`	`str \| list[str] \| None`	Keys of rows to ignore when aggregating. Default 'Totals'	`None`
`skip_single_rows`	`bool`	Whether to skip single rows when aggregating. Default True.	`True`

Returns:

Type	Description
`pd.Series:`	Table with aggregated rows added.

Examples:

>>> s.pita.add_subagg('mean', level=0)

`add_totals(label=None, ignore_keys=None, _fill='')`

Add totals to a Series.

Parameters:

Name	Type	Description	Default
`label`	`str \| None`	Label for the totals row. Default 'Totals'.	`None`
`ignore_keys`	`str \| list[str] \| None`	Keys of rows to ignore when aggregating. Default 'Subtotals'	`None`

Returns:

Type	Description
`pd.Series:`	Series with totals row added.

Examples:

>>> s.pita.add_totals()
>>> s.pita.add_totals(label='sum')

`add_subtotals(level=0, label=None, include_level_name=False, ignore_keys=None, skip_single_rows=True, _fill='')`

Add subtotals to a Series.

Parameters:

Name	Type	Description	Default
`level`	`Level \| list[Level]`	Level(s) to add subtotals to. Default 0.	`0`
`label`	`str \| None`	Label for the subtotals rows. Default 'Subtotals'.	`None`
`include_level_name`	`bool`	Whether to add level name to subtotal label.	`False`
`ignore_keys`	`str \| list[str] \| None`	Keys of rows to ignore when aggregating. Default 'Totals'	`None`
`skip_single_rows`	`bool`	Whether to skip single rows when aggregating. Default True.	`True`

Returns:

Type	Description
`pd.Series:`	Series with subtotal rows added.

Examples:

>>> s.pita.add_subtotals(level=0)
>>> s.pita.add_subtotals(level=[0, 1], include_level_name=True)

`sort_totals(axis=0, level=None, labels=None, totals_last=True, sort_remaining=True)`

Sort index/columns to position totals and subtotals at start or end within groups.

Convenience function that sorts common aggregate labels (totals, subtotals) to their appropriate positions, while leaving other items in their existing order. Uses default labels from flatbread configuration unless custom labels are provided.

Parameters:

Name	Type	Description	Default
`axis`	`Axis`	Axis to sort along: - 0 or 'index': sort the index (rows) - 1 or 'columns': sort the columns	`0`
`level`	`Level \| list[Level] \| None`	Index level(s) to sort. Can be level number(s), level name(s), or None for all levels.	`None`
`labels`	`list[str] \| None`	Custom labels to treat as totals/subtotals. If None, uses default labels from flatbread configuration ('Totals', 'Subtotals').	`None`
`totals_last`	`bool`	Whether to place totals/subtotals at the end (True) or beginning (False) of each group.	`True`
`sort_remaining`	`bool`	Whether to sort non-target levels alphabetically.	`True`

Returns:

Type	Description
`Series`	Series with totals/subtotals repositioned according to the specified parameters.

`value_counts(fillna='<NA>', label_n='count', add_pct=False, label_pct='pct', ndigits=-1, base=1)`

Similar to pandas value_counts except null values are by default also counted and a total is added. Optionally, percentages may also be added to the output.

Parameters:

Name	Type	Description	Default
`fillna`	`str`	What value to give null values. Set to None to not count null values. Default is ''.	`'<NA>'`
`label_n`	`str`	Name for the count column. Default is 'count'.	`'count'`
`add_pct`	`bool`	Whether to add a percentage column. Default is False.	`False`
`label_pct`	`str`	Name for the percentage column. Default is 'pct'.	`'pct'`
`ndigits`	`int`	Number of decimal places to round the percentages. Default is -1 (no rounding).	`-1`
`base`	`int`	The whole quantity against which to calculate the fraction.	`1`

Returns:

Type	Description
`pd.Series:`	Series reporting the count of each value in the original series.

`as_percentages(label_pct=None, label_totals=None, ndigits=None, base=1, apportioned_rounding=None)`

Transform data into percentages.

Parameters:

Name	Type	Description	Default
`label_pct`	`str \| None`	Label for the percentage column. Default is 'pct'.	`None`
`label_totals`	`str \| None`	Label of the totals row. If no label is supplied then totals will be assumed to be the last row. Default is None.	`None`
`ndigits`	`int \| None`	Number of decimal places to round the percentages. Default is -1 (no rounding).	`None`
`base`	`int`	The whole quantity against which to calculate the fraction.	`1`

Returns:

Type	Description
`pd.Series:`	Series transformed into percentages.

`as_pct(*args, **kwargs)`

Alias for :meth:as_percentages.

`add_percentages(label_n=None, label_pct=None, label_totals=None, ndigits=None, base=1, apportioned_rounding=None)`

Add percentage column to a Series.

Parameters:

Name	Type	Description	Default
`label_n`	`str \| None`	Label for the original count column. Default is 'n'.	`None`
`label_pct`	`str \| None`	Label for the percentage column. Default is 'pct'.	`None`
`label_totals`	`str \| None`	Label of the totals row. If no label is supplied then totals will be assumed to be the last row. Default is None.	`None`
`ndigits`	`int \| None`	Number of decimal places to round the percentages. Default is -1 (no rounding).	`None`
`base`	`int`	The whole quantity against which to calculate the fraction.	`1`

Returns:

Type	Description
`pd.DataFrame:`	DataFrame with the original Series and an additional column for the percentages.

Examples:

>>> s.pita.add_totals().pita.add_percentages()
>>> s.pita.add_totals().pita.add_percentages(ndigits=1, base=100)

`add_pct(*args, **kwargs)`

Alias for :meth:add_percentages.

`add_differences(*, label_n=None, label_diff=None, ignore_keys=None, periods=1)`

Add differences alongside original Series data.

Parameters:

Name	Type	Description	Default
`label_n`	`str or None`	Label for the original data column.	`None`
`label_diff`	`str or None`	Label for the difference column.	`None`
`ignore_keys`	`str or list[str] or None`	Keys to exclude from computation.	`None`
`periods`	`int`	Number of periods to shift.	`1`

Returns:

Type	Description
`DataFrame`	Two-column DataFrame with original values and differences.

Examples:

>>> s.pita.add_diffs()
>>> s.pita.add_diffs(periods=2)

`add_diffs(*args, **kwargs)`

Alias for :meth:as_percentages.

`add_pct_change(*, label_n=None, label_pct_change=None, ignore_keys=None, periods=1)`

Add percentage change alongside original Series data.

Parameters:

Name	Type	Description	Default
`label_n`	`str or None`	Label for the original data column.	`None`
`label_pct_change`	`str or None`	Label for the pct_change column.	`None`
`ignore_keys`	`str or list[str] or None`	Keys to exclude from computation.	`None`
`periods`	`int`	Number of periods to shift.	`1`

Returns:

Type	Description
`DataFrame`	Two-column DataFrame with original values and pct_change.

`export_excel(filepath, title=None, number_formats=None, border_specs=None, **kwargs)`

Export Series to Excel with automatic formatting based on flatbread configuration.

Parameters:

Name	Type	Description	Default
`filepath`	`str \| Path`	Path to save the Excel file	required
`title`	`str`	Title for the worksheet	`None`
`number_formats`	`dict`	Custom number formats (overrides auto-detected ones)	`None`
`border_specs`	`dict`	Custom border specifications (merged with margin borders)	`None`
`**kwargs`		Additional arguments passed to pandasxl WorksheetManager	`{}`

`add_level(value, level=0, level_name=None, axis=0)`

Add a level containing the specified value to a Series index.

Parameters:

Name	Type	Description	Default
`value`	`Any`	Value to fill the new level with.	required
`level`	`int`	Position to insert the new level. Defaults to 0 (start).	`0`
`level_name`	`Any`	Name for the new level. Defaults to None.	`None`
`axis`	`Axis`	Added for symmetry with DataFrame method.	`0`

Returns:

Type	Description
`pd.Series:`	Series with the new level added to the specified axis.

`merge_levels(level_a, level_b)`

Merge two levels of the index into one.

For each position, if one level's value is duplicated while the other's is unique, the unique value is kept. If both are unique (conflict), the value from level_a takes priority.

Parameters:

Name	Type	Description	Default
`level_a`	`Level`	First level (priority on conflict).	required
`level_b`	`Level`	Second level.	required

Returns:

Type	Description
`Series`	Series with the two levels merged into one.