Kumo Charts

カスタムインジケーター

独自のインジケーターも、組み込みのものと同じように扱えます。チャートに追加でき、凡例に表示され、アラートで監視でき、レイアウトに保存でき、チャートのない場所で計算することもできます。

最も簡単な書き方

各値を計算するのに何本さかのぼるか(lookback)をチャートに伝え、その本数の足から値を計算する関数(compute)を渡します。

コードを表示コードを隠す
import { createChart } from '@kumo-charts/core';
import { indicators, type IndicatorDefinition } from '@kumo-charts/core/indicators';
import { loadBars } from '@docs/data';

/** 価格が移動平均からどれだけ離れているか(パーセント) */
const DEVIATION: IndicatorDefinition<{ period: number }> = {
  type: 'DEVIATION',
  name: '移動平均乖離',
  pane: 'new', // 専用のペインを開く。'main' ならメインペインに描く
  precision: 2,
  params: { period: { default: 20, min: 2, max: 500, integer: true, label: '期間' } },
  outputs: () => [{ key: 'dev', label: '乖離%', plot: { kind: 'histogram', colorBy: 'sign' } }],
  levels: () => [0],
  lookback: ({ period }) => period,
  compute: (window) => {
    let sum = 0;
    for (let i = 0; i < window.length; i += 1) sum += window.price(i);
    const average = sum / window.length;
    const latest = window.price(window.length - 1);
    return [((latest - average) / average) * 100];
  }
};

const chart = createChart(document.getElementById('chart')!, {
  modules: [indicators([DEVIATION])]
});

chart.data.set(await loadBars(), { interval: '1m' });
chart.data.setTimeframe('1h');
chart.indicators.add({ type: 'DEVIATION' });

window は直近 lookback 本の足で、古い順に並んでいます。window.price(i) はインジケーターに設定された価格(デフォルトは終値)、window.bar(i) は足全体です。足が lookback 本に満たないうちは呼ばれず、その間の足には値がありません。

compute は、出力ごとに 1 つの値を持つ配列を返します。値がないところでは NaN を返します。

使う

チャートの作成時に、組み込みのものと一緒に渡します。

import { indicators, allIndicators } from '@kumo-charts/core/indicators';

createChart(container, { modules: [indicators([...allIndicators, DEVIATION])] });

または、作成したあとで登録します。

chart.indicators.register(DEVIATION);
chart.indicators.add({ type: 'DEVIATION', params: { period: 50 } });

1 本ずつ計算する

compute は足ごとにウィンドウ全体を計算し直すので、期間が長いと遅くなります。また、EMA のように、ずっと前からの状態を覚えておく必要があるインジケーターもあります。そういうときは create に書き換え、1 本ずつ先へ進めて計算する計算器を返します。

import type { IndicatorDefinition, IndicatorStream } from '@kumo-charts/core/indicators';

/** 何本続けて上昇・下落したか:上昇は正、下落は負 */
class StreakStream implements IndicatorStream {
  private readonly out = new Float64Array(1);

  constructor(
    private previous = Number.NaN,
    private streak = 0
  ) {}

  next(_bar: unknown, price: number): ArrayLike<number> {
    if (price > this.previous) this.streak = this.streak > 0 ? this.streak + 1 : 1;
    else if (price < this.previous) this.streak = this.streak < 0 ? this.streak - 1 : -1;
    else this.streak = 0;
    this.previous = price;
    this.out[0] = this.streak;
    return this.out;
  }

  clone(): IndicatorStream {
    return new StreakStream(this.previous, this.streak);
  }
}

export const STREAK: IndicatorDefinition<Record<string, never>> = {
  type: 'STREAK',
  name: '連続上昇・下落',
  pane: 'new',
  precision: 0,
  params: {},
  outputs: () => [{ key: 'streak', label: 'STREAK', plot: { kind: 'histogram', colorBy: 'sign' } }],
  create: () => new StreakStream()
};

ルールは 2 つあります。

  • next(bar, price) は足ごとに 1 回、時間の順に呼ばれます。bar オブジェクトは使い回されるので、その参照を保存しないでください。必要な値は数値として取り出して使います。
  • clone() はすべての状態をコピーしなければなりません。最新の足がリアルタイムで更新されるとき、チャートは更新前のコピーからその足を計算し直します。そのため、コピーと元のものが互いに影響し合ってはいけません。

ライブラリの部品で組み立てる

