Iteration 201: add combineFirstSeries and isNamedAggSpec benchmarks

Run: https://github.com/githubnext/tsessebe/actions/runs/24612917385

Add 2 new benchmark pairs (benchmarked_functions: 534 → 536):
- bench_combine_first_series_fn: standalone combineFirstSeries fn (Series/fill-missing)
- bench_is_named_agg_spec: isNamedAggSpec type-guard for NamedAgg spec dicts

Author: github-actions[bot]

benchmarks/pandas/bench_combine_first_series_fn.py

@@ -0,0 +1,41 @@
+"""
+Benchmark: Series.combine_first() — fill NaN values from another Series (union of indexes).
+Mirrors tsb bench_combine_first_series_fn.ts (standalone combineFirstSeries fn).
+Outputs JSON: {"function": "combine_first_series_fn", "mean_ms": ..., "iterations": ..., "total_ms": ...}
+"""
+import json
+import time
+import numpy as np
+import pandas as pd
+
+SIZE = 100_000
+WARMUP = 5
+ITERATIONS = 30
+
+rng = np.random.default_rng(42)
+raw = rng.uniform(0, 10, SIZE)
+mask = rng.integers(0, 4, SIZE) == 0  # ~25% nulls
+d1 = pd.array(raw, dtype="Float64")
+for idx in range(SIZE):
+    if mask[idx]:
+        d1[idx] = pd.NA
+
+s1 = pd.Series(d1, dtype="Float64")
+s2 = pd.Series(rng.uniform(0, 10, SIZE))
+
+for _ in range(WARMUP):
+    s1.combine_first(s2)
+
+times = []
+for _ in range(ITERATIONS):
+    t0 = time.perf_counter()
+    s1.combine_first(s2)
+    times.append((time.perf_counter() - t0) * 1000)
+
+total_ms = sum(times)
+print(json.dumps({
+    "function": "combine_first_series_fn",
+    "mean_ms": round(total_ms / ITERATIONS, 3),
+    "iterations": ITERATIONS,
+    "total_ms": round(total_ms, 3),
+}))

benchmarks/pandas/bench_is_named_agg_spec.py

@@ -0,0 +1,46 @@
+"""
+Benchmark: is_named_agg_spec equivalent — check whether all values in a dict
+are of a given type (mirrors tsb's isNamedAggSpec guard).
+In pandas the equivalent is isinstance-checking NamedAgg namedtuples.
+Outputs JSON: {"function": "is_named_agg_spec", "mean_ms": ..., "iterations": ..., "total_ms": ...}
+"""
+import json
+import time
+from collections import namedtuple
+
+WARMUP = 5
+ITERATIONS = 100
+
+NamedAgg = namedtuple("NamedAgg", ["column", "aggfunc"])
+
+
+def is_named_agg_spec(spec: dict) -> bool:
+    """Return True if every value is a NamedAgg instance."""
+    return all(isinstance(v, NamedAgg) for v in spec.values())
+
+
+# A valid spec — all NamedAgg instances (200 entries).
+valid_spec = {f"col_{i}": NamedAgg(f"src_{i % 10}", "sum") for i in range(200)}
+
+# An invalid spec — plain string values.
+invalid_spec = {f"col_{i}": "sum" for i in range(200)}
+
+for _ in range(WARMUP):
+    is_named_agg_spec(valid_spec)
+    is_named_agg_spec(invalid_spec)
+
+times = []
+for _ in range(ITERATIONS):
+    t0 = time.perf_counter()
+    for _ in range(500):
+        is_named_agg_spec(valid_spec)
+        is_named_agg_spec(invalid_spec)
+    times.append((time.perf_counter() - t0) * 1000)
+
+total_ms = sum(times)
+print(json.dumps({
+    "function": "is_named_agg_spec",
+    "mean_ms": round(total_ms / ITERATIONS, 3),
+    "iterations": ITERATIONS,
+    "total_ms": round(total_ms, 3),
+}))

