---
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)
```

# What is trendseries?

The `trendseries` package is a suite of four functions for analyzing 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** — the cycle, or output gap.

All four share the same pipe-friendly `data.frame` interface, the same 20
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?

Working with economic time series in R often involves cumbersome conversions
between data frames and `ts` objects. Most filtering methods are designed for
`ts` objects, but modern data analysis workflows use `data.frame` objects with
a date column. Converting back and forth between `ts` and `data.frame` is
tedious and error-prone.

The goal of `trendseries` is to provide a modern interface for exploratory
analysis of time series data in conventional `data.frame` format, without
giving up access to `ts`-native tools when you need them: every function has a
`ts`/`xts`/`zoo` counterpart (`extract_trends()`, or the `ts_col`/`df_to_ts()`
converters).

This package was designed with economic time series in mind. It includes
methods commonly used in economics (e.g., Hodrick-Prescott, Hamilton, etc.) as
well as general-purpose smoothing methods (e.g., LOESS, moving averages).

# The four functions

Each function adds new columns to a data frame, named after the component and
the method used (`trend_stl`, `seasadj_stl`, `detrend_hp`, etc.). The example
below threads the same dataset — `ibcbr`, the Central Bank's monthly index of
Brazilian economic activity — through all four.

```{r ibcbr-plot}
ggplot(ibcbr, aes(date, index)) +
  geom_line(linewidth = 0.7) +
  theme_minimal() +
  labs(title = "Brazilian economic activity (IBC-Br)", x = NULL, y = "Index")
```

## `augment_trends()`: fit a trend

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

head(ibcbr_trend)
```

## `decompose_series()`: split into trend, seasonal, and remainder

```{r decompose}
ibcbr_parts <- decompose_series(ibcbr, value_col = "index")

head(ibcbr_parts)
```

## `deseason_series()`: remove seasonality

```{r deseason}
ibcbr_sa <- deseason_series(ibcbr, value_col = "index")

head(ibcbr_sa)
```

## `detrend_series()`: extract the cycle

```{r detrend}
ibcbr_cycle <- detrend_series(ibcbr, value_col = "index")

head(ibcbr_cycle)
```

## `extract_trends()`: the `ts`-native interface

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 = "#C53030")
```

# Where to go next

This vignette is intentionally just a map. Each function has its own vignette
with worked examples, parameter details, and guidance on choosing between
methods:

| Vignette                                                                                 | 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 all 20 trend methods, by family                              |
| [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

This package was inspired by the need for a simpler workflow for trend
extraction in R. It builds upon many existing packages, including:

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

# Getting Help

If you run into issues:

-   Check the documentation: `?augment_trends`, `?decompose_series`,
    `?deseason_series`, `?detrend_series`
-   View examples: `example(augment_trends)`
-   Read other vignettes: `vignette(package = "trendseries")`
-   Report bugs: GitHub issues