# Row Summaries

Canonical page: https://www.adaptabletools.com/docs/handbook-summarising-rows

- AdapTable allows users to create Row Summaries in their Layouts (see [Table Layouts](https://www.adaptabletools.com/docs/handbook-layouts-table/index.md) and [Table Layout Wizard](https://www.adaptabletools.com/docs/handbook-layouts-wizard-table/index.md))
- They are pinned rows which can be placed at the top or bottom of the grid
- Each Row Summary can contain multiple aggregations over column data (filtered or all rows — see [Filtered Data](#filtered-data))

AdapTable provides Row Summaries which display **per-Column Aggregation** information.

The Aggregation functions are [Aggregation Scalar Functions](https://www.adaptabletools.com/docs/adaptable-ql-expression-functions/index.md) provided and evaluated by [AdapTableQL](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md)

Row Summaries can be pinned either at the **top** or **bottom** of the Grid.

Row Summaries are stored in a [Table Layout](https://www.adaptabletools.com/docs/handbook-layouts-table/index.md) enabling users to decide on their usage on a per-Layout basis.

- Layouts can, alternatively include **Grand Total Rows** to display Aggregation summaries
- [Grand Total Rows](https://www.adaptabletools.com/docs/handbook-aggregation-grand-total-row/index.md) are less powerful or configurable than Row Summaries (but settable via a single boolean prop)

Row Summaries are not available in [Pivot Layouts](https://www.adaptabletools.com/docs/handbook-layouts-pivot/index.md) (but Grand Total Rows are)

### How Row Summaries Work

Row Summaries leverage [AG Grid Row Pinning](https://ag-grid.com/javascript-data-grid/row-pinning/), and add Aggregations to given cells.

This means that they are always visible even when scrolling the Grid.

Row Summaries are provided to AG Grid as pinned row data, which AG Grid does not display together with manual row pinning or a pinned Grand Total Row. AdapTable therefore does not display a Layout's Row Summaries (and logs a console warning) when:

- the Layout's Grand Total Row is pinned (`GrandTotalRow` is `pinnedTop` or `pinnedBottom`); use `top` or `bottom` to show both
- AG Grid manual row pinning is enabled (`enableRowPinning` in GridOptions)

The Row Summaries section of the Layout Editor shows the same message.

The full list of Aggregation functions available in Row Summaries is:

| Operation       | Column DataType       | Description of summarised data                      |
| --------------- | --------------------- | --------------------------------------------------- |
| `Sum`           | Numeric               | Total of column values in scope                     |
| `Average`       | Numeric               | Average of column values in scope                   |
| `Median`        | Numeric               | Middle value of column values in scope (when ordered) |
| `Mode`          | Numeric, String, Date | Most common cell value in scope                     |
| `Distinct`      | Numeric, String, Date | Count of distinct values in scope                   |
| `Max`           | Numeric, Date         | Highest value in scope                            |
| `Min`           | Numeric, Date         | Lowest value in scope                               |
| `Count`         | Numeric, String, Date | Number of cells in scope                            |
| `Weighted Avg`  | Numeric               | Weighted average (requires a defined weighted column) |
| `Only`          | Numeric, String, Date | Value when every cell in scope matches            |
| `Std Deviation` | Numeric               | Standard deviation of column values in scope        |

**Example: Row Summary**

Displaying Row Summaries

- This example contains 2 Row Summaries:
  - **Top** Row Summary: *Github Stars* and *Github Watchers* both have `SUM` Aggregations, *Created At* shows `MIN`
  - **Bottom** Row Summary: *Issue Change* shows an Aggregation of `AVG` and *Language* has an Aggregation of `COUNT`

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Summary',
  initialState: {
    Dashboard: {
      ModuleButtons: ['CellSummary'],
      PinnedToolbars: ['Layout'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout'],
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'week_issue_change',
            'github_stars',
            'github_watchers',
            'created_at',
            'license',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          RowSummaries: [
            {
              Position: 'Top',
              ColumnsMap: {
                github_watchers: 'SUM',
                github_stars: 'SUM',
                created_at: 'MIN',
              },
            },
            {
              Position: 'Bottom',
              ColumnsMap: {
                week_issue_change: 'AVG',
                language: 'COUNT',
              },
            },
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
  },
};
```

## Formatting

By default Column Formatting is automatically applied to Row Summaries (and also to Group Rows).

The Format Column is only applied to cells in the Row Summary which have an Aggregation set

Where not required, this default behaviour can be changed by setting the `ExcludeSummaryRows` property to *true* in the [`RowScope`](https://www.adaptabletools.com/docs/reference/rowscope.md) property when defining the Format Column (summary rows are included when the property is omitted or *false*).

This allows you to create a Format Column that is **only** rendered in a Row Summary

The [`RowScope`](https://www.adaptabletools.com/docs/reference/rowscope.md) object enables 4 types of rows to be **excluded** from a Format Column:
- Data Rows  
- Grouped Rows
- Summary Rows
- Grand Total Rows

Make sure to set a [Column Scope](https://www.adaptabletools.com/docs/dev-guide-columns-scope/index.md) of **All** columns to ensure the entire row is formatted

**Example: Formatted Row Summary**

Formatting Row Summaries

- This example demonstrates formatting Row Summaries
- We provide a Top Row Summary with aggregations for the `Language`, `Github Stars` and `Github Watchers` columns
- We have provided 4 Format Columns, each of which has a different behaviour for Row Summaries:
  - `Language` (showing MODE) has a Fore Color of blue and **includes** Row Summaries but **excludes** regular rows
  - `Github Stars` has red italic font and **excludes** Row Summaries
  - `Github Watchers` has a Fore Color of yellow and **includes** Row Summaries
  - Whole Row Format for Row Summary achieved by **excluding** regular rows

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Formatted Row Summary',
  initialState: {
    Dashboard: {
      PinnedToolbars: ['Layout'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout'],
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'week_issue_change',
            'github_stars',
            'github_watchers',
            'license',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          RowSummaries: [
            {
              Position: 'Top',
              ColumnsMap: {
                language: 'MODE',
                github_watchers: 'SUM',
                github_stars: 'SUM',
              },
            },
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        // Language is Summary Row only
        {
          Name: 'formatColumn-language',
          Scope: {
            ColumnIds: ['language'],
          },
          Style: {
            ForeColor: 'LightBlue',
          },
          RowScope: {
            ExcludeDataRows: true,
          },
        },
        // Github Stars is Not Summary Row
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Style: {
            ForeColor: 'var(--ab-color-palette-30)',
            FontStyle: 'Italic',
          },
          RowScope: {
            ExcludeSummaryRows: true,
          },
        },
        // Github Watchers is all rows
        {
          Name: 'formatColumn-github_watchers',
          Scope: {
            ColumnIds: ['github_watchers'],
          },
          Style: {
            ForeColor: 'var(--ab-color-palette-21)',
          },
        },
        // Add a row format - just for Row summary
        {
          Name: 'style-all',
          Scope: {
            All: true,
          },
          Style: {
            BackColor: '#555555',
          },
          RowScope: {
            ExcludeDataRows: true,
          },
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
  },
};
```

## Filtered Data

By default Row Summaries show Aggregations for the currently visible (i.e. filtered) data in the Grid.

If this is not desired behaviour, set `IncludeOnlyFilteredRows` to *false* in the Row Summary definition

**Example: Filtered Row Summary**

Row Summaries with Filters

- This example contains 2 Row Summaries with the same 4 Aggregations (which we have also formatted)
- The only difference is that the Bottom Row Summary has `IncludeOnlyFilteredRows` set to false
- We have set a [Column Filter](https://www.adaptabletools.com/docs/handbook-column-filter/index.md) on the `Github Stars` Column, and also a [Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter/index.md)
- Accordingly the 2 Row Summaries show different values (e.g. `COUNT` for *Language* Column is 15 at the top and 25 at the bottom)

- Clear the Column Filter on the  `Github Stars` Column and the Grid Filter, and note that now the Row Summaries at the top and bottom match up

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Filtered Row Summary',
  initialState: {
    Dashboard: {
      ModuleButtons: ['CellSummary'],
      PinnedToolbars: ['Layout', 'GridFilter'],
    },

    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'week_issue_change',
            'github_stars',
            'github_watchers',
            'license',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          RowSummaries: [
            {
              Position: 'Top',
              ColumnsMap: {
                github_watchers: 'SUM',
                github_stars: 'SUM',
                week_issue_change: 'AVG',
                language: 'COUNT',
              },
              IncludeOnlyFilteredRows: true,
            },
            {
              Position: 'Bottom',
              ColumnsMap: {
                github_watchers: 'SUM',
                github_stars: 'SUM',
                week_issue_change: 'AVG',
                language: 'COUNT',
              },
              IncludeOnlyFilteredRows: false,
            },
          ],
          Name: 'Standard Layout',
          ColumnFilters: [
            {
              ColumnId: 'github_stars',
              Expression: '[github_stars] >= 5000 AND [github_stars] <= 90000',
            },
          ],
          GridFilter: {
            Expression: '[license]="MIT License" OR [github_watchers] > 67500',
          },
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'style-all',
          Scope: {
            All: true,
          },
          Style: {
            BackColor: '#555555',
            FontStyle: 'Italic',
          },
          RowScope: {
            ExcludeDataRows: true,
          },
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
  },
};
```

## Defining in Layouts

Row Summaries can be defined at design-time using the `RowSummaries` property of the Layout.

### Providing Row Summaries

Provide a list of Row Summaries.

Specify for each Row Summary its position:
- Top
- Bottom

The Columns Map specifies which columns in the Row will display an Aggregation, and of which summary type:

Two properties need to be provided for each entry:
- name of the Column
- the Summary Aggregation to use

By default a Row Summary will only include currently filtered rows in its evaluation.

Set `IncludeOnlyFilteredRows` to false to evaluate all Rows.

```ts [[1, 10, "RowSummaries"], [2, 12, "Position"], [2, 19, "Position"], [3, 13, "ColumnsMap"], [3, 20, "ColumnsMap"], [4, 24, "IncludeOnlyFilteredRows"]]
// 1. Provide 2 Row Summaries:
// Top: SUM Aggregation for Github Stars and Github Watchers
// Bottom: COUNT & AVG Aggregations for Language and Issue Change
const initialState: InitialState = {
  Layout: {
    CurrentLayout: 'Summary Layout',
    Layouts: [
    {
      Name: 'Summary Layout',
      RowSummaries: [
      {
        Position: 'Top',
        ColumnsMap: {
          github_watchers: 'SUM',
          github_stars: 'SUM',
        },
      },
      {
        Position: 'Bottom',
        ColumnsMap: {
          week_issue_change: 'AVG',
          language: 'COUNT',
        },
        IncludeOnlyFilteredRows: false
      },
    ],
    }],
  },
}
```

- Row Summaries can also be created at run-time using the Row Summary step in the [Table Layout Wizard](https://www.adaptabletools.com/docs/handbook-layouts-wizard-table/index.md)
- This allows users to create Row Summaries, choose the position, and select appropriate Aggregations

### FAQ

**Can we create Row Summaries at run-time?**
Yes, via the [Table Layout Wizard](https://www.adaptabletools.com/docs/handbook-layouts-wizard-table/index.md)
