Skip to content

v0.56.0 - Add ForgeFrame for histogram analysis (2026-03-28)

What Changed?

This release introduces ForgeFrame, a statistical analysis wrapper around BareFrame that provides histogram methods (h1, h2) inspired by CERN ROOT's TH1/TH2 interface. Non-numeric cells are silently excluded from all bin counts, making it safe to use with mixed-type spreadsheet data.

What's New

Main Feature: ForgeFrame histogram methods

What it does: ForgeFrame wraps a BareFrame and generates frequency histograms with equal-width bins over a user-defined axis range. Bin intervals follow ROOT convention ([low, high)). Underflow and overflow bins are always present in the output, even when their count is zero.

How to use it: Create a ForgeFrame via ForgeFrame.from(df), then call .h1() for a 1-D histogram or .h2() for a 2-D histogram.

Code example:

TypeScript
const df = BareFrame.fromColumns({
  score: [45, 60, 72, 85, 91, 88],
  bonus: [3,  8,  6,  12,  9,  7],
});

// 1-D histogram
ForgeFrame.from(df).h1("score", { nbins: 5, xlow: 50, xup: 100 });
// bin       | count | relative | cumulative_relative
// underflow | 1     | 0.1667   | 0.1667
// [50, 60)  | 1     | 0.1667   | 0.3333
// [60, 70)  | 1     | 0.1667   | 0.5000
// [70, 80)  | 1     | 0.1667   | 0.6667
// [80, 90)  | 2     | 0.3333   | 1.0000
// [90, 100) | 0     | 0.0000   | 1.0000
// overflow  | 0     | 0.0000   | 1.0000

// 2-D histogram
ForgeFrame.from(df).h2("score", "bonus", {
  xnbins: 2, xlow: 50, xup: 100,
  ynbins: 2, ylow: 0,  yup: 15,
});
// xbin      | ybin      | count
// [50, 75)  | [0, 7.5)  | 1
// [50, 75)  | [7.5, 15) | 1
// [75, 100) | [7.5, 15) | 2
// ... (underflow/overflow rows included)

Added

  • ForgeFrame class — statistical analysis wrapper for BareFrame
  • ForgeFrame.from(df, options?) — factory method; accepts optional precision for rounding
  • ForgeFrame.h1(header, options) — 1-D histogram returning bin, count, relative, cumulative_relative
  • ForgeFrame.h2(xHeader, yHeader, options) — 2-D histogram returning xbin, ybin, count
  • ForgeFrameOptions, H1Options, H2Options — exported option types
  • Full TypeDoc docstrings with @param, @returns, @throws, and @example blocks

Changed

  • Nothing

Fixed

  • Nothing

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

ForgeFrame is an entirely new class. No existing APIs were modified.

Release Details

  • Date: 2026-03-28
  • Version: v0.56.0
  • gaslamp: 115
  • pilotlamp: 73
  • Files Changed: 7
  • Commits:
  • bf24e443 feat(torch): add ForgeFrame for statistical histogram analysis
  • 33f15841 feat(torch): implement h2 2-D histogram method in ForgeFrame
  • feae4e42 docs(torch): update docstrings for ForgeFrame types and methods

Known Issues

  • ForgeFrame is not yet exported from src/torch/index.ts
  • No tests added yet for h1 or h2

Next Steps

  • Export ForgeFrame from src/torch/index.ts
  • Add tests for h1 and h2 (boundary values, non-numeric cells, error cases)