Aggregation

This group summarizes the numbers in a loaded CSV/TSV table: add up a column, average it, find its smallest and largest values, work out a percentile, count how often each value appears, or group the rows and aggregate a value per group. Four of these instructions simply save a number you can reuse later; the other two build a small summary table and register it as a new document.

Prerequisite: a CSV/TSV document must already be loaded — created with Create CSV/TSV file or opened with one of the Reading instructions. These instructions read an existing document; they do not open files themselves.

These concepts recur across the instructions in this group; they are explained here once.

• Document: the Document key points to the loaded CSV/TSV these instructions read from. If you leave it empty, the current document is used (the one instructions work on by default).

• Columns are found by name, ignoring upper/lower case. These instructions work on a table that was loaded with headers, so its rows have named columns. If the column you name isn’t in the table — or the table was loaded without headers (each row is just a list of values, with no column names) — the instruction finds nothing and does nothing.

• Only numbers count. For the numeric instructions (Sum, Average, Min/Max, Percentile), cells that aren’t numbers are simply skipped. If a column has no numeric values at all, the result is 0.

• Saving a result (Save … fields): this group mostly reads — it doesn’t change the document. The way you keep an answer is the Save … field: type a name and the result is stored under it for later instructions to use with @name. Leave it empty and the result is simply not saved.

• Dynamic values @name: the text fields (Column name, Group by columns, Value column, Name, Path, Document key, etc.) accept a saved value — type @ followed by its name and the engine substitutes it at run time.

• “From variable” fields: the numeric Percentile has a companion Percentile key field — a number field can’t take @name, so this is its equivalent:

  • If you leave it empty, the number typed in the normal field is used.
  • If you fill it in with the name of a saved value, the engine ignores the normal field and reads the number from that variable.

  This is mainly for chaining instructions. If you only work with fixed values, you can ignore it.

• Producing a summary document (Count By Value, Group And Aggregate): these two build a new table and register it as a separate document, using the same Name / Path / Output document key / Delimiter fields as the Reading instructions. Name is the file the summary will be saved under, Output document key names it so later instructions can target it, and the Delimiter also decides the extension (a tab saves it as .tsv, anything else as .csv). The summary is only registered when at least one of Name or Output document key is filled in.

• Average Column .csv
• Calculate Percentile .csv
• Count By Value .csv
• Group And Aggregate .csv
• Min Max Column .csv
• Sum Column .csv

Average Column .csv

Works out the average of the numbers in a column and saves it.

When to use it: for a mean value — average price, score, age — over a loaded table.

Parameter	Meaning	Default	Required
Column name	The column whose numbers are averaged (accepts @name)	(empty)	Yes
Document key	The loaded CSV/TSV to read. Empty = current document (accepts @name)	(empty)	No
Save result	Saves the average under this name for later instructions	(empty)	No

Important behavior: the average is taken over the numeric cells only. If Column name is empty or the column isn’t found, nothing happens. If the column has no numbers, the result is 0.

---

Calculate Percentile .csv

Works out the value at a given percentile (0–100) of a numeric column and saves it.

When to use it: for a median (percentile 50), a quartile (25 or 75), or any other cut-off point that describes where a value sits within the column.

Parameter	Meaning	Default	Required
Document key	The loaded CSV/TSV to read. Empty = current document (accepts @name)	(empty)	No
Column name	The numeric column to analyze (accepts @name)	(empty)	Yes
Percentile	The percentile to compute, 0–100 (50 = median, 25 = lower quartile, 75 = upper quartile)	50	No
Percentile (from variable)	Reads the percentile from a saved value instead of the field above	(empty)	No
Save result	Saves the computed value under this name	(empty)	No

Important behavior: the percentile is clamped to the 0–100 range. The value is computed by linear interpolation between the two closest numbers (the same method as the spreadsheet function PERCENTILE.INC). If Column name is empty, the column isn’t found, or it has no numbers, nothing is saved.

---

Count By Value .csv

Counts how many times each distinct value appears in a column. Optionally builds a two-column summary table (the value and its count) and registers it as a new document.

When to use it: to see the breakdown of a category column — how many rows per country, per status, per product — as a tally.

