SharedArrayBuffer requires Node.js 16.4+ with cross-origin isolation headers if used in a browser context. In Node.js (server-side), no extra configuration is needed.

Detects file format by extension and routes to the appropriate engine. .csv uses the Nitro engine (SharedArrayBuffer + Workers). .json uses the JSON engine with auto flattening.

const df = await Octopus.read('data.csv')
const df = await Octopus.read('data.json')
const df = await Octopus.read('data.csv', { workers: 4 })

Automatically detects the root array (e.g. "prizes" in Nobel dataset). Recursively flattens nested objects into columns. Expands nested arrays into multiple rows, inheriting parent fields.

// Input: { prizes: [{ year: "2023", laureates: [{id,name}] }] }
const df = await Octopus.read('nobel.json')
// Each laureate becomes its own row, with year inherited
// Columns: year, laureates_id, laureates_firstname, ...

Creates a new DataFrame. You typically get DataFrames from Octopus.read(), but you can construct one manually.

Converts a plain JS array of objects into a DataFrame. Numeric values are stored as Float64Array automatically.

const df = DataFrame.fromObjects([
  { name: 'Alice', score: 95 },
  { name: 'Bob',   score: 82 },
])

Prints the first n rows as a console.table. String values longer than 20 characters are truncated with ....

Returns a summary with row count, column count, column names, and estimated memory usage.

const info = df.info()
// { rowCount: 7832546, columnCount: 19, columns: [...], memoryUsage: '1139.45 MB' }

Prints descriptive statistics for all numeric columns: count, mean, min, 25%, 50%, 75%, max. Non-numeric columns are skipped.

Vectorized feature engineering. Applies formulas row-by-row using direct TypedArray access. Optimized fast paths for 1, 2, and 4 inputs. Returns this for chaining.

df.with_columns([
  { name: 'revenue_per_mile', inputs: ['total_amount', 'trip_distance'], formula: (amount, dist) => dist > 0 ? amount / dist : 0 },
  { name: 'speed_mph', inputs: ['trip_distance', 'duration_hours'], formula: (dist, dur) => dur > 0 ? dist / dur : 0 }
])

Returns a new DataFrame with only the specified columns. Essential for freeing RAM — drop unused columns as early as possible.

const slim = df.select(['fare_amount', 'tip_amount', 'trip_distance'])

Renames columns without copying data. Returns a new DataFrame with updated headers.

const df2 = df.rename({ tpep_pickup_datetime: 'pickup', PULocationID: 'zone' })

Forces a type conversion on a column. 'float' and 'int' both produce Float64Array. 'string' produces a regular JS Array. Mutates in-place.

Computes a running cumulative sum over a column. Creates a new column named {columnName}_cumsum. Mutates in-place.

Applies a StringIndexer to encode a string column as numeric IDs. Creates a new column named {input}_indexed and stores the indexer in metadata.indexers for later decoding.

Returns a new DataFrame containing only rows where the predicate returns true. The predicate receives the values of the listed columns for each row.

const valid = df.filter(
  ['fare_amount', 'trip_distance', 'passenger_count'],
  (fare, dist, pax) => fare > 0 && dist > 0 && pax > 0
)

Returns a new DataFrame with the first n rows.

Returns a new DataFrame with the last n rows.

Removes all rows containing null, undefined, or NaN in any column.

Replaces all null, undefined, or NaN values in all columns with the specified value. Mutates in-place.

Filters rows where the string column matches the regex pattern. Case-insensitive.

const result = df.str_contains('product_name', 'wireless')

Groups rows by a column and applies aggregation functions. Supports sum, mean, count, max, min. Pass a string for a single op or an array for multiple — output columns will be named {col}_{op}.

const byHour = df.groupBy('hour', { tip_pct: 'mean', fare_amount: 'sum' })

const byZone = df.groupBy('zone_id', {
  fare_amount: ['sum', 'mean', 'count'],
  tip_amount:  ['sum', 'max']
})
// Columns: fare_amount_sum, fare_amount_mean, fare_amount_count, ...

O(n) groupBy for bounded integer keys. Uses Uint32Array as a direct lookup — no Map, no hashing, no allocations. Returns array of { group, avg } sorted descending.

Alias for groupByRange(colName, targetCol, 300). Preset for NYC Taxi zone IDs.

Index sort — builds an index array, sorts by target column values, then reorders all columns in one pass. Returns a new DataFrame.

const top10 = df.sort('revenue_per_mile', false).head(10)

df.sum('fare_amount')   // 48291043.21
df.mean('tip_pct')     // 14.82
df.max('trip_distance') // 189.4

Returns an array of unique values in a column using a Set.

Returns the count of unique values. Faster than unique().length.

Returns a frequency table sorted from most to least common.

const freq = df.value_counts('payment_type')
// [{ value: 1, count: 5821034 }, { value: 2, count: 1823456 }]

Hash join on a common column. inner returns only matching rows. left keeps all left rows, filling unmatched right columns with null.

const enriched = trips.join(zones, 'zone_id', 'left')

Exports the DataFrame to a CSV file via streaming write. Floats are written with 4 decimal places. Validates the .csv extension.

await df.toCSV('output/results.csv')

Exports to a JSON file. Validates .json extension.

Exports to a plain text file. Validates .txt extension.

Converts the DataFrame back to a plain JS array of row objects. Useful for interoperability.

Returns a Column instance linked to the underlying TypedArray. Enables chained arithmetic that mutates the column in-place.

df.col('tpep_pickup_datetime')
  .to_datetime()
  .extract_hour(0)
// Creates new column: tpep_pickup_datetime_hour

df.col('total_amount')
  .sub(df.col('tip_amount'))
  .div(1.08)

The internal columnar primitive. Each column inside a DataFrame is backed by a Series. Use Series.fromRawBuffer() to reconstruct from raw buffer data. The optional indexer enables transparent numeric-ID to string translation via .get(index).