TS(3pm)

📦
version 0.83 · 3 versions
, in ubuntu noble

💖 PDL::Stats::TS — the manual, but make it cute 💖

okay bestie, so this is the page for PDL::Stats::TS, aka the basic time series functions module. It lives in the User Contributed Perl Documentation corner of the perl manual-verse. Pull up a chair, we're doing time series today and honestly? iconic. 🦋

🌸 DESCRIPTION 🌸

First things first, the vocabulary vibe check: the terms FUNCTIONS and METHODS are used arbitrarily here to mean methods that are threadable and methods that are NOT threadable, respectively. That's it, that's the whole distinction. No deeper lore. 💅

Also, the plots? They need PDL::Graphics::PGPLOT. No PGPLOT, no pretty pictures, periodt.

⚠️ EXPERIMENTAL! ⚠️ Like, in particular, bad value support is spotty and may be shaky. USE WITH DISCRETION! This is giving "we're testing in prod" energy and I need you to be aware of that. 😭

✨ SYNOPSIS ✨

use PDL::LiteF;
use PDL::NiceSlice;
use PDL::Stats::TS;

my $r = $data->acf(5);

look at her. three lines of use and one method call. so clean. so demure. 🌸

🎀 FUNCTIONS 🎀

💫 acf

Signature: (x(t); int h(); [o]r(h+1))

Autocorrelation function for up to lag h. If you don't pass h? It just defaults to t-1. She's self-sufficient like that. 👑

acf does not process bad values. ngl, she simply refuses.

usage:

perldl> $a = sequence 10

# lags 0 .. 5

perldl> p $a->acf(5)
[1 0.7 0.41212121 0.14848485 -0.078787879 -0.25757576]

💫 acvf

Signature: (x(t); int h(); [o]v(h+1))

Autocovariance function for up to lag h. And same deal as her sister up there — no h given means t-1 by default. 🫶

acvf does not process bad values.

usage:

perldl> $a = sequence 10

# lags 0 .. 5

perldl> p $a->acvf(5)
[82.5 57.75 34 12.25 -6.5 -21.25]

# autocorrelation

perldl> p $a->acvf(5) / $a->acvf(0)
[1 0.7 0.41212121 0.14848485 -0.078787879 -0.25757576]

see that second one? dividing acvf by acvf(0) literally gives you the autocorrelation. the way that math just works. 🧚

💫 diff

Signature: (x(t); [o]dx(t))

Differencing, bestie. DX(t) = X(t) - X(t-1), and DX(0) = X(0). Can be done inplace. ✨

diff does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 inte

Signature: (x(n); [o]ix(n))

Integration! The opposite of differencing, which is so satisfying. IX(t) = X(t) + X(t-1), and IX(0) = X(0). Can be done inplace. 💜

inte does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 dseason

Signature: (x(t); indx d(); [o]xd(t))

Deseasonalize your data using a moving average filter the size of period d. bye bye seasonality, you will not be missed. 🌈

dseason processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 fill_ma

Signature: (x(t); int q(); [o]xf(t))

Fill missing value with moving average. Formula time: xf(t) = sum(x(t-q .. t-1, t+1 .. t+q)) / 2q. 🍓

fill_ma does handle bad values. The output pdl bad flag is cleared unless the specified window size q is too small and there are still bad values. so like, pick a good q, okay?

  my $x_filled = $x->fill_ma( $q );

💫 filter_exp

Signature: (x(t); a(); [o]xf(t))

Filter, exponential smoothing. xf(t) = a * x(t) + (1-a) * xf(t-1). smooth like butter. 🧈

filter_exp does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 filter_ma

Signature: (x(t); indx q(); [o]xf(t))

Filter, moving average. xf(t) = sum(x(t-q .. t+q)) / (2q + 1). yes there's a + 1 in the denominator, do not skip the + 1, I'm watching. 👀

filter_ma does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 mae

Signature: (a(n); b(n); float+ [o]c())

Mean absolute error. MAE = 1/n * sum( abs(y - y_pred) ). classic. reliable. no drama.

Usage:

  $mae = $y->mae( $y_pred );

mae processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 mape

Signature: (a(n); b(n); float+ [o]c())

Mean absolute percent error. MAPE = 1/n * sum(abs((y - y_pred) / y)). note that division by y in there... yeah. remember it. you'll see why in a sec. 😬

Usage:

  $mape = $y->mape( $y_pred );

mape processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 wmape

Signature: (a(n); b(n); float+ [o]c())

