Skip to contents

Create a forecast object

Source: R/create_forecast.R
create_forecast.Rd

create_forecast() creates a forecast object given data and optional metadata. It accepts a variety of forecast formats as input and intelligently converts them into a standard format.

Usage

create_forecast(dat, name = NULL, forecast_time = NULL)

Arguments

dat

Forecast data. It can be in one of the following formats:

  • A data frame containing forecast data

  • A named list with a time field (vector of times) and a vals field (list of realization vectors). Each of the vectors in vals must have the same length as time

In the first option above, the data frame should contain:

  • A time column

  • (Optional) a sim column, containing simulation numbers for raw data

  • (Optional) a val column, containing raw data. If sim is present then val must be present as well.

  • (Optional) columns starting with val_q followed by a number from 0 to 100, containing quantile data

  • (Optional) a val_mean column, containing mean data

Times can be either numeric, dates, or date-times. All data must be numeric. sim must also be numeric if present.

name

(Optional) A string specifying the name of the forecast

forecast_time

(Optional) An integer, date, or date-time specifying when the forecast was created. Its type should match the type of values in the time column(s) of data If provided, this forecast will be scored only using data corresponding to dates/times greater than or equal to forecast_time. Additionally, plots of this forecast may graphically distinguish between values to the left and right of forecast_time.

Value

A named list with fields data, name, forecast_time. data is a data frame containing forecast data. name and forecast_time are the same as the parameters passed to create_forecast()

Examples

# forecast with numeric times and raw data
create_forecast(data.frame(time=1:3, val=10:12), name="a forecast", forecast_time=2)
#> $name
#> [1] "a forecast"
#> 
#> $forecast_time
#> [1] 2
#> 
#> $data
#>   time val
#> 1    1  10
#> 2    2  11
#> 3    3  12
#> 

# forecast with dates and mean-and-quantiles data
create_forecast(
  data.frame(
    time=c(lubridate::ymd("2024-01-01"), lubridate::ymd("2024-01-02")),
    val_mean=10:11, val_q2.5=5:6, val_q97.5=15:16
  ),
  name="another forecast"
)
#> $name
#> [1] "another forecast"
#> 
#> $forecast_time
#> NULL
#> 
#> $data
#>         time val_mean val_q2.5 val_q97.5
#> 1 2024-01-01       10        5        15
#> 2 2024-01-02       11        6        16
#> 

# an already-combined ensemble
create_forecast(dplyr::tibble(time=c(1,1,1,1,1,2,2,2,2,2), val=c(20,21,22,23,24,10,11,12,13,14)))
#> $name
#> NULL
#> 
#> $forecast_time
#> NULL
#> 
#> $data
#> # A tibble: 10 × 2
#>     time   val
#>    <dbl> <dbl>
#>  1     1    20
#>  2     1    21
#>  3     1    22
#>  4     1    23
#>  5     1    24
#>  6     2    10
#>  7     2    11
#>  8     2    12
#>  9     2    13
#> 10     2    14
#> 

# an already-combined ensemble with simulation numbers
create_forecast(dplyr::tibble(
  time=c(1,1,1,1,1,2,2,2,2,2),
  sim=c(1,2,3,4,5,1,2,3,4,5),
  val=c(20,21,22,23,24,10,11,12,13,14)
))
#> $name
#> NULL
#> 
#> $forecast_time
#> NULL
#> 
#> $data
#> # A tibble: 10 × 3
#>     time   sim   val
#>    <dbl> <dbl> <dbl>
#>  1     1     1    20
#>  2     1     2    21
#>  3     1     3    22
#>  4     1     4    23
#>  5     1     5    24
#>  6     2     1    10
#>  7     2     2    11
#>  8     2     3    12
#>  9     2     4    13
#> 10     2     5    14
#> 

# an ensemble of 4 realizations, each represented by a vector in `vals`
create_forecast(list(
  time=1:3,
  vals=list(4:6, 7:9, 10:12, 13:15)
))
#> $name
#> NULL
#> 
#> $forecast_time
#> NULL
#> 
#> $data
#>    time sim val
#> 1     1   1   4
#> 2     2   1   5
#> 3     3   1   6
#> 4     1   2   7
#> 5     2   2   8
#> 6     3   2   9
#> 7     1   3  10
#> 8     2   3  11
#> 9     3   3  12
#> 10    1   4  13
#> 11    2   4  14
#> 12    3   4  15
#>