gloomberb 0.11.2 → 0.12.0

package/src/plugins/builtin/econ-statistics/stats.ts

@@ -0,0 +1,522 @@
+import { formatNumber } from "../../../utils/format";
+import type { StatDef } from "./defs";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAILY = 6 * DAY_MS;
+const WEEKLY = 21 * DAY_MS;
+const MONTHLY = 75 * DAY_MS;
+const QUARTERLY = 200 * DAY_MS;
+
+const pct = (value: number) => `${formatNumber(value, 1)}%`;
+const pct2 = (value: number) => `${formatNumber(value, 2)}%`;
+const plain = (value: number) => formatNumber(value, 1);
+/** FRED reports payrolls and claims in thousands already. */
+const thousands = (value: number) => `${formatNumber(value / 1000, value >= 10_000 ? 1 : 2)}M`;
+const signedThousands = (value: number) =>
+  `${value > 0 ? "+" : ""}${formatNumber(value, 0)}k`;
+const billions = (value: number) => `${formatNumber(value, 0)}B`;
+
+function stat(def: StatDef): StatDef {
+  return def;
+}
+
+export const STATS: readonly StatDef[] = [
+  // ---- Inflation -------------------------------------------------------
+  stat({
+    id: "cpi-yoy",
+    label: "CPI",
+    shortLabel: "CPI y/y",
+    category: "inflation",
+    seriesId: "CPIAUCSL",
+    transform: "yoy",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 2, label: "2%" },
+    staleAfterMs: MONTHLY,
+    note: "Headline consumer prices against a year earlier, including food and energy.",
+    limit: 900,
+  }),
+  stat({
+    id: "core-cpi-yoy",
+    label: "Core CPI",
+    shortLabel: "Core CPI y/y",
+    category: "inflation",
+    seriesId: "CPILFESL",
+    transform: "yoy",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 2, label: "2%" },
+    staleAfterMs: MONTHLY,
+    note: "Consumer prices excluding food and energy, the slower-moving trend.",
+    limit: 900,
+  }),
+  stat({
+    id: "pce-yoy",
+    label: "PCE Prices",
+    shortLabel: "PCE y/y",
+    category: "inflation",
+    seriesId: "PCEPI",
+    transform: "yoy",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 2, label: "2%" },
+    staleAfterMs: MONTHLY,
+    note: "The price index for personal consumption, broader in scope than CPI.",
+    limit: 900,
+  }),
+  stat({
+    id: "core-pce-yoy",
+    label: "Core PCE Prices",
+    shortLabel: "Core PCE y/y",
+    category: "inflation",
+    seriesId: "PCEPILFE",
+    transform: "yoy",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 2, label: "Fed target" },
+    staleAfterMs: MONTHLY,
+    note: "The measure the Federal Reserve actually targets at two percent.",
+    limit: 900,
+  }),
+  stat({
+    id: "ppi-yoy",
+    label: "Producer Prices",
+    shortLabel: "PPI y/y",
+    category: "inflation",
+    seriesId: "PPIACO",
+    transform: "yoy",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "What producers receive, which tends to lead consumer prices.",
+    limit: 900,
+  }),
+
+  // ---- Labor -----------------------------------------------------------
+  stat({
+    id: "unemployment",
+    label: "Unemployment Rate",
+    shortLabel: "Unemployment",
+    category: "labor",
+    seriesId: "UNRATE",
+    transform: "level",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Share of the labour force without work and looking for it.",
+    limit: 900,
+  }),
+  stat({
+    id: "payrolls",
+    label: "Nonfarm Payrolls",
+    shortLabel: "Payrolls m/m",
+    category: "labor",
+    seriesId: "PAYEMS",
+    transform: "change",
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: signedThousands,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "Jobs added or lost last month, the single most watched release.",
+    limit: 900,
+  }),
+  stat({
+    id: "initial-claims",
+    label: "Initial Jobless Claims",
+    shortLabel: "Claims",
+    category: "labor",
+    seriesId: "ICSA",
+    transform: "level",
+    direction: "higher-is-bad",
+    axisUnit: "",
+    formatValue: (value) => `${formatNumber(value / 1000, 0)}k`,
+    reference: null,
+    staleAfterMs: WEEKLY,
+    note: "Weekly filings for unemployment benefits, the fastest labour signal.",
+    limit: 2000,
+  }),
+  stat({
+    id: "job-openings",
+    label: "Job Openings",
+    shortLabel: "Openings",
+    category: "labor",
+    seriesId: "JTSJOL",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: thousands,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Unfilled positions employers report, a read on labour demand.",
+    limit: 400,
+  }),
+
+  // ---- Growth ----------------------------------------------------------
+  stat({
+    id: "real-gdp",
+    label: "Real GDP",
+    shortLabel: "Real GDP q/q",
+    category: "growth",
+    seriesId: "GDPC1",
+    transform: "qoq-annualized",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: QUARTERLY,
+    note: "Inflation-adjusted output, stated at the annual rate the quarter implies.",
+    limit: 400,
+  }),
+  stat({
+    id: "industrial-production",
+    label: "Industrial Production",
+    shortLabel: "Ind. prod.",
+    category: "growth",
+    seriesId: "INDPRO",
+    transform: "yoy",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "Output of factories, mines and utilities against a year earlier.",
+    limit: 900,
+  }),
+  stat({
+    id: "capacity-utilization",
+    label: "Capacity Utilization",
+    shortLabel: "Capacity use",
+    category: "growth",
+    seriesId: "TCU",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "How much of industry's capacity is in use, a slack and inflation gauge.",
+    limit: 900,
+  }),
+  stat({
+    id: "durable-goods",
+    label: "Durable Goods Orders",
+    shortLabel: "Durables m/m",
+    category: "growth",
+    seriesId: "DGORDER",
+    transform: "mom",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "New orders for goods meant to last, a forward read on investment.",
+    limit: 500,
+  }),
+  stat({
+    id: "factory-orders",
+    label: "Factory Orders",
+    shortLabel: "Factory m/m",
+    category: "growth",
+    seriesId: "AMTMNO",
+    transform: "mom",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "New orders across manufacturing, durable and not.",
+    limit: 500,
+  }),
+
+  // ---- Consumer --------------------------------------------------------
+  stat({
+    id: "retail-sales",
+    label: "Retail Sales",
+    shortLabel: "Retail y/y",
+    category: "consumer",
+    seriesId: "RSAFS",
+    transform: "yoy",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "What households actually spent at retailers, not adjusted for prices.",
+    limit: 500,
+  }),
+  stat({
+    id: "core-retail-sales",
+    label: "Core Retail Sales",
+    shortLabel: "Core retail",
+    category: "consumer",
+    seriesId: "RSFSXMV",
+    transform: "yoy",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Retail sales excluding motor vehicles, which swing the headline around.",
+    limit: 500,
+  }),
+  stat({
+    id: "consumer-sentiment",
+    label: "Consumer Sentiment",
+    shortLabel: "Sentiment",
+    category: "consumer",
+    seriesId: "UMCSENT",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: plain,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Michigan's survey of how households feel about their finances.",
+    limit: 900,
+  }),
+  stat({
+    id: "personal-income",
+    label: "Personal Income",
+    shortLabel: "Income m/m",
+    category: "consumer",
+    seriesId: "PI",
+    transform: "mom",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "What households received before tax, month on month.",
+    limit: 900,
+  }),
+  stat({
+    id: "personal-spending",
+    label: "Personal Spending",
+    shortLabel: "Spending m/m",
+    category: "consumer",
+    seriesId: "PCE",
+    transform: "mom",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "What households spent, the largest single component of GDP.",
+    limit: 900,
+  }),
+
+  // ---- Housing ---------------------------------------------------------
+  stat({
+    id: "housing-starts",
+    label: "Housing Starts",
+    shortLabel: "Starts",
+    category: "housing",
+    seriesId: "HOUST",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: thousands,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Homes broken ground on, at an annual rate.",
+    limit: 900,
+  }),
+  stat({
+    id: "building-permits",
+    label: "Building Permits",
+    shortLabel: "Permits",
+    category: "housing",
+    seriesId: "PERMIT",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: thousands,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Permits issued, which lead starts by a month or two.",
+    limit: 900,
+  }),
+  stat({
+    id: "new-home-sales",
+    label: "New Home Sales",
+    shortLabel: "New homes",
+    category: "housing",
+    seriesId: "HSN1F",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: thousands,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "Newly built homes sold, at an annual rate.",
+    limit: 900,
+  }),
+  // ---- Rates & money ---------------------------------------------------
+  stat({
+    id: "fed-funds",
+    label: "Federal Funds Rate",
+    shortLabel: "Fed funds",
+    category: "rates",
+    seriesId: "FEDFUNDS",
+    transform: "level",
+    direction: "neutral",
+    axisUnit: "%",
+    formatValue: pct2,
+    reference: null,
+    staleAfterMs: MONTHLY,
+    note: "The policy rate the Federal Reserve sets.",
+    limit: 900,
+  }),
+  stat({
+    id: "ten-year",
+    label: "10-Year Treasury",
+    shortLabel: "10Y yield",
+    category: "rates",
+    seriesId: "DGS10",
+    transform: "level",
+    direction: "neutral",
+    axisUnit: "%",
+    formatValue: pct2,
+    reference: null,
+    staleAfterMs: DAILY,
+    note: "The benchmark long rate that discounts almost everything else.",
+    limit: 3000,
+  }),
+  stat({
+    id: "two-year",
+    label: "2-Year Treasury",
+    shortLabel: "2Y yield",
+    category: "rates",
+    seriesId: "DGS2",
+    transform: "level",
+    direction: "neutral",
+    axisUnit: "%",
+    formatValue: pct2,
+    reference: null,
+    staleAfterMs: DAILY,
+    note: "The short end, which tracks where policy is expected to go.",
+    limit: 3000,
+  }),
+  stat({
+    id: "curve-spread",
+    label: "10Y minus 2Y Spread",
+    shortLabel: "2s10s",
+    category: "rates",
+    seriesId: "T10Y2Y",
+    transform: "level",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct2,
+    reference: { value: 0, label: "inversion" },
+    staleAfterMs: DAILY,
+    note: "The curve spread. Below zero it has preceded every modern recession.",
+    limit: 3000,
+  }),
+  stat({
+    id: "real-ten-year",
+    label: "10-Year Real Yield",
+    shortLabel: "10Y real",
+    category: "rates",
+    seriesId: "DFII10",
+    transform: "level",
+    direction: "neutral",
+    axisUnit: "%",
+    formatValue: pct2,
+    reference: { value: 0, label: "zero" },
+    staleAfterMs: DAILY,
+    note: "The inflation-protected long rate, the real cost of money.",
+    limit: 3000,
+  }),
+  stat({
+    id: "m2-yoy",
+    label: "M2 Money Stock",
+    shortLabel: "M2 y/y",
+    category: "rates",
+    seriesId: "M2SL",
+    transform: "yoy",
+    direction: "neutral",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: MONTHLY,
+    note: "Money supply growth, which contracted outright for the first time in 2022.",
+    limit: 900,
+  }),
+
+  // ---- Trade & costs ---------------------------------------------------
+  stat({
+    id: "trade-balance",
+    label: "Trade Balance",
+    shortLabel: "Trade balance",
+    category: "trade",
+    seriesId: "BOPGSTB",
+    transform: "level",
+    scale: 0.001,
+    direction: "higher-is-good",
+    axisUnit: "",
+    formatValue: billions,
+    reference: { value: 0, label: "balanced" },
+    staleAfterMs: MONTHLY,
+    note: "Goods and services exported less imported, persistently negative.",
+    limit: 500,
+  }),
+  stat({
+    id: "productivity",
+    label: "Nonfarm Productivity",
+    shortLabel: "Productivity",
+    category: "trade",
+    seriesId: "OPHNFB",
+    transform: "qoq-annualized",
+    direction: "higher-is-good",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: QUARTERLY,
+    note: "Output per hour worked. It is what lets pay rise without inflation.",
+    limit: 400,
+  }),
+  stat({
+    id: "unit-labor-costs",
+    label: "Unit Labor Costs",
+    shortLabel: "Labor costs",
+    category: "trade",
+    seriesId: "ULCNFB",
+    transform: "qoq-annualized",
+    direction: "higher-is-bad",
+    axisUnit: "%",
+    formatValue: pct,
+    reference: { value: 0, label: "flat" },
+    staleAfterMs: QUARTERLY,
+    note: "What a unit of output costs in labour, pay growth net of productivity.",
+    limit: 400,
+  }),
+];
+
+export function findStat(id: string | null | undefined): StatDef {
+  const normalized = id?.trim().toLowerCase();
+  return STATS.find((entry) => entry.id === normalized) ?? STATS[0]!;
+}
+
+export const DEFAULT_STAT_ID = STATS[0]!.id;
+
+/** Resolves shortcut arguments like `ECST cpi` onto a statistic. */
+export function resolveStatArg(arg: string | null | undefined): StatDef | null {
+  const query = arg?.trim().toLowerCase();
+  if (!query) return null;
+  return STATS.find((entry) => entry.id === query)
+    ?? STATS.find((entry) => entry.seriesId.toLowerCase() === query)
+    ?? STATS.find((entry) =>
+      entry.id.startsWith(query)
+      || entry.label.toLowerCase().startsWith(query)
+      || entry.shortLabel.toLowerCase().startsWith(query))
+    ?? null;
+}

