LibTmFr

Library "LibTmFr"
This is a utility library for handling timeframes and
multi-timeframe (MTF) analysis in Pine Script. It provides a
collection of functions designed to handle common tasks related
to period detection, session alignment, timeframe construction,
and time calculations, forming a foundation for
MTF indicators.

Key Capabilities:

1. **MTF Period Engine:** The library includes functions for
managing higher-timeframe (HTF) periods.
- **Period Detection (`isNewPeriod`):** Detects the first bar
of a given timeframe. It includes custom logic to handle
multi-month and multi-year intervals where
`timeframe.change()` may not be sufficient.
- **Bar Counting (`sinceNewPeriod`):** Counts the number of
bars that have passed in the current HTF period or
returns the final count for a completed historical period.

2. **Automatic Timeframe Selection:** Offers functions for building
a top-down analysis framework:
- **Automatic HTF (`autoHTF`):** Suggests a higher timeframe
(HTF) for broader context based on the current timeframe.
- **Automatic LTF (`autoLTF`):** Suggests an appropriate lower
timeframe (LTF) for granular intra-bar analysis.

3. **Timeframe Manipulation and Comparison:** Includes tools for
working with timeframe strings:
- **Build & Split (`buildTF`, `splitTF`):** Functions to
programmatically construct valid Pine Script timeframe
strings (e.g., "4H") and parse them back into their
numeric and unit components.
- **Comparison (`isHigherTF`, `isActiveTF`, `isLowerTF`):**
A set of functions to check if a given timeframe is
higher, lower, or the same as the script's active timeframe.
- **Multiple Validation (`isMultipleTF`):** Checks if a
higher timeframe is a practical multiple of the current
timeframe. This is based on the assumption that checking
if recent, completed HTF periods contained more than one
bar is a valid proxy for preventing data gaps.

4. **Timestamp Interpolation:** Contains an `interpTimestamp()`
function that calculates an absolute timestamp by
interpolating at a given percentage across a specified
range of bars (e.g., 50% of the way through the last
20 bars), enabling time calculations at a resolution
finer than the chart's native bars.

---

**DISCLAIMER**

This library is provided "AS IS" and for informational and
educational purposes only. It does not constitute financial,
investment, or trading advice.

The author assumes no liability for any errors, inaccuracies,
or omissions in the code. Using this library to build
trading indicators or strategies is entirely at your own risk.

As a developer using this library, you are solely responsible
for the rigorous testing, validation, and performance of any
scripts you create based on these functions. The author shall
not be held liable for any financial losses incurred directly
or indirectly from the use of this library or any scripts
derived from it.

buildTF(quantity, unit)
  Builds a Pine Script timeframe string from a numeric quantity and a unit enum.
The resulting string can be used with `request.security()` or `input.timeframe`.
  Parameters:
    quantity (int): series int Number to specifie how many `unit` the timeframe spans.
    unit (series TFUnit): series TFUnit The size category for the bars.
  Returns: series string A Pine-style timeframe identifier, e.g.
"5S" → 5-seconds bars
"30" → 30-minute bars
"120" → 2-hour bars
"1D" → daily bars
"3M" → 3-month bars
"24M" → 2-year bars

splitTF(tf)
  Splits a Pine‑timeframe identifier into numeric quantity and unit (TFUnit).
  Parameters:
    tf (string): series string Timeframe string, e.g.
"5S", "30", "120", "1D", "3M", "24M".
  Returns: [quantity, unit]
quantity series int The numeric value of the timeframe (e.g., 15 for "15", 3 for "3M").
unit series TFUnit The unit of the timeframe (e.g., TFUnit.minutes, TFUnit.months).

Notes on strings without a suffix:
• Pure digits are minutes; if divisible by 60, they are treated as hours.
• An "M" suffix is months; if divisible by 12, it is converted to years.

autoHTF(tf)
  Picks an appropriate **higher timeframe (HTF)** relative to the selected timeframe.
It steps up along a coarse ladder to produce sensible jumps for top‑down analysis.

Mapping → chosen HTF:
≤ 1 min → 60 (1h) ≈ ×60
≤ 3 min → 180 (3h) ≈ ×60
≤ 5 min → 240 (4h) ≈ ×48
≤ 15 min → D (1 day) ≈ ×26–×32 (regular session 6.5–8 h)
> 15 min → W (1 week) ≈ ×64–×80 for 30m; varies with input
≤ 1 h → W (1 week) ≈ ×32–×40
≤ 4 h → M (1 month) ≈ ×36–×44 (~22 trading days / month)
> 4 h → 3M (3 months) ≈ ×36–×66 (e.g., 12h→×36–×44; 8h→×53–×66)
≤ 1 day → 3M (3 months) ≈ ×60–×66 (~20–22 trading days / month)
> 1 day → 12M (1 year) ≈ ×(252–264)/quantity
≤ 1 week → 12M (1 year) ≈ ×52
> 1 week → 48M (4 years) ≈ ×(208)/quantity
= 1 M → 48M (4 years) ≈ ×48
> 1 M → error ("HTF too big")
any → error ("HTF too big")