benchmarks/tsb/bench_combine_first_series_fn.ts

@@ -0,0 +1,46 @@
+/**
+ * Benchmark: combineFirstSeries (standalone fn) — fill NaN values from another Series (union of indexes).
+ * Uses the exported `combineFirstSeries` function rather than the `Series.combineFirst()` method.
+ * Mirrors bench_combine_first.ts but exercises the standalone export.
+ * Outputs JSON: {"function": "combine_first_series_fn", "mean_ms": ..., "iterations": ..., "total_ms": ...}
+ */
+import { Series, combineFirstSeries } from "../../src/index.ts";
+
+const SIZE = 100_000;
+const WARMUP = 5;
+const ITERATIONS = 30;
+
+const rng = (seed: number) => {
+  let s = seed;
+  return () => {
+    s = (s * 1664525 + 1013904223) & 0xffffffff;
+    return ((s >>> 0) / 0xffffffff) * 10;
+  };
+};
+const rand = rng(42);
+
+const d1: (number | null)[] = Array.from({ length: SIZE }, (_, i) => (i % 4 === 0 ? null : rand()));
+const d2 = Array.from({ length: SIZE }, () => rand());
+const s1 = new Series(d1);
+const s2 = new Series(d2);
+
+for (let i = 0; i < WARMUP; i++) {
+  combineFirstSeries(s1, s2);
+}
+
+const times: number[] = [];
+for (let i = 0; i < ITERATIONS; i++) {
+  const t0 = performance.now();
+  combineFirstSeries(s1, s2);
+  times.push(performance.now() - t0);
+}
+
+const total = times.reduce((a, b) => a + b, 0);
+console.log(
+  JSON.stringify({
+    function: "combine_first_series_fn",
+    mean_ms: Math.round((total / ITERATIONS) * 1000) / 1000,
+    iterations: ITERATIONS,
+    total_ms: Math.round(total * 1000) / 1000,
+  }),
+);

benchmarks/tsb/bench_is_named_agg_spec.ts

@@ -0,0 +1,48 @@
+/**
+ * Benchmark: isNamedAggSpec — type-guard that checks whether a spec object
+ * consists entirely of NamedAgg instances.  Used by DataFrameGroupBy.agg()
+ * to distinguish NamedAggSpec from plain AggSpec dicts.
+ * Outputs JSON: {"function": "is_named_agg_spec", "mean_ms": ..., "iterations": ..., "total_ms": ...}
+ */
+import { isNamedAggSpec, namedAgg } from "../../src/index.ts";
+
+const WARMUP = 5;
+const ITERATIONS = 100;
+
+// A large spec dict that IS a NamedAggSpec — all values are NamedAgg instances.
+const validSpec = Object.fromEntries(
+  Array.from({ length: 200 }, (_, i) => [
+    `col_${i}`,
+    namedAgg(`src_${i % 10}`, "sum"),
+  ]),
+);
+
+// A dict that is NOT a NamedAggSpec — plain string values.
+const invalidSpec: Record<string, string> = Object.fromEntries(
+  Array.from({ length: 200 }, (_, i) => [`col_${i}`, "sum"]),
+);
+
+for (let i = 0; i < WARMUP; i++) {
+  isNamedAggSpec(validSpec);
+  isNamedAggSpec(invalidSpec);
+}
+
+const times: number[] = [];
+for (let i = 0; i < ITERATIONS; i++) {
+  const t0 = performance.now();
+  for (let j = 0; j < 500; j++) {
+    isNamedAggSpec(validSpec);
+    isNamedAggSpec(invalidSpec);
+  }
+  times.push(performance.now() - t0);
+}
+
+const total = times.reduce((a, b) => a + b, 0);
+console.log(
+  JSON.stringify({
+    function: "is_named_agg_spec",
+    mean_ms: Math.round((total / ITERATIONS) * 1000) / 1000,
+    iterations: ITERATIONS,
+    total_ms: Math.round(total * 1000) / 1000,
+  }),
+);