---
title: "Forecasting at New Locations"
output: rmarkdown::html_vignette
bibliography: mcgf.bib
vignette: >
  %\VignetteIndexEntry{forecasting-new-locations}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Overview

`krige_new()` extends an estimated MCGF model to spatial locations that were
not used for fitting. This is useful when:

- a station is newly installed;
- forecasts are required on a target grid;
- some sites are intentionally held out for validation; or
- future scenario generation is needed at additional locations.

There are two ways to describe the new sites:

1. provide their coordinates with `locations_new`, or
2. provide precomputed signed distances with `dists_new`.

This vignette demonstrates the coordinate workflow.

# Prepare an MCGF object

The built-in `sim1` data contain both observations and locations.

```{r setup}
library(mcgf)
data(sim1)

x <- mcgf(
    sim1$data,
    locations = sim1$locations
)

x <- add_acfs(x, lag_max = 5)
x <- add_ccfs(x, lag_max = 5)
```

# Fit the base covariance model

For a first new-location forecast, a separable base model is sufficient.

```{r fit-base}
fit_sep <- fit_base(
    x,
    model = "sep",
    lag = 5,
    par_init = c(
        c = 0.001,
        gamma = 0.5,
        a = 0.3,
        alpha = 0.5
    ),
    par_fixed = c(nugget = 0)
)

x <- add_base(x, fit_base = fit_sep)
```

# Define a new location

For illustration, place a new site near the centre of the existing network.

```{r new-location}
new_location <- matrix(
    colMeans(sim1$locations),
    nrow = 1
)
rownames(new_location) <- "New_site"

new_location
```

# Forecast with `krige_new()`

```{r predict-new}
pred <- krige_new(
    x,
    locations_new = new_location,
    model = "base",
    interval = TRUE
)

dim(pred$fit)
```

The output contains forecasts for the original sites **and** the appended new
site. The new site is the last spatial column.

```{r inspect-new}
new_index <- dim(pred$fit)[2]

head(pred$fit[, new_index])
head(pred$lower[, new_index])
head(pred$upper[, new_index])
```

# Forecast using new observed data

If you have a separate future period for the original locations, supply it with
`newdata`:

```r
pred_future <- krige_new(
    x,
    newdata = future_data,
    locations_new = new_location,
    model = "base",
    interval = TRUE
)
```

`future_data` must have the same columns, in the same order, as the fitted
`mcgf` object.

# If observations at the new location are available

You can also provide `newdata_new`. These observations are then included in the
lagged information used for forecasting.

```r
pred_with_new_history <- krige_new(
    x,
    newdata = future_data,
    locations_new = new_location,
    newdata_new = future_new_site,
    model = "base",
    interval = TRUE
)
```

The number of rows in `newdata_new` must match `newdata`, and the number of
columns must match the number of new locations.

# Supplying distances directly

If the object does not contain coordinates, calculate the distances yourself
and pass them through `dists_new`.

```r
d_new <- find_dists_new(
    locations = observed_locations,
    locations_new = new_location,
    longlat = TRUE
)

pred <- krige_new(
    x,
    dists_new = d_new,
    model = "base"
)
```

Do not supply both `locations_new` and `dists_new`.

# General stationary model

Once a Lagrangian model has been fitted and added with `add_lagr()`, switch to:

```r
pred_all <- krige_new(
    x,
    locations_new = new_location,
    model = "all",
    interval = TRUE
)
```

This extends both the base and directional Lagrangian covariance to the new
location.

# Regime-switching objects

`krige_new()` also has an `mcgf_rs` method. Use `dists_new_ls` and
`sds_new_ls` when distance or marginal-variance assumptions differ by regime.
For soft regime forecasts, supply regime probabilities using `prob`.

See `vignette("mcgf_rs", package = "mcgf")` for a complete RS-MCGF fit.


<div id="refs"></div>