analysis

analysis

Modules:

Name	Description
movement
patterns
utils

Functions:

Name	Description
bars_since	Bars Since Analysis
change	Change Analysis
cross	Cross Analysis
crossover	Crossover Analysis
crossunder	Crossunder Analysis
doji	Doji Pattern
dojistar	Dojistar Pattern
falling	Falling Analysis
falling_count	Falling Count Analysis
hammer	Hammer Pattern
highest	Highest Reading Analysis
highestbar	Highest Bar Offset Analysis
inverted_hammer	Inverted Hammer Pattern
lowest	Lowest Reading Analysis
lowestbar	Lowest Bar Offset Analysis
mean_falling	Mean Falling Analysis
mean_rising	Mean Rising Analysis
percent_change	Percent Change Analysis
rising	Rising Analysis
rising_count	Rising Count Analysis
value_range	Value Range Analysis
value_when	Value When Analysis

bars_since

bars_since(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    value: float | int | bool = True,
    index: int = -1,
) -> int | None

Bars Since Analysis

Returns how many bars ago the given indicator last matched value. A return value of 0 means the current bar matches. If no match exists, returns None.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The indicator series to scan.	required
value	float | int | bool	The value to match against. Defaults to True.	True
index	int	The index to start the backward scan from. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
int | None	int | None: The number of bars since the most recent matching value,
int | None	or None if no matching value exists.

Source code in hexital/analysis/movement.py

def bars_since(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    value: float | int | bool = True,
    index: int = -1,
) -> int | None:
    """Bars Since Analysis

    Returns how many bars ago the given `indicator` last matched `value`.
    A return value of `0` means the current bar matches. If no match exists,
    returns `None`.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The indicator series to scan.
        value (float | int | bool, optional): The value to match against. Defaults to `True`.
        index (int, optional): The index to start the backward scan from.
            Defaults to -1 (latest candle).

    Returns:
        int | None: The number of bars since the most recent matching value,
        or `None` if no matching value exists.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set:
        return None

    idx = absindex(index, len(candle_set))

    for offset, candle_idx in enumerate(range(idx, -1, -1)):
        if reading_by_index(candle_set, indicator, candle_idx) == value:
            return offset

    return None

change

change(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> float | int | None

Change Analysis

Returns the difference between the current reading and the reading length bars back.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The indicator series to compare.	required
length	int	How many bars back to compare against. Defaults to 1.	1
index	int	The index to evaluate from. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
float | int | None	float | int | None: The current reading minus the reading length bars back,
float | int | None	or None if there is insufficient valid data.

Source code in hexital/analysis/movement.py

def change(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> float | int | None:
    """Change Analysis

    Returns the difference between the current reading and the reading
    `length` bars back.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The indicator series to compare.
        length (int, optional): How many bars back to compare against. Defaults to 1.
        index (int, optional): The index to evaluate from. Defaults to -1 (latest candle).

    Returns:
        float | int | None: The current reading minus the reading `length` bars back,
        or `None` if there is insufficient valid data.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set or length < 1:
        return None

    idx = absindex(index, len(candle_set))
    current = _scalar_reading(candle_set, indicator, idx)
    previous = _scalar_reading(candle_set, indicator, idx - length)

    if current is None or previous is None:
        return None

    return current - previous

cross

cross(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    indicator_cmp: str,
    length: int = 1,
    index: int = -1,
) -> bool

Cross Analysis

Determines whether the indicator reading has crossed the indicator_cmp reading within a specified range of candles. The cross can occur in either direction.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The primary indicator to evaluate.	required
indicator_cmp	str	The secondary indicator to compare against.	required
length	int	The number of candles to include in the range. Defaults to 1. (compares the latest with the previous).	1
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if indicator has crossed indicator_cmp within the specified range; otherwise False.

Source code in hexital/analysis/movement.py

