# scope_profiler.summary

*module*

Shared per-region summary table.

One renderer, used by ``ProfileManager.finalize()``,
:meth:`ProfilingResults.print_summary` and ``scope-profiler inspect``, so the
three agree on columns, units and formatting.

Everything here works off duck-typed results/region objects, so this module has
no scope-profiler imports and cannot introduce an import cycle.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L1-L1)

## scope_profiler.summary.DEFAULT_REGION_TABLE_COLUMNS

*attribute* · *module attribute*

```python
DEFAULT_REGION_TABLE_COLUMNS = ('region', 'percent', 'total')
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L98-L102)

## scope_profiler.summary.REGION_TABLE_COLUMNS

*attribute* · *module attribute*

```python
REGION_TABLE_COLUMNS = ('region', *REGION_TABLE_COLUMN_NAMES[1:])
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L97-L97)

## scope_profiler.summary.REGION_TABLE_COLUMN_NAMES

*attribute* · *module attribute*

```python
REGION_TABLE_COLUMN_NAMES = tuple((key for key, _ in _COLUMNS))
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L96-L96)

## scope_profiler.summary.SORT_KEYS

*attribute* · *module attribute*

```python
SORT_KEYS = ('start', 'total', 'calls', 'avg', 'min', 'max', 'first', 'last', 'std', 'p50', 'p95', 'p99', 'imbalance', 'name')
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L58-L73)

## scope_profiler.summary.format_region_table

*function*

```python
def format_region_table(rows, columns=None, percentage_mode: str = 'coverage')
```

Format :func:`region_rows` output as displayed by the region table.

Shared by the terminal table and the HTML report so both show the same
columns, tree indentation, inline call counts and ``(own)`` rows.

Returns
-------
selected_columns : tuple of (key, header)
    The columns to display, in order.
display_rows : list of (row, display, is_own)
    ``display`` maps every column key to its cell text. ``row`` is the
    source row; for an ``(own)`` row (``is_own`` true) it is the parent
    region whose time excluding children the row shows.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L669-L774)

## scope_profiler.summary.gpu_timing_warnings

*function*

```python
def gpu_timing_warnings(rows) -> list[str]
```

Explain CPU enqueue timings when device totals exceed them by over 2x.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L777-L796)

## scope_profiler.summary.likwid_tables

*function*

```python
def likwid_tables(results, include=None, exclude=None, ranks=None) -> list
```

Build one LIKWID counter table per (rank, event group).

Regions become columns and counters become rows: a run typically has a
handful of regions but a few dozen counters, so this orientation stays
readable where the transpose would not. Splitting per event group keeps
every column of a table comparable, since a group fixes which events and
metrics exist.

Columns are ordered by descending LIKWID runtime (ties alphabetically), so
the costliest regions lead, as in the region table.

Parameters
----------
results : ProfilingResults
    Source of the LIKWID results.
include, exclude : list of str or str, optional
    Regex patterns selecting which regions to report, matched as for the
    region table.
ranks : list of int, optional
    Restrict to these ranks (default: all).

Returns
-------
list of dict
    One entry per table, each with ``rank``, ``group``, ``columns`` (the
    region labels) and ``sections`` (``(title, rows)`` pairs, where a row
    is ``(name, values)``). Empty when the file holds no LIKWID data.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L950-L1055)

## scope_profiler.summary.normalize_region_table_columns

*function*

```python
def normalize_region_table_columns(columns=None) -> tuple[tuple[str, str], ...]
```

Return validated ``(row_key, header)`` pairs for a region table.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L107-L131)

## scope_profiler.summary.perf_event_tables

*function*

```python
def perf_event_tables(results, include=None, exclude=None, ranks=None) -> list
```

Build one built-in perf-event counter table per rank.

These counters are already summed across calls by the collector, so each
region occupies one row and calls/events occupy columns. Missing events
use ``-`` rather than being treated as zero.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L1109-L1145)

## scope_profiler.summary.print_likwid_table

*function*

```python
def print_likwid_table(table, title=None, stream=None) -> None
```

Print one LIKWID counter table from :func:`likwid_tables`.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L1073-L1096)

## scope_profiler.summary.print_likwid_tables

*function*

```python
def print_likwid_tables(results, include=None, exclude=None, ranks=None, stream=None)
```

Print every LIKWID counter table a result set exposes.

A no-op for files recorded without LIKWID, so callers can invoke it
unconditionally.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L1099-L1106)

## scope_profiler.summary.print_perf_event_tables

*function*

```python
def print_perf_event_tables(results, include=None, exclude=None, ranks=None, stream=None)
```

Print every built-in Linux perf-event counter table in ``results``.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L1148-L1176)

## scope_profiler.summary.print_region_table

*function*

```python
def print_region_table(rows, title=None, stream=None, suppress_notes: bool = False, total_time: float | None = None, columns=None, percentage_mode: str = 'coverage', file_path=None) -> None
```

Print the aligned per-region statistics table.

Parameters
----------
rows : list of dict
    Rows from :func:`region_rows`.
title : str, optional
    Heading printed above the table.
stream : file-like, optional
    Where to write (default: stdout).
suppress_notes : bool, optional
    Don't print the explanatory notes below the table (default: False).
total_time : float, optional
    Accepted for compatibility. Session elapsed time is shown in the
    ``scope_profiler.session`` row.
columns : list of str or str, optional
    Region summary columns to print. Defaults to ``region``,
    ``percent`` and ``total``. An indented ``(own)`` row shows
    time excluding children for each parent region. Call counts other than one
    appear after region names unless a separate ``calls`` column is
    explicitly selected. The percentage is
    relative to ``scope_profiler.session``. The public name for the first
    column is ``region``; ``name`` is accepted as an alias for Python
    callers.
percentage_mode : {"coverage", "exclusive"}, optional
    Quantity used for the ``% session`` column. Wall-clock coverage is the
    default; exclusive time can be selected for attribution-focused tables.
file_path : str or Path, optional
    File represented by the table, used for the help hints in the info box.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L799-L913)

## scope_profiler.summary.region_row

*function*

```python
def region_row(region, ranks=None, *, include_exclusive: bool = False) -> dict
```

Collect the summary statistics shown for one region.

Duration entries are ``None`` when the region has no recorded calls for
the selected ranks, which the table renders as a dash.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L256-L354)

## scope_profiler.summary.region_rows

*function*

```python
def region_rows(results, include=None, exclude=None, ranks=None, sort: str = 'start', percentage_mode: str = 'coverage') -> list
```

Build the summary rows for every region a result set exposes.

Parameters
----------
results : ProfilingResults
    Source of the regions; loaded from a file or built in memory alike.
include, exclude : list of str or str, optional
    Regex patterns selecting which regions to summarize.
ranks : list of int, optional
    Restrict the statistics to these ranks (default: all).
sort : str, optional
    One of :data:`SORT_KEYS`: ``start`` (default), ``total``, ``calls``, ``avg``,
    ``min``, ``max`` and ``std`` sort descending, ``name`` alphabetically.
percentage_mode : {"coverage", "exclusive"}, optional
    Quantity used for the ``% session`` column. Wall-clock coverage is the
    default; exclusive time can be selected for attribution-focused tables.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/summary.py#L363-L617)