EMA や標準偏差のようなよく使う計算は、自分で書き直す必要はありません。@kumo-charts/core/indicators は、ライブラリ自身のインジケーターが使っている部品を公開しています。どれも clone() できます。

部品 計算するもの
movingAverage(kind, period) 移動平均:'sma'、'ema'、'rma'、'wma'、'vwma'。組み込みのインジケーターが選ぶ平均と同じ
StandardDeviation 直近 period 個の値の標準偏差
RollingExtremes 直近 period 本の足の最高値と最安値
RingBuffer 直近 capacity 個の値。最大、最小、合計も取れる
Previous ひとつ前の値

たとえば EMA の上下に標準偏差の何倍かを足し引きしたバンドです。

import type { Bar } from '@kumo-charts/core';
import {
  movingAverage,
  StandardDeviation,
  type BarStep,
  type IndicatorDefinition,
  type IndicatorStream
} from '@kumo-charts/core/indicators';

class EmaBandStream implements IndicatorStream {
  private readonly out = new Float64Array(3);

  constructor(
    private readonly width: number,
    private readonly average: BarStep,
    private readonly deviation: StandardDeviation
  ) {}

  next(bar: Bar, price: number): ArrayLike<number> {
    const middle = this.average.next(price, bar); // 足は出来高加重平均が出来高を読むため
    const spread = this.deviation.next(price) * this.width;
    this.out[0] = middle;
    this.out[1] = middle + spread;
    this.out[2] = middle - spread;
    return this.out;
  }

  clone(): IndicatorStream {
    // ブロックはそれぞれ自分の状態をコピーする
    return new EmaBandStream(this.width, this.average.clone(), this.deviation.clone());
  }
}

export const EMA_BAND: IndicatorDefinition<{ period: number; width: number }> = {
  type: 'EMA_BAND',
  name: 'EMA バンド',
  pane: 'main',
  precision: 'price',
  params: {
    period: { default: 20, min: 2, max: 500, integer: true, label: '期間' },
    width: { default: 2, min: 0.1, max: 10, label: '倍率' }
  },
  outputs: () => [
    { key: 'basis', label: 'EMA', plot: { kind: 'line' } },
    { key: 'upper', label: '上限', plot: { kind: 'line' } },
    { key: 'lower', label: '下限', plot: { kind: 'line' } }
  ],
  fills: () => [{ from: 'upper', to: 'lower' }],
  create: ({ period, width }) =>
    new EmaBandStream(width, movingAverage('ema', period), new StandardDeviation(period))
};

平均と標準偏差は、period 個の値がそろうまでは NaN です。NaN は読み飛ばし、値はそのままです。clone() で部品をそれぞれ clone() すれば、計算器全体がコピーされます。

出力の描き方

各出力の plot は次のとおりです。

kind 描き方
line 折れ線。style は solid、dashed、dotted のいずれか。width は線の太さ(ピクセル、0.5〜10、既定 1.25)
segments 値が変わらない区間ごとに水平線を描く。日ごとのピボットポイントなど。style、width は line と同じ
histogram 0 から伸びる棒。正負(sign)、増減(change)、足の向き(bar)で色分けする
columns 別の出力(または固定値)からこの値までの棒
candles ローソク足。この出力が終値、ほかの 3 つが始値・高値・安値。テーマの上昇・下落色
box 別の出力からこの値までのボックス。取引セッションの高値・安値の範囲など
marker 値がある足に図形やテキストを描く。ゴールデンクロスの位置の矢印など。value: true で値も書く(ピボットの価格など)
zigzag ジグザグ。high、low の 2 つの出力の値を足の順に並べ、同じ向きの連続からは最後の 1 つだけを取って結ぶ。extend で最新の足でのこの出力の値まで延ばし、labels でピボットの横に価格・変化・出来高を書く。style、width は line と同じ
hidden 描かない。凡例への表示とアラートのためだけに使う

ローソク足として描くとき、始値・高値・安値の 3 つの出力はふつう hidden にします。単独では描かれず、凡例には値が表示されます。4 つの値はそのローソク足の色で表示され、価格スケールは高値・安値に合わせて伸縮します。ローソク足の出力に色を設定すると、すべての足がその色になります。

import type { IndicatorOutput } from '@kumo-charts/core/indicators';

const outputs: IndicatorOutput[] = [
  { key: 'open', label: 'Open', plot: { kind: 'hidden' } },
  { key: 'high', label: 'High', plot: { kind: 'hidden' } },
  { key: 'low', label: 'Low', plot: { kind: 'hidden' } },
  {
    key: 'close',
    label: 'Close',
    plot: { kind: 'candles', open: 'open', high: 'high', low: 'low' }
  }
];

