Welcome to the zoltr vignette for project owners and forecasters. You should read this if you are interested in creating and managing your own zoltardata.com projects using this package to access them via the Zoltar API. Building on the Getting Started vignette, this one covers creating projects and models, and uploading forecasts.
Before starting, you should have an account on zoltardata.com, and an .Renviron
file set up as described in Getting Started.
library(zoltr)
zoltar_connection <- new_connection()
zoltar_authenticate(zoltar_connection, Sys.getenv("Z_USERNAME"), Sys.getenv("Z_PASSWORD"))Let’s use the create_project() function to make a
temporary project to work with. (Note that if you’re repeating this step
and need to delete a previously-created project, you can either use the
web UI’s delete button on the project detail page or call the zoltr
delete_project() function to do it programmatically.)
create_project() takes a project_config
parameter that is a list specifying everything Zoltar needs
to create a project, including meta information like name, whether it’s
public, etc. In addition, it lists the units, targets, and timezeros to
create. The new project’s URL is returned, which you can pass to other
functions. Here we use docs-project.json, which is the one
that creates the example documentation project.
project_config <- jsonlite::read_json("docs-project.json") # "name": "My project"
project_url <- create_project(zoltar_connection, project_config)
the_project_info <- project_info(zoltar_connection, project_url)We can use the create_model() function to create a model
in a particular project. Like create_project(), it takes a
list that is the configuration to use when creating the
model. There is an example at example-model-config.json,
but here we will construct the list ourselves.
model_config <- list("name" = "a model_name",
"abbreviation" = "an abbreviation",
"team_name" = "a team_name",
"description" = "a description",
"contributors" = "the contributors",
"license" = "other",
"notes" = "some notes",
"citation" = "a citation",
"methods" = "the methods",
"home_url" = "http://example.com/",
"aux_data_url" = "http://example.com/")
model_url <- create_model(zoltar_connection, project_url, model_config)Now let’s upload a forecast to the model using
upload_forecast() and then see how to list all of a model’s
forecasts (in this case just the one).
As we noted in Getting Started with zoltr, long operations like querying or uploading forecasts are queued, and require polling to determine when they are done.
upload_forecast() takes the model_url to
upload to, the timezero_date in the project to associate
the forecast with, and the forecast_data itself. The latter
is a nested list of predictions as documented in
docs.zoltardata.com, but you
can learn about it by looking at the example
docs-predictions.json. Briefly, you can see that there is a
predictions list of prediction elements (the
meta section is ignored), each of which encodes data for a
particular unit and target combination. Each
prediction element has a class that’s one of four
possibilities: bin, named, point,
and sample. The structure of the
prediction element's contents (the prediction
section) is determined by the particular class. For example, a
point just has a value, but a bin
has a table of cat and prob values.
Here we will upload the docs-predictions.json file. Note
that the passed timezero_date matches one of the timezeros
in docs-project.json, the file that was used to create the
project. It is an error otherwise.
forecast_data <- jsonlite::read_json("docs-predictions.json")
job_url <- upload_forecast(zoltar_connection, model_url, "2011-10-02", forecast_data, TRUE)
busy_poll_job(zoltar_connection, job_url)Hopefully you’ll see some number of “QUEUED” entries followed by a “SUCCESS” one. (How long it takes will depend on how much other work Zoltar is handling.)
Get the new forecast’s URL from the Job object and then
call the forecasts() function to get a
data.frame of that model’s forecasts (just the one in our
case).
the_job_info <- job_info(zoltar_connection, job_url)
forecast_url <- job_info_forecast_url(zoltar_connection, the_job_info)
the_forecast_info <- forecast_info(zoltar_connection, forecast_url)
the_forecasts <- forecasts(zoltar_connection, the_forecast_info$forecast_model_url)
str(the_forecasts)
#> 'data.frame': 1 obs. of 12 variables:
#> $ id : int 109913
#> $ url : chr "https://www.zoltardata.com/api/forecast/109913/"
#> $ forecast_model_url: chr "https://www.zoltardata.com/api/model/987/"
#> $ source : chr "forecast-22397cc338c8.json"
#> $ timezero_url : chr "https://www.zoltardata.com/api/timezero/3746/"
#> $ timezero_date : Date, format: "2011-10-02"
#> $ data_version_date : Date, format: NA
#> $ is_season_start : logi TRUE
#> $ created_at : POSIXct, format: "2024-04-08 13:25:51"
#> $ issued_at : POSIXct, format: "2024-04-08 13:25:51"
#> $ notes : chr ""
#> $ forecast_data_url : chr "https://www.zoltardata.com/api/forecast/109913/data/"NB: This will delete all the data associated with the project without warning, including models and forecasts.
delete_project(zoltar_connection, project_url)
#> Response [https://www.zoltardata.com/api/project/365/]
#> Date: 2024-04-08 13:25
#> Status: 204
#> Content-Type: <unknown>
#> <EMPTY BODY>