hubUtils

---
output: github_document
---

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# Example Complex Forecast Hub

**This repository is under construction.**

This repository is designed as an example modeling Hub that follows the infrastructure guidelines laid out by the [Consortium of Infectious Disease Modeling Hubs](https://github.com/Infectious-Disease-Modeling-Hubs/).

The example model outputs that are provided here are adapted from forecasts submitted to the FluSight Forecast Hub for the 2022/23 season. The original forecasts were provided in quantile format, but they have been modified to provide examples of additional model output types and targets. They should be viewed only as illustrations of the data formats, not as realistic examples of forecasts. **Note that the folder `internal-data-raw` is not a part of the standard hub setup; it contains the original source data and scripts used to create the example model output data and target data.**

## Working with the data in R

Install the [hubData package](https://infectious-disease-modeling-hubs.github.io/hubData/) to work with the data in R.

To connect to a local copy of the data, first clone this repository.

You can then use functions in the `hubData` package to connect to hub data as well as dplyr functions to filter and select data prior to collecting the data into R. 

```{r}
library(hubData)
library(dplyr)
```

For example, to connect to the hub and collect all model outputs:

```{r}
model_outputs <- connect_hub(hub_path = ".") %>%
  collect_hub()
```


To access time series target data, you can use the `connect_target_time_series()` function. For example, to collect all time series targets:

```{r}
target_time_series_data <- connect_target_timeseries() |>
  collect()
target_time_series_data
```

You can also filter data prior to collecting it. For example, to collect oracle-output target data for specific targets, you can use `dplyr` function `filter()` to select the targets you are interested in.

```{r}
inc_flu_hosp_oracle_data <- connect_target_oracle_output() |>
  filter(target == "wk inc flu hosp") |>
  collect()
inc_flu_hosp_oracle_data
  
flu_hosp_rate_category_oracle_data <- connect_target_oracle_output() |>
  filter(target == "wk flu hosp rate category") |>
  collect()
flu_hosp_rate_category_oracle_data
```


### Accessing data from the cloud

To connect to a copy of this example data hosted in the cloud (on AWS S3), first you need to create a hub path that points to the S3 bucket where the hub data is stored. You can do this using the `s3_bucket()` function from the `hubData` package.

```{r}
hub_path <- s3_bucket("hubverse-example-complex-forecast-hub")
```

You can then use the same `connect_hub()` and `connect_target_*()` functions to connect to and access the data in the cloud and also `dplyr` functions to subset data prior to collecting. 

For example, to collect all model outputs for a specific target end date and location, you can use the following code:

```{r}
connect_hub(hub_path, skip_checks = TRUE) |>
  filter(target_end_date == "2022-10-22",
         location == "02") |>
  collect_hub()
```