出力のその他の設定:

import type { IndicatorOutput } from '@kumo-charts/core/indicators';

const upper: IndicatorOutput = {
  key: 'upper',
  label: 'Upper',
  plot: { kind: 'line' },
  color: '#5b9cf0', // 指定しなければテーマの palette から順に取る
  themeColor: 'up', // またはテーマの上昇・下落の色を使う
  offset: 26, // 26 本右にずらして描く。一目均衡表の先行スパンなど
  legend: false, // 凡例に表示しない
  precision: 4, // この出力だけの小数点以下の桁数
  autoscale: false // 価格軸の自動スケールの対象にしない
};

2 本のラインの間を塗りつぶすには、定義に fills を書きます。たとえばボリンジャーバンドの上下のバンドの間なら fills: () => [{ from: 'upper', to: 'lower' }] です。outputs と同じくパラメーターから返すので、パラメーターでバンドを出したときだけ塗りつぶすこともできます。塗りつぶしに使う出力がそのパラメーターでは出ないときは、インジケーターを追加するときにエラーになり、黙って描かれないことはありません。

ジグザグ

ジグザグのように、ピボットが数本後にならないと見つからず、さらに先のピボットに置き換わることもあるインジケーターは zigzag で描きます。計算器は各足でその時点で見つけた高値・安値だけを返し、後から変えません。描くときに同じ向きの連続から最後の 1 つを取るので、後の値がピボットを先へ移します。

import type { Bar } from '@kumo-charts/core';
import {
  RingBuffer,
  type IndicatorDefinition,
  type IndicatorStream
} from '@kumo-charts/core/indicators';

// 終値が period 本の中で最も高ければ高値、最も安ければ安値として記録する
class SwingStream implements IndicatorStream {
  private readonly out = new Float64Array(3);

  constructor(private readonly closes: RingBuffer) {}

  next(bar: Bar): ArrayLike<number> {
    this.closes.push(bar.close);
    const full = this.closes.full;
    this.out[0] = bar.close; // ラインは最新の終値まで延びる
    this.out[1] = full && bar.close >= this.closes.max() ? bar.close : Number.NaN;
    this.out[2] = full && bar.close <= this.closes.min() ? bar.close : Number.NaN;
    return this.out;
  }

  clone(): IndicatorStream {
    return new SwingStream(this.closes.clone());
  }
}

const SWINGS: IndicatorDefinition<{ period: number }> = {
  type: 'SWINGS',
  name: 'スイング',
  pane: 'main',
  precision: 'price',
  params: { period: { default: 20, min: 2, integer: true } },
  outputs: () => [
    {
      key: 'line',
      label: 'スイング',
      plot: {
        kind: 'zigzag',
        high: 'high',
        low: 'low',
        extend: true,
        labels: { price: true, change: 'percent' }
      },
      legend: false
    },
    { key: 'high', label: '高値', plot: { kind: 'hidden' }, legend: false },
    { key: 'low', label: '安値', plot: { kind: 'hidden' }, legend: false }
  ],
  create: ({ period }) => new SwingStream(new RingBuffer(period))
};

labels の change は absolute(価格)か percent(パーセント)で、volume: true は 2 つのピボットの間の出来高(前のピボットの次の足からこのピボットの足まで。最初のピボットは最初の足から)を書きます。高値のラベルは上に、テーマの上昇色で、安値のラベルは下に、下落色で書き、ラインが延びる先の最新の足にもラベルが付きます。high、low の出力はふつう hidden、legend: false にして、ラインだけに使います。

パラメーター

import type { ParamSpec } from '@kumo-charts/core/indicators';

const params = {
  period: { default: 14, min: 1, max: 500, integer: true, label: '期間' },
  periods: { default: [5, 10, 20], min: 1, integer: true }, // 数値の配列。複数の移動平均など
  anchor: {
    default: 1,
    // これらの値しか取れない。画面ではドロップダウンとして表示する
    options: [
      { value: 1, label: '日' },
      { value: 2, label: '週' }
    ]
  }
} satisfies Record<string, ParamSpec>;

パラメーターはすべて数値か数値の配列です。ユーザーが指定したパラメーターはここに書いた範囲でチェックされ、範囲外ならエラーになります。

取引日に合わせて計算する

取引日、週、月ごとに計算をやり直すインジケーター、たとえば日ごとに計算し直す VWAP では、2 番目の引数で受け取る取引カレンダーを使います。

