Add Ichimoku

README.md

@@ -42,6 +42,7 @@ The main feature of these indicators is their continuous operation, which means
 - [Welles Wilder's Smoothing Average (WWS)](./docs/WellesWildersSmoothingAverage.md).
 - [Weighted moving average (WMA)](./docs/WeightedMovingAverage.md)
 - [Parabolic Stop And Reverse (PSAR)](./docs/ParabolicStopAndReverse.md).
+- [Ichimoku Cloud](./docs/Ichimoku.md).
 - Volume Profile (TBD)
 
 ## Candles

docs/Ichimoku.md

@@ -0,0 +1,134 @@
+# Ichimoku Cloud Trading Guide
+
+The **Ichimoku Cloud** (Ichimoku Kinko Hyo) is a comprehensive technical analysis tool used to identify trends, momentum, and support/resistance levels in financial markets. It provides a "one-glance" view of market conditions, making it popular among traders in forex, stocks, and cryptocurrencies. This guide explains the components of the Ichimoku indicator, how to interpret its signals, and how to use it for trading decisions.
+
+## Components of the Ichimoku Cloud
+
+The Ichimoku indicator consists of five main components, each providing unique insights into price action:
+
+1. **Tenkan-sen (Conversion Line)**:
+   - Calculated as the average of the highest high and lowest low over a short period (default: 9 periods).
+   - Represents short-term price momentum and acts as a trigger line for trading signals.
+   - Formula: `(Highest High + Lowest Low) / 2` over 9 periods.
+
+2. **Kijun-sen (Base Line)**:
+   - Calculated as the average of the highest high and lowest low over a longer period (default: 26 periods).
+   - Represents medium-term price momentum and serves as a support/resistance level.
+   - Formula: `(Highest High + Lowest Low) / 2` over 26 periods.
+
+3. **Senkou Span A (Leading Span A)**:
+   - Calculated as the average of Tenkan-sen and Kijun-sen, plotted 26 periods ahead.
+   - Forms one boundary of the Ichimoku Cloud (Kumo) and indicates potential support/resistance.
+   - Formula: `(Tenkan-sen + Kijun-sen) / 2`, shifted forward 26 periods.
+
+4. **Senkou Span B (Leading Span B)**:
+   - Calculated as the average of the highest high and lowest low over a longer period (default: 52 periods), plotted 26 periods ahead.
+   - Forms the other boundary of the Cloud and indicates stronger support/resistance.
+   - Formula: `(Highest High + Lowest Low) / 2` over 52 periods, shifted forward 26 periods.
+
+5. **Chikou Span (Lagging Span)**:
+   - The closing price of the current period, plotted 26 periods back.
+   - Used to confirm momentum by comparing the current price to historical prices.
+   - Formula: Closing price, shifted backward 26 periods.
+
+The **Cloud (Kumo)** is the area between Senkou Span A and Senkou Span B. Its color and thickness provide insights into market trends and strength:
+- **Green Cloud**: Senkou Span A > Senkou Span B (bullish).
+- **Red Cloud**: Senkou Span A < Senkou Span B (bearish).
+- **Thick Cloud**: Strong support/resistance (wide gap between Spans).
+- **Thin Cloud**: Weak support/resistance (narrow gap).
+
+## Interpreting Ichimoku Signals
+
+The Ichimoku Cloud provides multiple signals for identifying trends, entry points, and exits. Below are the key signals for trading:
+
+### 1. Trend Identification
+- **Bullish Trend**: Price is above the Cloud (Senkou Span A > Senkou Span B).
+- **Bearish Trend**: Price is below the Cloud (Senkou Span A < Senkou Span B).
+- **Neutral/Range-Bound**: Price is within the Cloud, indicating indecision or consolidation.
+
+### 2. Tenkan-sen and Kijun-sen Cross
+- **Bullish Signal (Golden Cross)**: Tenkan-sen crosses above Kijun-sen, preferably above the Cloud, indicating a potential buy.
+- **Bearish Signal (Death Cross)**: Tenkan-sen crosses below Kijun-sen, preferably below the Cloud, indicating a potential sell.
+- **Strength**: Signals are stronger when they occur above (bullish) or below (bearish) the Cloud, and weaker when inside the Cloud.
+
+### 3. Price vs. Cloud
+- **Breakout Above Cloud**: Price moving from below to above the Cloud suggests a bullish trend, especially if confirmed by other signals.
+- **Breakout Below Cloud**: Price moving from above to below the Cloud suggests a bearish trend.
+- **Support/Resistance**: The Cloud acts as dynamic support (in uptrends) or resistance (in downtrends). Prices bouncing off the Cloud confirm its strength.
+
+### 4. Chikou Span Confirmation
+- **Bullish Confirmation**: Chikou Span is above the price from 26 periods ago and above the Cloud, confirming upward momentum.
+- **Bearish Confirmation**: Chikou Span is below the price from 26 periods ago and below the Cloud, confirming downward momentum.
+- **No Obstacles**: Chikou Span should be free of price or Cloud interference for stronger signals.
+
+### 5. Cloud Future Trend
+- **Bullish Future**: Senkou Span A crosses above Senkou Span B in the future (26 periods ahead), indicating a strengthening uptrend.
+- **Bearish Future**: Senkou Span A crosses below Senkou Span B in the future, indicating a strengthening downtrend.
+
+## Trading Strategy with Ichimoku Cloud
+
+Below is a basic trading strategy using the Ichimoku Cloud to make buy and sell decisions. This strategy combines multiple signals for higher accuracy.
+
+### Buy (Long) Conditions
+1. **Price Position**: Price is above the Cloud (Senkou Span A > Senkou Span B).
+2. **Tenkan-Kijun Cross**: Tenkan-sen crosses above Kijun-sen (bullish crossover).
+3. **Chikou Confirmation**: Chikou Span is above the price from 26 periods ago and not obstructed by the Cloud.
+4. **Price vs. Lines**: Price is above both Tenkan-sen and Kijun-sen.
+5. **Optional (Stronger Signal)**: The Cloud is thick (wide gap between Senkou Span A and B) and green, indicating strong support.
+
+**Action**: Open a long position when all conditions are met. Set a stop-loss below the Cloud or recent low, and a take-profit based on risk-reward ratio (e.g., 2:1).
+
+### Sell (Short) Conditions
+1. **Price Position**: Price is below the Cloud (Senkou Span A < Senkou Span B).
+2. **Tenkan-Kijun Cross**: Tenkan-sen crosses below Kijun-sen (bearish crossover).
+3. **Chikou Confirmation**: Chikou Span is below the price from 26 periods ago and not obstructed by the Cloud.
+4. **Price vs. Lines**: Price is below both Tenkan-sen and Kijun-sen.
+5. **Optional (Stronger Signal)**: The Cloud is thick and red, indicating strong resistance.
+
+**Action**: Open a short position when all conditions are met. Set a stop-loss above the Cloud or recent high, and a take-profit based on risk-reward ratio.
+
+### Exit Conditions
+- **Close Long**: Price falls below the Cloud, or Tenkan-sen crosses below Kijun-sen, or Chikou Span drops below the price from 26 periods ago.
+- **Close Short**: Price rises above the Cloud, or Tenkan-sen crosses above Kijun-sen, or Chikou Span rises above the price from 26 periods ago.
+- **Stop-Loss/Take-Profit**: Exit if the price hits predefined stop-loss or take-profit levels.
+
+## Implementation Tips
+- **Timeframes**: Use Ichimoku on multiple timeframes (e.g., H1, H4, D1) to confirm trends. For example, ensure the daily Cloud is bullish before buying on an hourly chart.
+- **Parameters**: Default periods (9, 26, 52, 26) work well for most markets, but you can adjust them for specific assets or timeframes (e.g., 7, 22, 44 for crypto).
+- **Combine with Other Indicators**: Pair Ichimoku with indicators like RSI, MACD, or volume to filter false signals.
+- **Risk Management**: Always use stop-loss and position sizing to manage risk, especially in volatile markets like futures or crypto.
+- **Backtesting**: Test the strategy on historical data to evaluate performance before live trading.
+
+## Example Code Snippet
+Below is a pseudocode example of how to implement the Ichimoku strategy in a trading system (TypeScript, assuming integration with a library like `@debut/indicators`):
+
+```typescript
+import { Ichimoku } from '@debut/indicators';
+
+const ichimoku = new Ichimoku({ tenkanPeriod: 9, kijunPeriod: 26, senkouBPeriod: 52, displacement: 26 });
+
+function trade(candle: { high: number, low: number, close: number }) {
+  const { tenkanSen, kijunSen, senkouSpanA, senkouSpanB, chikouSpan } = ichimoku.nextValue(candle);
+
+  if (tenkanSen && kijunSen && senkouSpanA && senkouSpanB && chikouSpan) {
+    const isAboveCloud = candle.close > Math.max(senkouSpanA, senkouSpanB);
+    const isBelowCloud = candle.close < Math.min(senkouSpanA, senkouSpanB);
+    const isTenkanAboveKijun = tenkanSen > kijunSen;
+    const isChikouAbovePrice = chikouSpan > candle.close;
+
+    if (isAboveCloud && isTenkanAboveKijun && isChikouAbovePrice && candle.close > kijunSen) {
+      return { action: 'buy', price: candle.close };
+    } else if (isBelowCloud && !isTenkanAboveKijun && !isChikouAbovePrice && candle.close < kijunSen) {
+      return { action: 'sell', price: candle.close };
+    }
+  }
+  return { action: 'hold', price: candle.close };
+}
+```
+
+## Notes
+- **Market Suitability**: Ichimoku works best in trending markets. In range-bound markets, signals within the Cloud may be unreliable.
+- **Volatility**: Adjust stop-loss and take-profit levels based on market volatility (e.g., use ATR for dynamic levels).
+- **Practice**: Use a demo account or backtesting platform to practice the strategy before trading with real funds.
+
+By combining the Ichimoku Cloud's components and signals, traders can make informed buy and sell decisions while managing risk effectively.

index.ts

@@ -39,4 +39,5 @@ export { Sampler } from './src/providers/sampler';
 export { VolumeProfile } from './src/volume-profile'; /** BETA UNSTABLE */
 export { ChaikinOscillator } from './src/chaikin';
 export { AMA } from './src/ama';
+export * from './src/ichimoku';
 // export { OrderBlock } from './src/order-block';

src/ichimoku.ts

@@ -0,0 +1,115 @@
+
+
+export interface IchimokuInput {
+  tenkanPeriod?: number; // Period for Tenkan-sen
+  kijunPeriod?: number; // Period for Kijun-sen
+  senkouBPeriod?: number; // Period for Senkou Span B
+  displacement?: number; // Displacement for Senkou Spans and Chikou Span
+}
+
+export interface IchimokuOutput {
+  tenkanSen: number | null; // Tenkan-sen (Conversion Line)
+  kijunSen: number | null; // Kijun-sen (Base Line)
+  senkouSpanA: number | null; // Senkou Span A (Leading Span A)
+  senkouSpanB: number | null; // Senkou Span B (Leading Span B)
+  chikouSpan: number | null; // Chikou Span (Lagging Span)
+}
+
+export class Ichimoku {
+  private tenkanPeriod: number;
+  private kijunPeriod: number;
+  private senkouBPeriod: number;
+  private displacement: number;
+  private highBuffer: number[];
+  private lowBuffer: number[];
+  private closeBuffer: number[];
+  private tenkanSen: number[];
+  private kijunSen: number[];
+  private senkouSpanA: number[];
+  private senkouSpanB: number[];
+  private chikouSpan: number[];
+
+  constructor(input: IchimokuInput = {}) {   
+    this.tenkanPeriod = input.tenkanPeriod || 9;
+    this.kijunPeriod = input.kijunPeriod || 26;
+    this.senkouBPeriod = input.senkouBPeriod || 52;
+    this.displacement = input.displacement || 26;
+    this.highBuffer = [];
+    this.lowBuffer = [];
+    this.closeBuffer = [];
+    this.tenkanSen = [];
+    this.kijunSen = [];
+    this.senkouSpanA = [];
+    this.senkouSpanB = [];
+    this.chikouSpan = [];
+  }
+
+  // Calculate the highest high or lowest low over a period
+  private calculateHighLow(period: number, isHigh: boolean): number | null {
+    const buffer = isHigh ? this.highBuffer : this.lowBuffer;
+    if (buffer.length < period) return null;
+    return isHigh
+      ? Math.max(...buffer.slice(-period))
+      : Math.min(...buffer.slice(-period));
+  }
+
+  // Calculate Tenkan-sen or Kijun-sen
+  private calculateLine(period: number): number | null {
+    const high = this.calculateHighLow(period, true);
+    const low = this.calculateHighLow(period, false);
+    if (high === null || low === null) return null;
+    return (high + low) / 2;
+  }
+
+  nextValue(high: number, low: number, close: number): IchimokuOutput{
+    return this.next({high, low, close})
+  }
+
+  next(candle: { high: number; low: number; close: number }): IchimokuOutput {
+    this.highBuffer.push(candle.high);
+    this.lowBuffer.push(candle.low);
+    this.closeBuffer.push(candle.close);
+
+    // Calculate Tenkan-sen
+    const tenkanSen = this.calculateLine(this.tenkanPeriod);
+    if (tenkanSen !== null) this.tenkanSen.push(tenkanSen);
+
+    // Calculate Kijun-sen
+    const kijunSen = this.calculateLine(this.kijunPeriod);
+    if (kijunSen !== null) this.kijunSen.push(kijunSen);
+
+    // Calculate Senkou Span A
+    let senkouSpanA: number | null = null;
+    if (tenkanSen !== null && kijunSen !== null) {
+      senkouSpanA = (tenkanSen + kijunSen) / 2;
+      this.senkouSpanA.push(senkouSpanA);
+    }
+
+    // Calculate Senkou Span B
+    const senkouSpanB = this.calculateLine(this.senkouBPeriod);
+    if (senkouSpanB !== null) this.senkouSpanB.push(senkouSpanB);
+
+    // Calculate Chikou Span (lagging close price)
+    let chikouSpan: number | null = null;
+    if (this.closeBuffer.length > this.displacement) {
+      chikouSpan = this.closeBuffer[this.closeBuffer.length - 1 - this.displacement];
+      this.chikouSpan.push(chikouSpan);
+    }
+
+    // Maintain buffer size
+    if (this.highBuffer.length > this.senkouBPeriod) {
+      this.highBuffer.shift();
+      this.lowBuffer.shift();
+      this.closeBuffer.shift();
+    }
+
+    // Return values for the current candle
+    return {
+      tenkanSen: tenkanSen,
+      kijunSen: kijunSen,
+      senkouSpanA: this.senkouSpanA.length > this.displacement ? this.senkouSpanA[this.senkouSpanA.length - 1 - this.displacement] : null,
+      senkouSpanB: this.senkouSpanB.length > this.displacement ? this.senkouSpanB[this.senkouSpanB.length - 1 - this.displacement] : null,
+      chikouSpan: chikouSpan,
+    };
+  }
+}