movement

movement

Functions:

Name	Description
above	Above Analysis
bars_since	Bars Since Analysis
below	Below Analysis
change	Change Analysis
cross	Cross Analysis
crossover	Crossover Analysis
crossunder	Crossunder Analysis
falling	Falling Analysis
falling_count	Falling Count Analysis
flipped	Flipped Reading Analysis
highest	Highest Reading Analysis
highestbar	Highest Bar Offset Analysis
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

above

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

Above Analysis

Checks whether the indicator reading is higher than the indicator_cmp reading. By default, it evaluates the latest candle but can also check n candles back. If any candle within the specified range is above, it returns True.

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 0 (only the current index).	0
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

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

Source code in hexital/analysis/movement.py

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

    Checks whether the `indicator` reading is higher than the `indicator_cmp` reading.
    By default, it evaluates the latest candle but can also check `n` candles back.
    If any candle within the specified range is above, it returns `True`.

    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 0 (only the current index).
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if `indicator` is above `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 _above(
            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 _above(
            candle_set[0][length:idx],
            indicator,
            candle_set[1][length:idx],
            indicator_cmp,
        )

    return False

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

below

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

Below Analysis

Checks whether the indicator reading is lower than the indicator_cmp reading. By default, it evaluates the latest candle but can also check n candles back. If any candle within the specified range is below, it returns True.

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 0 (only the current index).	0
index	int	The index to start the evaluation. Defaults to -1 (latest candle).	-1

Returns:

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

Source code in hexital/analysis/movement.py

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

    Checks whether the `indicator` reading is lower than the `indicator_cmp` reading.
    By default, it evaluates the latest candle but can also check `n` candles back.
    If any candle within the specified range is below, it returns `True`.

    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 0 (only the current index).
        index (int, optional): The index to start the evaluation. Defaults to -1 (latest candle).

    Returns:
        bool: `True` if `indicator` is below `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 _below(
            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 _below(
            candle_set[0][length:idx],
            indicator,
            candle_set[1][length:idx],
            indicator_cmp,
        )

    return False

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

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

flipped

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

Flipped Reading Analysis

Determines whether the indicator has "flipped" its value, meaning the current reading is different from its previous reading, and within the last length candles, the indicator was above its previous reading.

Parameters:

Name	Type	Description	Default
candles	Indicator | Hexital | List[Candle]	The data source containing the indicators.	required
indicator	str	The indicator to evaluate.	required
length	int	The number of candles to check for a flip. 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 the indicator has flipped (current value differs from previous); otherwise False.

Source code in hexital/analysis/movement.py

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

    Determines whether the `indicator` has "flipped" its value, meaning the current reading is different
    from its previous reading, and within the last `length` candles, the indicator was above its previous reading.

    Args:
        candles (Indicator | Hexital | List[Candle]): The data source containing the indicators.
        indicator (str): The indicator to evaluate.
        length (int, optional): The number of candles to check for a flip. 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 the indicator has flipped (current value differs from previous); otherwise `False`.
    """
    candle_set = _retrieve_candles(candles, indicator)
    if not isinstance(candle_set, list) or not candle_set:
        return False

    idx = absindex(index, len(candle_set))

    for idx in range(idx, idx - length, -1):
        if reading_by_index(candle_set, indicator, idx) != reading_by_index(
            candle_set, indicator, idx - 1
        ):
            return True

    return False

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

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