
<!-- README.md is generated from README.Rmd. Please edit that file -->

# <img src='https://raw.githubusercontent.com/cefet-rj-dal/tspredit/master/inst/logo.png' alt='Logo do pacote TSPredIT' align='centre' height='125' width='125'/> TSPredIT

<!-- badges: start -->

![GitHub
Stars](https://img.shields.io/github/stars/cefet-rj-dal/tspredit?logo=Github)
![CRAN Downloads](https://cranlogs.r-pkg.org/badges/tspredit)
<!-- badges: end -->

**TSPredIT** (Time Series Prediction with Integrated Tuning) is a
framework for time series forecasting that keeps the predictive workflow
modular while expanding what can be tuned around it. Built on top of
[DAL Toolbox](https://github.com/cefet-rj-dal/daltoolbox), it helps the
reader move from a raw series to a complete forecasting pipeline that
may include temporal sampling, filtering, augmentation, normalization,
prediction, comparison, and integrated tuning.

The package is not only a collection of forecasters. Its main didactic
value is to show that time-series prediction benefits from treating the
whole pipeline as a sequence of explicit decisions: how to represent the
series, how to split it in time order, whether to smooth noise, whether
to enrich the windows, how to scale values, which model family to use,
and which protocol should be used for evaluation.

------------------------------------------------------------------------

## Documentation

The documentation was reorganized to support two complementary entry
points:

- a guided tutorial track for readers who want to learn the workflow
  step by step
- thematic example collections for readers who want to inspect one stage
  of the forecasting pipeline at a time

If you are new to `tspredit`, start with the tutorials. If you already
know the package structure, the thematic collections remain available
and were rewritten with a more didactic order and clearer grouping.

### Guided tutorial track

- [Tutorials](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/tutorial/) -
  a 10-part sequence that starts with ARIMA forecasting protocols, then
  builds the sliding-window MLP pipeline piece by piece, and ends with
  model comparison and integrated tuning.

### Thematic example collections

- [Time-series data
  utilities](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/tsdata/) -
  build `ts_data`, project windows into inputs and targets, and create
  train/test splits that preserve temporal order.
- [Datasets](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/datasets/) -
  inspect the packaged datasets documented in `R/data.R` and
  `R/tspredbench.R`, one dataset at a time.
- [Filtering](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/filter/) -
  compare identity baselines, smoothing methods, robust filters,
  decomposition methods, and state-space or seasonal adjustments.
- [Lag
  mapping](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/lagmapping/) -
  study how different lag-selection rules decide which past observations
  are exposed to the predictor, from positional baselines to
  correlation-driven and supervised mappings.
- [Augmentation](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/augment/) -
  study when synthetic windows help, from simple perturbations to
  recency-aware transformations.
- [Normalization](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/normalization/) -
  inspect how scale, drift, and differencing affect the signal seen by
  the predictor.
- [Prediction](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/prediction/) -
  move from classical baselines to machine-learning and neural
  forecasting models, then to tuning.
- [Multivariate
  forecasting](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/multivariate/) -
  extend the pipeline to target-centered multivariate workflows by
  combining one model for `y` with auxiliary-variable pipelines.
- [Custom
  extensions](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/custom/) -
  learn how to add your own predictors, filters, augmentations, and
  normalization methods without breaking the package contract.

### Suggested reading order

If you want the clearest learning path across the collections, this
sequence is usually the most productive:

1.  [Time-series data
    utilities](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/tsdata/)
2.  [Tutorials](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/tutorial/)
3.  [Datasets](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/datasets/)
4.  [Filtering](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/filter/)
5.  [Lag
    mapping](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/lagmapping/)
6.  [Augmentation](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/augment/)
    and
    [Normalization](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/normalization/)
7.  [Prediction](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/prediction/)
8.  [Multivariate
    forecasting](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/multivariate/)
9.  [Custom
    extensions](https://github.com/cefet-rj-dal/tspredit/tree/main/examples/custom/)

This order follows the forecasting pipeline more closely: first
represent and split the series, then inspect the data, then decide
whether to smooth the signal, then decide which lags should become
predictors, then apply data expansion and scaling, and only after that
compare models and more advanced extensions.

### Documentation design

The examples were revised to be more useful for learning:

- files inside each collection follow a suggested reading order
- category `README` files explain why each group exists before listing
  files
- examples now open by explaining the method or technique before jumping
  into code
- tutorial files no longer expose `output` front matter at the top of
  the document

Additional documentation for the underlying DAL Toolbox is available at:

- [DAL Toolbox
  documentation](https://cefet-rj-dal.github.io/daltoolbox/)

------------------------------------------------------------------------

## Installation

The latest version of TSPredIT is available on CRAN:

``` r
install.packages("tspredit")
```

You can install the development version from GitHub:

``` r
library(devtools)
devtools::install_github("cefet-rj-dal/tspredit", force = TRUE, upgrade = "never")
```

------------------------------------------------------------------------

## Bug reports and feature requests

To report issues or suggest improvements, please open a ticket here:

<https://github.com/cefet-rj-dal/tspredit/issues>