Notes:
• Inputs in months or years are restricted: only 1M is allowed; larger months/any years throw.
• Returns a Pine timeframe string usable in `request.security()` and `input.timeframe`.
  Parameters:
    tf (string): series string Selected timeframe (e.g., "D", "240", or `timeframe.period`).
  Returns: series string Suggested higher timeframe.

autoLTF(tf)
  Selects an appropriate **lower timeframe LTF)** for intra‑bar evaluation
based on the selected timeframe. The goal is to keep intra‑bar
loops performant while providing enough granularity.

Mapping → chosen LTF:
≤ 1 min → 1S ≈ ×60
≤ 5 min → 5S ≈ ×60
≤ 15 min → 15S ≈ ×60
≤ 30 min → 30S ≈ ×60
> 30 min → 60S (1m) ≈ ×31–×59 (for 31–59 minute charts)
≤ 1 h → 1 (1m) ≈ ×60
≤ 2 h → 2 (2m) ≈ ×60
≤ 4 h → 5 (5m) ≈ ×48
> 4 h → 15 (15m) ≈ ×24–×48 (e.g., 6h→×24, 8h→×32, 12h→×48)
≤ 1 day → 15 (15m) ≈ ×26–×32 (regular sessions ~6.5–8h)
> 1 day → 60 (60m) ≈ ×(26–32) per day × quantity
≤ 1 week → 60 (60m) ≈ ×32–×40 (≈5 sessions of ~6.5–8h)
> 1 week → 240 (4h) ≈ ×(8–10) per week × quantity
≤ 1 M → 240 (4h) ≈ ×33–×44 (~20–22 sessions × 6.5–8h / 4h)
≤ 3 M → D (1d) ≈ ×(20–22) per month × quantity
> 3 M → W (1w) ≈ ×(4–5) per month × quantity
≤ 1 Y → W (1w) ≈ ×52
> 1 Y → M (1M) ≈ ×12 per year × quantity

Notes:
• Ratios for D/W/M are given as ranges because they depend on
**regular session length** (typically ~6.5–8h, not 24h).
• Returned strings can be used with `request.security()` and `input.timeframe`.
  Parameters:
    tf (string): series string Selected timeframe (e.g., "D", "240", or timeframe.period).
  Returns: series string Suggested lower TF to use for intra‑bar work.

isNewPeriod(tf, offset)
  Returns `true` when a new session-aligned period begins, or on the Nth bar of that period.
  Parameters:
    tf (string): series string Target higher timeframe (e.g., "D", "W", "M").
    offset (simple int): simple int 0 → checks for the first bar of the new period.
1+ → checks for the N-th bar of the period.
  Returns: series bool `true` if the condition is met.

sinceNewPeriod(tf, offset)
  Counts how many bars have passed within a higher timeframe (HTF) period.
For daily, weekly, and monthly resolutions, the period is aligned with the trading session.
  Parameters:
    tf (string): series string Target parent timeframe (e.g., "60", "D").
    offset (simple int): simple int 0 → Running count for the current period.
1+ → Finalized count for the Nth most recent *completed* period.
  Returns: series int Number of bars.

isHigherTF(tf, main)
  Returns `true` when the selected timeframe represents a
higher resolution than the active timeframe.
  Parameters:
    tf (string): series string Selected timeframe.
    main (bool): series bool When `true`, the comparison is made against the chart's main timeframe
instead of the script's active timeframe. Optional. Defaults to `false`.
  Returns: series bool `true` if `tf` > active TF; otherwise `false`.

isActiveTF(tf, main)
  Returns `true` when the selected timeframe represents the
exact resolution of the active timeframe.
  Parameters:
    tf (string): series string Selected timeframe.
    main (bool): series bool When `true`, the comparison is made against the chart's main timeframe
instead of the script's active timeframe. Optional. Defaults to `false`.
  Returns: series bool `true` if `tf` == active TF; otherwise `false`.

isLowerTF(tf, main)
  Returns `true` when the selected timeframe represents a
lower resolution than the active timeframe.
  Parameters:
    tf (string): series string Selected timeframe.
    main (bool): series bool When `true`, the comparison is made against the chart's main timeframe
instead of the script's active timeframe. Optional. Defaults to `false`.
  Returns: series bool `true` if `tf` < active TF; otherwise `false`.

isMultipleTF(tf)
  Returns `true` if the selected timeframe (`tf`) is a practical multiple
of the active skript's timeframe. It verifies this by checking if `tf` is a higher timeframe
that has consistently contained more than one bar of the skript's timeframe in recent periods.
The period detection is session-aware.
  Parameters:
    tf (string): series string The higher timeframe to check.
  Returns: series bool `true` if `tf` is a practical multiple; otherwise `false`.

interpTimestamp(offStart, offEnd, pct)
  Calculates a precise absolute timestamp by interpolating within a bar range based on a percentage.
This version works with RELATIVE bar offsets from the current bar.
  Parameters:
    offStart (int): series int The relative offset of the starting bar (e.g., 10 for 10 bars ago).
    offEnd (int): series int The relative offset of the ending bar (e.g., 1 for 1 bar ago). Must be <= offStart.
    pct (float): series float The percentage of the bar range to measure (e.g., 50.5 for 50.5%).
Values are clamped to the [0, 100] range.
  Returns: series int The calculated, interpolated absolute Unix timestamp in milliseconds.