gloomberb 0.19.1 → 0.19.3

package/src/time-series/resolve.ts

@@ -1,4 +1,5 @@
 import { logFailure } from "../utils/log-failure";
+import { servedFromSavedCopy } from "../data/saved-copies";
 import { hasValidQuoteObservationTime } from "../market-data/quotes/freshness";
 import { delistingLabel } from "../market-data/quotes/delisting";
 import { financialPeriodCoverage, financialPeriodCoverageWarnings, limitSeriesObservations } from "./financial-period-coverage";
@@ -42,7 +43,7 @@ import { FORWARD_PE_BASIS_NOTICE, REALIZED_NTM_PE_BASIS_NOTICE } from "./forward
 import { valuationPriceWarning } from "./valuation-price";
 import { VALUATION_CURRENCY_WARNING_PREFIX } from "./valuation-currency";
 import { chartPriceHistoryIntegrityNotices } from "./market";
-import { maxStudyWarmupPoints, resolveStudies } from "./studies";
+import { maxStudyWarmupPoints, resolveStudies } from "./studies/resolve";
 import { clipSeriesToWindow } from "./alignment";
 import { totalReturnSeries } from "./total-return";
 import {
@@ -54,6 +55,7 @@ import {
   totalReturnLevelsNotice,
 } from "./price-comparison";
 import { chartQuoteOverrideKeyForSource } from "./live-quotes";
+import { coinLegsAtSessionClose } from "./coin-session-close";
 import { chartSeriesSourceKey } from "../capabilities/chart-series";
 import { rememberSeedListingFacts } from "./parsed-history-cache";
 import {
@@ -827,7 +829,7 @@ async function resolveChartSpecPass(
           cache.capabilitySeriesByRequest.set(key, pending);
           cache.revision += 1;
         }
-        return baseCapabilitySeries(seriesSpec, await pending, index);
+        return asSavedCopy(baseCapabilitySeries(seriesSpec, await pending, index));
       }
       if (seriesSpec.source.kind === "economic") {
         const request: FredSeriesRequest = {
@@ -845,6 +847,8 @@ async function resolveChartSpecPass(
           priorityWarnings.push(`${result.label}: ${coverageNotice}`);
           coverageNotices.push(`${result.label}: ${coverageNotice}`);
         }
+        // A saved copy that answered for a failed refresh is dated in the footer, as every pane's is.
+        if (result && fred.source === "stale-fallback") return asSavedCopy({ ...result, savedAt: fred.fetchedAt });
         const freshnessWarning = staleFredWarning(fred);
         if (result && freshnessWarning) priorityWarnings.push(`${result.label}: ${freshnessWarning}`);
         return result;
@@ -1054,8 +1058,16 @@ async function resolveChartSpecPass(
   const commonCadence = servedCadences.size === 1 ? [...servedCadences][0] : undefined;
   const resolution = commonCadence ?? undefined;
   const comparisonResolution = resolution ?? "auto";
-  const priceComparison = resolvePriceComparison(spec, rawSeries, bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow,
-    { preset: hasExplicitWindow ? null : spec.viewport.range, now: referenceNow.getTime() + Math.max(0, Date.now() - resolutionStartedAt) });
+  const comparisonOptions = { preset: hasExplicitWindow ? null : spec.viewport.range, now: referenceNow.getTime() + Math.max(0, Date.now() - resolutionStartedAt) };
+  let priceComparison = resolvePriceComparison(spec, rawSeries, bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow, comparisonOptions);
+  // A coin compared in daily closes with a listing that closes each day is measured at that close when its hourly bars reach.
+  const timed = sources.dataProvider && comparisonResolution === "1d"
+    ? await coinLegsAtSessionClose(priceComparison, rawSeries, sources.dataProvider, comparisonOptions.now) : null;
+  if (timed?.timing.atSessionClose.size) {
+    rawSeries.splice(0, rawSeries.length, ...timed.series);
+    priceComparison = resolvePriceComparison(spec, rawSeries, bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow,
+      { ...comparisonOptions, atSessionClose: timed.timing.atSessionClose, closedEnds: timed.timing.closedEnds });
+  }
   const displayBounds = comparisonDisplayBounds(bounds, priceComparison);
   const comparisonBounds = priceComparison && priceComparison.start !== null
     ? priceComparison : bounds;
@@ -1180,6 +1192,7 @@ async function resolveChartSpecPass(
     loading: false,
     errors,
     warnings: [...new Set([...priorityWarnings, ...warnings])],
+    ...savedCopyOf(rawSeries.filter((entry) => visibleSeriesIds.has(entry.id))),
     ...(coverageNotices.length ? { coverageNotices: [...new Set(coverageNotices)] } : {}),
     ...(returnBasisNotice ? { returnBasisNotice } : {}),
     ...(delistings.size ? { delistings: [...delistings.values()] } : {}),
@@ -1188,3 +1201,18 @@ async function resolveChartSpecPass(
     ...(builtBarSize && rawSeries.some((entry) => entry.barSize === builtBarSize) ? { barSize: builtBarSize } : {}),
   };
 }
+
+/**
+ * A series drawn from a copy a failed refresh left answering (`savedAt`),
+ * marked as one, so a command charting it ends with "couldn't refresh; saved
+ * copy from …" as the app's footer says.
+ */
+function asSavedCopy(series: ResolvedSeries): ResolvedSeries {
+  return series.savedAt != null ? servedFromSavedCopy(series, series.savedAt) : series;
+}
+
+/** The oldest saved copy among `series` that answered for a failed refresh, which the chart's footer dates. */
+function savedCopyOf(series: readonly ResolvedSeries[]): { savedAt?: number } {
+  const saved = series.flatMap((entry) => entry.savedAt != null && Number.isFinite(entry.savedAt) ? [entry.savedAt] : []);
+  return saved.length ? { savedAt: Math.min(...saved) } : {};
+}

package/src/time-series/series-presentation.ts

@@ -2,7 +2,7 @@ import { limitSeriesObservations } from "./financial-period-coverage";
 import type { ManualChartResolution } from "./resolution";
 import { getTimeSeriesField } from "./field-catalog";
 import { collectPriceHistoryIntegrity } from "./market";
-import { activeStudyInputSeriesIds } from "./studies";
+import { activeStudyInputSeriesIds } from "./studies/resolve";
 import { applyResolvedSeriesTransform } from "./transforms";
 import { clipSeriesToWindow } from "./alignment";
 import type { StudyAnchor } from "./leverage";

package/src/time-series/studies/formula.ts

@@ -0,0 +1,205 @@
+import { alignTimeSeries } from "../alignment";
+import type { ChartStudySpec, ResolvedSeries, TimeSeriesPoint } from "../types";
+import { isFiniteNumber } from "../../utils/guards";
+import { GALLONS_PER_BARREL, isBarrelsPerTonne, perBarrelUnit, perTonneUnit } from "../price-units";
+import { derivedPoint, outputSeries } from "./shared";
+import {
+  combinedUnit,
+  derivedValueDecimals,
+  fxConversionIssue,
+  isPriceGroup,
+  knownUnitSignature,
+  legName,
+  unitMismatchMessage,
+  type SeriesUnit,
+} from "./units";
+
+interface FormulaLeg {
+  /** The input's place in the study's inputs. */
+  index: number;
+  /** Its multiplier, its sign included. */
+  weight: number;
+  /** The multiplier carries the 42 gallons that make a per-gallon price per barrel. */
+  perBarrel: boolean;
+  /** The barrels in a tonne the multiplier carries (7.45 for gasoil), making a per-barrel price per tonne. */
+  perTonne: number | null;
+}
+
+export interface FormulaTerms {
+  /** The inputs the formula adds up. */
+  legs: FormulaLeg[];
+  /** The inputs the whole sum is multiplied (1) or divided (-1) by: `/EURUSD=X`. */
+  factors: Array<{ index: number; power: 1 | -1 }>;
+  divisor: number;
+}
+
+/**
+ * A formula study's terms: `weight1`, `perBarrel1`, `perTonne1` ... per
+ * input it adds up, `power1` ... (1 or -1) per input it multiplies or divides
+ * the sum by, and an optional `divisor`. A saved or hand-edited spec can carry
+ * a multiplier or divisor no formula was written with (a value that is not a
+ * number is dropped when the spec loads, so it arrives missing); that is an
+ * error, not a silent 1.
+ */
+export function formulaTerms(spec: ChartStudySpec, inputs: readonly ResolvedSeries[]): FormulaTerms | { error: string } {
+  const legs: FormulaLeg[] = [];
+  const factors: FormulaTerms["factors"] = [];
+  for (const [index, input] of inputs.entries()) {
+    const power = spec.parameters[`power${index + 1}`];
+    if (power !== undefined) {
+      if (power !== 1 && power !== -1) return { error: `The formula neither multiplies nor divides by ${legName(input)}; write the formula again.` };
+      factors.push({ index, power });
+      continue;
+    }
+    const weight = spec.parameters[`weight${index + 1}`];
+    if (!isFiniteNumber(weight)) return { error: `The multiplier of ${legName(input)} is missing or not a number; write the formula again.` };
+    if (weight === 0) return { error: `${legName(input)} has a multiplier of 0, which removes it; leave it out of the formula instead.` };
+    const perTonne = spec.parameters[`perTonne${index + 1}`];
+    legs.push({
+      index,
+      weight,
+      perBarrel: spec.parameters[`perBarrel${index + 1}`] === 1,
+      perTonne: isFiniteNumber(perTonne) && isBarrelsPerTonne(perTonne) ? perTonne : null,
+    });
+  }
+  if (legs.length === 0) return { error: "The formula has no series to add up, only series it divides by; write the formula again." };
+  const divisor = spec.parameters.divisor ?? 1;
+  if (!isFiniteNumber(divisor)) return { error: "The formula's divisor is not a number; write the formula again." };
+  if (divisor === 0) return { error: "A formula cannot be divided by 0." };
+  return { legs, factors, divisor };
+}
+
+/**
+ * A leg's unit once its multiplier is applied: 42 gallons of a per-gallon
+ * price are a barrel's worth, and 7.45 barrels of gasoil a tonne's.
+ */
+function formulaLegUnit(leg: FormulaLeg, input: ResolvedSeries): string {
+  const unit = leg.perBarrel ? perBarrelUnit(input.unit) : input.unit;
+  return leg.perTonne ? perTonneUnit(unit) : unit;
+}
+
+/** Why a formula's legs cannot be summed, or null when every leg counts the same known unit. */
+function formulaUnitMismatch(terms: FormulaTerms, inputs: readonly ResolvedSeries[]): string | null {
+  if (terms.legs.length < 2) return null;
+  const legs = terms.legs.map((leg) => ({ series: inputs[leg.index]!, unit: formulaLegUnit(leg, inputs[leg.index]!) }));
+  const signatures = legs.map(({ series, unit }) => knownUnitSignature({ unit, unitGroup: series.unitGroup }));
+  const other = signatures.findIndex((signature, index) => index > 0 && (signature === null || signature !== signatures[0]));
+  if (signatures[0] !== null && other < 0) return null;
+  return unitMismatchMessage("formula", legs[0]!, legs[Math.max(1, other)]!);
+}
+
+function formatFormulaNumber(value: number): string {
+  return String(Number(value.toPrecision(10)));
+}
+
+/**
+ * A formula as the legend names it, from the terms it was written with:
+ * `42×HO=F - CL=F`, `(2×42×RB=F + 42×HO=F - 3×CL=F)/3`, `(42×HO=F - BZ=F)/EURUSD=X`.
+ */
+function formulaLabel(inputs: readonly ResolvedSeries[], terms: FormulaTerms): string {
+  const sum = terms.legs.map((leg, position) => {
+    const magnitude = Math.abs(leg.weight);
+    // The conversions it carries are named as written: 7.45×42×HO=F.
+    const conversions = [...(leg.perTonne ? [leg.perTonne] : []), ...(leg.perBarrel ? [GALLONS_PER_BARREL] : [])];
+    const count = conversions.reduce((rest, factor) => rest / factor, magnitude);
+    const factors = [...(Math.abs(count - 1) < 1e-9 ? [] : [formatFormulaNumber(count)]), ...conversions.map(String)];
+    const term = [...factors, legName(inputs[leg.index]!)].join("×");
+    if (position === 0) return leg.weight < 0 ? `-${term}` : term;
+    return `${leg.weight < 0 ? "-" : "+"} ${term}`;
+  }).join(" ");
+  if (terms.divisor === 1 && terms.factors.length === 0) return sum;
+  return [
+    `(${sum})`,
+    ...(terms.divisor === 1 ? [] : [`/${formatFormulaNumber(terms.divisor)}`]),
+    ...terms.factors.map(({ index, power }) => `${power < 0 ? "/" : "×"}${legName(inputs[index]!)}`),
+  ].join("");
+}
+
+/** Every input's value on each date they share, each carried forward to the others' dates. */
+function alignedSamples(inputs: readonly ResolvedSeries[]): Array<{ point: TimeSeriesPoint; values: number[] }> {
+  return alignTimeSeries(inputs, { mode: "intersection", carryForward: true }).flatMap((row) => {
+    const aligned = inputs.map((input) => row.values[input.id]);
+    if (aligned.some((entry) => !isFiniteNumber(entry?.value))) return [];
+    const availability = Math.max(...aligned.map((entry) => entry!.point.availableAt?.getTime() ?? entry!.point.date.getTime()));
+    return [{
+      values: aligned.map((entry) => entry!.value as number),
+      point: {
+        date: new Date(row.date),
+        observedAt: new Date(row.date),
+        availableAt: Number.isFinite(availability) ? new Date(availability) : undefined,
+        value: null,
+        provenance: { quality: "derived" as const },
+      },
+    }];
+  });
+}
+
+/**
+ * A weighted sum of the legs over a divisor, in the unit the legs share once
+ * converted, then times or over the series it is scaled by, in the unit
+ * that arithmetic leaves: a crack in USD / barrel over EURUSD=X is EUR / barrel.
+ */
+/**
+ * A formula's unit: its legs' once converted, then times or over each series
+ * it is scaled by. Legs that count different units, or an FX rate the wrong
+ * way up, are an error that says why: a crack over USDJPY=X is no price, and
+ * times it JPY / barrel.
+ */
+export function formulaUnit(terms: FormulaTerms, inputs: readonly ResolvedSeries[]): SeriesUnit | { error: string } {
+  const mismatch = formulaUnitMismatch(terms, inputs);
+  if (mismatch) return { error: mismatch };
+  const first = inputs[terms.legs[0]!.index]!;
+  let unit: SeriesUnit = { unit: formulaLegUnit(terms.legs[0]!, first), unitGroup: first.unitGroup };
+  for (const factor of terms.factors) {
+    const series = inputs[factor.index]!;
+    const next = combinedUnit(unit, series, factor.power);
+    const issue = fxConversionIssue(unit, series, factor.power, next);
+    if (issue) return { error: issue };
+    unit = next;
+  }
+  return unit;
+}
+
+export function resolveFormula(
+  spec: ChartStudySpec,
+  inputs: readonly ResolvedSeries[],
+  terms: FormulaTerms,
+  unit: SeriesUnit,
+  color: string,
+): ResolvedSeries[] {
+  const first = inputs[terms.legs[0]!.index]!;
+  // Rounded off the float's last digits: 42 × 4.6233 - 96.12 is 98.0586, not 98.05860000000001.
+  const points = alignedSamples(inputs).map(({ point, values }) => {
+    let value: number | null = terms.legs.reduce((sum, leg) => sum + values[leg.index]! * leg.weight, 0) / terms.divisor;
+    for (const factor of terms.factors) {
+      const scale = values[factor.index]!;
+      value = value === null || (factor.power < 0 && scale === 0) ? null : factor.power < 0 ? value / scale : value * scale;
+    }
+    return derivedPoint({ point, value: 0 }, value === null ? null : Number(value.toPrecision(12)));
+  });
+  const frequencies = new Set(inputs.map((input) => input.nativeFrequency));
+  const resolutions = new Set(inputs.map((input) => input.historyResolution));
+  const scaled = terms.factors.length > 0;
+  // A price per quantity reads with its unit beside it, as a future's does.
+  const statedUnit = scaled
+    ? isPriceGroup(unit.unitGroup) && unit.unit.includes("/") ? unit.unit : null
+    : inputs.some((input) => input.statedUnit) ? unit.unit : null;
+  const valueDecimals = !scaled || isPriceGroup(unit.unitGroup) ? derivedValueDecimals(inputs, points) : undefined;
+  return [outputSeries(spec, first, {
+    label: formulaLabel(inputs, terms),
+    points,
+    color,
+    unit: unit.unit,
+    unitGroup: unit.unitGroup,
+    statedUnit,
+    // A weighted sum is no traded price: its decimals are its legs', not a contract's tick.
+    priceAssetCategory: null,
+    ...(valueDecimals !== undefined ? { valueDecimals } : {}),
+    // As the pair formulas: as-of levels, constant until an input changes.
+    style: "step",
+    interpolation: "step-after",
+    axis: "left",
+    nativeFrequency: frequencies.size === 1 ? first.nativeFrequency : "auto",
+    historyResolution: resolutions.size === 1 ? first.historyResolution : null,
+  })];
+}

package/src/time-series/studies/indicators.ts

@@ -0,0 +1,299 @@
+import { mergePriceHistoryIntegrity } from "../../utils/price-history-integrity";
+import { isRealizedVolatilityEstimator, rollingRealizedVolatility } from "../../market-data/realized-volatility";
+import { averageTrueRange } from "../trader-studies";
+import type { ChartStudySpec, ResolvedSeries, TimeSeriesPoint } from "../types";
+import { isFiniteNumber } from "../../utils/guards";
+import {
+  derivedPoint,
+  outputSeries,
+  positiveInteger,
+  samplesFor,
+  STUDY_COLORS,
+  studyBars,
+  studyPeriod,
+  type NumericSample,
+} from "./shared";
+
+export interface IndexedValue {
+  index: number;
+  value: number;
+}
+
+/** Exported so backtest rules and chart studies share identical math. */
+export function sma(values: readonly number[], period: number): IndexedValue[] {
+  if (values.length < period) return [];
+  const result: IndexedValue[] = [];
+  let sum = 0;
+  for (let index = 0; index < values.length; index += 1) {
+    sum += values[index]!;
+    if (index >= period) sum -= values[index - period]!;
+    if (index >= period - 1) result.push({ index, value: sum / period });
+  }
+  return result;
+}
+
+export function ema(values: readonly number[], period: number): IndexedValue[] {
+  if (values.length < period) return [];
+  const result: IndexedValue[] = [];
+  let current = values.slice(0, period).reduce((sum, value) => sum + value, 0) / period;
+  result.push({ index: period - 1, value: current });
+  const multiplier = 2 / (period + 1);
+  for (let index = period; index < values.length; index += 1) {
+    current = values[index]! * multiplier + current * (1 - multiplier);
+    result.push({ index, value: current });
+  }
+  return result;
+}
+
+export function rsi(values: readonly number[], period: number): IndexedValue[] {
+  if (values.length < period + 1) return [];
+  let averageGain = 0;
+  let averageLoss = 0;
+  for (let index = 1; index <= period; index += 1) {
+    const change = values[index]! - values[index - 1]!;
+    if (change > 0) averageGain += change;
+    else averageLoss -= change;
+  }
+  averageGain /= period;
+  averageLoss /= period;
+  const result: IndexedValue[] = [{
+    index: period,
+    value: averageLoss === 0 ? 100 : 100 - 100 / (1 + averageGain / averageLoss),
+  }];
+  for (let index = period + 1; index < values.length; index += 1) {
+    const change = values[index]! - values[index - 1]!;
+    averageGain = (averageGain * (period - 1) + Math.max(change, 0)) / period;
+    averageLoss = (averageLoss * (period - 1) + Math.max(-change, 0)) / period;
+    result.push({
+      index,
+      value: averageLoss === 0 ? 100 : 100 - 100 / (1 + averageGain / averageLoss),
+    });
+  }
+  return result;
+}
+
+function indexedPoints(samples: readonly NumericSample[], values: readonly IndexedValue[]): TimeSeriesPoint[] {
+  return values.flatMap(({ index, value }) => {
+    const sample = samples[index];
+    return sample ? [derivedPoint(sample, value)] : [];
+  });
+}
+
+export function studyWarmupPoints(spec: ChartStudySpec): number {
+  if (spec.kind === "realized-vol") {
+    const window = positiveInteger(spec.parameters.window, 30);
+    return spec.parameters.estimator === undefined || spec.parameters.estimator === "close-to-close" || spec.parameters.estimator === "yang-zhang"
+      ? window : window - 1;
+  }
+  if (spec.kind === "sma" || spec.kind === "ema" || spec.kind === "bollinger") {
+    return studyPeriod(spec, 20) - 1;
+  }
+  if (spec.kind === "rsi") return studyPeriod(spec, 14);
+  if (spec.kind === "macd") {
+    const slow = positiveInteger(spec.parameters.slow, 26);
+    const signal = positiveInteger(spec.parameters.signal, 9);
+    return slow + signal - 2;
+  }
+  if (spec.kind === "correlation") return studyPeriod(spec, 20);
+  if (spec.kind === "atr") return studyPeriod(spec, 14) - 1;
+  return 0;
+}
+
+export function resolveRealizedVolatility(spec: ChartStudySpec, input: ResolvedSeries, color: string): ResolvedSeries[] {
+  const window = positiveInteger(spec.parameters.window, 30);
+  const estimator = isRealizedVolatilityEstimator(spec.parameters.estimator) ? spec.parameters.estimator : "close-to-close";
+  // Retain invalid rows and the last correction for each date. Dropping one
+  // would turn two separated returns into adjacent observations.
+  const byDate = new Map(input.points.map((point) => [point.date.getTime(), point]));
+  const source = [...byDate.values()].sort((a, b) => a.date.getTime() - b.date.getTime());
+  const calculated = rollingRealizedVolatility(source.map((point) => ({
+    date: point.date,
+    close: point.provenance?.priceHistoryIntegrity || point.provenance?.valuationPriceIssues?.length
+      ? Number.NaN : (point.close === undefined ? point.value : point.close) ?? Number.NaN,
+    open: point.open ?? undefined,
+    high: point.high ?? undefined,
+    low: point.low ?? undefined,
+  })), { windows: [window], estimator });
+  const warmup = studyWarmupPoints(spec);
+  const points = calculated.map((point, index): TimeSeriesPoint => {
+    const original = source[index]!;
+    const value = point.values[window];
+    const derived = derivedPoint({ point: original, value: 0 }, value == null ? null : value * 100);
+    if (value == null) {
+      const affected = source.slice(Math.max(0, index - warmup), index + 1);
+      const integrity = affected.flatMap((entry) => entry.provenance?.priceHistoryIntegrity ? [entry.provenance.priceHistoryIntegrity] : []);
+      if (integrity.length) derived.provenance!.priceHistoryIntegrity = mergePriceHistoryIntegrity(...integrity);
+    }
+    return derived;
+  });
+  return [outputSeries(spec, input, {
+    label: `RV(${window}, ${estimator}) ${input.label}`,
+    points,
+    color,
+    unit: "%",
+    unitGroup: "percent",
+    axis: "left",
+  })];
+}
+
+export function resolveMovingAverage(
+  spec: ChartStudySpec,
+  input: ResolvedSeries,
+  color: string,
+  exponential: boolean,
+): ResolvedSeries[] {
+  const period = studyPeriod(spec, 20);
+  const samples = samplesFor(input);
+  const calculated = exponential
+    ? ema(samples.map(({ value }) => value), period)
+    : sma(samples.map(({ value }) => value), period);
+  const name = exponential ? "EMA" : "SMA";
+  return [outputSeries(spec, input, {
+    label: `${name}(${period}) ${input.label}`,
+    points: indexedPoints(samples, calculated),
+    color,
+  })];
+}
+
+export function resolveBollinger(
+  spec: ChartStudySpec,
+  input: ResolvedSeries,
+  color: string,
+): ResolvedSeries[] {
+  const period = studyPeriod(spec, 20);
+  const deviations = isFiniteNumber(spec.parameters.stdDev) && spec.parameters.stdDev > 0
+    ? spec.parameters.stdDev
+    : 2;
+  const samples = samplesFor(input);
+  const values = samples.map(({ value }) => value);
+  const middle = sma(values, period);
+  const upper: IndexedValue[] = [];
+  const lower: IndexedValue[] = [];
+  for (const point of middle) {
+    const window = values.slice(point.index - period + 1, point.index + 1);
+    const variance = window.reduce((sum, value) => sum + (value - point.value) ** 2, 0) / period;
+    const deviation = Math.sqrt(variance) * deviations;
+    upper.push({ index: point.index, value: point.value + deviation });
+    lower.push({ index: point.index, value: point.value - deviation });
+  }
+  const label = `Bollinger(${period},${deviations}) ${input.label}`;
+  return [
+    outputSeries(spec, input, {
+      id: `${spec.id}:upper`,
+      label: `${label} Upper`,
+      points: indexedPoints(samples, upper),
+      color,
+    }),
+    outputSeries(spec, input, {
+      id: `${spec.id}:middle`,
+      label: `${label} Middle`,
+      points: indexedPoints(samples, middle),
+      color,
+    }),
+    outputSeries(spec, input, {
+      id: `${spec.id}:lower`,
+      label: `${label} Lower`,
+      points: indexedPoints(samples, lower),
+      color,
+    }),
+  ];
+}
+
+export function resolveRsi(spec: ChartStudySpec, input: ResolvedSeries, color: string): ResolvedSeries[] {
+  const period = studyPeriod(spec, 14);
+  const samples = samplesFor(input);
+  return [outputSeries(spec, input, {
+    label: `RSI(${period}) ${input.label}`,
+    points: indexedPoints(samples, rsi(samples.map(({ value }) => value), period)),
+    color,
+    unit: "index",
+    unitGroup: "oscillator-0-100",
+    axis: "left",
+  })];
+}
+
+export function resolveMacd(spec: ChartStudySpec, input: ResolvedSeries, color: string): ResolvedSeries[] {
+  const fastPeriod = positiveInteger(spec.parameters.fast, 12);
+  const slowPeriod = positiveInteger(spec.parameters.slow, 26);
+  const signalPeriod = positiveInteger(spec.parameters.signal, 9);
+  if (fastPeriod >= slowPeriod) return [];
+  const samples = samplesFor(input);
+  const values = samples.map(({ value }) => value);
+  const fast = new Map(ema(values, fastPeriod).map((point) => [point.index, point.value]));
+  const macd = ema(values, slowPeriod).flatMap(({ index, value }) => {
+    const fastValue = fast.get(index);
+    return fastValue === undefined ? [] : [{ index, value: fastValue - value }];
+  });
+  const signalOnMacd = ema(macd.map(({ value }) => value), signalPeriod);
+  const signal = signalOnMacd.flatMap(({ index, value }) => {
+    const source = macd[index];
+    return source ? [{ index: source.index, value }] : [];
+  });
+  const macdByIndex = new Map(macd.map((point) => [point.index, point.value]));
+  const histogram = signal.map(({ index, value }) => ({ index, value: macdByIndex.get(index)! - value }));
+  const label = `MACD(${fastPeriod},${slowPeriod},${signalPeriod}) ${input.label}`;
+  return [
+    outputSeries(spec, input, {
+      id: `${spec.id}:macd`,
+      label,
+      points: indexedPoints(samples, macd),
+      color,
+      axis: "left",
+    }),
+    outputSeries(spec, input, {
+      id: `${spec.id}:signal`,
+      label: `${label} Signal`,
+      points: indexedPoints(samples, signal),
+      color: STUDY_COLORS[1]!,
+      axis: "left",
+    }),
+    outputSeries(spec, input, {
+      id: `${spec.id}:histogram`,
+      label: `${label} Histogram`,
+      points: indexedPoints(samples, histogram),
+      color: STUDY_COLORS[4]!,
+      style: "columns",
+      axis: "left",
+    }),
+  ];
+}
+
+export function resolveVolume(spec: ChartStudySpec, input: ResolvedSeries, color: string, nameInput: boolean): ResolvedSeries[] {
+  // No bar has volume to plot (spot FX quotes 0 for every bar; a coin's window
+  // can miss every bar's), so the study adds no panel rather than an empty one.
+  if (input.points.length > 0 && !input.points.some((point) => isFiniteNumber(point.volume) && point.volume !== 0)) return [];
+  // Left to its own colour, volume follows the candles: the price's colour for
+  // a bar that rose, the falling colour for one that fell. A colour picked for it stays flat.
+  const directional = !spec.color;
+  const points = [...input.points]
+    .sort((left, right) => left.date.getTime() - right.date.getTime())
+    .flatMap((point) => isFiniteNumber(point.volume)
+      ? [{
+        ...derivedPoint({ point, value: point.volume }, point.volume),
+        ...(directional && isFiniteNumber(point.open) && isFiniteNumber(point.close) && point.close < point.open ? { fell: true } : {}),
+      }]
+      : []);
+  return [outputSeries(spec, input, {
+    label: nameInput ? `Volume ${input.label}` : "Volume",
+    points,
+    color: directional ? input.color : color,
+    unit: input.volumeUnit ?? "",
+    unitGroup: "volume",
+    style: "columns",
+    axis: "left",
+  })];
+}
+
+export function resolveAtr(spec: ChartStudySpec, input: ResolvedSeries, color: string, nameInput: boolean): ResolvedSeries[] {
+  const period = studyPeriod(spec, 14);
+  const bars = studyBars(input);
+  return [outputSeries(spec, input, {
+    label: nameInput ? `ATR(${period}) ${input.label}` : `ATR(${period})`,
+    points: averageTrueRange(bars, period).flatMap(({ index, value }) => {
+      const bar = bars[index];
+      return bar ? [derivedPoint(bar.sample, value)] : [];
+    }),
+    color,
+    axis: "left",
+  })];
+}

package/src/time-series/studies/leverage.ts

@@ -0,0 +1,75 @@
+import type { ManualChartResolution } from "../resolution";
+import type { ChartStudySpec, ResolvedSeries } from "../types";
+import { studyMessageName } from "../series-name";
+import {
+  dailyLeverageGrowth,
+  leverageDecayPoints,
+  leverageFactorLabel,
+  leverageSymbol,
+  sessionCloses,
+  type StudyAnchor,
+} from "../leverage";
+import { DECAY_COLORS, derivedPoint, outputSeries } from "./shared";
+
+/** The objective's line and its decay compound session returns: they need daily bars, whatever the chart's range. */
+export function dailyBarsIssue(spec: ChartStudySpec, input: ResolvedSeries, marketResolution: ManualChartResolution | undefined): string | null {
+  const resolution = input.historyResolution === undefined ? marketResolution : input.historyResolution;
+  if (input.nativeFrequency === "daily" && (resolution === undefined || resolution === "1d")) return null;
+  return `${studyMessageName(spec)}: ${leverageFactorLabel(Number(spec.parameters.factor))} daily needs daily bars. Choose D bars.`;
+}
+
+/**
+ * The line a leveraged or inverse fund's daily objective draws from its index
+ * fund, in percent from where the chart compares (3× daily QQQ beside TQQQ),
+ * on the percent axis the compared legs share.
+ */
+export function resolveLeverageLine(spec: ChartStudySpec, index: ResolvedSeries, color: string, anchor: StudyAnchor | undefined): ResolvedSeries[] {
+  const factor = spec.parameters.factor as number;
+  const closes = sessionCloses(index, anchor);
+  const growth = dailyLeverageGrowth(closes.map((entry) => entry.close), factor);
+  return [outputSeries(spec, index, {
+    label: `${leverageFactorLabel(factor)} daily ${leverageSymbol(index)}`,
+    points: closes.map((entry, position) => derivedPoint({ point: entry.point, value: entry.close }, (growth[position]! - 1) * 100)),
+    color,
+    unit: "%",
+    unitGroup: "percent",
+    statedUnit: null,
+    priceAssetCategory: null,
+    axis: "left",
+  })];
+}
+
+/**
+ * How far the fund falls short of its daily objective, in percentage points
+ * from where the chart compares: the fund against the daily line (fees,
+ * financing, tracking), and the daily line against the factor times the index
+ * fund's return over the period (compounding, which daily resets cost in a
+ * market that swings).
+ */
+export function resolveLeverageDecay(
+  spec: ChartStudySpec,
+  fund: ResolvedSeries,
+  index: ResolvedSeries,
+  anchors: ReadonlyMap<string, StudyAnchor> | undefined,
+): ResolvedSeries[] {
+  const factor = spec.parameters.factor as number;
+  const decay = leverageDecayPoints(sessionCloses(fund, anchors?.get(fund.id)), sessionCloses(index, anchors?.get(index.id)), factor);
+  const daily = `${leverageFactorLabel(factor)} daily`;
+  const line = (id: string, label: string, color: string, value: (point: (typeof decay)[number]) => number) => outputSeries(spec, fund, {
+    id: `${spec.id}:${id}`,
+    label,
+    points: decay.map((entry) => derivedPoint({ point: entry.point, value: entry.fund }, value(entry))),
+    color: spec.color ?? color,
+    unit: "pp",
+    // Not a percent group: a difference of returns reads in points (-0.96 pp), not as a return.
+    unitGroup: "pp",
+    statedUnit: null,
+    priceAssetCategory: null,
+    axis: "left",
+  });
+  return [
+    line("fund", `${leverageSymbol(fund)} decay vs ${daily} ${leverageSymbol(index)}`, DECAY_COLORS[0], (entry) => entry.fund - entry.daily),
+    // `3× QQQ`: three times QQQ's return over the period, the multiple a daily reset does not deliver.
+    line("compounding", `${daily} ${leverageSymbol(index)} decay vs ${leverageFactorLabel(factor)} ${leverageSymbol(index)}`, DECAY_COLORS[1], (entry) => entry.daily - entry.period),
+  ];
+}