---
title: "ST and VPP workflows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ST and VPP workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(TSGenerator)
```

## Seasonal Trajectories (ST)

### Preview

Catalogue access requires WEkEO and is therefore shown without being executed during vignette builds.

```{r st-preview, eval=FALSE}
st_preview <- download_st(
  start = "2020-04-01",
  end = "2020-06-30",
  tile_id = "30TXM",
  product = c("PPI", "QFLAG"),
  download = FALSE
)
```

### Download

```{r st-download, eval=FALSE}
st_download <- download_st(
  start = "2020-04-01",
  end = "2020-06-30",
  tile_id = "30TXM",
  product = c("PPI", "QFLAG"),
  output_dir = file.path(tempdir(), "HRVPP_ST"),
  overwrite = FALSE,
  prompt = TRUE
)
```

### Extract PPI

Raster extraction examples require user-supplied HR-VPP files and polygons and are not executed during the package build.

```{r st-extract, eval=FALSE}
st_ts <- extract_ts(
  x = file.path(tempdir(), "HRVPP_ST", "PPI"),
  polygons = parcels,
  id_col = "Parcel_ID",
  fun = "median"
)
```

### Assess temporal completeness

The temporal API can be demonstrated with a self-contained series.

```{r}
st_example <- data.frame(
  ID = rep(c("parcel_1", "parcel_2"), each = 4),
  Date = rep(as.Date("2020-04-01") + c(0, 10, 20, 30), 2),
  Value = c(0.20, 0.31, NA, 0.58, 0.18, 0.29, 0.43, 0.55)
)
plan <- temporal_plan(st_example, expected_step = 10)
missingness <- summarize_missingness(plan)
completeness <- assess_ts_quality(plan)
missingness
completeness
```

Do not interpret these completeness classes as ST-QFLAG confidence classes.

### Apply ST-QFLAG when required

The code definitions themselves are available offline:

```{r}
st_qflag_classes <- quality_info("ST")
st_qflag_classes
```

Masking requires matching user-supplied target and QFLAG rasters:

```{r st-mask, eval=FALSE}
st_clean <- mask_quality(
  x = st_raster,
  quality = st_qflag_raster,
  type = "ST",
  min_quality = 4
)
```

The default ST quality policy and any stricter threshold should be reported in the methods of a scientific analysis.

## Vegetation Phenology and Productivity (VPP)

### Preview/download selected parameters

```{r vpp-preview, eval=FALSE}
vpp_preview <- download_vpp(
  start = "2020-01-01",
  end = "2020-12-31",
  tile_id = "30TXM",
  product = c("SOSD", "MAXD", "EOSD", "LENGTH", "MAXV", "AMPL"),
  season = "s1",
  download = FALSE
)
```

### Product-aware extraction

```{r vpp-extract, eval=FALSE}
vpp <- extract_vpp(
  x = file.path(tempdir(), "HRVPP_VPP"),
  polygons = parcels,
  id_col = "Parcel_ID",
  fun = "median"
)
```

The output separates `Date` and numeric `Value`. This avoids treating encoded phenological dates like continuous spectral values.

### VPP quality

```{r}
quality_info("VPP")
```

```{r vpp-mask, eval=FALSE}
vpp_clean <- mask_quality(
  x = vpp_raster,
  quality = vpp_qflag,
  type = "VPP"
)
```

The default VPP mask retains medium/high confidence codes. Use explicit `keep_codes` when the study requires a different policy.

## Missingness modelling

A small synthetic table keeps the vignette deterministic and independent of external files. A modest basis dimension keeps the example fast and appropriate for the number of unique DOY values.

```{r}
missingness_data <- expand.grid(
  Year = 2020:2021,
  DOY = seq(20, 340, by = 40),
  Replicate = 1:3
)
missingness_data$Value <- seq_len(nrow(missingness_data)) / nrow(missingness_data)
missingness_data$Value[seq(3, nrow(missingness_data), by = 7)] <- NA_real_

fit <- model_missingness(
  missingness_data,
  year_col = "Year",
  doy_col = "DOY",
  value_col = "Value",
  k = 5
)

plot_missingness(fit, sos = 85, max_doy = 160, eos = 280)
```

The model and plot are separate objects. This makes the statistical result reusable without hidden plotting side effects.