def cross(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    indicator_cmp: str,
    length: int = 1,
    index: int = -1,
) -> bool:
    """Cross Analysis

    Determines whether the `indicator` reading has crossed the `indicator_cmp` reading
    within a specified range of candles. The cross can occur in either direction.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The primary indicator to evaluate.
        indicator_cmp (str): The secondary indicator to compare against.
        length (int, optional): The number of candles to include in the range. Defaults to 1.
            (compares the latest with the previous).
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if `indicator` has crossed `indicator_cmp` within the specified range; otherwise `False`.
    """
    candles_ = _retrieve_candles(candles, indicator, indicator_cmp)

    if isinstance(candles_, list):
        idx = absindex(index, len(candles_)) + 1
        length = idx - (length + 1)
        return _cross(
            candles_[length:idx], indicator, candles_[length:idx], indicator_cmp
        )

    if isinstance(candles_, tuple):
        candle_set = _timeframe_pair_candles(candles_)
        idx = absindex(index, len(candle_set[0])) + 1
        length = idx - (length + 1)
        return _cross(
            candle_set[0][length:idx],
            indicator,
            candle_set[1][length:idx],
            indicator_cmp,
        )

    return False

crossover

crossover(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    indicator_cmp: str,
    length: int = 1,
    index: int = -1,
) -> bool

Crossover Analysis

Determines whether the indicator reading has crossed over the indicator_cmp reading within a specified range of candles. A crossover occurs when indicator transitions from below to above indicator_cmp within the given range.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The primary indicator to evaluate.	required
indicator_cmp	str	The secondary indicator to compare against.	required
length	int	The number of candles to include in the range. Defaults to 1. If length exceeds the total number of candles, all available candles are checked.	1
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if indicator has crossed over indicator_cmp within the specified range;
	bool	otherwise False.

Source code in hexital/analysis/movement.py

def crossover(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    indicator_cmp: str,
    length: int = 1,
    index: int = -1,
) -> bool:
    """Crossover Analysis

    Determines whether the `indicator` reading has crossed over the `indicator_cmp` reading
    within a specified range of candles. A crossover occurs when `indicator` transitions from below
    to above `indicator_cmp` within the given range.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The primary indicator to evaluate.
        indicator_cmp (str): The secondary indicator to compare against.
        length (int, optional): The number of candles to include in the range. Defaults to 1.
            If `length` exceeds the total number of candles, all available candles are checked.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if `indicator` has crossed over `indicator_cmp` within the specified range;
        otherwise `False`.
    """
    candles_ = _retrieve_candles(candles, indicator, indicator_cmp)

    if isinstance(candles_, list):
        idx = absindex(index, len(candles_)) + 1
        length = idx - (length + 1)
        return _crossover(
            candles_[length:idx], indicator, candles_[length:idx], indicator_cmp
        )

    if isinstance(candles_, tuple):
        candle_set = _timeframe_pair_candles(candles_)
        idx = absindex(index, len(candle_set[0])) + 1
        length = idx - (length + 1)

        return _crossover(
            candle_set[0][length:idx],
            indicator,
            candle_set[1][length:idx],
            indicator_cmp,
        )

    return False

crossunder

crossunder(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    indicator_cmp: str,
    length: int = 1,
    index: int = -1,
) -> bool

Crossunder Analysis

Determines whether the indicator reading has crossed under the indicator_cmp reading within a specified range of candles. A crossunder occurs when indicator transitions from above to below indicator_cmp within the given range.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The primary indicator to evaluate.	required
indicator_cmp	str	The secondary indicator to compare against.	required
length	int	The number of candles to include in the range. Defaults to 1. If length exceeds the total number of candles, all available candles are checked.	1
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if indicator has crossed under indicator_cmp within the specified range;
	bool	otherwise False.

Source code in hexital/analysis/movement.py

def crossunder(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    indicator_cmp: str,
    length: int = 1,
    index: int = -1,
) -> bool:
    """Crossunder Analysis

    Determines whether the `indicator` reading has crossed under the `indicator_cmp` reading
    within a specified range of candles. A crossunder occurs when `indicator` transitions from above
    to below `indicator_cmp` within the given range.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The primary indicator to evaluate.
        indicator_cmp (str): The secondary indicator to compare against.
        length (int, optional): The number of candles to include in the range. Defaults to 1.
            If `length` exceeds the total number of candles, all available candles are checked.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if `indicator` has crossed under `indicator_cmp` within the specified range;
        otherwise `False`.
    """
    candles_ = _retrieve_candles(candles, indicator, indicator_cmp)

    if isinstance(candles_, list):
        idx = absindex(index, len(candles_)) + 1
        length = idx - (length + 1)
        return _crossunder(
            candles_[length:idx], indicator, candles_[length:idx], indicator_cmp
        )

    if isinstance(candles_, tuple):
        candle_set = _timeframe_pair_candles(candles_)
        idx = absindex(index, len(candle_set[0])) + 1
        length = idx - (length + 1)

        return _crossunder(
            candle_set[0][length:idx],
            indicator,
            candle_set[1][length:idx],
            indicator_cmp,
        )

    return False