Weighted mean absolute percent error. avg(abs(error)) / avg(abs(data)). And the glow-up here is real: this is much more robust compared to mape with that division by zero error situation (cf. Schütz, W., & Kolassa, 2006). so if mape is giving you chaos, wmape is your emotionally stable friend. 💅

Usage:

  $wmape = $y->wmape( $y_pred );

wmape processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 portmanteau

Signature: (r(h); longlong t(); [o]Q())

Portmanteau significance test (Ljung-Box) for autocorrelations. fancy name, very serious job. 🎀

Usage:

perldl> $a = sequence 10

# acf for lags 0-5
# lag 0 excluded from portmanteau

perldl> p $chisq = $a->acf(5)->portmanteau( $a->nelem )
11.1753902662994

# get p-value from chisq distr

perldl> use PDL::GSL::CDF
perldl> p 1 - gsl_cdf_chisq_P( $chisq, 5 )
0.0480112934306748

note: lag 0 is excluded from the portmanteau. don't come for me, that's just how she is.

portmanteau does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

💫 pred_ar

Signature: (x(d); b(p|p+1); int t(); [o]pred(t))

Calculates predicted values up to period t (i.e. extend the current series up to period t) for autoregressive series, with or without constant. If there is a constant, it's the last element in b, exactly as would be returned by ols or ols_t. 📈

pred_ar does not process bad values.

  CONST  => 1,

Usage:

perldl> $x = sequence 2

  # last element is constant
perldl> $b = pdl(.8, -.2, .3)

perldl> p $x->pred_ar($b, 7)
[0       1     1.1    0.74   0.492  0.3656 0.31408]

  # no constant
perldl> p $x->pred_ar($b(0:1), 7, {const=>0})
[0       1     0.8    0.44   0.192  0.0656 0.01408]

two different answers, one tiny {const=>0}. the power. 🔥

💫 season_m

Given the length of the season, this returns seasonal mean and var for each period. (In scalar context it returns the seasonal mean only, just so you know. 💜)

Default options (case insensitive, because she's chill like that):

  START_POSITION => 0,     # series starts at this position in season
  MISSING        => -999,  # internal mark for missing points in season
  PLOT  => 0,              # boolean
    # see PDL::Graphics::PGPLOT::Window for next options
  WIN   => undef,          # pass pgwin object for more plotting control
  DEV   => '/xs',          # open and close dev for plotting if no WIN
                           # defaults to '/png' in Windows
  COLOR => 1,

See PDL::Graphics::PGPLOT for the detailed graphing options, she's got range.

  my ($m, $ms) = $data->season_m( 24, { START_POSITION=>2 } );

💫 plot_dseason

Plots the deseasonalized data and the original data points. It opens and closes a default window for plotting unless a pgwin object is passed in options. And it returns the deseasonalized data, because she's generous. 🫶

Default options (case insensitive):

  WIN   => undef,
  DEV   => '/xs',    # open and close dev for plotting if no WIN
                     # defaults to '/png' in Windows
  COLOR => 1,        # data point color

See PDL::Graphics::PGPLOT for the detailed graphing options.

👑 METHODS 👑

💫 plot_acf

Plots and returns autocorrelations for a time series. two for one, we love a multitasker. ✨

Default options (case insensitive):

  SIG  => 0.05,      # can specify .10, .05, .01, or .001
  DEV  => '/xs',     # open and close dev for plotting
                     # defaults to '/png' in Windows

Usage:

perldl> $a = sequence 10

perldl> p $r = $a->plot_acf(5)
[1 0.7 0.41212121 0.14848485 -0.078787879 -0.25757576]

📚 REFERENCES 📚

  • Brockwell, P.J., & Davis, R.A. (2002). Introcution to Time Series and Forecasting (2nd ed.). New York, NY: Springer.
  • Schütz, W., & Kolassa, S. (2006). Foresight: advantages of the MAD/Mean ratio over the MAPE. Retrieved Jan 28, 2010, from http://www.saf-ag.com/226+M5965d28cd19.html

(yes, do the reading bestie, I know, but it's literally time series, it's giving academia chic 🎓)

🦋 AUTHOR 🦋

Copyright (C) 2009 Maggie J. Xiong <maggiexyz users.sourceforge.net>

All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation as described in the file COPYING in the PDL distribution.

okay and that's the whole page! 💖 This was documented for perl v5.38.2 on 2024-03-31 — so if you're reading this, that's the version and date of this whole thing. go forth and autocorrelate responsibly, bestie. no cap. 🎀✨💅

📦 where this page comes from