package/src/plugins/builtin/econ-statistics/transform.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { applyTransform, periodsPerYear } from "./transform";
+
+function monthly(values: number[], startYear = 2020): Array<{ date: string; value: number }> {
+  return values.map((value, index) => {
+    const month = (index % 12) + 1;
+    const year = startYear + Math.floor(index / 12);
+    return { date: `${year}-${String(month).padStart(2, "0")}-01`, value };
+  });
+}
+
+describe("periodsPerYear", () => {
+  test("reads cadence off the gaps rather than being told", () => {
+    expect(periodsPerYear(monthly([1, 2, 3, 4, 5]))).toBe(12);
+    expect(periodsPerYear([
+      { date: "2024-01-01", value: 1 },
+      { date: "2024-04-01", value: 2 },
+      { date: "2024-07-01", value: 3 },
+      { date: "2024-10-01", value: 4 },
+    ])).toBe(4);
+    expect(periodsPerYear([
+      { date: "2024-01-06", value: 1 },
+      { date: "2024-01-13", value: 2 },
+      { date: "2024-01-20", value: 3 },
+      { date: "2024-01-27", value: 4 },
+    ])).toBe(52);
+  });
+});
+
+describe("applyTransform", () => {
+  test("year over year looks back a whole cadence, not one print", () => {
+    // 13 monthly points where the index rises 10% across the year.
+    const points = monthly([100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 110]);
+    const yoy = applyTransform(points, "yoy");
+    expect(yoy).toHaveLength(1);
+    expect(yoy[0]!.date).toBe("2021-01-01");
+    expect(yoy[0]!.value).toBeCloseTo(10, 6);
+  });
+
+  test("month over month uses the previous print", () => {
+    const mom = applyTransform(monthly([100, 101]), "mom");
+    expect(mom).toHaveLength(1);
+    expect(mom[0]!.value).toBeCloseTo(1, 6);
+  });
+
+  test("a quarterly move is stated at the annual rate it implies", () => {
+    // Cadence is inferred from the gaps, so it takes a few prints to see quarterly.
+    const quarterly = [
+      { date: "2024-01-01", value: 100 },
+      { date: "2024-04-01", value: 100 },
+      { date: "2024-07-01", value: 100 },
+      { date: "2024-10-01", value: 101 },
+    ];
+    // 1% in a quarter compounds to about 4.06% a year, not 4%.
+    const value = applyTransform(quarterly, "qoq-annualized").at(-1)!.value;
+    expect(value).toBeCloseTo((Math.pow(1.01, 4) - 1) * 100, 6);
+    expect(value).toBeGreaterThan(4);
+  });
+
+  test("too few prints to infer cadence falls back to monthly", () => {
+    // Two points cannot show a gap pattern, so a year-over-year lag is unknowable.
+    expect(applyTransform([
+      { date: "2024-01-01", value: 100 },
+      { date: "2024-04-01", value: 101 },
+    ], "yoy")).toHaveLength(0);
+  });
+
+  test("change is a difference, so it keeps the series' own units", () => {
+    const change = applyTransform(monthly([150_000, 150_120]), "change");
+    expect(change[0]!.value).toBeCloseTo(120, 6);
+  });
+
+  test("levels pass through and gaps are dropped, not interpolated", () => {
+    const level = applyTransform([
+      { date: "2024-03-01", value: 2 },
+      { date: "2024-01-01", value: null },
+      { date: "2024-02-01", value: 1 },
+    ], "level");
+    // Sorted ascending, with the null month absent rather than filled in.
+    expect(level.map((point) => point.date)).toEqual(["2024-02-01", "2024-03-01"]);
+  });
+
+  test("a zero base cannot produce a percent change", () => {
+    expect(applyTransform(monthly([0, 5]), "mom")).toHaveLength(0);
+  });
+});

