---
title: "Getting Started with trendseries"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with trendseries}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  markdown:
    wrap: 80
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5,
  fig.align = "center",
  message = FALSE,
  warning = FALSE
)
```

```{r setup}
#| include: false
library(trendseries)
library(ggplot2)
library(ekioplot)

series_palette <- unname(c(
  ekio_pal("blue")["700"],
  ekio_pal("blue")["400"],
  ekio_pal("teal")["600"]
))
highlight_orange <- unname(ekio_pal("orange")["400"])
```

# What is trendseries?

`trendseries` is a pipe-friendly interface to the trend, seasonal, and cyclical
structure of economic time series.

- **`augment_trends()`** fits a smooth **trend** to a series.
- **`decompose_series()`** splits a series into **trend**, **seasonal**, and
  **remainder** components.
- **`deseason_series()`** removes the **seasonal** component, returning a
  seasonally adjusted series.
- **`detrend_series()`** removes the trend, returning the **deviation from
  trend** (a.k.a. the cycle, or output gap).
- **`index_series()`** rescales one or more series to a common base period and
  value.

All five share the same pipe-friendly `data.frame` interface, the same
underlying trend methods, and the same unified parameter system. Throughout this
vignette (and the package documentation generally) the terms `data.frame` and
"data frame" refer to any dataset in a rectangular format, i.e.,
`data.frame`/`tibble`/`data.table`.

## Why trendseries?

Most filtering methods in R are designed for `ts` objects, but analysis
workflows use data frames with a date column. Converting back and forth is
tedious and error-prone. `trendseries` works on data frames throughout, and
keeps the `ts`-native interface available for when you need it.

The package sources filtering and smoothing functions across different packages
and provides a unified interface when possible. The methods are the ones
applied to economic series — Hodrick-Prescott, Hamilton, Beveridge-Nelson,
Henderson, Spencer, and moving averages, among others — alongside
general-purpose smoothers such as STL and loess.

# A simple example

Each function works by adding columns to the data frame, named after the
component and the method used (`trend_stl`, `seasadj_stl`, `detrend_hp`, etc.).
The examples below use the IBC-Br series (`ibcbr`), the Brazilian Central Bank's
monthly index of economic activity.

`augment_trends()` fits a smooth trend to a series and returns it as a new
column.

```{r augment}
ibcbr_trend <- augment_trends(ibcbr, value_col = "index", methods = "stl")

head(ibcbr_trend)
```

```{r ibcbr-plot}
ggplot(ibcbr_trend, aes(date)) +
  geom_line(aes(y = index, color = "Original"), linewidth = 0.5, alpha = 0.5) +
  geom_line(aes(y = trend_stl, color = "Trend (STL)"), linewidth = 0.7) +
  scale_color_manual(
    values = c("Original" = series_palette[[1]], "Trend (STL)" = highlight_orange)
  ) +
  labs(
    title = "Brazilian economic activity (IBC-Br)",
    x = NULL,
    y = "Index",
    color = NULL
  ) +
  theme_ekio(background = "white") +
  theme(legend.position = "bottom")
```

Every trend method reachable through `augment_trends()` is also reachable
through `extract_trends()`, which takes `ts`/`xts`/`zoo` objects instead of data
frames and returns them, for users who prefer to stay in base R's time series
ecosystem.

```{r extract}
stl_trend <- extract_trends(AirPassengers, methods = "stl")
plot.ts(AirPassengers)
lines(stl_trend, col = highlight_orange)
```

## Indexing series

Use `index_series()` to compare series on a common base. By default it uses the
earliest non-missing observation; `base_period` can instead select a year or a
date range and use its mean as the reference value. If the first dated value is
missing, the function warns when it moves the base to a later observation.

```{r index}
ibcbr_indexed <- ibcbr |>
  index_series(value_col = "index", base_period = 2019)

head(ibcbr_indexed)
```

The function also calculates separate references for grouped data and supports
multiple value columns. To select a different base date for each group, pass the
name of a `Date` column to `base_period`. Each group must have one non-missing
date in that column.

# Where to go next

Each function has its own article on the package website with worked examples,
parameter details, and guidance on choosing between methods.

| Article | Covers |
|---------------------------------------------|-----------------------------------|
| [Augmenting Trends](https://viniciusoike.github.io/trendseries/articles/augment-trends.html) | `augment_trends()`/`extract_trends()`: grouping, multiple methods, finer control |
| [Decomposing Series](https://viniciusoike.github.io/trendseries/articles/decompose-series.html) | `decompose_series()`/`deseason_series()`: trend/seasonal/remainder splits |
| [Detrending Series](https://viniciusoike.github.io/trendseries/articles/detrend-series.html) | `detrend_series()`: cycles, output gaps, the deseason-then-detrend workflow |
| [Trend Extraction Methods](https://viniciusoike.github.io/trendseries/articles/methods.html) | Catalogue of the trend methods |
| [Moving Averages](https://viniciusoike.github.io/trendseries/articles/moving-averages.html) | SMA, WMA, EWMA, Triangular, Median, Gaussian, Spencer, Henderson |
| [Econometric Filters](https://viniciusoike.github.io/trendseries/articles/econometric-filters.html) | HP, BK, CF, Hamilton, Beveridge-Nelson, UCM |

# Acknowledgements

`trendseries` builds on existing packages.

- `mFilter` for economic filters.
- `hpfilter` for Hodrick-Prescott filtering.
- `tsbox` for time series conversions.

# Getting Help

- Check the documentation: `?augment_trends`, `?decompose_series`,
  `?deseason_series`, `?detrend_series`, `?index_series`
- View examples: `example(augment_trends)`
- Browse the articles: <https://viniciusoike.github.io/trendseries/articles/>
- Report bugs: GitHub issues