doji

doji(
    candles: list[Candle], lookback: int | None = None, index: int | None = None
) -> bool

Doji Pattern A candle body is Doji when it's shorter than 10% of the average of the n(10) previous candles' high-low range.

Source: https://github.com/TA-Lib/ta-lib

Parameters:

Name	Type	Description	Default
candles	Optional[int]	Candles to use to find Doji Candle	required
lookback	Optional[int]	Lookback allows detecting an Doji candles N back. Defaults to None.	None
index	Optional[int]	Index of Candle to check. Defaults to None/Latest.	None

Returns:

Name	Type	Description
bool	bool	True if given Candle/Candle range is Doji

Source code in hexital/analysis/patterns.py

def doji(
    candles: list[Candle],
    lookback: int | None = None,
    index: int | None = None,
) -> bool:
    """Doji Pattern
    A candle body is Doji when it's shorter than 10% of the average of the
    n(10) previous candles' high-low range.

    Source: https://github.com/TA-Lib/ta-lib

    Args:
        candles (Optional[int]): Candles to use to find Doji Candle
        lookback (Optional[int]): Lookback allows detecting an Doji candles N back. Defaults to None.
        index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

    Returns:
        bool: True if given Candle/Candle range is Doji
    """
    index_ = absindex(index, len(candles))

    if lookback is None:
        return _doji(candles, index_)

    return any(_doji(candles, i) for i in range(len(candles) - lookback, len(candles)))

dojistar

dojistar(
    candles: list[Candle], lookback: int | None = None, index: int | None = None
) -> bool

Dojistar Pattern A Dojistar is either bearish or bullish, and is detected when we have a larger then average candle followed by a candle candle shorter than 10% of the average of the n(10) of the average and then the candle gaps up or down. A trend is required to find which direction.

Source: https://github.com/TA-Lib/ta-lib Args: candles (Optional[int]): Candles to use to find Dojistar Candle lookback (Optional[int]): Lookback allows detecting an Dojistar candles N back. Defaults to None. index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

Returns:

Name	Type	Description
bool	bool	True if given Candle/Candle range is Doji star

Source code in hexital/analysis/patterns.py

def dojistar(
    candles: list[Candle],
    lookback: int | None = None,
    index: int | None = None,
) -> bool:
    """Dojistar Pattern
    A Dojistar is either bearish or bullish, and is detected when we have a larger then average
    candle followed by a candle candle shorter than 10% of the average of the
    n(10) of the average and then the candle gaps up or down.
    A trend is required to find which direction.

    Source: https://github.com/TA-Lib/ta-lib
    Args:
        candles (Optional[int]): Candles to use to find Dojistar Candle
        lookback (Optional[int]): Lookback allows detecting an Dojistar candles N back. Defaults to None.
        index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

    Returns:
        bool: True if given Candle/Candle range is Doji star
    """
    index_ = absindex(index, len(candles))

    if lookback is None:
        return _dojistar(candles, index_)

    return any(
        _dojistar(candles, i) for i in range(len(candles) - lookback, len(candles))
    )

falling