package/src/plugins/builtin/econ-statistics/transform.ts

@@ -0,0 +1,85 @@
+import type { DatedObservation } from "../shared/series-cache";
+
+/**
+ * How a raw FRED series becomes the number people quote. An index level like CPI
+ * is meaningless on its own; the year-over-year change is the statistic.
+ */
+export type StatTransform =
+  | "level"
+  | "yoy"
+  | "mom"
+  | "qoq-annualized"
+  | "change";
+
+export interface StatPoint {
+  date: string;
+  value: number;
+}
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Infers cadence from the median gap between prints, so a transform does not have
+ * to be told whether a series is daily, weekly, monthly or quarterly.
+ */
+export function periodsPerYear(observations: readonly DatedObservation[]): number {
+  const dates = observations
+    .filter((entry) => entry.value != null)
+    .map((entry) => Date.parse(entry.date))
+    .filter((value) => Number.isFinite(value));
+  if (dates.length < 3) return 12;
+
+  const gaps: number[] = [];
+  for (let i = 1; i < dates.length; i += 1) {
+    const gap = (dates[i]! - dates[i - 1]!) / MS_PER_DAY;
+    if (gap > 0) gaps.push(gap);
+  }
+  if (gaps.length === 0) return 12;
+  gaps.sort((a, b) => a - b);
+  const median = gaps[Math.floor(gaps.length / 2)]!;
+
+  if (median <= 4) return 252;
+  if (median <= 10) return 52;
+  if (median <= 45) return 12;
+  if (median <= 135) return 4;
+  return 1;
+}
+
+/** Applies a transform, dropping the leading points it cannot look back from. */
+export function applyTransform(
+  observations: readonly DatedObservation[],
+  transform: StatTransform,
+): StatPoint[] {
+  const clean = observations
+    .filter((entry): entry is { date: string; value: number } =>
+      entry.value != null && Number.isFinite(entry.value))
+    .slice()
+    .sort((a, b) => a.date.localeCompare(b.date));
+  if (clean.length === 0) return [];
+
+  if (transform === "level") {
+    return clean.map((entry) => ({ date: entry.date, value: entry.value }));
+  }
+
+  const perYear = periodsPerYear(clean);
+  const lag = transform === "yoy" ? perYear : 1;
+  const out: StatPoint[] = [];
+  for (let i = lag; i < clean.length; i += 1) {
+    const now = clean[i]!;
+    const before = clean[i - lag]!;
+    if (transform === "change") {
+      out.push({ date: now.date, value: now.value - before.value });
+      continue;
+    }
+    if (before.value === 0) continue;
+    const ratio = now.value / before.value;
+    if (transform === "qoq-annualized") {
+      // A quarterly move stated as the annual rate it implies, as the BEA reports it.
+      if (ratio <= 0) continue;
+      out.push({ date: now.date, value: (Math.pow(ratio, perYear) - 1) * 100 });
+      continue;
+    }
+    out.push({ date: now.date, value: (ratio - 1) * 100 });
+  }
+  return out;
+}