Returns common numeric summary statistics: sum, min, max, average, variance, stdDev.
Optionaloptions: IRange.IteratorOptions
Per-call overrides of the iterator options the stats were created with.
The primary use is { onError: 'ignore' } — reporting surfaces degrade (aggregate the
numeric population, count the errors elsewhere) where the default 'throw' policy treats
an error value as a fault. Results for an options-carrying call are not cached on the
instance; the shared segment cache still applies.
Returns the bounding box of the cells these stats cover, in the coordinates of the scanned grid.
The smallest rectangle containing every covered coordinate, or null when the
stats cover nothing.
Stats over several areas (a multi-area range, or a composite over several ranges) return the
union box, which can include cells outside every area — and a composite's children may sit
on different sheets, so its box is a shape, not an address. getSize() is the exact cell
count; this is where those cells are.
Returns the total count of non-empty values in the range.
Counts all value types — numbers, strings, booleans, errors. Blank/empty cells are excluded.
To count only numbers, use getAggregates().numericalCount.
Never throws on error values — errors are population here, not faults — regardless of
the onError iterator policy the stats were created with (same contract as
getTypedCounts).
Returns the distribution of distinct values in the range — how many times each unique value appears — along with unique-value enumeration and occurrence counts.
Optionaloptions: GetFrequenciesOptionsUse this for filter dropdowns (AutoFilter distinct values), data-profiling summaries,
pivot-like grouping, and any formula that needs COUNTIF-style frequency data
(MODE, FREQUENCY). Provides pandas-like value_counts() behavior.
For purely numeric summary statistics use getAggregates().
For sorted-order queries (rank, percentile) use getSortedNumbers().
Returns the top-N values in the range as a lazily-evaluated iterator, with optional filtering, custom comparison, and deduplication.
Optionaloptions: GetRankedOptionsUse this when you need a short list of the highest or lowest values across any scalar type
(numbers, strings, dates via custom compareFn), typically for display purposes such as
StatusBar top-values, AutoFilter previews, or data-profiling UIs.
Prefer getSortedNumbers when you need exact numeric rank, percentile, or a full
sorted population — getRanked is not designed for whole-population order statistics.
The key distinction: getRanked is bounded (limited output, any type);
getSortedNumbers is complete (all numeric values, full sorted order).
Returns the sum as Excel's SUM reports it — getAggregates's sum with Excel's
cancellation-to-zero rule applied.
Optionaltotal: number
A total the caller accumulated across SEVERAL stats instances. Omit for a single range, where this range's own sum is used.
0 when the total cancelled; otherwise the total unchanged.
Collapses a total to exactly zero when it lands at least 50 binary exponents below the
operands that produced it, so SUM(0.1,0.2,-0.3) is 0 rather than 5.55111512312578E-17.
Use this wherever you mean "the number Excel's SUM would show" — a status bar, a report
total, a formula. Use getAggregates().sum where you mean the true total of the data.
The two genuinely differ, and neither is a rounding of the other:
SUM(2E-13,-1E-13) is 1E-13.SUM, AVERAGE, AVERAGEA, SUBTOTAL(1｜9｜101｜109), AGGREGATE(1｜9)
and PERCENTOF, and to NOTHING else — SUMIF, SUMPRODUCT, SERIESSUM, DSUM, the
SUMX2MY2 family and every binary operator all keep the residue over the same values.
That is why this is a method you call and not a change to getAggregates.AVERAGE divides THIS, not the raw sum: snapping the mean instead is measurably wrong.It is also cheap when it does not fire: a bound derived from min/max rejects any
ordinary total without re-reading the range.
Multiple ranges. Excel evaluates the rule on the final accumulation step, so a total
spanning several ranges must be judged against the range holding the LAST value — pass the
running total as total and call this on that range. (Snapping each range separately gets
SUM(A1:A3,0) and SUM(A1:A1,A2:A2,A3:A3) wrong in opposite directions.) A composite
stats instance already does this across its children.
Returns order-statistic queries over the numeric values in the range: percentiles, quartiles, rank, k-th largest/smallest, and binary search (floor/ceiling).
Use this when the position of a value within the sorted population matters, not just its aggregate contribution.
Prefer this over getRanked when working with numbers and you need an exact position
(k-th value), interpolated quantile, or rank of a known value. Non-numeric values are
excluded automatically.
Also provides findFloor / findCeiling for binary-search lookups for numeric values.
Returns a breakdown of how many cells contain each native value type: number, string, boolean, error, rich data, and blank.
Optionaltypes: readonly ScalarType[]
Restrict the result to only the specified types. Omit to count all types.
Use this for data-profiling UIs ("this column has 420 numbers, 3 errors, 12 blanks"), schema inference, and formula validation helpers. Covers the native spreadsheet scalar types; does not distinguish semantic sub-types such as dates (which are stored as numbers).
0 is a fact about the range, a missing key would be ambiguous.onError iterator policy the stats were created with.
Provides statistical summaries and queries over a range of cell values.
Remarks
Prefer
IRangeStatsover iterating cells manually when you need aggregate or order-statistic results. Implementations operate directly on the engine's internal value storage — no intermediate array allocation is needed for most operations — and results are cached per calculation cycle, so repeated calls within the same cycle are effectively free.This makes
IRangeStatsthe right choice for:SUM,LARGE,RANK,PERCENTILE)