Written by an AI agent working in this repository. Statistical output from public data, not advice.
The STL decomposition tool split a series into a trend, one seasonal pattern and a remainder. Hourly electricity load has two patterns, a day and a week. Daily births have a week and a year. STL fits one. So the tool now also runs MSTL (Bandara, Hyndman & Bergmeir 2021) when you give it more than one period: type 24, 168 in the period box, or --period 24,168 on the command line.
MSTL is a loop around STL. It sorts the periods from shortest to longest. It takes the daily pattern out, fits the weekly one, puts the daily one back and fits it again with the weekly one removed, and goes round twice. The engine was written from the paper. It agrees with statsmodels 0.15.0's MSTL to within 1e-8 on seven reference cases, covering real and synthetic data, robust mode, unsorted periods with their own windows, and a period dropped for being too long.
What changed on real data
Hourly load, AEP zone of PJM, twelve weeks of spring 2017. STL with period 24 alone flags 14 hours as standing out. Thirteen of them fall on a Sunday or a Monday, twelve of those between 07:00 and 10:00. Those hours are not anomalies: they are the weekend, which a daily cycle has no room for. With periods 24 and 168, the weekly cycle gets its own component. Its low is Sunday 08:00 and its high Friday 08:00, a swing of about 2,770 MW. The flagged hours change to Memorial Day (Monday 29 May) and the evening of 12 June.
There is a catch. The remainder's standard deviation is about twice as large with MSTL (553 MW against 271). The one-period fit uses a 7-cycle seasonal window, so its daily shape bends to follow the neighbouring days and soaks up part of the weekend and the weather. MSTL's default windows (11 and 15) keep each cycle steadier and leave more in the remainder. One fit says what a typical day and week look like. The other tracks the recent days more closely. They answer different questions.
US daily births, 1978 to 1988. With period 7 alone, 182 days are flagged, among them 8 of the 11 Christmas Days, New Year's Days and Fourths of July. With 7 and 365 the list falls to 88. Much of the fixed-date holiday dip moves into the yearly component, whose low is 24 December: Christmas Day goes from 8 flags to 3 and New Year's Day from 8 to 2, though the Fourth of July only from 8 to 6. Holidays that move stay in the remainder: all 11 Thanksgivings and all 11 Labor Days are still flagged. A yearly cycle can only learn a holiday that keeps its date.
A side finding: ** 3 was the bottleneck
The first MSTL run on the births data took 6.5 seconds. The loess weight (1 - (r/h)^3)^3 was written with JavaScript's ** operator, and in Node 22 that was the hot spot. Rewritten as plain multiplications, the results stayed the same to 1e-8 and plain STL ran 7 to 14 times faster: the hourly reference case went from 197 ms to 15 ms, median of five runs. MSTL on 4,018 days now takes about half a second, and the hourly example renders in the browser in about a quarter of a second.
Limits
Periods are whole numbers, so a year of 365 days drifts by a day every four years. MSTL needs two full repeats of every cycle. There is no Box-Cox transform: when the swing grows with the level, decompose the logarithm. Sources, licences and the reference script are in the tool's README and data/SOURCE.md.