import type { Bar, Calendar } from '@kumo-charts/core';
import type { IndicatorDefinition, IndicatorStream } from '@kumo-charts/core/indicators';

class DayHighStream implements IndicatorStream {
  private readonly out = new Float64Array(1);

  constructor(
    private readonly calendar: Calendar,
    private day: number | null = null,
    private high = Number.NaN
  ) {}

  next(bar: Bar): ArrayLike<number> {
    // この足がどの取引日に属するか。取引セッション外の時間は null
    const day = this.calendar.bucket(bar.time, '1D');
    this.high = day === this.day ? Math.max(this.high, bar.high) : bar.high;
    this.day = day;
    this.out[0] = this.high;
    return this.out;
  }

  clone(): IndicatorStream {
    return new DayHighStream(this.calendar, this.day, this.high);
  }
}

const DAY_HIGH: IndicatorDefinition<Record<string, never>> = {
  type: 'DAY_HIGH',
  name: '当日高値',
  pane: 'main',
  precision: 'price',
  params: {},
  outputs: () => [{ key: 'high', label: 'DH', plot: { kind: 'segments' } }],
  create: (_params, { calendar }) => new DayHighStream(calendar)
};

このカレンダーはチャートの calendar オプションそのものです。ユーザーが取引セッションを変えると、インジケーターは計算し直されます。2 番目の引数には足の期間 interval もあります。チャートが表示している時間足で、data.set() に期間を渡さなかった足では null です。

ローソク足以外のデータを読む

計算器はローソク足以外のデータ、たとえば別に取得した資金調達率、建玉、約定履歴も読めます。そのデータがいつ変わったかをチャートは知らないので、変わるたびに chart.indicators.refresh() を呼んでください。チャートがそのインジケーターを計算し直し、それを読むインジケーター(その移動平均など)も一緒に計算し直します。

import type { Bar } from '@kumo-charts/core';
import type { IndicatorDefinition, IndicatorStream } from '@kumo-charts/core/indicators';

/** 資金調達率を足の時刻ごとに保存し、取得した分から入れる */
const rates = new Map<number, number>();

class FundingStream implements IndicatorStream {
  private readonly out = new Float64Array(1);

  next(bar: Bar): ArrayLike<number> {
    this.out[0] = rates.get(bar.time) ?? Number.NaN; // まだ取得していない足は描かない
    return this.out;
  }

  clone(): IndicatorStream {
    return new FundingStream(); // 外のデータは計算器の状態ではないので複製しない
  }
}

const FUNDING: IndicatorDefinition<Record<string, never>> = {
  type: 'FUNDING',
  name: '資金調達率',
  pane: 'new',
  precision: 4,
  params: {},
  outputs: () => [{ key: 'rate', label: '料率', plot: { kind: 'histogram', colorBy: 'sign' } }],
  create: () => new FundingStream()
};

chart.indicators.register(FUNDING);
const id = chart.indicators.add({ type: 'FUNDING' });

// 履歴をまとめて取得した:インジケーター全体を計算し直す
const history = (await (await fetch('/api/funding')).json()) as Array<[number, number]>;
history.forEach(([time, rate]) => rates.set(time, rate));
chart.indicators.refresh(id);

// 最新の足の値が変わった:その足だけを計算し直す
export function onRate(time: number, rate: number): void {
  rates.set(time, rate);
  chart.indicators.refresh(id, time);
}

refresh(id, from) は時刻 from を含む足から計算し直します。from が最新の足なら、ティックと同じくその足だけを計算します。それより前の足のとき、または from を省いたときは、インジケーター全体を最初から計算します。外のデータは計算器の状態ではないので clone() で複製する必要はありませんが、計算器自身の状態はこれまでどおりすべて複製します。チャートなしで計算するとき(computeIndicator())は知らせる先がないため、計算器は呼び出した時点のデータを読みます。データが変わったら計算し直してください。

チャートなしで計算する

import { computeIndicator } from '@kumo-charts/core/indicators';

const { dev } = computeIndicator(DEVIATION, bars, { params: { period: 50 } });
// dev[i] は i 本目の足の値。チャート上で計算した値と同じ

1 本ずつ進めるには createIndicatorCalculator() を使います。サーバーでリアルタイムデータに合わせて計算したり、アラートを判定したりするのに向いています。どれも Node.js で動きます。

↑↓ で選択 · Enter で開く · Esc で閉じる