================================================================================
                    GANN TIMER INDICATOR - USER GUIDE
================================================================================

OVERVIEW
--------
The Gann Timer Indicator is a time-based cycle indicator that uses Gann Time 
Cycle principles to identify potential reversal dates in the market. It 
calculates cluster dates from swing highs and lows using ZigZag, and displays 
them on your chart with visual elements and labels.

================================================================================
                            HOW IT WORKS
================================================================================

1. PIVOT DETECTION
   - The indicator uses ZigZag to identify swing highs and lows (pivot points)
   - ZigZag settings (Depth, Deviation, Backstep) control pivot sensitivity
   - Only stable pivots (excluding last few bars "Depth") are used for calculations

2. TIME PERIOD CALCULATION
   - From each pivot point, the indicator calculates forward target dates
   - Uses 9 Gann time periods: 72, 90, 120, 144, 180, 240, 270, 288, 360
   - Calculates both Trading Days (TD) and Calendar Days (CD)
   - For crypto instruments: TD = CD (7 days/week)

3. AGGREGATION ALGORITHM
   - Multiple target dates from different pivots may cluster together
   - The algorithm groups nearby lines (± Tolerance days) into clusters
   - Uses a scoring system to find optimal cluster centers
   - Only clusters meeting minimum size (default: 3 lines) are displayed

4. VISUAL DISPLAY
   - Vertical Lines: Show cluster centers (thickness = number of lines)
   - 5-Day Windows: Yellow before entry, Green when entered
   - Labels: Stacked vertically showing all lines in the cluster
   - ZigZag Lines: Optional display of the underlying ZigZag

================================================================================
                          ZIGZAG SETTINGS GUIDE
================================================================================

IMPORTANT: 
   - The primary setting for defining "Major" vs "Minor" swings on Daily charts is **Depth**.
   - **Deviation** and **Backstep** have minimal impact on defining major pivots on D1 timeframe (unless set to very high values).
   - They are included mainly to ensure the ZigZag line is drawn correctly visually.

HOW TO ADJUST PIVOT STRENGTH:

1. FOCUS ON DEPTH:
   - Increase **InpDepth** to filter out smaller swings and find Major Pivots.
   - Example Normal Swings: Depth = 12
   - Example Major Swings:  Depth = 15 to 25+

2. LEAVE OTHERS CONSTANT:
   - Keep Deviation around 5-10.
   - Keep Backstep around 3-5.
   - CRITICAL: **Backstep must always be LESS than Depth**.

Note: Adjust Depth until you see the desired major high/lows highlighted.

================================================================================
                         SETTINGS EXPLANATION
================================================================================

ZIGZAG SETTINGS:
   - InpDepth: 15 (ZigZag Depth)
   - InpDeviation: 5 (ZigZag Deviation)
   - InpBackstep: 3 (ZigZag Backstep)
   - InpLookback: 730 (Lookback Period in days, approx 2 years)
   - InpMinPastCandles: 25 (Minimum past candles to show for context)

AGGREGATION SETTINGS:
   - InpAggregationTolerance: 1 (Days tolerance for grouping, ±1 day)
   - InpMinClusterSize: 3 (Minimum lines required to form a cluster)

DISPLAY OPTIONS:
   - InpShowZigZag: true (Show ZigZag Lines)
   - InpShowLines: true (Show Vertical Cluster Lines)
   - InpShowLabels: true (Show Text Labels)
   - InpShowWindows: true (Show 5-Day Time Windows)
   - InpShowPastData: true (Show Past Clusters/Windows)
   - InpShowTD: true (Show Trading Days calculations)
   - InpShowCD: true (Show Calendar Days calculations)
   - InpShowSingleLines: false (Show Single/Non-Aggregated Lines. Default OFF to reduce clutter)

COLORS:
   - Fully customizable colors for Lines, Windows (Entered/Future), Labels, and ZigZag.

ALERTS:
   - InpEnableAlerts: Master switch to enable alerts
   - InpAlertCluster: Alert on the exact Cluster Date
   - InpAlertWindow: Alert when price enters the 5-day Window (2 days before target)

