tstrends.label_tuning package
Submodules
tstrends.label_tuning.base module
- tstrends.label_tuning.base.verify_time_series_and_labels(time_series, labels)[source]
Verify that time series and labels are valid for label tuning or filtering.
- class tstrends.label_tuning.base.BaseLabelTuner[source]
Bases:
ABCAbstract base class for all label tuners.
This class serves as a template for all label tuners. Label tuners take standard trend labels (-1, 1) or (-1, 0, 1) and enhance them with additional information about the potential trend magnitude.
- None
- class tstrends.label_tuning.base.BasePostprocessor[source]
Bases:
ABCCommon interface for post-processing tuned label values.
Filters, smoothers, and shifters implement
process()and can be chained bytstrends.label_tuning.RemainingValueTunervia apostprocessorslist.
- class tstrends.label_tuning.base.BaseFilter[source]
Bases:
BasePostprocessorAbstract base class for per-timestep filters on tuned label values.
Filters compute coefficients in
[0, 1](or a bounded range after flooring) that can be multiplied element-wise with tuned magnitudes to emphasize or suppress regions within each trend interval.- abstractmethod get_coefficients(time_series, labels)[source]
Compute per-timestep multiplicative coefficients.
- filter(values, time_series, labels)[source]
Multiply
valuesbyget_coefficients(time_series, labels).- Parameters:
- Returns:
Element-wise product as a float array.
- Raises:
ValueError – If
valueslength differs fromtime_series.- Return type:
- class tstrends.label_tuning.base.BaseSmoother(window_size=3, direction='left')[source]
Bases:
BasePostprocessorAbstract base class for all label smoothers.
Label smoothers take tuned label values and apply various smoothing techniques, particularly to transfer trend signals to earlier time points.
- __init__(window_size=3, direction='left')[source]
Initialize the smoother with a window size.
- Parameters:
- Raises:
ValueError – If window_size < 2 or direction is invalid.
TypeError – If direction is not a string or Direction enum.
tstrends.label_tuning.remaining_value_tuner module
Remaining value change tuner for trend labels.
This module provides a tuner that enhances trend labels with information about the remaining value change until the end of a continuous trend interval.
- class tstrends.label_tuning.remaining_value_tuner.RemainingValueTuner(postprocessors=None)[source]
Bases:
BaseLabelTunerA tuner that calculates the remaining value change in intervals of continuous labels.
For each point in the time series, it calculates the absolute value change from the current position to the end of the current trend interval.
- Parameters:
postprocessors (list[BasePostprocessor] | None)
- postprocessors
Steps applied in order after computing remaining values (e.g.
Shifter,ForwardLookingFilter, smoothers). Passtime_seriesandlabelsinto each step for filters; smoothers and shifters ignore context as documented on each class.- Type:
Optional[list[BasePostprocessor]], optional
- __init__(postprocessors=None)[source]
Initialize the RemainingValueTuner.
- Parameters:
postprocessors (list[BasePostprocessor] | None)
- tune(time_series, labels, enforce_monotonicity=False, normalize_over_interval=False, **kwargs)[source]
Tune trend labels to provide information about remaining value change.
For each point in the time series, calculates how much the value will change until the end of the current trend interval. The sign of the result matches the original label.
- Parameters:
time_series (list[float]) – The price series used for trend detection.
labels (list[int]) – The original trend labels (-1, 1) or (-1, 0, 1).
enforce_monotonicity (bool, optional) – If True, the labels in each interval will not reverse on uncaptured countertrends.
normalize_over_interval (bool, optional) – If True, the remaining value change will be normalized over the interval.
kwargs (Any)
- Returns:
Tuned up labels with the list of postprocessors applied.
- Return type:
tstrends.label_tuning.filtering module
Efficiency-based intra-trend weighting for tuned labels.
Within each non-neutral trend interval, weights emphasize timesteps where forward-looking directional efficiency (net move over path length) is high.
- class tstrends.label_tuning.filtering.ForwardLookingFilter(forward_window=None, forward_window_rel=None, smoothing_window=None, smoothing_window_rel=None, quantile=0.95)[source]
Bases:
BaseFilterPer-timestep weights from a normalized forward-looking efficiency metric.
For timestep
tinside an interval (with horizonh):\[e_t = \frac{|x_{t+h} - x_t|}{\sum_{k=1}^{h} |x_{t+k} - x_{t+k-1}| + \epsilon}\]Weights are smoothed to avoid propagating time series noise into the labels and scaled by a high quantile (avoiding a max to add robustness) so that low-efficiency regions are downweighted but not zeroed.
- Parameters:
- __init__(forward_window=None, forward_window_rel=None, smoothing_window=None, smoothing_window_rel=None, quantile=0.95)[source]
- Parameters:
forward_window (int | None) – Absolute horizon
hfor efficiency (net vs path length).forward_window_rel (float | None) – Relative horizon as a fraction of each trend interval length (mutually exclusive with
forward_window).smoothing_window (int | None) – Length of the centered moving-average kernel on the filtering weights.
smoothing_window_rel (float | None) – Relative length of the centered moving-average kernel on the filtering weights, as a fraction of each trend interval length (mutually exclusive with
smoothing_window).quantile (float) – High quantile for robust normalization denominator.
- Return type:
tstrends.label_tuning.shifting module
Temporal shifting of tuned label sequences.
Used as a post-processor in BasePostprocessor
pipelines (e.g. tune()).
- class tstrends.label_tuning.shifting.Shifter(periods)[source]
Bases:
BasePostprocessorShift tuned values forward (positive
periods) or backward (negative).Forward shift moves each value to a later index, padding the start with zeros. Backward shift moves values to earlier indices, padding the end with zeros.
- Parameters:
periods (int)
- periods
Number of steps to shift; must be non-zero. Sign sets direction.
tstrends.label_tuning.smoothing module
Smoothing implementations for trend labels.
This module provides various smoothing algorithm implementations for trend label processing.
- class tstrends.label_tuning.smoothing.SimpleMovingAverage(window_size=3, direction='left')[source]
Bases:
BaseSmootherSimple moving average smoother with equal weights.
This smoother applies equal weights to all values in the window, resulting in uniform smoothing. Each point in the window has the same influence on the result.
Examples
For a window size of 3: - With values [10, 20, 30], each value gets 1/3 weight (33.3%) - Result = (10 * 0.333) + (20 * 0.333) + (30 * 0.333) = 20
This approach produces gradual smoothing with consistent lag across all frequencies, making it good for removing noise but less responsive to recent changes.
- __init__(window_size=3, direction='left')[source]
Initialize the smoother with a window size.
- Parameters:
- Raises:
ValueError – If window_size < 2 or direction is invalid.
TypeError – If direction is not a string or Direction enum.
- class tstrends.label_tuning.smoothing.LinearWeightedAverage(window_size=3, direction='left')[source]
Bases:
BaseSmootherLinear weighted moving average smoother.
This smoother applies linearly increasing weights to values in the window, giving more importance to recent values and less to older ones. This creates a more responsive smoothing that better preserves the shape of trends.
Examples
For a window size of 3 with left-sided smoothing: - With values [10, 20, 30], weights are distributed as:
Oldest value (10): 1/6 weight (16.7%)
Middle value (20): 2/6 weight (33.3%)
Recent value (30): 3/6 weight (50.0%)
Result = (10 * 0.167) + (20 * 0.333) + (30 * 0.5) = 23.33
Compared to SimpleMovingAverage, LinearWeightedAverage: - Responds more quickly to recent changes - Reduces lag in trend detection - Better preserves the shape of peaks and valleys - More effective for early trend detection
- __init__(window_size=3, direction='left')[source]
Initialize the smoother with a window size.
- Parameters:
- Raises:
ValueError – If window_size < 2 or direction is invalid.
TypeError – If direction is not a string or Direction enum.
tstrends.label_tuning.smoothing_direction module
Direction enums for smoothing operations.
This module provides the Direction enum used to specify smoothing directions in time series processing.
- class tstrends.label_tuning.smoothing_direction.Direction(value)[source]
Bases:
EnumDirection of smoothing to apply.
The direction determines which values are included in the smoothing window relative to the current point being smoothed.
- Values:
- LEFT: Only uses past values (causal smoothing).
For point at time t, uses points [t-n+1, t-n+2, …, t].
- CENTERED: Uses both past and future values (non-causal smoothing).
For point at time t, uses points [t-n/2, …, t, …, t+n/2].
Example
For a time series [10, 20, 30, 40, 50] with window_size=3: - LEFT smoothing for point at index 2 (value 30) uses [10, 20, 30] - CENTERED smoothing for point at index 2 (value 30) uses [20, 30, 40]
- LEFT = 'left'
- CENTERED = 'centered'
Module contents
Label tuning module for enhancing trend labels with magnitude information.
This module provides tools to tune trend labels (UP/NEUTRAL/DOWN) by adding information about the potential trend magnitude or remaining potential until the next trend change.
- class tstrends.label_tuning.BasePostprocessor[source]
Bases:
ABCCommon interface for post-processing tuned label values.
Filters, smoothers, and shifters implement
process()and can be chained bytstrends.label_tuning.RemainingValueTunervia apostprocessorslist.
- class tstrends.label_tuning.ForwardLookingFilter(forward_window=None, forward_window_rel=None, smoothing_window=None, smoothing_window_rel=None, quantile=0.95)[source]
Bases:
BaseFilterPer-timestep weights from a normalized forward-looking efficiency metric.
For timestep
tinside an interval (with horizonh):\[e_t = \frac{|x_{t+h} - x_t|}{\sum_{k=1}^{h} |x_{t+k} - x_{t+k-1}| + \epsilon}\]Weights are smoothed to avoid propagating time series noise into the labels and scaled by a high quantile (avoiding a max to add robustness) so that low-efficiency regions are downweighted but not zeroed.
- Parameters:
- __init__(forward_window=None, forward_window_rel=None, smoothing_window=None, smoothing_window_rel=None, quantile=0.95)[source]
- Parameters:
forward_window (int | None) – Absolute horizon
hfor efficiency (net vs path length).forward_window_rel (float | None) – Relative horizon as a fraction of each trend interval length (mutually exclusive with
forward_window).smoothing_window (int | None) – Length of the centered moving-average kernel on the filtering weights.
smoothing_window_rel (float | None) – Relative length of the centered moving-average kernel on the filtering weights, as a fraction of each trend interval length (mutually exclusive with
smoothing_window).quantile (float) – High quantile for robust normalization denominator.
- Return type:
- class tstrends.label_tuning.RemainingValueTuner(postprocessors=None)[source]
Bases:
BaseLabelTunerA tuner that calculates the remaining value change in intervals of continuous labels.
For each point in the time series, it calculates the absolute value change from the current position to the end of the current trend interval.
- Parameters:
postprocessors (list[BasePostprocessor] | None)
- postprocessors
Steps applied in order after computing remaining values (e.g.
Shifter,ForwardLookingFilter, smoothers). Passtime_seriesandlabelsinto each step for filters; smoothers and shifters ignore context as documented on each class.- Type:
Optional[list[BasePostprocessor]], optional
- __init__(postprocessors=None)[source]
Initialize the RemainingValueTuner.
- Parameters:
postprocessors (list[BasePostprocessor] | None)
- tune(time_series, labels, enforce_monotonicity=False, normalize_over_interval=False, **kwargs)[source]
Tune trend labels to provide information about remaining value change.
For each point in the time series, calculates how much the value will change until the end of the current trend interval. The sign of the result matches the original label.
- Parameters:
time_series (list[float]) – The price series used for trend detection.
labels (list[int]) – The original trend labels (-1, 1) or (-1, 0, 1).
enforce_monotonicity (bool, optional) – If True, the labels in each interval will not reverse on uncaptured countertrends.
normalize_over_interval (bool, optional) – If True, the remaining value change will be normalized over the interval.
kwargs (Any)
- Returns:
Tuned up labels with the list of postprocessors applied.
- Return type:
- class tstrends.label_tuning.Shifter(periods)[source]
Bases:
BasePostprocessorShift tuned values forward (positive
periods) or backward (negative).Forward shift moves each value to a later index, padding the start with zeros. Backward shift moves values to earlier indices, padding the end with zeros.
- Parameters:
periods (int)
- periods
Number of steps to shift; must be non-zero. Sign sets direction.
- class tstrends.label_tuning.SimpleMovingAverage(window_size=3, direction='left')[source]
Bases:
BaseSmootherSimple moving average smoother with equal weights.
This smoother applies equal weights to all values in the window, resulting in uniform smoothing. Each point in the window has the same influence on the result.
Examples
For a window size of 3: - With values [10, 20, 30], each value gets 1/3 weight (33.3%) - Result = (10 * 0.333) + (20 * 0.333) + (30 * 0.333) = 20
This approach produces gradual smoothing with consistent lag across all frequencies, making it good for removing noise but less responsive to recent changes.
- __init__(window_size=3, direction='left')[source]
Initialize the smoother with a window size.
- Parameters:
- Raises:
ValueError – If window_size < 2 or direction is invalid.
TypeError – If direction is not a string or Direction enum.
- class tstrends.label_tuning.LinearWeightedAverage(window_size=3, direction='left')[source]
Bases:
BaseSmootherLinear weighted moving average smoother.
This smoother applies linearly increasing weights to values in the window, giving more importance to recent values and less to older ones. This creates a more responsive smoothing that better preserves the shape of trends.
Examples
For a window size of 3 with left-sided smoothing: - With values [10, 20, 30], weights are distributed as:
Oldest value (10): 1/6 weight (16.7%)
Middle value (20): 2/6 weight (33.3%)
Recent value (30): 3/6 weight (50.0%)
Result = (10 * 0.167) + (20 * 0.333) + (30 * 0.5) = 23.33
Compared to SimpleMovingAverage, LinearWeightedAverage: - Responds more quickly to recent changes - Reduces lag in trend detection - Better preserves the shape of peaks and valleys - More effective for early trend detection
- __init__(window_size=3, direction='left')[source]
Initialize the smoother with a window size.
- Parameters:
- Raises:
ValueError – If window_size < 2 or direction is invalid.
TypeError – If direction is not a string or Direction enum.
- class tstrends.label_tuning.Direction(value)[source]
Bases:
EnumDirection of smoothing to apply.
The direction determines which values are included in the smoothing window relative to the current point being smoothed.
- Values:
- LEFT: Only uses past values (causal smoothing).
For point at time t, uses points [t-n+1, t-n+2, …, t].
- CENTERED: Uses both past and future values (non-causal smoothing).
For point at time t, uses points [t-n/2, …, t, …, t+n/2].
Example
For a time series [10, 20, 30, 40, 50] with window_size=3: - LEFT smoothing for point at index 2 (value 30) uses [10, 20, 30] - CENTERED smoothing for point at index 2 (value 30) uses [20, 30, 40]
- LEFT = 'left'
- CENTERED = 'centered'