-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathREADME.Rmd
More file actions
139 lines (106 loc) · 5.94 KB
/
Copy pathREADME.Rmd
File metadata and controls
139 lines (106 loc) · 5.94 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
fig.align = "center",
fig.width = 7,
warning = FALSE,
dev = "svg"
)
```
# trendseries: extract trends from time series
<!-- badges: start -->
<img src="man/figures/logo.png" align="right" height="200"/>
[](https://CRAN.R-project.org/package=trendseries)
[](https://viniciusoike.r-universe.dev/trendseries)
<!-- badges: end -->
`trendseries` provides a unified interface to extract trends, cycles, and seasonal components from time series. Most filtering methods in R are designed for `ts` objects, but datasets typically come in a `data.frame` format with a date column, which makes applying filters cumbersome. `trendseries` bridges this gap: `augment_trends()`, `decompose_series()`, `deseason_series()`, and `detrend_series()` all work directly on `data.frame`/`tibble` objects, while `extract_trends()` provides the same methods for `ts`/`xts`/`zoo` objects when you need to stay in native time-series format.
## Installation
`trendseries` is available on CRAN
```{r, eval = FALSE}
install.packages("trendseries")
```
You can install the newest version of trendseries from [R-Universe](https://viniciusoike.r-universe.dev/trendseries).
``` r
install.packages(
'trendseries',
repos = c(
'https://viniciusoike.r-universe.dev',
'https://cloud.r-project.org'
)
)
```
## Core Functions
Five core functions cover `data.frame`/`tibble`/`data.table` workflows.
- **`augment_trends()`**: adds trend columns to the original dataset.
- **`augment_rolling()`**: add rolling window trend columns to the original dataset.
- **`decompose_series()`**: splits a series into trend, seasonal, and remainder components.
- **`deseason_series()`**: wraps `decompose_series()` to return a seasonally adjusted series.
- **`detrend_series()`**: wraps `augment_trends()` to return the deviation from trend (the cycle).
Some functions like `augment_trends()` also have a `ts`/`xts`/`zoo`-native counterpart via **`extract_trends()`**, for workflows that stay in native time-series format.
## Usage
The example below computes three filters (HP, STL, and moving average) on a quarterly index of construction activity. `augment_trends()` detects the frequency of the data and picks conventional defaults for the HP filter.
```{r}
library(trendseries)
library(ggplot2)
data(gdp_construction)
# Computes multiple trends at once
series <- gdp_construction |>
# Automatically detects frequency
# Trends are added as new columns to the original dataset
augment_trends(
value_col = "index",
methods = c("hp", "stl", "ma")
)
series
```
An equivalent `extract_trends()` function is also available for `ts` objects.
```{r}
stl_trend <- extract_trends(AirPassengers, methods = "stl")
plot.ts(AirPassengers)
lines(stl_trend, col = "#C53030")
```
## Available Methods
The methods below come from four families: econometric filters, bandpass
filters, moving averages, and smoothing. The
[Trend Extraction Methods](https://viniciusoike.github.io/trendseries/articles/methods.html)
vignette describes each one — when to use it and which parameters it takes.
| Method | Category | Description |
|--------------|------------------|----------------------------------------|
| `hp` | econometric | Hodrick-Prescott filter |
| `hamilton` | econometric | Hamilton regression filter |
| `bn` | econometric | Beveridge-Nelson decomposition |
| `ucm` | econometric | Unobserved components model |
| `bk` | bandpass | Baxter-King bandpass filter |
| `cf` | bandpass | Christiano-Fitzgerald bandpass filter |
| `ma` | moving average | Simple moving average |
| `wma` | moving average | Weighted moving average |
| `ewma` | moving average | Exponentially weighted moving average |
| `triangular` | moving average | Triangular moving average |
| `median` | moving average | Median filter |
| `gaussian` | moving average | Gaussian-weighted moving average |
| `spencer` | moving average | Spencer's 15-term moving average |
| `henderson` | moving average | Henderson moving average |
| `stl` | smoothing | Seasonal-trend decomposition via Loess |
| `loess` | smoothing | Local polynomial regression |
| `spline` | smoothing | Smoothing splines |
| `poly` | smoothing | Polynomial trends |
| `kernel` | smoothing | Kernel smoother |
| `kalman` | smoothing | Kalman filter/smoother |
## Learn More
To learn more about the package be sure to visit the [webiste](https://viniciusoike.github.io/trendseries/)
The vignettes below cover each function in detail.
- [Introduction to trendseries](https://viniciusoike.github.io/trendseries/articles/trendseries.html)
- [Augmenting Trends](https://viniciusoike.github.io/trendseries/articles/augment-trends.html)
- [Decomposing Series](https://viniciusoike.github.io/trendseries/articles/decompose-series.html)
- [Detrending Series](https://viniciusoike.github.io/trendseries/articles/detrend-series.html)
- [Trend Extraction Methods](https://viniciusoike.github.io/trendseries/articles/methods.html)
- [Moving Averages](https://viniciusoike.github.io/trendseries/articles/moving-averages.html)
- [Econometric Filters](https://viniciusoike.github.io/trendseries/articles/econometric-filters.html)