TIME PERIODS:
   - Toggle individual Gann periods (72, 90, 120, 144, 180, 240, 270, 288, 360) on/off.

================================================================================
                           AGGREGATION ALGORITHM
================================================================================

The indicator uses an intelligent clustering algorithm:

STEP 1: Score Calculation
   - For each day, calculates a score based on nearby pivot lines
   - Score = sum of weights of lines within tolerance range
   - Original line dates get a bias boost

STEP 2: Greedy Selection
   - Selects day with highest score as cluster center
   - Aggregates all lines within tolerance to this center
   - Prevents overlap by excluding nearby days

STEP 3: Result
   - Final lines are drawn at cluster centers
   - Line thickness represents number of aggregated lines
   - Only clusters meeting 'Min Cluster Size' are displayed (unless ShowSingleLines is true)

================================================================================
                            TRADING DAYS vs CALENDAR DAYS
================================================================================

TRADING DAYS (TD):
   - Counts only market trading days
   - Excludes weekends (Saturday, Sunday) and holidays (where no data exists)
   - Example: 180 TD ≈ 252 calendar days

CALENDAR DAYS (CD):
   - Counts all calendar days straight through
   - Includes weekends and holidays
   - Example: 180 CD = exactly 180 days

CRYPTO INSTRUMENTS:
   - Automatically detected (symbols like BTCUSD, ETHUSD, etc.)
   - Trading Days = Calendar Days (7 days/week)
   - Labels might show combined info

================================================================================
                            5-DAY WINDOW SYSTEM
================================================================================

Each cluster date has a 5-day trading window:
   - 2 days BEFORE the cluster date
   - The cluster date itself
   - 2 days AFTER the cluster date

Visual Indicators:
   - Yellow Rectangle: Future/Upcoming window
   - Green Rectangle: Active/Entered window (Price has reached the start of window)
   - Vertical Line: Marks the center cluster date

This window represents the "opportunity period" where reversals are 
most likely to occur according to Gann Timer principles.

================================================================================
                            LABEL FORMAT
================================================================================

Labels show details for each line in the cluster:
   - Time period type (e.g., "90TD", "180CD")
   - Source pivot info (e.g., "from 2024.08.15 HI")

Example Labels:
   - "90TD from 2024.08.15 LO"
   - "180CD from 2024.09.28 HI"

Labels are:
   - Stacked vertically at the right side of the chart
   - Positioned at the cluster line
   - Can be hidden for past dates to reduce clutter

================================================================================
                           NON-REPAINTING BEHAVIOR
================================================================================

The indicator is designed to be non-repainting:
   - Only recalculates when a new STABLE pivot is confirmed
   - Excludes the most recent forming bars from pivot detection
   - History remains stable once drawn

================================================================================
                             USAGE TIPS
================================================================================

1. START WITH DEFAULTS
   - The default settings are tuned for general Forex pairs (D1 timeframe).
   - Observe the clusters. If too many, increase 'Min Cluster Size' or 'Depth'.

2. ADJUST FOR VOLATILITY
   - High volatility: Increase ZigZag Deviation
   - Low volatility: Decrease ZigZag Deviation

3. CLUSTER SIGNIFICANCE
   - More lines in a cluster = stronger signal.
   - The indicator filters out "weak" clusters (less than 3 lines) by default.
   - You can see everything by setting 'Min Cluster Size' to 1 or enabling 'Show Single Lines'.

4. TIME WINDOWS
   - Watch for Yellow windows. When they turn Green, the time window is open.
   - Look for price action reversal signals within this green window.

================================================================================
                            LIMITATIONS
================================================================================

- Recommended for Daily (D1) timeframe analysis, though it works on others.
- Calculations use Daily data internally regardless of chart timeframe.
- Requires sufficient history (at least 2 years/730 days recommended).

================================================================================
                            COPYRIGHT
================================================================================

Developed for Karl Christoffersen
Based on Gann Time Cycle principles
Gann Timer concept from Gann Angles newsletter (1991)

================================================================================
END OF GUIDE
================================================================================