falling(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> bool

Falling Analysis

Determines whether the indicator consistently falling across a specified range of candles. By default, it checks if the current indicator value is lower than the previous one.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 1. (compares the latest with the previous).	1
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if the indicator is lower than each previous readings in the range; otherwise False.

Source code in hexital/analysis/movement.py

def falling(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> bool:
    """Falling Analysis

    Determines whether the `indicator` consistently falling across a specified range of candles.
    By default, it checks if the current indicator value is lower than the previous one.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 1.
            (compares the latest with the previous).
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if the `indicator` is lower than each previous readings in the range; otherwise `False`.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if (
        not isinstance(candle_set, list)
        or not candle_set
        or length < 1
        or len(candle_set) < 2
    ):
        return False

    idx = absindex(index, len(candle_set))

    latest_reading = _scalar_reading(candle_set, indicator, idx)
    if latest_reading is None:
        return False

    readings = get_readings_period(candle_set, indicator, length, idx)
    if not readings:
        return False

    return all(reading > latest_reading for reading in readings)

falling_count

falling_count(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 100,
    index: int = -1,
) -> int

Falling Count Analysis

Counts consecutive falling bars ending at index, up to length comparisons back.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The indicator series to evaluate.	required
length	int	Maximum number of backward comparisons to check. Defaults to 100.	100
index	int	The index to evaluate from. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
int	int	The number of consecutive falling comparisons ending at index.

Source code in hexital/analysis/movement.py

def falling_count(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 100,
    index: int = -1,
) -> int:
    """Falling Count Analysis

    Counts consecutive falling bars ending at `index`, up to `length`
    comparisons back.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The indicator series to evaluate.
        length (int, optional): Maximum number of backward comparisons to check.
            Defaults to 100.
        index (int, optional): The index to evaluate from. Defaults to -1 (latest candle).

    Returns:
        int: The number of consecutive falling comparisons ending at `index`.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set or length < 1:
        return 0

    idx = absindex(index, len(candle_set))
    count = 0

    for candle_idx in range(idx, idx - length, -1):
        current = _scalar_reading(candle_set, indicator, candle_idx)
        previous = _scalar_reading(candle_set, indicator, candle_idx - 1)

        if current is None or previous is None or current >= previous:
            break

        count += 1

    return count

hammer

hammer(
    candles: list[Candle], lookback: int | None = None, index: int | None = None
) -> bool | int

Hammer Pattern A Hammer is detected when the Candle's open and close values are considered shorter than 10% of the average of the n(10) candles. However the low is larger than the average.

Source: https://github.com/TA-Lib/ta-lib Args: candles (Optional[int]): Candles to use to find Hammer Candle lookback (Optional[int]): Lookback allows detecting an Hammer candles N back. Defaults to None. index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

Returns:

Name	Type	Description
bool	bool | int	True if given Candle/Candle range is Hammer

Source code in hexital/analysis/patterns.py

def hammer(
    candles: list[Candle],
    lookback: int | None = None,
    index: int | None = None,
) -> bool | int:
    """Hammer Pattern
    A Hammer is detected when the Candle's open and close values are considered shorter
    than 10% of the average of the n(10) candles. However the low is larger than the average.

    Source: https://github.com/TA-Lib/ta-lib
    Args:
        candles (Optional[int]): Candles to use to find Hammer Candle
        lookback (Optional[int]): Lookback allows detecting an Hammer candles N back. Defaults to None.
        index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

    Returns:
        bool: True if given Candle/Candle range is Hammer
    """
    index_ = absindex(index, len(candles))

    if lookback is None:
        return _hammer(candles, index_)

    return any(_hammer(candles, i) for i in range(len(candles) - lookback, len(candles)))

highest

highest(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> float | None

Highest Reading Analysis

Determines the highest value of the specified indicator over a given number of candles. By default, includes the latest candle and evaluates up to the previous four candles.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
float | None	float | None: The highest reading for the specified indicator within the range,
float | None	or None if no valid readings are found.

Source code in hexital/analysis/movement.py

def highest(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> float | None:
    """Highest Reading Analysis

    Determines the highest value of the specified `indicator` over a given number of candles.
    By default, includes the latest candle and evaluates up to the previous four candles.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        float | None: The highest reading for the specified `indicator` within the range,
        or `None` if no valid readings are found.
    """
    candles_ = _retrieve_candles(candles, indicator)
    if not isinstance(candles_, list):
        return None
    return utils.highest(candles_, indicator, length, index)

highestbar

highestbar(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> int | None

Highest Bar Offset Analysis

Determines the offset (distance) to the candle with the highest reading of the specified indicator within a given range. By default, includes the latest candle and evaluates up to the previous four candles.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
int | None	int | None: The offset to the candle with the highest reading, relative to the starting index,
int | None	or None if no valid readings are found.

Source code in hexital/analysis/movement.py

def highestbar(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> int | None:
    """Highest Bar Offset Analysis

    Determines the offset (distance) to the candle with the highest reading of the specified `indicator`
    within a given range. By default, includes the latest candle and evaluates up to the previous four candles.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        int | None: The offset to the candle with the highest reading, relative to the starting index,
        or `None` if no valid readings are found.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set:
        return None

    idx = absindex(index, len(candle_set))

    high = None
    distance = 0

    for offset, candle_idx in enumerate(range(idx, idx - length, -1)):
        current = _scalar_reading(candle_set, indicator, candle_idx)
        if current is None:
            continue

        if high is None or high < current:
            high = current
            distance = offset

    return distance

inverted_hammer

inverted_hammer(
    candles: list[Candle], lookback: int | None = None, index: int | None = None
) -> bool | int

Inverted Hammer Pattern An Inverted Hammer is detected when the Candle's open and close values are considered shorter than 10% of the average of the n(10) candles. However the high is larger than the average.

Source: https://github.com/TA-Lib/ta-lib Args: candles (Optional[int]): Candles to use to find Inverted Hammer Candle lookback (Optional[int]): Lookback allows detecting an InvertedHammer candles N back. Defaults to None. index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

Returns:

Name	Type	Description
bool	bool | int	True if given Candle/Candle range is Inverted Hammer

Source code in hexital/analysis/patterns.py

def inverted_hammer(
    candles: list[Candle],
    lookback: int | None = None,
    index: int | None = None,
) -> bool | int:
    """Inverted Hammer Pattern
    An Inverted Hammer is detected when the Candle's open and close values are considered shorter
    than 10% of the average of the n(10) candles. However the high is larger than the average.

    Source: https://github.com/TA-Lib/ta-lib
    Args:
        candles (Optional[int]): Candles to use to find Inverted Hammer Candle
        lookback (Optional[int]): Lookback allows detecting an InvertedHammer candles N back. Defaults to None.
        index (Optional[int]): Index of Candle to check. Defaults to None/Latest.

    Returns:
        bool: True if given Candle/Candle range is Inverted Hammer
    """
    index_ = absindex(index, len(candles))

    if lookback is None:
        return _inverted_hammer(candles, index_)

    return any(
        _inverted_hammer(candles, i) for i in range(len(candles) - lookback, len(candles))
    )

lowest

lowest(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> float | None

Lowest Reading Analysis

Determines the lowest value of the specified indicator over a given number of candles. By default, includes the latest candle and evaluates up to the previous four candles.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
float | None	float | None: The lowest reading for the specified indicator within the range,
float | None	or None if no valid readings are found.

Source code in hexital/analysis/movement.py

def lowest(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> float | None:
    """Lowest Reading Analysis

    Determines the lowest value of the specified `indicator` over a given number of candles.
    By default, includes the latest candle and evaluates up to the previous four candles.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        float | None: The lowest reading for the specified `indicator` within the range,
        or `None` if no valid readings are found.
    """
    candles_ = _retrieve_candles(candles, indicator)
    if not isinstance(candles_, list):
        return None
    return utils.lowest(candles_, indicator, length, index)

lowestbar

lowestbar(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> int | None

Lowest Bar Offset Analysis

Determines the offset (distance) to the candle with the lowest reading of the specified indicator within a given range. By default, includes the latest candle and evaluates up to the previous four candles.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
int | None	int | None: The offset to the candle with the lowest reading, relative to the starting index,
int | None	or None if no valid readings are found.

Source code in hexital/analysis/movement.py

def lowestbar(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> int | None:
    """Lowest Bar Offset Analysis

    Determines the offset (distance) to the candle with the lowest reading of the specified `indicator`
    within a given range. By default, includes the latest candle and evaluates up to the previous four candles.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        int | None: The offset to the candle with the lowest reading, relative to the starting index,
        or `None` if no valid readings are found.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set:
        return None

    idx = absindex(index, len(candle_set))

    low = None
    distance = 0

    for offset, candle_idx in enumerate(range(idx, idx - length, -1)):
        current = _scalar_reading(candle_set, indicator, candle_idx)
        if current is None:
            continue

        if low is None or low > current:
            low = current
            distance = offset

    return distance

mean_falling

mean_falling(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> bool

Mean Falling Analysis

Evaluates whether the indicator is, on average, falling across a specified range of candles. By default, it checks if the current indicator value is lower than the average of the previous four readings.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if the indicator is lower than the average of the specified n readings; otherwise False.

Source code in hexital/analysis/movement.py

def mean_falling(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> bool:
    """Mean Falling Analysis

    Evaluates whether the `indicator` is, on average, falling across a specified range of candles.
    By default, it checks if the current indicator value is lower than the average of the previous four readings.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if the `indicator` is lower than the average of the specified `n` readings; otherwise `False`.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if (
        not isinstance(candle_set, list)
        or not candle_set
        or length < 1
        or len(candle_set) < 2
    ):
        return False

    idx = absindex(index, len(candle_set))

    latest_reading = _scalar_reading(candle_set, indicator, idx)
    if latest_reading is None:
        return False

    readings = get_readings_period(candle_set, indicator, length, idx)
    if not readings:
        return False

    return sum(readings) / len(readings) > latest_reading

mean_rising

mean_rising(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> bool

Mean Rising Analysis

Evaluates whether the indicator is, on average, rising across a specified range of candles. By default, it checks if the current indicator value is higher than the average of the previous four readings.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if the indicator is higher than the average of the specified n readings; otherwise False.

Source code in hexital/analysis/movement.py

def mean_rising(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> bool:
    """Mean Rising Analysis

    Evaluates whether the `indicator` is, on average, rising across a specified range of candles.
    By default, it checks if the current indicator value is higher than the average of the previous four readings.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if the `indicator` is higher than the average of the specified `n` readings; otherwise `False`.
    """

    candle_set = _retrieve_candles(candles, indicator)
    if (
        not isinstance(candle_set, list)
        or not candle_set
        or length < 1
        or len(candle_set) < 2
    ):
        return False

    idx = absindex(index, len(candle_set))

    latest_reading = _scalar_reading(candle_set, indicator, idx)
    if latest_reading is None:
        return False

    readings = get_readings_period(candle_set, indicator, length, idx)
    if not readings:
        return False

    return sum(readings) / len(readings) < latest_reading

percent_change

percent_change(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> float | None

Percent Change Analysis

Returns the percentage change between the current reading and the reading length bars back.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The indicator series to compare.	required
length	int	How many bars back to compare against. Defaults to 1.	1
index	int	The index to evaluate from. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
float | None	float | None: The percentage change from the reading length bars back to the
float | None	current reading, or None if there is insufficient valid data or the prior value is zero.

Source code in hexital/analysis/movement.py

def percent_change(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> float | None:
    """Percent Change Analysis

    Returns the percentage change between the current reading and the reading
    `length` bars back.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The indicator series to compare.
        length (int, optional): How many bars back to compare against. Defaults to 1.
        index (int, optional): The index to evaluate from. Defaults to -1 (latest candle).

    Returns:
        float | None: The percentage change from the reading `length` bars back to the
        current reading, or `None` if there is insufficient valid data or the prior value is zero.
    """
    delta = change(candles, indicator, length, index)
    if delta is None:
        return None

    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set:
        return None

    idx = absindex(index, len(candle_set))
    previous = _scalar_reading(candle_set, indicator, idx - length)

    if previous in (None, 0):
        return None

    return (delta / previous) * 100

rising

rising(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> bool

Rising Analysis

Determines whether the indicator consistently rises across a specified range of candles. By default, it checks if the current indicator value is greater than the previous one.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 1. (compares the latest with the previous).	1
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
bool	bool	True if the indicator is greater than each previous readings in the range; otherwise False.

Source code in hexital/analysis/movement.py

def rising(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 1,
    index: int = -1,
) -> bool:
    """Rising Analysis

    Determines whether the `indicator` consistently rises across a specified range of candles.
    By default, it checks if the current indicator value is greater than the previous one.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 1.
            (compares the latest with the previous).
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if the `indicator` is greater than each previous readings in the range; otherwise `False`.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if (
        not isinstance(candle_set, list)
        or not candle_set
        or length < 1
        or len(candle_set) < 2
    ):
        return False

    idx = absindex(index, len(candle_set))

    latest_reading = _scalar_reading(candle_set, indicator, idx)
    if latest_reading is None:
        return False

    readings = get_readings_period(candle_set, indicator, length, idx)
    if not readings:
        return False

    return all(reading < latest_reading for reading in readings)

rising_count

rising_count(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 100,
    index: int = -1,
) -> int

Rising Count Analysis

Counts consecutive rising bars ending at index, up to length comparisons back.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The indicator series to evaluate.	required
length	int	Maximum number of backward comparisons to check. Defaults to 100.	100
index	int	The index to evaluate from. Defaults to -1 (latest candle).	-1

Returns:

Name	Type	Description
int	int	The number of consecutive rising comparisons ending at index.

Source code in hexital/analysis/movement.py

def rising_count(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 100,
    index: int = -1,
) -> int:
    """Rising Count Analysis

    Counts consecutive rising bars ending at `index`, up to `length`
    comparisons back.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The indicator series to evaluate.
        length (int, optional): Maximum number of backward comparisons to check.
            Defaults to 100.
        index (int, optional): The index to evaluate from. Defaults to -1 (latest candle).

    Returns:
        int: The number of consecutive rising comparisons ending at `index`.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set or length < 1:
        return 0

    idx = absindex(index, len(candle_set))
    count = 0

    for candle_idx in range(idx, idx - length, -1):
        current = _scalar_reading(candle_set, indicator, candle_idx)
        previous = _scalar_reading(candle_set, indicator, candle_idx - 1)

        if current is None or previous is None or current <= previous:
            break

        count += 1

    return count

value_range

value_range(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> float | None

Value Range Analysis

Calculates the difference between the minimum and maximum values for the given indicator within a specified range of candles. Includes the latest candle by default. If the specified length exceeds the available candles, it will evaluate all candles.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The name of the indicator to evaluate.	required
length	int	The number of candles to include in the range. Defaults to 4.	4
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
float | None	float | None: The difference between the minimum and maximum indicator values in the range,
float | None	or None if there are insufficient readings.

Source code in hexital/analysis/movement.py

def value_range(
    candles: Indicator | Hexital | list[Candle],
    indicator: str,
    length: int = 4,
    index: int = -1,
) -> float | None:
    """Value Range Analysis

    Calculates the difference between the minimum and maximum values for the given `indicator`
    within a specified range of candles. Includes the latest candle by default. If the specified
    length exceeds the available candles, it will evaluate all candles.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The name of the indicator to evaluate.
        length (int, optional): The number of candles to include in the range. Defaults to 4.
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        float | None: The difference between the minimum and maximum indicator values in the range,
        or `None` if there are insufficient readings.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set:
        return None

    readings = get_readings_period(candle_set, indicator, length, index, True)

    if len(readings) < 2:
        return None

    return abs(min(readings) - max(readings))

value_when

value_when(
    candles: Indicator | Hexital | list[Candle],
    condition_indicator: str,
    indicator: str,
    value: float | int | bool = True,
    occurrence: int = 0,
    index: int = -1,
) -> float | dict | None

Value When Analysis

Returns the indicator reading from the nth most recent bar where condition_indicator matched value. occurrence=0 means the latest match.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
condition_indicator	str	The indicator series used as the condition.	required
indicator	str	The indicator reading to return when the condition matches.	required
value	float | int | bool	The value the condition indicator must equal. Defaults to True.	True
occurrence	int	Which matching occurrence to return, where 0 is the latest match. Defaults to 0.	0
index	int	The index to start the backward scan from. Defaults to -1 (latest candle).	-1

Returns:

Type	Description
float | dict | None	float | dict | None: The reading of indicator at the requested matching occurrence,
float | dict | None	or None if no such match exists.

Source code in hexital/analysis/movement.py

def value_when(
    candles: Indicator | Hexital | list[Candle],
    condition_indicator: str,
    indicator: str,
    value: float | int | bool = True,
    occurrence: int = 0,
    index: int = -1,
) -> float | dict | None:
    """Value When Analysis

    Returns the `indicator` reading from the nth most recent bar where
    `condition_indicator` matched `value`. `occurrence=0` means the latest match.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        condition_indicator (str): The indicator series used as the condition.
        indicator (str): The indicator reading to return when the condition matches.
        value (float | int | bool, optional): The value the condition indicator must equal.
            Defaults to `True`.
        occurrence (int, optional): Which matching occurrence to return, where `0` is the
            latest match. Defaults to 0.
        index (int, optional): The index to start the backward scan from.
            Defaults to -1 (latest candle).

    Returns:
        float | dict | None: The reading of `indicator` at the requested matching occurrence,
        or `None` if no such match exists.
    """
    candle_set = _retrieve_candles(candles, condition_indicator)
    if not isinstance(candle_set, list) or not candle_set or occurrence < 0:
        return None

    idx = absindex(index, len(candle_set))
    found = 0

    for candle_idx in range(idx, -1, -1):
        if reading_by_index(candle_set, condition_indicator, candle_idx) != value:
            continue

        if found == occurrence:
            return reading_by_index(candle_set, indicator, candle_idx)

        found += 1

    return None