Class: FlameFrame\<T>¶
A schema-validated subclass of BareFrame.
FlameFrame<T> extends BareFrame with a FlameRecord<T> schema.
Use FlameFrame.from to validate a BareFrame against the schema.
The resulting frame contains only rows that passed all guards,
and exposes all BareFrame properties (length, headers, etc.) directly.
For a schema-free DataFrame, use BareFrame instead.
Example¶
const schema = {
name: FlameGuards.isString,
age: FlameGuards.isNumber,
};
// Validate on input
const df = BareFrame.fromSheet(sheet);
const { passed, failed } = FlameFrame.from(df, schema);
if (failed.length > 0) {
Logger.log(failed.toString());
}
// Transform using BareFrame, then re-validate on output
const adults = df.filter((row) => (row.get("age") as number) >= 18);
const { passed: validatedAdults } = FlameFrame.from(adults, schema);
validatedAdults.toSheet(outputSheet);
Since¶
0.39.0
Extends¶
Type Parameters¶
T¶
T extends Record\<string, Cell> = never
DataFrame¶
fromArrays()¶
staticfromArrays(arrays,headers?):BareFrame
Creates a BareFrame from a header-annotated 2D array.
When headers is omitted the first row is consumed as column names
and data starts from the second row. When arrays is empty (or contains
only a header row), an empty BareFrame with the resolved headers is returned.
Parameters¶
arrays¶
Cell[][]
2D array. First row is headers when headers is omitted.
headers?¶
string[]
Explicit column names. When provided, all rows are data rows.
Returns¶
New BareFrame
Example¶
// headers inferred from first row
const df = BareFrame.fromArrays([["name", "age"], ["Alice", 25]]);
// headers provided explicitly
const df2 = BareFrame.fromArrays([["Alice", 25]], ["name", "age"]);
// empty input → empty BareFrame
const empty = BareFrame.fromArrays([]);
Inherited from¶
fromRows()¶
staticfromRows(rows):BareFrame
Creates a BareFrame from an array of row Maps.
Delegates to rowsToMap in convert.ts.
Parameters¶
rows¶
Map\<string, Cell>[]
Array of row Maps (each maps column name → cell value)
Returns¶
New BareFrame
Example¶
const rows = [
new Map([["name", "Alice"], ["age", 25]]),
new Map([["name", "Bob"], ["age", 30]]),
];
const df = BareFrame.fromRows(rows);
Inherited from¶
fromColumns()¶
staticfromColumns(columns):BareFrame
Creates a BareFrame from a column-oriented plain object.
Delegates to columnsToMap in convert.ts.
Parameters¶
columns¶
Record\<string, Cell[]>
Plain object mapping column names to value arrays
Returns¶
New BareFrame
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
Inherited from¶
fromMap()¶
staticfromMap(map):BareFrame
Creates a BareFrame from a column-oriented Map.
The Map is defensively copied so that later mutations to the source do not affect the BareFrame.
Parameters¶
map¶
Map\<string, Cell[]>
Column-oriented Map
Returns¶
New BareFrame
Example¶
const map = new Map([["name", ["Alice", "Bob"]], ["age", [25, 30]]]);
const df = BareFrame.fromMap(map);
Inherited from¶
fromRange()¶
staticfromRange(range,headers?):BareFrame
Creates a BareFrame from a Google Apps Script Range object.
When headers is omitted, the first row of the range is consumed as
column names and data starts from the second row.
When headers is provided, all rows are treated as data rows.
Parameters¶
range¶
Range
GAS Range object
headers?¶
string[]
Explicit column names (optional). When omitted, first row is used.
Returns¶
New BareFrame
Example¶
// First row as headers (default)
const df = BareFrame.fromRange(sheet.getRange("A1:C10"));
// Explicit headers — all rows become data rows
const df2 = BareFrame.fromRange(sheet.getRange("A1:C10"), ["name", "age", "score"]);
Since¶
0.35.0
Inherited from¶
fromSheet()¶
staticfromSheet(sheet,headers?):BareFrame
Creates a BareFrame from a Google Apps Script Sheet object.
Reads the entire data range of the sheet via getDataRange().
When headers is omitted, the first row is consumed as column names.
When headers is provided, all rows are treated as data rows.
Parameters¶
sheet¶
Sheet
GAS Sheet object
headers?¶
string[]
Explicit column names (optional). When omitted, first row is used.
Returns¶
New BareFrame
Example¶
// First row as headers (default)
const df = BareFrame.fromSheet(SpreadsheetApp.getActiveSheet());
// Explicit headers — all rows become data rows
const df2 = BareFrame.fromSheet(sheet, ["name", "age"]);
Since¶
0.35.0
Inherited from¶
toSheet()¶
toSheet(
sheet,options?):void
Writes the BareFrame to a Google Apps Script Sheet object.
By default, clears the sheet and writes from row 1 with a header row.
Use options to append data or skip the header.
Parameters¶
sheet¶
Sheet
GAS Sheet object to write to
options?¶
ToSheetOptions = {}
Write options
Returns¶
void
Example¶
// Overwrite sheet (default)
df.toSheet(sheet);
// Append without header
df.toSheet(sheet, { clear: false, header: false, startRow: sheet.getLastRow() + 1 });
Since¶
0.41.0
Inherited from¶
headers¶
Get Signature¶
get headers():
string[]
Returns column names in insertion order.
Example¶
df.headers; // ["name", "age"]
Returns¶
string[]
Array of column names in order
Inherited from¶
length¶
Get Signature¶
get length():
number
Returns the number of rows.
Example¶
df.length; // 2
Returns¶
number
Number of rows in the DataFrame
Inherited from¶
shape¶
Get Signature¶
get shape(): [
number,number]
Returns [rows, columns].
Example¶
df.shape; // [2, 2]
Returns¶
Tuple of [number of rows, number of columns]
Inherited from¶
select()¶
select(
headers):BareFrame
Returns a new BareFrame containing only the specified columns.
Parameters¶
headers¶
string[]
Column names to keep
Returns¶
New BareFrame
Throws¶
Error when any of the specified column names do not exist
Examples¶
const names = df.select(["name"]);
Error — column does not exist:
df.select(["missing"]); // throws Error: column "missing" does not exist
Inherited from¶
drop()¶
drop(
headers):BareFrame
Alias for dropColumns. Returns a new BareFrame with the specified columns removed.
Parameters¶
headers¶
string[]
Column names to remove
Returns¶
New BareFrame without the specified columns
Throws¶
Error when any of the specified column names do not exist
Example¶
const withoutAge = df.drop(["age"]);
Inherited from¶
dropColumns()¶
dropColumns(
headers):BareFrame
Returns a new BareFrame with the specified columns removed.
Parameters¶
headers¶
string[]
Column names to remove
Returns¶
New BareFrame without the specified columns
Throws¶
Error when any of the specified column names do not exist
Examples¶
const withoutAge = df.dropColumns(["age"]);
Error — column does not exist:
df.dropColumns(["missing"]); // throws Error: column "missing" does not exist
Inherited from¶
dropRows()¶
dropRows(
indices):BareFrame
Returns a new BareFrame with the specified rows removed.
Parameters¶
indices¶
number[]
0-based row indices to remove
Returns¶
New BareFrame without the specified rows
Throws¶
Error when any of the specified indices are out of range
Examples¶
// Remove the first and third rows (0-based)
const result = df.dropRows([0, 2]);
Error — index out of range:
df.dropRows([99]); // throws Error: row index 99 is out of range
Inherited from¶
filter()¶
filter(
predicate):BareFrame
Returns a new BareFrame containing only the rows for which predicate
returns true.
Parameters¶
predicate¶
Function receiving each row as Map<string, Cell> and its index
Returns¶
New BareFrame
Example¶
const adults = df.filter((row) => (row.get("age") as number) > 18);
Inherited from¶
withColumn()¶
withColumn(
header,mapper):BareFrame
Returns a new BareFrame with a column added or replaced.
mapper is called for each row (as Map<string, Cell>) and its
0-based index. The returned value becomes the cell for that row.
Parameters¶
header¶
string
mapper¶
Function receiving each row Map and row index
Returns¶
New BareFrame
Example¶
const df2 = df.withColumn("doubled", (row) => (row.get("age") as number) * 2);
// Row index as a new column
const df3 = df.withColumn("idx", (_row, i) => i);
Inherited from¶
rename()¶
rename(
mapping):BareFrame
Returns a new BareFrame with columns renamed according to mapping.
Columns not listed in mapping are kept with their original names.
Insertion order is preserved.
Parameters¶
mapping¶
Record\<string, string>
Plain object mapping old column names to new names
Returns¶
New BareFrame
Throws¶
Error when any key in mapping does not exist as a column
Examples¶
const renamed = df.rename({ age: "years", name: "fullName" });
Error — column does not exist:
df.rename({ missing: "newName" }); // throws Error: column "missing" does not exist
Inherited from¶
fillna()¶
fillna(
value):BareFrame
Returns a new BareFrame with null, undefined, and empty-string cells
replaced by value.
All columns are scanned. Only cells that are strictly null, undefined,
or "" are replaced; other falsy values such as 0 or false are kept.
Parameters¶
value¶
Replacement value for missing cells
Returns¶
New BareFrame with missing cells filled
Example¶
const df = BareFrame.fromColumns({
name: ["Alice", null, "Charlie"],
age: [25, null, 35],
});
const filled = df.fillna(0);
// name | age
// Alice | 25
// 0 | 0
// Charlie | 35
Inherited from¶
melt()¶
melt(
options?):BareFrame
Reshapes the BareFrame from wide format to long format.
Each row in the source is expanded into one row per value column.
idVars columns are repeated for every expanded row.
When valueVars is omitted, all columns not listed in idVars are melted.
Parameters¶
options?¶
MeltOptions = {}
Melt options
Returns¶
New BareFrame in long format
Throws¶
Error when any column name in idVars or valueVars does not exist
Example¶
const df = BareFrame.fromColumns({
name: ["Alice", "Bob"],
math: [90, 80],
english: [70, 85],
});
const long = df.melt({ idVars: ["name"] });
// name | variable | value
// Alice | math | 90
// Alice | english | 70
// Bob | math | 80
// Bob | english | 85
Inherited from¶
pivot()¶
pivot(
options):BareFrame
Reshapes the BareFrame from long format to wide format.
Unique values from options.columns become the new column headers.
Unique values from options.index become the row identifiers.
When a combination of index and column value does not exist in the source,
the cell is filled with null.
Parameters¶
options¶
PivotOptions
Pivot options (see PivotOptions)
Returns¶
New BareFrame in wide format
Throws¶
Error when any column name in options does not exist
Example¶
const df = BareFrame.fromColumns({
date: ["2024-01", "2024-01", "2024-02", "2024-02"],
metric: ["sales", "profit", "sales", "profit"],
value: [100, 20, 110, 25],
});
const wide = df.pivot({ index: "date", columns: "metric", values: "value" });
// date | sales | profit
// 2024-01 | 100 | 20
// 2024-02 | 110 | 25
Inherited from¶
unfoldColumns()¶
unfoldColumns(
options):BareFrame
Unfold grouped columns into individual rows.
Expands columns that represent repeated groups (e.g., multiple people, questions, or time periods) from wide format into long format, where each group becomes a separate row.
Parameters¶
options¶
UnfoldOptions
Unfold options (see UnfoldOptions)
Returns¶
New BareFrame with unfolded rows
Throws¶
Error when fixed headers do not exist, groups/groupHeaders lengths mismatch, or (in strict mode) when group columns do not exist or group size mismatches.
Remarks¶
- Fixed headers are preserved on every unfolded row (e.g., timestamp, email).
- Each group becomes a separate row with the same fixed values.
- In permissive mode (default), missing columns in groups are filled with
null. - In strict mode (
strict: true), missing columns or size mismatches throw an error.
Example¶
const df = BareFrame.fromColumns({
timestamp: ["2024-03-25"],
email: ["a@example.com"],
person1_name: ["Alice"],
person1_age: [30],
person2_name: ["Bob"],
person2_age: [25],
});
const unfolded = df.unfoldColumns({
fixedHeaders: ["timestamp", "email"],
groups: [
["person1_name", "person1_age"],
["person2_name", "person2_age"],
],
groupHeaders: ["name", "age"],
});
// Result:
// timestamp | email | name | age
// 2024-03-25 | a@example.com | Alice | 30
// 2024-03-25 | a@example.com | Bob | 25
Since¶
0.44.0
Inherited from¶
slice()¶
slice(
start,end?):BareFrame
Returns a new BareFrame containing rows from start up to (not including) end.
Follows the same semantics as Array.prototype.slice:
omitting end includes all remaining rows.
Parameters¶
start¶
number
0-based start row index (inclusive)
end?¶
number
0-based end row index (exclusive); defaults to this.length
Returns¶
New BareFrame with the selected row range
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob", "Charlie"], age: [25, 30, 35] });
df.slice(1); // Bob, Charlie
df.slice(0, 2); // Alice, Bob
Inherited from¶
head()¶
head(
n?):BareFrame
Returns a new BareFrame containing the first n rows.
Parameters¶
n?¶
number = 5
Number of rows to return (default: 5)
Returns¶
New BareFrame with up to n rows from the top
Example¶
df.head(2); // first 2 rows
Inherited from¶
tail()¶
tail(
n?):BareFrame
Returns a new BareFrame containing the last n rows.
Parameters¶
n?¶
number = 5
Number of rows to return (default: 5)
Returns¶
New BareFrame with up to n rows from the bottom
Example¶
df.tail(2); // last 2 rows
Inherited from¶
sortBy()¶
sortBy(
headers,options?):BareFrame
Returns a new BareFrame with rows sorted by one or more columns.
Columns are sorted left-to-right: ties in the first column are broken by the second, and so on. Null values are always sorted to the end regardless of sort direction.
Parameters¶
headers¶
string[]
Column names to sort by, in priority order
options?¶
SortOptions = {}
Sort options
Returns¶
New BareFrame with rows in sorted order
Remarks¶
The caller is responsible for specifying headers in the correct priority
order and for ensuring options.ascending corresponds to each column in
the same position. No validation is performed on the intended sort order.
Throws¶
Error when any column in headers does not exist
Throws¶
Error when options.ascending length does not match headers length
Examples¶
const df = BareFrame.fromColumns({
dept: ["eng", "hr", "eng"],
age: [30, 25, 25],
score: [80, 70, 90],
});
// single column, ascending (default)
df.sortBy(["age"]);
// dept | age | score
// eng | 25 | 90
// eng | 30 | 80
// hr | 25 | 70
// single column, descending
df.sortBy(["age"], { ascending: [false] });
// dept | age | score
// eng | 30 | 80
// hr | 25 | 70
// eng | 25 | 90
// multi-column: dept ascending, age descending
df.sortBy(["dept", "age"], { ascending: [true, false] });
// dept | age | score
// eng | 30 | 80
// eng | 25 | 90
// hr | 25 | 70
Error — column does not exist:
df.sortBy(["missing"]); // throws Error: column "missing" does not exist
Error — ascending length mismatch:
df.sortBy(["age", "score"], { ascending: [true] }); // throws Error: ascending length mismatch
Inherited from¶
concat()¶
concat(
other):BareFrame
Returns a new BareFrame with the rows of other appended below this one.
Both DataFrames must have identical headers in the same order.
Parameters¶
other¶
BareFrame to append
Returns¶
New BareFrame with combined rows
Throws¶
Error when column count or column names do not match
Examples¶
const top = BareFrame.fromColumns({ name: ["Alice"], age: [25] });
const btm = BareFrame.fromColumns({ name: ["Bob"], age: [30] });
top.concat(btm);
// name | age
// Alice | 25
// Bob | 30
Error — header mismatch:
const a = BareFrame.fromColumns({ name: ["Alice"] });
const b = BareFrame.fromColumns({ age: [25] });
a.concat(b); // throws Error: column mismatch at position 0: "name" vs "age"
Inherited from¶
join()¶
join(
other,on,options?):BareFrame
Returns a new BareFrame joined with other on a common column.
Parameters¶
other¶
BareFrame to join with
on¶
string
Column name to join on (must exist in both DataFrames)
options?¶
JoinOptions = {}
Join options
Returns¶
New BareFrame with joined rows
Remarks¶
Dispatches to joinInner, joinLeft, joinRight, or joinOuter
based on options.how. Use those methods directly for explicit control.
Throws¶
Error when on does not exist in either BareFrame
Example¶
const left = BareFrame.fromColumns({ id: [1, 2, 3], name: ["Alice", "Bob", "Charlie"] });
const right = BareFrame.fromColumns({ id: [1, 2, 4], score: [90, 80, 70] });
left.join(right, "id"); // inner: id=1,2 only
left.join(right, "id", { how: "left" }); // left: all 3 left rows, id=3 score=null
left.join(right, "id", { how: "right" }); // right: all 3 right rows, id=4 name=null
left.join(right, "id", { how: "outer" }); // outer: all 4 unique ids
Inherited from¶
joinInner()¶
joinInner(
other,on):BareFrame
Returns a new BareFrame with only the rows whose on-column value
exists in both DataFrames (inner join).
Only rows with a matching key in both DataFrames are included.
Right-side columns that share a name with the left side (except on) are omitted.
Parameters¶
other¶
BareFrame to join with
on¶
string
Column name to join on
Returns¶
New BareFrame containing only matched rows from both DataFrames
Throws¶
Error when on does not exist in either BareFrame
Example¶
const left = BareFrame.fromColumns({ id: [1, 2, 3], name: ["Alice", "Bob", "Charlie"] });
const right = BareFrame.fromColumns({ id: [1, 2, 4], score: [90, 80, 70] });
left.joinInner(right, "id");
// id | name | score
// 1 | Alice | 90
// 2 | Bob | 80
Inherited from¶
joinLeft()¶
joinLeft(
other,on):BareFrame
Returns a new BareFrame with all rows from this BareFrame and matched rows from other (left join).
All left rows are preserved. Rows with no matching key in other get
null for all right-side columns.
Parameters¶
other¶
BareFrame to join with
on¶
string
Column name to join on
Returns¶
New BareFrame with all left rows; unmatched rows have null for right-side columns
Throws¶
Error when on does not exist in either BareFrame
Example¶
const left = BareFrame.fromColumns({ id: [1, 2, 3], name: ["Alice", "Bob", "Charlie"] });
const right = BareFrame.fromColumns({ id: [1, 2, 4], score: [90, 80, 70] });
left.joinLeft(right, "id");
// id | name | score
// 1 | Alice | 90
// 2 | Bob | 80
// 3 | Charlie | null
Inherited from¶
joinRight()¶
joinRight(
other,on):BareFrame
Returns a new BareFrame with matched rows from this BareFrame and all rows from other (right join).
All right rows are preserved. Rows with no matching key in this BareFrame get
null for all left-side columns.
Parameters¶
other¶
BareFrame to join with
on¶
string
Column name to join on
Returns¶
New BareFrame with all right rows; unmatched rows have null for left-side columns
Throws¶
Error when on does not exist in either BareFrame
Example¶
const left = BareFrame.fromColumns({ id: [1, 2, 3], name: ["Alice", "Bob", "Charlie"] });
const right = BareFrame.fromColumns({ id: [1, 2, 4], score: [90, 80, 70] });
left.joinRight(right, "id");
// id | name | score
// 1 | Alice | 90
// 2 | Bob | 80
// 4 | null | 70
Inherited from¶
joinOuter()¶
joinOuter(
other,on):BareFrame
Returns a new BareFrame with all rows from both DataFrames (full outer join).
Rows with matching keys are merged. Rows that exist only in the left
BareFrame get null for right-side columns, and rows that exist only
in the right BareFrame get null for left-side columns.
Parameters¶
other¶
BareFrame to join with
on¶
string
Column name to join on
Returns¶
New BareFrame with all rows from both DataFrames
Throws¶
Error when on does not exist in either BareFrame
Example¶
const left = BareFrame.fromColumns({ id: [1, 2, 3], name: ["Alice", "Bob", "Charlie"] });
const right = BareFrame.fromColumns({ id: [2, 3, 4], score: [80, 70, 60] });
left.joinOuter(right, "id");
// id | name | score
// 1 | Alice | null
// 2 | Bob | 80
// 3 | Charlie | 70
// 4 | null | 60
Inherited from¶
groupBy()¶
groupBy(
headers):GroupedFrame
Groups the BareFrame by one or more key columns.
Parameters¶
headers¶
string[]
One or more column names to group by
Returns¶
GroupedFrame ready for aggregation
Remarks¶
Groups are formed column-by-column without converting to row Maps.
Each unique combination of key-column values becomes one group,
in the order of first appearance.
The returned GroupedFrame holds a reference to this frame — no data
is copied until an aggregation method (count, first, last, agg)
is called.
Throws¶
Error when any column in headers does not exist
Example¶
const df = BareFrame.fromColumns({
dept: ["eng", "eng", "hr"],
score: [80, 90, 70],
});
// single key
df.groupBy(["dept"]).count();
// dept | count
// eng | 2
// hr | 1
// composite key
df.groupBy(["dept", "score"]).count();
// dept | score | count
// eng | 80 | 1
// eng | 90 | 1
// hr | 70 | 1
Inherited from¶
resampleBy()¶
resampleBy(
header,freq,options?):GroupedFrame
Groups rows into time buckets for time-series aggregation.
Parameters¶
header¶
string
Time column name (Date or numeric timestamp in milliseconds)
freq¶
string
Frequency string
options?¶
ResampleOptions = {}
Resample options. See ResampleOptions
Returns¶
GroupedFrame for chaining aggregation methods
Remarks¶
Resamples time-series data by converting timestamps in the specified column to time bucket boundaries (as Unix timestamps in milliseconds), then grouping rows by the resulting buckets. This enables aggregation operations (sum, mean, count, etc.) across time periods.
The time column is replaced with numeric bucket boundary values (milliseconds
since epoch). To exclude this column from results, use .select() to keep only
the aggregated columns. For timezone-aware display, format these numeric values
using GAS utilities like Utilities.formatDate().
Frequency format: "Ns", "Nm", "Nh", "Nd", "Nw" where N is a
positive integer (e.g., "1s", "60s", "15m", "1h", "2h", "1d",
"7d", "1w", "2w").
Throws¶
Error when the specified column does not exist
Throws¶
Error when frequency format is invalid
Examples¶
Basic hourly aggregation:
const df = BareFrame.fromColumns({
timestamp: [
new Date("2026-04-03T10:30:00Z"),
new Date("2026-04-03T10:45:00Z"),
new Date("2026-04-03T11:15:00Z"),
],
value: [100, 200, 150],
});
df.resampleBy("timestamp", "1h").sum(["value"]);
// timestamp column is now numbers (milliseconds)
// Groups 10:30 and 10:45 into same bucket (sum=300)
// Groups 11:15 into different bucket (sum=150)
TZ-aware display — format bucket timestamps in local time:
const result = df.resampleBy("timestamp", "1h").sum(["value"]);
result.withColumn("timestamp", (row) =>
Utilities.formatDate(
new Date(row.get("timestamp") as number),
Session.getScriptTimeZone(),
"yyyy-MM-dd HH:mm:ss",
)
);
// "2026-04-03 10:00:00" | 300
// "2026-04-03 11:00:00" | 150
Custom rounding with 15-minute buckets:
df.resampleBy("timestamp", "15m", { round: "ceil" }).count();
// Rounds each timestamp up to the next 15-minute boundary
Since¶
0.61.0
Inherited from¶
isDuplicated()¶
isDuplicated(
options?):BareFrame
Returns a new BareFrame with an "is_duplicated" boolean column appended.
Parameters¶
options?¶
DuplicateOptions = {}
Duplicate check options
Returns¶
New BareFrame with all original columns plus "is_duplicated".
Remarks¶
A row is considered duplicated when another row in the DataFrame produces the
same composite key from the specified columns.
The keep parameter controls which occurrence is NOT marked as duplicated.
Use findDuplicatedRows to extract only the duplicated rows, or
dropDuplicatedRows to remove them.
Throws¶
Error when the DataFrame is empty.
Throws¶
Error when any name in options.headers does not exist as a column.
Examples¶
const df = BareFrame.fromColumns({
name: ["Alice", "Bob", "Alice"],
age: [25, 30, 25],
});
// keep="first" (default): mark the second "Alice" as duplicated
df.isDuplicated();
// name | age | is_duplicated
// Alice | 25 | false
// Bob | 30 | false
// Alice | 25 | true
// keep="last": mark the first "Alice" as duplicated
df.isDuplicated({ keep: "last" });
// name | age | is_duplicated
// Alice | 25 | true
// Bob | 30 | false
// Alice | 25 | false
// keep="none": mark all occurrences of "Alice" as duplicated
df.isDuplicated({ keep: "none" });
// name | age | is_duplicated
// Alice | 25 | true
// Bob | 30 | false
// Alice | 25 | true
// headers: check only the "name" column
df.isDuplicated({ headers: ["name"] });
// name | age | is_duplicated
// Alice | 25 | false
// Bob | 30 | false
// Alice | 25 | true
Error — empty DataFrame:
BareFrame.fromColumns({}).isDuplicated(); // throws Error: cannot check duplicates on an empty DataFrame
Error — column does not exist:
df.isDuplicated({ headers: ["missing"] }); // throws Error: column "missing" does not exist
Since¶
0.46.0
Inherited from¶
findDuplicatedRows()¶
findDuplicatedRows(
options?):BareFrame
Returns a new BareFrame containing only the duplicated rows.
Parameters¶
options?¶
DuplicateOptions = {}
Duplicate check options
Returns¶
New BareFrame with only duplicated rows and original columns.
Throws¶
Error when the DataFrame is empty.
Throws¶
Error when any name in options.headers does not exist as a column.
Example¶
const df = BareFrame.fromColumns({
name: ["Alice", "Bob", "Alice", "Charlie", "Bob"],
score: [80, 70, 80, 90, 70],
});
// keep="first" (default): return the non-first occurrences
df.findDuplicatedRows();
// name | score
// Alice | 80
// Bob | 70
// keep="none": return all occurrences of duplicated values
df.findDuplicatedRows({ keep: "none" });
// name | score
// Alice | 80
// Bob | 70
// Alice | 80
// Bob | 70
Since¶
0.46.0
Inherited from¶
dropDuplicatedRows()¶
dropDuplicatedRows(
options?):BareFrame
Returns a new BareFrame with duplicated rows removed.
Parameters¶
options?¶
DuplicateOptions = {}
Duplicate check options
Returns¶
New BareFrame without duplicated rows and original columns.
Throws¶
Error when the DataFrame is empty.
Throws¶
Error when any name in options.headers does not exist as a column.
Example¶
const df = BareFrame.fromColumns({
name: ["Alice", "Bob", "Alice", "Charlie", "Bob"],
score: [80, 70, 80, 90, 70],
});
// keep="first" (default): keep the first occurrence of each value
df.dropDuplicatedRows();
// name | score
// Alice | 80
// Bob | 70
// Charlie | 90
// keep="last": keep the last occurrence of each value
df.dropDuplicatedRows({ keep: "last" });
// name | score
// Alice | 80
// Charlie | 90
// Bob | 70
// keep="none": remove all rows that have any duplicate
df.dropDuplicatedRows({ keep: "none" });
// name | score
// Charlie | 90
Since¶
0.46.0
Inherited from¶
toString()¶
toString():
string
Returns a one-line summary of this BareFrame.
Returns¶
string
Summary string in the format BareFrame(<rows> rows × <cols> cols, headers=[...])
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.toString();
// "BareFrame(2 rows × 2 cols, headers=[name, age])"
Inherited from¶
toTableString()¶
toTableString(
maxRows?,maxColWidth?):string
Returns a markdown-style table string of the BareFrame contents.
Parameters¶
maxRows?¶
number = 10
Maximum number of rows to include (default: 10)
maxColWidth?¶
number = 20
Maximum character width per column (default: 20)
Returns¶
string
Formatted table string
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.toTableString();
// | name | age |
// | ----- | --- |
// | Alice | 25 |
// | Bob | 30 |
Inherited from¶
display()¶
display(
maxRows?,maxColWidth?):string
Returns a formatted table string of the BareFrame contents.
Parameters¶
maxRows?¶
number = 10
Maximum number of rows to include (default: 10)
maxColWidth?¶
number = 20
Maximum character width per column (default: 20)
Returns¶
string
Formatted table string
Remarks¶
Alias for toTableString. Use display() for interactive exploration.
Example¶
console.log(df.display());
Inherited from¶
describe()¶
describe():
BareFrame
Returns a summary BareFrame of descriptive statistics for numeric columns.
Each row in the result corresponds to one numeric column in the source. Non-numeric columns are ignored. Returns an empty BareFrame when no numeric columns exist.
The result has five columns:
- column — source column name
- count — number of numeric values (non-numeric cells excluded)
- mean — arithmetic mean
- min — minimum value
- max — maximum value
Returns¶
New BareFrame with one row per numeric column
Example¶
const df = BareFrame.fromColumns({
name: ["Alice", "Bob", "Charlie"],
age: [25, 30, 35],
score: [95, 87, 92],
});
df.describe();
// column | count | mean | min | max
// age | 3 | 30 | 25 | 35
// score | 3 | 91.3 | 87 | 95
Inherited from¶
toArrays()¶
toArrays(
headers?):Cell[][]
Converts the BareFrame to a header-annotated 2D array.
The first row contains column names. When headers is provided only
those columns (in that order) are included.
Parameters¶
headers?¶
string[]
Columns to include (default: all columns in insertion order)
Returns¶
Cell[][]
2D array with header row prepended
Throws¶
Error when any column in headers does not exist
Example¶
df.toArrays();
// [["name", "age"], ["Alice", 25], ["Bob", 30]]
df.toArrays(["name"]);
// [["name"], ["Alice"], ["Bob"]]
Inherited from¶
getRow()¶
getRow(
index):Map\<string,Cell>
Returns the row at index as a Map<string, Cell>.
Parameters¶
index¶
number
Zero-based row index
Returns¶
Map\<string, Cell>
Row data as a Map keyed by column name
Throws¶
RangeError when index is out of bounds
Examples¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.getRow(0).get("name"); // "Alice"
df.getRow(1).get("age"); // 30
Error — index out of bounds:
df.getRow(99); // throws RangeError: index 99 is out of bounds
Inherited from¶
getColumn()¶
getColumn(
header):Cell[]
Returns the values in column name as a Cell[].
Parameters¶
header¶
string
Returns¶
Cell[]
Array of cell values in row order
Throws¶
Error when name does not exist as a column
Examples¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.getColumn("age"); // [25, 30]
df.getColumn("name"); // ["Alice", "Bob"]
Error — column does not exist:
df.getColumn("missing"); // throws Error: column "missing" does not exist
Inherited from¶
toRows()¶
toRows():
Map\<string,Cell>[]
Converts the BareFrame to an array of row Maps.
Delegates to mapToRows in convert.ts.
Returns¶
Map\<string, Cell>[]
Array of row Maps
Example¶
const rows = df.toRows();
rows[0].get("name"); // "Alice"
Inherited from¶
toObjects()¶
toObjects():
Record\<string,Cell>[]
Converts the BareFrame to an array of plain objects.
Each object represents one row, mapping column name to cell value.
Unlike toRows, the result is JSON-serializable.
Returns¶
Record\<string, Cell>[]
Array of plain objects in row order
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.toObjects();
// [{ name: "Alice", age: 25 }, { name: "Bob", age: 30 }]
JSON.stringify(df.toObjects()); // JSON-serializable
Inherited from¶
toColumns()¶
toColumns():
Record\<string,Cell[]>
Converts the BareFrame to a column-oriented plain object.
Delegates to mapToColumns in convert.ts.
Returns¶
Record\<string, Cell[]>
Plain object mapping column names to value arrays
Example¶
const cols = df.toColumns();
cols["name"]; // ["Alice", "Bob"]
Inherited from¶
toJson()¶
toJson(
indent?):string
Serializes the BareFrame to a JSON string.
Parameters¶
indent?¶
number = 0
Number of spaces for pretty-printing (default: 0 = compact)
Returns¶
string
JSON string representation of the DataFrame
Remarks¶
Converts to an array of row objects via toObjects(), then serializes
with JSON.stringify. Each row is a plain object mapping column name
to cell value.
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.toJson();
// '[{"name":"Alice","age":25},{"name":"Bob","age":30}]'
df.toJson(2);
// '[
// { "name": "Alice", "age": 25 },
// { "name": "Bob", "age": 30 }
// ]'
Inherited from¶
toCsv()¶
toCsv(
separator?):string
Serializes the BareFrame to a CSV string.
Parameters¶
separator?¶
string = ","
Column delimiter (default: ",")
Returns¶
string
CSV string representation of the DataFrame
Remarks¶
The first row is the header line using this.headers.
Each subsequent row contains cell values joined by separator.
Values that contain the separator, double-quotes, or newlines
are wrapped in double-quotes and internal double-quotes are escaped as "".
Example¶
const df = BareFrame.fromColumns({ name: ["Alice", "Bob"], age: [25, 30] });
df.toCsv();
// 'name,age\nAlice,25\nBob,30'
df.toCsv("\t");
// 'name\tage\nAlice\t25\nBob\t30'
Inherited from¶
FlameFrame¶
from()¶
staticfrom\<T>(df,schema,options?):FlameFrameResult\<T>
Creates a FlameFrame from an existing BareFrame.
This is the only factory method.
Validates each row against the schema and returns only rows that passed.
Invalid rows are recorded in errors with their original row index from df.
Type Parameters¶
T¶
T extends Record\<string, Cell>
Parameters¶
df¶
Source BareFrame
schema¶
FlameRecord\<T>
Validation schema mapping column names to Flame guards
options?¶
FlameFrameOptions = {}
Validation options (strict)
Returns¶
FlameFrameResult\<T>
{ passed, failed } — valid-rows-only frame and invalid rows with error details
Throws¶
TypeError if df is not a BareFrame (e.g. a GAS Sheet or Range was passed by mistake)
Example¶
const df = BareFrame.fromSheet(sheet);
const { passed, failed } = FlameFrame.from(df, {
name: FlameGuards.isString,
age: FlameGuards.isNumber,
});
if (failed.length > 0) {
Logger.log(failed.toString());
}
passed.toSheet(outputSheet); // writes valid rows only
schema¶
Get Signature¶
get schema():
FlameRecord\<T>
Returns the validation schema associated with this frame.
Only available on passed frames returned from FlameFrame.from().
The failed frame is a BareFrame and has no schema.
Example¶
const { passed, failed } = FlameFrame.from(df, schema);
const s = passed.schema;
s["name"](42); // false — runs the guard
Returns¶
FlameRecord\<T>
toDataFrame()¶
toDataFrame():
BareFrame
Returns the underlying BareFrame without schema information.
Since FlameFrame extends BareFrame, you can use any BareFrame method directly.
This method is kept for backward compatibility but is no longer necessary.
Returns¶
A BareFrame containing the same rows
Example¶
const { passed, failed } = FlameFrame.from(df, schema);
// Instead of: const plainDf = passed.toDataFrame();
// Just use passed directly as a BareFrame
passed.toSheet(sheet);
Deprecated¶
since 0.65.0 — FlameFrame extends BareFrame, so you can use all BareFrame methods directly. Call other methods instead of converting to a plain BareFrame.
Other¶
MESSAGE_COLUMN¶
readonlystaticMESSAGE_COLUMN:"invalid_message"="invalid_message"
Column name used for validation error messages.