Parameter	Meaning	Default	Required
Document key	The loaded CSV/TSV to read. Empty = current document (accepts @name)	(empty)	No
Column name	The column whose values are tallied (accepts @name)	(empty)	Yes
Sort by count	Yes = most frequent first; No = alphabetical by value	Yes	No
Case sensitive	Yes = treat Apple and apple as different values; No = as the same	No	No
Delimiter	Delimiter/extension of the produced summary document (accepts @name)	,	No
Sort by count (from variable)	Reads the yes/no value from a saved value	(empty)	No
Case sensitive (from variable)	Reads the yes/no value from a saved value	(empty)	No
Name	File name the summary document will be saved under (accepts @name)	(empty)	To save
Path	Folder the summary document will be saved to (accepts @name)	(empty)	To save
Output document key	Names the summary document so later instructions can target it (accepts @name)	(empty)	No
Save result	Saves the value→count pairs as a single named result	(empty)	No
Save count	Saves the number of distinct values found	(empty)	No

Important behavior: if Column name is empty or the column isn’t found, nothing happens. The summary table (columns: the tallied column, then Count) is registered as a new document only when Name or Output document key is filled in; otherwise you can still capture the tally through Save result / Save count. A tab Delimiter saves the summary as a .tsv.

---

Group And Aggregate .csv

Groups the rows by one or more columns and computes a summary value per group (sum, average, min, max, or count), then registers the grouped result as a new document.

When to use it: for a pivot-style summary — total sales per region, average score per class, number of orders per customer.

Parameter	Meaning	Default	Required
Document key	The loaded CSV/TSV to read. Empty = current document (accepts @name)	(empty)	No
Group by columns	One or more columns to group by, separated by commas (accepts @name)	(empty)	Yes
Value column	The numeric column the summary is computed from (accepts @name)	(empty)	No
Aggregation	How to summarize each group: sum, average, min, max, or count (accepts @name)	sum	No
Output column name	Header for the summary column; empty = the aggregation name in capitals (accepts @name)	(empty)	No
Delimiter	Delimiter/extension of the produced summary document (accepts @name)	,	No
Name	File name the summary document will be saved under (accepts @name)	(empty)	To save
Path	Folder the summary document will be saved to (accepts @name)	(empty)	To save
Output document key	Names the summary document so later instructions can target it (accepts @name)	(empty)	No
Save group count	Saves the number of groups written	(empty)	No

Important behavior: if you fill in neither Name nor Output document key, the grouping still happens and Save group count key is still saved — only the summary document is not kept. The instruction does nothing if Group by columns is empty, if the table is empty, or if none of the named group columns exist. Only group columns that actually exist are used. count counts the rows in each group and ignores Value column; the other functions work on the numbers in Value column (a group with no numbers gives 0). A tab Delimiter saves the summary as a .tsv.

---

Min Max Column .csv

Finds the smallest and largest numbers in a column and saves each one.

When to use it: to learn a column’s range — lowest and highest price, oldest and newest value, etc.

Parameter	Meaning	Default	Required
Column name	The column to scan for its minimum and maximum (accepts @name)	(empty)	Yes
Document key	The loaded CSV/TSV to read. Empty = current document (accepts @name)	(empty)	No
Save minimum	Saves the smallest value under this name	(empty)	No
Save maximum	Saves the largest value under this name	(empty)	No

Important behavior: there are two save fields — you can capture the minimum, the maximum, or both. If Column name is empty or the column isn’t found, nothing happens. If the column has no numbers, both results are 0.

---

Sum Column .csv

Adds up all the numbers in a column and saves the total.

When to use it: to get a column total — sales, quantities, amounts — from a loaded table.

Parameter	Meaning	Default	Required
Column name	The column whose numbers are added up (accepts @name)	(empty)	Yes
Document key	The loaded CSV/TSV to read. Empty = current document (accepts @name)	(empty)	No
Save result	Saves the total under this name for later instructions	(empty)	No

Important behavior: if Column name is empty, or the column isn’t in the table, the instruction does nothing (nothing is saved). Non-numeric cells are skipped; a column with no numbers totals 0.

---