autots.evaluator.feature_detector.utils package¶
Submodules¶
autots.evaluator.feature_detector.utils.formatting module¶
FormattingMixin for TimeSeriesFeatureDetector.
- class autots.evaluator.feature_detector.utils.formatting.FormattingMixin¶
Bases:
objectMixin providing template building, serialization, and reconstruction validation.
autots.evaluator.feature_detector.utils.joint_trend_selection module¶
Vectorized joint selection of trend hinges (slope changes) and steps (level shifts).
Greedy forward selection under one least-squares model [1, t, nuisance,
hinges, steps] with a BIC stop, then relocation and pruning. Every candidate
position is scored at once: by Frisch-Waugh-Lovell, adding column x to a
model with orthonormal basis Q and residual r lowers SSE by
(r.x)^2 / (|x|^2 - |Q'x|^2), and for hinge/step columns all the inner
products come from prefix/suffix cumulative sums in O(n) per basis vector.
Conventions: t is scaled to [0, 1) for conditioning. A step at c is
1[i >= c] - 1 (-1 before, 0 after), matching LevelShiftMagic, so a
positive coefficient is an upward shift and the final level is unaffected.
All positions and lengths are in points (periods), not days.
- class autots.evaluator.feature_detector.utils.joint_trend_selection.HingeStepCandidates(n)¶
Bases:
objectClosed-form inner products and norms for every hinge/step position.
- column(position, kind)¶
- dots(vectors, kind)¶
Inner products of every candidate column with each column of
vectors-> (n, k).
- norm2(kind)¶
- class autots.evaluator.feature_detector.utils.joint_trend_selection.JointTrendModel(values, nuisance=None)¶
Bases:
objectHolds the base design and builds full designs for a given term list.
- basis_and_residual(terms)¶
Orthonormal basis of [base, terms] and the residual of values on it.
Same column space as _orthonormal_basis(self.design(terms)): term columns are projected off the cached base basis and only that (n, len(terms)) remainder is SVD’d, with the rank tolerance scaled as for the full design.
- design(terms)¶
- term_statistics(terms, return_inflation=False)¶
beta, SSE increase if each term is dropped, AR(1)-adjusted t, SSE, variance.
- autots.evaluator.feature_detector.utils.joint_trend_selection.joint_fit(values, terms, nuisance=None)¶
One least-squares fit of the selected terms.
Returns dict with
trend(intercept, slope, hinges),level_shift(steps), per-termcoefficient(hinge: slope change per point; step: shift size) and AR(1)-adjustedt_stat, plusvarianceof the residual.
- autots.evaluator.feature_detector.utils.joint_trend_selection.profile_likelihood_windows(values, terms, nuisance=None, min_segment=28, edge=0, critical_value=3.84)¶
95% date window per term from the profile likelihood of its position.
Each term is moved between its same-kind neighbours with all others held; positions whose SSE rises by at most
critical_value * variance_AR(chi^2_1) over the best position form the window. Returns [(low, high)] aligned to terms.
- autots.evaluator.feature_detector.utils.joint_trend_selection.select_hinge_step_terms(values, nuisance=None, min_segment=28, edge=14, max_terms=16, bic_multiplier=2.0, step_t_threshold=4.0, search_steps=True, fixed_steps=(), max_refine_rounds=5, effective_n_prune=True)¶
Select hinge knots and steps for one series.
effective_n_prunedivides the pruning/merge likelihood gain by the AR(1) variance inflation of the current residual (BIC on the effective sample size).fixed_stepsare externally proposed step positions (e.g. LevelShiftMagic candidates): they are never relocated or BIC-pruned, only dropped when their joint-model |t| falls belowstep_t_threshold.search_stepslets the greedy search also propose steps (the unified mode). Returns a sorted list of(kind, position).
- autots.evaluator.feature_detector.utils.joint_trend_selection.split_transient_step_pairs(step_details, max_gap, cancel_ratio=0.5)¶
Pair adjacent opposite-sign steps that nearly cancel within
max_gappoints.A holiday block or multi-week anomaly otherwise enters the trend as two permanent level shifts. Returns (kept_steps, transients) where each transient is {‘start’, ‘end’, ‘magnitude’} with magnitude the effect while it lasted.
autots.evaluator.feature_detector.utils.rescaling module¶
RescalingMixin for TimeSeriesFeatureDetector.
- class autots.evaluator.feature_detector.utils.rescaling.RescalingMixin¶
Bases:
objectMixin providing methods to convert components from standardized to original scale.
autots.evaluator.feature_detector.utils.trend_forecast module¶
Trend extrapolation helpers for TimeSeriesFeatureDetector.forecast.
Two additions over plain last-segment OLS extrapolation: - future_trend_change_variance: variance from changepoints and level shifts that
have not happened yet, at the rates the detector observed in training.
shrink_last_slope: empirical-Bayes shrinkage of a noisy last-segment slope toward a recency-weighted average of earlier segment slopes.
damped_trend_steps: per-period damping phi of the extrapolated slope.
All rates are per observation step (not per day) because forecast horizons and stored slopes are both in steps.
- autots.evaluator.feature_detector.utils.trend_forecast.damped_trend_steps(forecast_length, trend_damping=None)¶
Effective step counts sum_{i<=h} phi^i for h = 1..forecast_length.
The trend at step h is
last + slope * steps[h-1]; the total increment is bounded by slope * phi / (1 - phi) for phi < 1. phi None or 1 gives 1..H.
- autots.evaluator.feature_detector.utils.trend_forecast.future_trend_change_variance(rates, horizon)¶
(H, N) variance added by future slope changes and level shifts.
A slope change delta arriving at step t shifts the level at horizon h by delta*(h - t); summing over Poisson arrivals gives rate*E[delta^2]*sum k^2 for k = 0..h-1, the exact grid form of h^3/3. Level shifts add rate*E[s^2]*h.
- autots.evaluator.feature_detector.utils.trend_forecast.resolve_trend_damping(trend_damping, date_index=None)¶
Per-period phi (float) or None from a validated trend_damping.
‘auto’ is DEFAULT_TREND_DAMPING_PER_DAY compounded over the median period length, so the calendar half-life is the same for hourly, daily or weekly data (weekly 0.99**7 ~= 0.932). A non-datetime index counts as daily.
- autots.evaluator.feature_detector.utils.trend_forecast.segment_sxx(segment_length)¶
Sum of squared x deviations for x = 0..m-1, i.e. m(m^2 - 1)/12.
Shared by the OLS leverage term and the slope-precision used in shrinkage.
- autots.evaluator.feature_detector.utils.trend_forecast.shrink_last_slope(slope_info, date_index, residual_sigma, mean_sq_slope_change, recency_days=180.0)¶
Shrink the last segment slope toward earlier segment slopes.
Prior mean: earlier slopes weighted by length * exp(-age_days / recency_days), age measured from segment end to the training end in calendar days so the decay is frequency independent. Shrinkage is precision weighted: the last slope’s OLS variance sigma^2/Sxx against tau^2 = E[delta^2]/2, the slope dispersion implied by independent adjacent segments. Short last segments are pulled strongly; long well-determined ones barely move.
Returns the last slope unchanged when there is no earlier segment or no usable dispersion/noise estimate.
- autots.evaluator.feature_detector.utils.trend_forecast.trend_change_rates(trend_changepoints, level_shifts, columns, n_obs)¶
Per-series event rates and mean squared sizes from detected events.
- Parameters:
trend_changepoints – {series: [(date, prior_slope, new_slope), …]}
level_shifts – {series: [(date, magnitude, …), …]}
columns – series order for the output arrays.
n_obs – number of training observations (rate denominator).
- Returns:
rate_cp, mean_sq_slope_change, rate_ls, mean_sq_level_shift. Series with no events get zeros, so their future-change variance vanishes (the previous behaviour).
- Return type:
dict of (N,) float arrays
- autots.evaluator.feature_detector.utils.trend_forecast.validate_trend_damping(trend_damping)¶
Return phi as a float in (0, 1], ‘auto’, or None (undamped).
Raises instead of silently ignoring an out-of-range phi: phi > 1 would be an accelerating trend and phi <= 0 is meaningless, both almost surely typos.
