New features
diff --git a/pkgdown.yml b/pkgdown.yml
index dca55d2..23aa062 100644
--- a/pkgdown.yml
+++ b/pkgdown.yml
@@ -6,7 +6,7 @@ articles:
interpretation: interpretation.html
planes-components: planes-components.html
rplanes-explorer: rplanes-explorer.html
-last_built: 2024-07-17T11:46Z
+last_built: 2024-07-17T11:48Z
urls:
reference: https://signaturescience.github.io/rplanes/reference
article: https://signaturescience.github.io/rplanes/articles
diff --git a/search.json b/search.json
index b6fb313..5fbaff8 100644
--- a/search.json
+++ b/search.json
@@ -1 +1 @@
-[{"path":"https://signaturescience.github.io/rplanes/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 Signature Science LLC Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"Basic Usage","text":"rplanes package (plausibility analysis epidemiological signals) provides functionality prepare data analyze plausibility forecasted observed epidemiological signals. functions implement set plausibility algorithms agnostic geographic time resolutions calculated independently presented combined score. package allows users : Prepare signal data (either forecast observed) evaluated Create set baseline characteristics previously observed data Compare characteristics evaluated data location Synthesize individual component results overall score package workflow demonstrated detail (see Figure 1). Figure 1 provides detailed description workflow used rplanes. rplanes processing begins forecast observed data prepared pre-specified format. required input data format documented package. convenience, package includes read_forecast() function prepare forecast data quantile format commonly used forecasting hubs. prepped forecast observed data converted signal object using to_signal(). signal data compared baseline characteristics previously observed data location. characteristics aggregated using plane_seed(). seed signal data prepared, user can run plausibility scoring independently location evaluated data. Scores comprised individual binary plausibility components. functions drive component wrapped plane_score() function ease--use. default plane_score() wrapper try use relevant components, however user can dictate specific components needed. important note depending type signal evaluated (.e., forecast versus observed data), components may apply.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"analyzing-plausibility-of-forecast-data","dir":"Articles","previous_headings":"","what":"Analyzing plausibility of forecast data","title":"Basic Usage","text":"Plausibility analysis can support operational forecasting outbreak analytic activities. demonstrate use rplanes score example forecasted data set. Several packages must loaded prior conducting analysis:","code":"library(rplanes) library(dplyr) library(purrr) library(ggplot2)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"prepare-observed-data","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Prepare observed data","title":"Basic Usage","text":"motivate example use incident flu hospitalization reported via HHS Protect. Note data aggregated daily weekly resolution, provided format internal rplanes package data. select columns ’re interested (“date”, “location”, “flu.admits”) make sure date field formatted date: important emphasize observed data must minimum include columns location (geographic unit FIPS code), date (date reported value; must date class), reported value location/date combination.","code":"hosp_all <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) %>% select(date, location, flu.admits) %>% mutate(date = as.Date(date)) head(hosp_all)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"convert-observed-data-into-a-signal-with-to_signal","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Convert observed data into a signal with to_signal()","title":"Basic Usage","text":"downstream plausibility analysis requires observed /forecasted data converted S3 “signal” class. to_signal() function constructs object applies additional “observed” “forecast” class depending type signal specified. convert observed data signal object:","code":"observed_signal <- to_signal(input = hosp_all, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\", horizon = NULL)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"create-a-seed-from-the-observed-data-via-plane_seed","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Create a seed from the observed data via plane_seed()","title":"Basic Usage","text":"plane_seed() function provides means internally calculate store baseline characteristics observed data package calls “seed”. characteristics summarized independently location, used downstream scoring functions. example, input prepped observed signal object make use “cut_date” argument. restricting dates specified cut date, ensure baseline characteristics computed based data overlaps forecast. practice, may possible use default (NULL) cut date analyzing forecasts, long reported data available (exceeding) first horizon forecast.","code":"prepped_seed <- plane_seed(observed_signal, cut_date = \"2022-10-29\")"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"prepare-forecast-data","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Prepare forecast data","title":"Basic Usage","text":"forecast data assessed must include point estimate representation uncertainty (.e., prediction interval) location horizon. analysis rplanes, forecast data must prepared include following: location: Geographic unit FIPS code date: Date corresponding forecast horizon horizon: Forecast horizon lower: Lower limit given prediction interval forecast point: Point estimate forecast upper: Upper limit given prediction interval forecast convenience, rplanes package includes read_forecast() convert forecasts quantile format used many forecast hubs1,2 format needed plausibility analysis. read_forecast() function reads csv input returns tibble summarized forecast data location horizon original file. example, use forecast incident weekly flu hospitalizations. forecast originally quantile format referenced included rplanes example data: can use read_forecast() load data convert required format:","code":"forecast_fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") read.csv(forecast_fp) %>% head(.) prepped_forecast <- read_forecast(forecast_fp) head(prepped_forecast)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"convert-forecast-data-into-a-signal-with-to_signal","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Convert forecast data into a signal with to_signal()","title":"Basic Usage","text":"forecast formatted appropriately, can convert signal object:","code":"forecast_signal <- prepped_forecast %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", resolution = \"weeks\", horizon = 4)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"run-plane_score-and-visualize-results","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Run plane_score() and visualize results","title":"Basic Usage","text":"planes_score() function wraps PLANES scoring plausibility components across locations single step. function can accept arguments specific component functions allows user dictate components use (default ). arguments see ?plane_score. pass input forecast signal function along prepped seed run scoring independently locations: Note forecasts evaluate time period, prepare forecast signal appropriately use seed (.e., recreate seed forecast). output plane_score() list scoring results locations. can convert scores_summary element list tibble. default, score uses equal weights components. However, users can modify behavior using “weights” argument needed. res object shows location, number flags raised (“n_flags”), weighted flags (“n_flags_weighted”), number components tested (“n_components”), overall sum weights components tested (“weights_denominator”), “score” (“n_flags_weighted” divided “weights_denominator”), names components tested, names components flagged (): evaluated forecast, locations one fewer flags raised. However, several locations two three seven possible components flagged implausibility.","code":"scores <- plane_score(input = forecast_signal, seed = prepped_seed) res <- scores$scores_summary %>% map_df(., as_tibble) head(res) res %>% count(n_flags) %>% mutate(n_flags = as.character(n_flags)) %>% ggplot(aes(n_flags,n)) + geom_col() + labs(x = \"Number of flags raised\", y = \"Count\")"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"analyzing-plausibility-of-observed-data","dir":"Articles","previous_headings":"","what":"Analyzing plausibility of observed data","title":"Basic Usage","text":"One might want test observed reported data plausibility check phenomena like backfill systematic errors reporting mechanisms. steps use rplanes analyze plausibility observed data similar forecast assessments. input data must converted signal, passed (along seed) scoring function. However, key difference observed data data source used create input signal can used seeding, albeit cut date differentiate data evaluated baseline.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"prepare-observed-data-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Prepare observed data","title":"Basic Usage","text":"example, also use reported HHS Protect flu hospitalization data. However, truncate data stop end 2022. scenario, interested assessing recent reported week (.e., week 2022-12-31) plausibility. Note practice, may interest assess multiple time points recently observed data. begin, read data filter dates prior 2023:","code":"hosp_pre23 <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) %>% select(date, location, flu.admits) %>% mutate(date = as.Date(date)) %>% filter(date < as.Date(\"2023-01-01\")) head(hosp_pre23)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"convert-observed-data-into-a-signal-with-to_signal-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Convert observed data into a signal with to_signal()","title":"Basic Usage","text":"data loaded, can convert hospitalization tibble signal object:","code":"observed_signal <- to_signal(input = hosp_pre23, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\", horizon = NULL)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"create-a-seed-from-the-observed-data-via-plane_seed-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Create a seed from the observed data via plane_seed()","title":"Basic Usage","text":"can use observed signal input plane_score(), also input plane_seed(). However, must use argument restricts seeding dates prior cut date (inclusive). example, assessing observed data week 2022-12-31 want seed plausibility analysis characteristics recent reported date (.e., 2022-12-24):","code":"prepped_seed <- plane_seed(observed_signal, cut_date = \"2022-12-24\")"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"run-plane_score-and-visualize-results-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Run plane_score() and visualize results","title":"Basic Usage","text":"forecast assessments, PLANES scoring wrapped convenience plane_score() function. Since assessing observed signal case, can explicitly tell scoring use certain components. important emphasize components work forecasts observed signals. Currently, plane_cover(), plane_taper(), plane_trend(), plane_shape() (run inside plane_score()) work forecasts observed data: results indicate just one location flag raised. , case two components used scoring results interpreted accordingly. Furthermore, consider reported signals date observed data retrieved paramount. likely meaningful analyze plausibility observed data real time (near real time) opposed retrospectively, since backfill reporting issues may corrected prior assessment.","code":"scores <- plane_score(observed_signal, seed = prepped_seed, components = c(\"repeat\",\"diff\")) res <- scores$scores_summary %>% map_df(., as_tibble) head(res) res %>% count(n_flags) %>% mutate(n_flags = as.character(n_flags)) %>% ggplot(aes(n_flags,n)) + geom_col() + labs(x = \"Number of flags raised\", y = \"Count\")"},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"PLANES Interpretation","text":"rplanes package includes vignettes detailing basic usage descriptions individual components package uses plausibility analysis. vignette focuses interpreting rplanes plausibility outputs. content includes primer weighting scheme plausibility components, discussion limitations may arise relying seed data, considerations flag raised.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"weighting-scheme-within-plane_score","dir":"Articles","previous_headings":"","what":"Weighting scheme within plane_score()","title":"PLANES Interpretation","text":"plane_score() function allows users evaluate multiple plausibility components simultaneously (.e., without call individual scoring functions given component). wrapper returns overall score summarize components evaluated. plane_score() function includes optional “weights” argument allows user-specified weighting components overall score. default (weights = NULL), component given equal weighting. optionally weight certain components higher lower, user must specify named vector value representing weight given component. length vector must equal number components used “components” argument plane_score(). technical details plane_score() apply weighting scheme, users refer function documentation (?plane_score) basic usage vignette.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"motivations-for-weighting","dir":"Articles","previous_headings":"Weighting scheme within plane_score()","what":"Motivations for weighting","title":"PLANES Interpretation","text":"weighting scheme incorporated scores may context-dependent. words, users may varying concerns specific components evaluated given timing, historical data patterns, specific goals plausibility assessment. included several examples highlighting use-cases applying weighting scheme plane_score(): users retrospectively analyzing forecast signals ground-truth, observed data horizon reported, may aware large jump reported cases actually occurred. scenario, might less interested difference component, evaluates forecast raises flag point--point difference greater difference found observed seed. However, users might still concerned unreasonable jumps forecasted cases. Rather eliminating difference component altogether, users can reduce weight within plane_score(). expected large uptick cases, users might increase weight trend component heavily penalize unexpected dips cases. ensures significant trends given appropriate emphasis analysis. beginning season, zeros may common locations, users might decide reduce relative weight zero repeat components. adjustment may help account seasonality expected patterns data. working relatively short time series seed data (e.g., several months), users may encounter many shape flags due limited number shapes found seed data. cases, users can reduce relative weight shape component. evaluating forecasts operationally, users may interested ensuring prediction intervals appropriately calibrated (e.g., narrow). case, cover taper components might merit higher weighting.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"limitations-that-arise-from-seed-data","dir":"Articles","previous_headings":"","what":"Limitations that arise from seed data","title":"PLANES Interpretation","text":"described basic usage vignette, rplanes plausibility analysis procedure requires establishing “seed” object based observed signal. seed data serves basis background characteristics used assess plausibility. , plausibility results depend upon reliability length time series used establish seed data. discuss factors potentially impact plausibility analysis rplanes.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"reliability-of-seed-data","dir":"Articles","previous_headings":"Limitations that arise from seed data","what":"Reliability of seed data","title":"PLANES Interpretation","text":"plausibility analysis rplanes assumes users access observed data establish baseline characteristics time series. Presumably, observed signal trustworthy faithful representation one expect signal evaluated. However, practice, data issues lagged reporting, backfill, systematic biases ascertainment may lead unexpected behaviors rplanes (.e., many flags raised). known issues within seed data, users carefully consider individual components used plausibility scoring determine might impact results plausibility analysis. example, consider observed data may lack consistent reporting certain locations, particularly early time series. case, seed data might contain many consecutive zeros across long time span followed reliable reporting locations, therefore rplanes rarely (ever) raise flags repeat zero components. scenario, truncating observed data begin reporting becomes reliable creating seed may appropriate.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"length-of-seed-data","dir":"Articles","previous_headings":"Limitations that arise from seed data","what":"Length of seed data","title":"PLANES Interpretation","text":"Besides reliability, length (.e., number observations) observed signal used create seed can influence rplanes plausibility scoring. general, data provides higher resolution characteristics manifest evaluated signal. However, users aware computational costs potential reduction sensitivity components amount available seed data increases. provide several considerations examples balancing length observed data used create seed. scenarios seed created relatively small number observations, users may notice components higher sensitivity resulting flags raised. individual components required seed signal length ratio must met function run (e.g., shape requires seed least four times length forecast evaluated). However, even built-minimum length, cases seed data may short produce reasonable results. example, consider evaluating forecast four weeks ahead. case, seed must contain least 16 weekly observations given location. However, 16 weeks roughly four months data, (depending seasonality timing observations) may adequately capture shapes plausibly manifest four weeks future. table detailing potential complications caused seed object short. possible issues, recommend users manually examine flagged locations feasible consider reducing relative weights within plane_score() function. observations seed may lead limitations described , many seed values can also trigger unexpected behavior. amount seed data increases, plausibility components lower sensitivity, result fewer flags. rplanes package includes options mitigate . using repeat component, increasing “prepend” length decreasing repeat tolerance increase sensitivity. circumstances, decreased sensitivity mitigated adjusting component parameters. evaluating shape component, longer seed time-series likely contain unique shapes, resulting fewer potentially novel shapes forecasts therefore fewer flags raised. observed similar epidemiological signal (alone) enough justification infer shape unusual flagged. example, may appropriate flag forecasts COVID-19 activity 2024 exhibit trajectories similar extreme surges 2020-2021. However, situation user’s reference seed data included pandemic activity levels, flag raised. Unlike situations seed data short, changing relative weights components flagged much impact overall scores. -weighting components using short seed object causes potentially erroneous flags less effect overall score, however increasing weights cause flags raised (.e., changing weights change sensitivity components). , manual inspection “missed flags” much challenging time-consuming. suggest users suspect sensitivity components plane_score() negatively impacted many seed values consider truncating data prior creating seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"what-to-do-when-a-flag-is-raised","dir":"Articles","previous_headings":"","what":"What to do when a flag is raised","title":"PLANES Interpretation","text":"rplanes package provides mechanism review plausibility epidemiological signals. considering interpret results, paramount distinguish signals may plausible versus possible. signal perceived implausible, may come reflect true patterns reporting horizons evaluated eclipsed. recommend users consider plausibility analysis primarily guide rather replacement subsequent manual review. extent feasible, users may consider manually inspecting flagged signals. inspecting flags, suggest users plot observed seed data along signal evaluated. many flags raised signal appears implausible subject matter experts, users can likely accept plausibility score either censor adjust forecast observed signal evaluated. score also used downstream weight forecast (e.g., ensemble model). flags raised signal appear implausible, inspect individual flagged components. Adjusting arguments repeat trend can increase decrease sensitivity. Short seed data can cause certain components overly-sensitive (diff, repeat, shape, zero), users can either weight components less within plane_score() remove altogether. drawing conclusions rplanes results, recommend users first analyze retrospective data package understand distribution flags expect signal. example, reviewing operational forecasts flu hospitalizations, users may consider retrieving historical forecasts signal, retrospectively masking observed data available forecast week, summarizing plausibility scores. analysis provide critical insight baseline sensitivity signal scoring. Users may consider setting thresholds action future evaluated signals based distribution flags raised analysis.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"summary","dir":"Articles","previous_headings":"","what":"Summary","title":"PLANES Interpretation","text":"many reasons user might want change relative weights individual components leave components plane_score() function altogether. Manual inspection raised flags may informative, particularly users suspect flags raised erroneously (reasons discussed vignette). also recommend collecting (simulating) signals expect trigger flags calibration purposes. Lastly, suggest retrospective analysis plausibility scores batch (across multiple evaluation time points) can highly informative guiding interpretation.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"PLANES Components","text":"rplanes package currently set seven components perform plausibility analysis epidemiological signals (PLANES). individual components assesses different characteristics evaluated signal, resolving binary indicator (.e., TRUE FALSE whether signal implausible). components wrapped via plane_score() function generate overall score based number components flag raised. provide narrative walk individual PLANES components. full list components, along corresponding functions parameters (applicable), provided table . important emphasize rplanes designed work forecasted observed epidemiological signals. However, components work types signals. Several components (including coverage, taper, trend, shape) can used assess plausibility forecasts. components designed take location (.e., string specifying location code), signal prepared to_signal() evaluated, seed prepared plane_seed() holds baseline characteristics. customize behavior, functions accept additional arguments, detailed examples follow. component function returns list standardized minimum return “indicator” element, returns TRUE component flag raised (.e., data implausible) FALSE component flag raised (.e., data implausible). important emphasize individual components wrapped plane_score() function ease--use, practice users likely use wrapper instead accessing functions directly. However, examples use functions outside plane_score() clearly demonstrate operate. Likewise, created mock forecast data examples demonstrate usage. Users refer “Basic Usage” vignette practical guidance prepare data rplanes analyses.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"data-preparation","dir":"Articles","previous_headings":"","what":"Data preparation","title":"PLANES Components","text":"mentioned , data evaluated examples follow mock forecasts. compare forecasted values HHS Protect incident flu hospitalization data aggregated daily weekly resolution, provided internal rplanes package data. details data preparation rplanes see “Basic Usage” vignette. code load required packages, prepare observed data signal to_signal(), convert observed signal seed plane_seed(). Note examples use cut date “2022-06-04” seed data:","code":"## load packages library(rplanes) library(dplyr) library(ggplot2) ## read in observed data hosp_all <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) %>% select(date, location, flu.admits) %>% mutate(date = as.Date(date)) ## prepare observed signal observed_signal <- to_signal(input = hosp_all, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\", horizon = NULL) ## create seed with cut date prepped_seed <- plane_seed(observed_signal, cut_date = \"2022-06-04\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"difference---plane_diff","dir":"Articles","previous_headings":"","what":"Difference - plane_diff()","title":"PLANES Components","text":"difference component checks point--point differences evaluated signal. component can used either forecasts observed signals. function internally computes maximum observed difference (using absolute value) checks see point--point differences evaluated data exceed threshold. , flag raised.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible","dir":"Articles","previous_headings":"Difference - plane_diff()","what":"Flagged as implausible","title":"PLANES Components","text":"example uses forecasted signal 1 week-ahead forecast dramatically jumps recent observed data: seed stores last observed value maximum difference given location: expect implausibility flag raised case: can visualize point--point differences see data jumps forecast:","code":"point_est <- c(100, 120, 140, 160) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(10, 20, 30, 40), ## make a large jump in hospitalizations to trigger diff component point = point_est, upper = point_est + c(10, 20, 30, 40), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 prepped_seed$`01`$diff$max #> [1] 21 plane_diff(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE #> #> $values #> [1] 19 100 120 140 160 #> #> $evaluated_differences #> [1] 81 20 20 20 #> #> $maximum_difference #> [1] 21 diff_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) diff_flags <- diff_dat %>% filter(type == \"forecast\") %>% filter(date == min(date)) diff_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = diff_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Difference component\\nFlagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible","dir":"Articles","previous_headings":"Difference - plane_diff()","what":"Not flagged as implausible","title":"PLANES Components","text":"next example include data “jump” absolute difference beyond observed time series previously: , can see last value maximum observed difference given location used internally seed: Given max difference, expect implausibility flag raised case: plot shows forecasted data raise difference flag:","code":"point_est <- c(28, 31, 34, 37) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 prepped_seed$`01`$diff$max #> [1] 21 plane_diff(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE #> #> $values #> [1] 19 28 31 34 37 #> #> $evaluated_differences #> [1] 9 3 3 3 #> #> $maximum_difference #> [1] 21 diff_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) diff_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Difference component\\nNot flagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"coverage---plane_cover","dir":"Articles","previous_headings":"","what":"Coverage - plane_cover()","title":"PLANES Components","text":"coverage component compares prediction interval first horizon evaluated signal recent value seed. interval cover recent data point, flag raised implausible. component requires prediction interval, can used assess plausibility forecast signals.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-1","dir":"Articles","previous_headings":"Coverage - plane_cover()","what":"Flagged as implausible","title":"PLANES Components","text":"can create forecast data includes prediction interval cover recent value seed: prediction interval quite narrow departs last observed value seed: expect coverage flag raised: plot shows coverage forecast prediction intervals relation seed data:","code":"## make sure the 1 week-ahead point estimate and PI do not cover the last reported obs point_est <- c(60, 62, 64, 66) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(2, 4, 6, 8), point = point_est, upper = point_est + c(2, 4, 6, 8) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 plane_cover(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE #> #> $last_value #> [1] 19 #> #> $bounds #> $bounds$lower #> [1] 58 #> #> $bounds$upper #> [1] 62 cover_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) cov_flags <- cover_dat %>% filter(type == \"observed\") %>% filter(date == max(date)) ggplot(data = cover_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = cov_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Coverage component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-1","dir":"Articles","previous_headings":"Coverage - plane_cover()","what":"Not flagged as implausible","title":"PLANES Components","text":"can put together example prediction interval first horizon covers recent value seed data: Given coverage, expect signal flagged implausible: , can visualize coverage forecast relative seed data:","code":"## make sure the 1 week-ahead point estimate and PI cover the last reported obs point_est <- c(28, 31, 34, 37) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - 28, point = point_est, upper = point_est + 28 ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 plane_cover(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE #> #> $last_value #> [1] 19 #> #> $bounds #> $bounds$lower #> [1] 0 #> #> $bounds$upper #> [1] 56 cover_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) ggplot(data = cover_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Coverage component\\nNot flagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"taper---plane_taper","dir":"Articles","previous_headings":"","what":"Taper - plane_taper()","title":"PLANES Components","text":"taper component checks whether prediction interval evaluated signal decreases width (.e., certainty increases) horizons progress. component requires prediction interval, can used assess plausibility forecast signals.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-2","dir":"Articles","previous_headings":"Taper - plane_taper()","what":"Flagged as implausible","title":"PLANES Components","text":"create mock forecast narrowing prediction interval: width prediction interval narrows 40 30 20 10 forecasted horizons. expect taper flag raised: plot visually demonstrates tapering effect:","code":"point_est <- c(30, 33, 36, 39) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, ## make the lower and upper bounds get narrower as horizon increases lower = point_est - c(20, 15, 10, 5), point = point_est, upper = point_est + c(20, 15, 10, 5) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_taper(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE #> #> $widths #> [1] 40 30 20 10 taper_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) taper_flags <- taper_dat %>% filter(type == \"forecast\") taper_dat %>% ggplot(data = taper_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = taper_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu Hospital Admissions\") + ggtitle(paste(\"Taper component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-2","dir":"Articles","previous_headings":"Taper - plane_taper()","what":"Not flagged as implausible","title":"PLANES Components","text":"Now can look example forecasted prediction interval increases width horizons progress: expect implausibility flag raised case: visualization see forecast prediction interval taper:","code":"point_est <- c(30, 33, 36, 39) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, ## make the lower and upper bounds get wider as horizon increases lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_taper(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE #> #> $widths #> [1] 10 20 30 40 taper_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) taper_dat %>% ggplot(data = taper_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu Hospital Admissions\") + ggtitle(paste(\"Taper component\\nNot flagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"repeat---plane_repeat","dir":"Articles","previous_headings":"","what":"Repeat - plane_repeat()","title":"PLANES Components","text":"repeat component checks whether consecutive values observed forecasted signal repeated k times. seed created, stores maximum number consecutive repeats location uses default value k. evaluated data exceeds k signal considered implausible flag raised. k threshold repeats can customized using “tolerance” parameter. function also allows users customize “prepend” length (.e., number recent values seed concatenated evaluated signal checking repeats). illustrate repeat parameters, can contrive simple example. Consider seed values 11, 12, 13, 13, 13 evaluated forecast point estimates 13, 13, 15, 16. tolerance threshold set 4 prepend length 2 sequence 13, 13, 13, 13, 15, 16 checked set four values repeated consecutively. case, flag raised. value 13 repeated four times tolerate four repeats. However, keep tolerance 4 change prepend length 3, evaluated sequence 13, 13, 13, 13, 13, 15, 16, flag raised, repeats tolerance threshold. parameters see ?plane_repeat().","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-3","dir":"Articles","previous_headings":"Repeat - plane_repeat()","what":"Flagged as implausible","title":"PLANES Components","text":"can mock example data repeats point estimate: can check maximum number repeats seen seed data: number repeated point estimates defined exceeds maximum repeats expect flag raised: can visualize repeats forecast data:","code":"## make sure the point estimates repeat point_est <- c(55, 55, 55, 55) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$max_repeats #> [1] 2 plane_repeat(location = \"01\", input = prepped_forecast, seed = prepped_seed, tolerance = NULL, prepend = NULL) #> $indicator #> [1] TRUE #> #> $repeats #> # A tibble: 4 × 6 #> point location date horizon lower upper #> #> 1 55 01 2022-06-11 1 50 60 #> 2 55 01 2022-06-18 2 45 65 #> 3 55 01 2022-06-25 3 40 70 #> 4 55 01 2022-07-02 4 35 75 repeat_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) repeat_flags <- repeat_dat %>% filter(type == \"forecast\") repeat_dat %>% ggplot(data = repeat_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = repeat_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper,fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Repeat component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"controlling-sensitivity-with-parameters","dir":"Articles","previous_headings":"Repeat - plane_repeat()","what":"Controlling sensitivity with parameters","title":"PLANES Components","text":"described , “tolerance” parameter allows user override default behavior sets maximum number repeats via seed. Setting higher tolerance decrease sensitivity repeat assessment. example, increase tolerance 4 expect flag raised:","code":"plane_repeat(location = \"01\", input = prepped_forecast, seed = prepped_seed, tolerance = 4, prepend = NULL) #> $indicator #> [1] FALSE #> #> $repeats #> # A tibble: 0 × 6 #> # ℹ 6 variables: point , location , date , horizon , #> # lower , upper "},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-3","dir":"Articles","previous_headings":"Repeat - plane_repeat()","what":"Not flagged as implausible","title":"PLANES Components","text":"prepare mock forecast data repeating point estimates: can see maximum number repeats seed: Based threshold, expect implausibility flag repeats raised: Lastly, can visualize repeats signal:","code":"## make sure the point estimates do not repeat point_est <- c(55, 57, 59, 61) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$max_repeats #> [1] 2 plane_repeat(location = \"01\", input = prepped_forecast, seed = prepped_seed, tolerance = NULL, prepend = NULL) #> $indicator #> [1] FALSE #> #> $repeats #> # A tibble: 0 × 6 #> # ℹ 6 variables: point , location , date , horizon , #> # lower , upper repeat_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) repeat_dat %>% ggplot(data = repeat_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Repeat component\\nNot flagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"trend---plane_trend","dir":"Articles","previous_headings":"","what":"Trend - plane_trend()","title":"PLANES Components","text":"trend component assesses whether significant change magnitude direction slope evaluated signal compared recent data seed. “change point” identified forecasted horizons /recent seed value, flag raised implausibility. trend component requires least four times many seed values evaluated values. Furthermore, component currently can used forecasted signals. One parameters trend function “sig_lvl”, defines significance level internal permutation test used detect change points. default value set 0.1. significance level determines sensitivity trend plausibility assessment, lower value corresponding less sensitive evaluation. trend algorithm methods see ?plane_trend().","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-4","dir":"Articles","previous_headings":"Trend - plane_trend()","what":"Flagged as implausible","title":"PLANES Components","text":"create example data doubles forecasted horizon: expect dramatic increase slope detected change point flag raised: plot shows forecasted value identified change point:","code":"point_est <- c(25, 50, 100, 200) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 20, 40), point = point_est, upper = point_est + c(5, 10, 20, 40), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1) #> $indicator #> [1] TRUE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 01 1 2022-02-19 20 Observed FALSE FALSE #> 2 01 2 2022-02-26 14 Observed FALSE FALSE #> 3 01 3 2022-03-05 35 Observed FALSE FALSE #> 4 01 4 2022-03-12 30 Observed FALSE FALSE #> 5 01 5 2022-03-19 30 Observed FALSE FALSE #> 6 01 6 2022-03-26 25 Observed FALSE FALSE #> 7 01 7 2022-04-02 32 Observed FALSE FALSE #> 8 01 8 2022-04-09 29 Observed FALSE FALSE #> 9 01 9 2022-04-16 19 Observed FALSE FALSE #> 10 01 10 2022-04-23 30 Observed FALSE FALSE #> 11 01 11 2022-04-30 13 Observed FALSE FALSE #> 12 01 12 2022-05-07 25 Observed FALSE FALSE #> 13 01 13 2022-05-14 15 Observed FALSE FALSE #> 14 01 14 2022-05-21 12 Observed FALSE FALSE #> 15 01 15 2022-05-28 22 Observed FALSE FALSE #> 16 01 16 2022-06-04 19 Observed FALSE FALSE #> 17 01 17 2022-06-11 25 Forecast FALSE FALSE #> 18 01 18 2022-06-18 50 Forecast TRUE TRUE #> 19 01 19 2022-06-25 100 Forecast FALSE FALSE #> 20 01 20 2022-07-02 200 Forecast FALSE FALSE #> #> $flagged_dates #> [1] \"2022-06-18\" trend_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) trend_flags <- plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1)$output %>% filter(Changepoint == TRUE) ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = trend_flags, mapping = aes(x = Date, y = Value), shape=23, size=4) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Trend component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"controlling-sensitivity-with-parameters-1","dir":"Articles","previous_headings":"Trend - plane_trend()","what":"Controlling sensitivity with parameters","title":"PLANES Components","text":"toggling significance level, can control sensitivity trend assessment. lower significance level 0.001 see flag longer raised using data :","code":"plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.001) #> $indicator #> [1] FALSE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 01 1 2022-02-19 20 Observed FALSE FALSE #> 2 01 2 2022-02-26 14 Observed FALSE FALSE #> 3 01 3 2022-03-05 35 Observed FALSE FALSE #> 4 01 4 2022-03-12 30 Observed FALSE FALSE #> 5 01 5 2022-03-19 30 Observed FALSE FALSE #> 6 01 6 2022-03-26 25 Observed FALSE FALSE #> 7 01 7 2022-04-02 32 Observed FALSE FALSE #> 8 01 8 2022-04-09 29 Observed FALSE FALSE #> 9 01 9 2022-04-16 19 Observed FALSE FALSE #> 10 01 10 2022-04-23 30 Observed FALSE FALSE #> 11 01 11 2022-04-30 13 Observed FALSE FALSE #> 12 01 12 2022-05-07 25 Observed FALSE FALSE #> 13 01 13 2022-05-14 15 Observed FALSE FALSE #> 14 01 14 2022-05-21 12 Observed FALSE FALSE #> 15 01 15 2022-05-28 22 Observed FALSE FALSE #> 16 01 16 2022-06-04 19 Observed FALSE FALSE #> 17 01 17 2022-06-11 25 Forecast FALSE FALSE #> 18 01 18 2022-06-18 50 Forecast FALSE FALSE #> 19 01 19 2022-06-25 100 Forecast FALSE FALSE #> 20 01 20 2022-07-02 200 Forecast FALSE FALSE #> #> $flagged_dates #> [1] NA"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-4","dir":"Articles","previous_headings":"Trend - plane_trend()","what":"Not flagged as implausible","title":"PLANES Components","text":"can also make example data reflects consistent trend seed: case expect implausibility flag raised: visualization shows consistency forecasted trend comparison data seed: Note cases plane_trend() identify change point seed data raise implausibility flag forecast. trend component checks change points forecasted horizons recent value seed. significant change point found elsewhere seed time series, function raise flag. However, output includes change points detected regardless whether raised implausibility flag. demonstrate , can look location “06”. example, need define new prepped_seed object change point occurs previously defined cut date: case expect implausibility flag raised, see change point: Note 2022-09-17, change point detected, forecast, last observed data point flag raised. visualization shows change point observed data:","code":"point_est <- c(40, 41, 40, 43) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1) #> $indicator #> [1] FALSE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 01 1 2022-02-19 20 Observed FALSE FALSE #> 2 01 2 2022-02-26 14 Observed FALSE FALSE #> 3 01 3 2022-03-05 35 Observed FALSE FALSE #> 4 01 4 2022-03-12 30 Observed FALSE FALSE #> 5 01 5 2022-03-19 30 Observed FALSE FALSE #> 6 01 6 2022-03-26 25 Observed FALSE FALSE #> 7 01 7 2022-04-02 32 Observed FALSE FALSE #> 8 01 8 2022-04-09 29 Observed FALSE FALSE #> 9 01 9 2022-04-16 19 Observed FALSE FALSE #> 10 01 10 2022-04-23 30 Observed FALSE FALSE #> 11 01 11 2022-04-30 13 Observed FALSE FALSE #> 12 01 12 2022-05-07 25 Observed FALSE FALSE #> 13 01 13 2022-05-14 15 Observed FALSE FALSE #> 14 01 14 2022-05-21 12 Observed FALSE FALSE #> 15 01 15 2022-05-28 22 Observed FALSE FALSE #> 16 01 16 2022-06-04 19 Observed FALSE FALSE #> 17 01 17 2022-06-11 40 Forecast FALSE FALSE #> 18 01 18 2022-06-18 41 Forecast FALSE FALSE #> 19 01 19 2022-06-25 40 Forecast FALSE FALSE #> 20 01 20 2022-07-02 43 Forecast FALSE FALSE #> #> $flagged_dates #> [1] NA trend_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) trend_flags <- plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1)$output %>% filter(Changepoint == TRUE) ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = trend_flags, mapping = aes(x = Date, y = Value), shape=23, size=4) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Trend component\\nNot flagged\")) ## create seed with cut date prepped_seed2 <- plane_seed(observed_signal, cut_date = \"2022-10-29\") point_est <- c(40, 41, 40, 43) prepped_forecast <- tibble( location = \"06\", date = seq(as.Date(\"2022-11-05\"), as.Date(\"2022-11-26\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_trend(location = \"06\", input = prepped_forecast, seed = prepped_seed2, sig_lvl = 0.1) #> $indicator #> [1] FALSE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 06 1 2022-07-16 102 Observed FALSE FALSE #> 2 06 2 2022-07-23 64 Observed FALSE FALSE #> 3 06 3 2022-07-30 46 Observed FALSE FALSE #> 4 06 4 2022-08-06 39 Observed FALSE FALSE #> 5 06 5 2022-08-13 38 Observed FALSE FALSE #> 6 06 6 2022-08-20 39 Observed FALSE FALSE #> 7 06 7 2022-08-27 33 Observed FALSE FALSE #> 8 06 8 2022-09-03 35 Observed FALSE FALSE #> 9 06 9 2022-09-10 29 Observed FALSE FALSE #> 10 06 10 2022-09-17 24 Observed TRUE FALSE #> 11 06 11 2022-09-24 35 Observed FALSE FALSE #> 12 06 12 2022-10-01 72 Observed FALSE FALSE #> 13 06 13 2022-10-08 93 Observed FALSE FALSE #> 14 06 14 2022-10-15 97 Observed FALSE FALSE #> 15 06 15 2022-10-22 124 Observed FALSE FALSE #> 16 06 16 2022-10-29 211 Observed FALSE FALSE #> 17 06 17 2022-11-05 40 Forecast FALSE FALSE #> 18 06 18 2022-11-12 41 Forecast FALSE FALSE #> 19 06 19 2022-11-19 40 Forecast FALSE FALSE #> 20 06 20 2022-11-26 43 Forecast FALSE FALSE #> #> $flagged_dates #> [1] NA trend_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"06\") %>% filter(date <= \"2022-10-29\") %>% mutate(type=\"observed\"), . ) trend_flags <- plane_trend(location = \"06\", input = prepped_forecast, seed = prepped_seed2, sig_lvl = 0.1)$output %>% filter(Changepoint == TRUE) ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = trend_flags, mapping = aes(x = Date, y = Value), shape=23, size=4) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Trend component\\nNot flagged but change point in seed\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"shape---plane_shape","dir":"Articles","previous_headings":"","what":"Shape - plane_shape()","title":"PLANES Components","text":"shape component evaluates shape trajectory forecast signal compares shape existing shapes observed seed data. shape identified novel, flag raised, signal considered implausible. component one additional argument defines method used identify shapes - one “sdiff” (scaled difference; set default) “dtw” (Dynamic Time Warping). Based preliminary analyses, “dtw” method higher sensitivity slightly lower specificity “sdiff” method much computationally expensive. information shape algorithm, see ?plane_shape().","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-5","dir":"Articles","previous_headings":"Shape - plane_shape()","what":"Flagged as implausible","title":"PLANES Components","text":"example , set point estimates prediction intervals forecast signal shape novel compared seed data (see plot ). expect implausibility flag raised example: indicator TRUE, meaning forecast implausible, shape novel relative seed data. can visualize shape differences see shape flagged. forecast plot (red line) clearly looks different shape observed seed data (blue line):","code":"point_est <- c(60, 60, 60, 10) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - 10, ## make an unusual shape in hospitalizations to trigger shape component point = point_est, upper = point_est + 10, ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_shape(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE shape_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) shape_flags <- shape_dat %>% filter(type == \"forecast\") shape_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = shape_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Shape component\\nFlagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-5","dir":"Articles","previous_headings":"Shape - plane_shape()","what":"Not flagged as implausible","title":"PLANES Components","text":"Next ’ll look example forecast familiar shape shouldn’t trigger flag: expect implausibility flag raised example: indicator FALSE, meaning forecast considered plausible, shape familiar relative seed data. can visualize shape similarities/differences see shape flagged. forecast plot (red line) looks similar shape see observed seed data (blue line) mid April mid June:","code":"point_est <- c(28, 18, 30, 20) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - 10, ## make a familiar shape in hospitalizations to not trigger shape component point = point_est, upper = point_est + 10, ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_shape(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE shape_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) shape_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Shape component\\nNot Flagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"zero---plane_zero","dir":"Articles","previous_headings":"","what":"Zero - plane_zero()","title":"PLANES Components","text":"function checks presence value(s) equal zero evaluated signal. zeros found, function look seed see zeros anywhere else time series. , function consider evaluated zero plausible flags raised (.e., indicator returned FALSE). , function consider evaluated zero implausible flag raised (.e., indicator returned TRUE). function can used either forecast observed signals.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-6","dir":"Articles","previous_headings":"Zero - plane_zero()","what":"Flagged as implausible","title":"PLANES Components","text":"example , add zero signal point estimate location seed zeros: seed stores logical indicating whether zeros present seed data, none example: expect implausibility flag raised location: indicator TRUE, meaning forecast signal implausible zeros forecast signal observed seed. can visualize . signal red (forecast example) zero early July, zeros found seed data blue.","code":"point_est <- c(31, 30, 31, 0) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = c(26,24,24,0), ## add zeros in hospitalizations to trigger zero component point = point_est, upper = c(36,36,38,15) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$any_zeros #> [1] FALSE plane_zero(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE zero_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) zero_flags <- zero_dat %>% filter(flu.admits == 0) zero_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(data = zero_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Zero component\\nFlagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-6","dir":"Articles","previous_headings":"Zero - plane_zero()","what":"Not flagged as implausible","title":"PLANES Components","text":"function trigger implausibility flag zero signal (either observed forecast) one seed. words, flag raised : (1) zeros signal (2) zeros seed. Let’s look example zeros signal (location “02”) seed. flag triggered: seed stores logical indicating whether zeros present seed data, zeros example: expect implausibility flag raised location: indicator FALSE, meaning forecast signal plausible, zeros forecast signal observed seed. can visualize . signal red (forecast example) zero around early-mid June, also zeros found seed data blue.","code":"point_est <- c(0, 6, 2, 3) prepped_forecast <- tibble( location = \"02\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = c(0,5,0,1), ## add zeros in hospitalizations point = point_est, upper = c(1,7,4,5), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`02`$any_zeros #> [1] TRUE plane_zero(location = \"02\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE zero_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"02\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) zero_flags <- zero_dat %>% filter(flu.admits == 0) zero_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(data = zero_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Zero component\\nNot Flagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"rplanes Explorer","text":"rplanes features Shiny app allows users interact package functions perform plausibility analysis epidemiological signals. rplanes Explorer app developed maintained part R package. Users can launch app locally use hosted Shiny server running rplanes_explorer() function.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"analysis-steps","dir":"Articles","previous_headings":"","what":"Analysis steps","title":"rplanes Explorer","text":"application allows users run plausibility analysis several steps: Select type signal evaluated Upload data use plausibility analysis seed Upload data containing signal evaluated (observed signal identify number points evaluate) Enter resolution, outcome, forecast horizon (applicable) Optionally modify default parameters used analysis Click “Analyze”","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"example-data","dir":"Articles","previous_headings":"","what":"Example data","title":"rplanes Explorer","text":"app includes example data help users familiarize plausibility analysis features. example based observed data originally obtained healthdata.gov flu admissions (“previous_day_admission_influenza_confirmed” field) aggregated location epidemiological week. data includes states national resolution United States. selection observed data used example provided : example forecast data set evaluated selected CDC FluSight hospitalization forecasts submitted 2021-2022 2022-2023 influenza seasons. selection forecast data used example provided :","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"inputs-and-outputs","dir":"Articles","previous_headings":"Usage","what":"Inputs and outputs","title":"rplanes Explorer","text":"app includes inputs type signal evaluated, file uploads (needed), parameter modifications. analysis complete, output analysis displayed visually user collection plots tables. “Help” tab app includes detailed information inputs outputs explorer app.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"launching-the-app","dir":"Articles","previous_headings":"Usage","what":"Launching the app","title":"rplanes Explorer","text":"app delivered function rplanes package. launch app, users can run rplanes_explorer() function. Note function wraps shiny::runApp() inherits arguments. example, adding argument launch.browser = TRUE open app web browser setting port = 80 run app port 80 localhost.","code":"library(rplanes) rplanes_explorer(host = \"0.0.0.0\", launch.browser = TRUE, port = 80)"},{"path":"https://signaturescience.github.io/rplanes/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"VP Nagraj. Author, maintainer. Desiree Williams. Author. Amy Benefield. Author.","code":""},{"path":"https://signaturescience.github.io/rplanes/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Nagraj V, Williams D, Benefield (2024). rplanes: Plausibility Analysis Epidemiological Signals. R package version 0.1.0, https://signaturescience.github.io/rplanes/.","code":"@Manual{, title = {rplanes: Plausibility Analysis of Epidemiological Signals}, author = {VP Nagraj and Desiree Williams and Amy Benefield}, year = {2024}, note = {R package version 0.1.0}, url = {https://signaturescience.github.io/rplanes/}, }"},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"introduction","dir":"","previous_headings":"","what":"Introduction","title":"Plausibility Analysis of Epidemiological Signals","text":"rplanes package (plausibility analysis epidemiological signals) provides functionality prepare data analyze plausibility forecasted reported epidemiological signals. functions implement set plausibility algorithms agnostic geographic time resolutions calculated independently presented combined score.","code":""},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Plausibility Analysis of Epidemiological Signals","text":"package available install CRAN: Alternatively can install package GitHub:","code":"install.packages(\"rplanes\") #install.packages(\"remotes\") remotes::install_github(\"signaturescience/rplanes\", build_vignettes=TRUE)"},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"getting-started","dir":"","previous_headings":"","what":"Getting Started","title":"Plausibility Analysis of Epidemiological Signals","text":"rplanes package includes vignettes describing package features detail. get started, refer “Basic Usage” vignette package website R console:","code":"vignette(\"basic-usage\", package=\"rplanes\")"},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"contributing","dir":"","previous_headings":"","what":"Contributing","title":"Plausibility Analysis of Epidemiological Signals","text":"Please use GitHub issues report bugs request features. Contributions reviewed via pull requests.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":null,"dir":"Reference","previous_headings":"","what":"Check completeness of seed and signal data — check_incomplete","title":"Check completeness of seed and signal data — check_incomplete","text":"unexported helper used internally valid_dates optionally issue warning potential completeness seed signal data based dates provided.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check completeness of seed and signal data — check_incomplete","text":"","code":"check_incomplete(seed_date, signal_date, resolution)"},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check completeness of seed and signal data — check_incomplete","text":"seed_date Last date available seed object signal_date First date available signal object resolution Character vector specifying temporal resolution (e.g., \"weeks\", \"months\")","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check completeness of seed and signal data — check_incomplete","text":"Operates side-effect returns warning() seed signal dates combined indicate incomplete week month.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":null,"dir":"Reference","previous_headings":"","what":"Sliding windows — create_sliding_windows_df","title":"Sliding windows — create_sliding_windows_df","text":"unexported helper function used within plane_shape() generate sliding windows vector return data frame row subset (sliding window) time series. length windowed time series (therefore number columns) equal \"window_size\". number windows equal (length(vector) - window_size) + 1. example, given time series length 38 window size length 4, 35 windowed time series (rows), 4 time stamps (columns).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sliding windows — create_sliding_windows_df","text":"","code":"create_sliding_windows_df(vector, window_size)"},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sliding windows — create_sliding_windows_df","text":"vector numeric integer vector time series used create sliding windows window_size integer specifying size (.e., number elements) windowed time series desired","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Sliding windows — create_sliding_windows_df","text":"data.frame row subset (sliding window) time series.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":null,"dir":"Reference","previous_headings":"","what":"Cut into categorical differences — cutter","title":"Cut into categorical differences — cutter","text":"unexported helper function takes input number observed difference cuts categorical description (e.g., \"increase\", \"decrease\", \"stable\") change.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cut into categorical differences — cutter","text":"","code":"cutter(x, threshold = 1)"},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cut into categorical differences — cutter","text":"x Vector length 1 scaled difference categorized threshold Limit used define categorical differences; default 1","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Cut into categorical differences — cutter","text":"Character vector length 1 categorical description difference","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":null,"dir":"Reference","previous_headings":"","what":"Epiweek start — epiweek_start","title":"Epiweek start — epiweek_start","text":"unexported helper identifies date first day epiweek given date. function used internally inside valid_dates.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Epiweek start — epiweek_start","text":"","code":"epiweek_start(date)"},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Epiweek start — epiweek_start","text":"date Date queried","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Epiweek start — epiweek_start","text":"Date first day epiweek input date.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":null,"dir":"Reference","previous_headings":"","what":"Determine shapes — get_shapes","title":"Determine shapes — get_shapes","text":"unexported helper function used identify shape plane_shape() function's scaled difference (\"sdiff\") method.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Determine shapes — get_shapes","text":"","code":"get_shapes(input_data, window_size)"},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Determine shapes — get_shapes","text":"input_data data frame containing least two columns, one must named \"value\" value assessed another named \"dates\" date observed data window_size number categorical differences used define shape","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Determine shapes — get_shapes","text":"vector shapes identified. element vector include shape, cluster categorical differences (size specified \"window_size\") collapsed \";\" (e.g., c(\"decrease;stable;stable;stable\",\"stable;stable;stable;increase\",\"stable;stable;increase;increase\")).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":null,"dir":"Reference","previous_headings":"","what":"Check forecast — is_forecast","title":"Check forecast — is_forecast","text":"function checks object class signal forecast.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check forecast — is_forecast","text":"","code":"is_forecast(x)"},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check forecast — is_forecast","text":"x Input object checked","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check forecast — is_forecast","text":"Logical whether input object inherits \"signal\" \"forecast\" classes.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check forecast — is_forecast","text":"","code":"## get path to example forecast file fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") ex_forecast <- read_forecast(fp) sig <- to_signal(ex_forecast, outcome=\"flu.admits\", type=\"forecast\", horizon=4, resolution=\"weeks\") is_forecast(sig)"},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":null,"dir":"Reference","previous_headings":"","what":"Check observed — is_observed","title":"Check observed — is_observed","text":"function checks object class signal observed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check observed — is_observed","text":"","code":"is_observed(x)"},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check observed — is_observed","text":"x Input object checked","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check observed — is_observed","text":"Logical whether input object inherits \"signal\" \"observed\" classes.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check observed — is_observed","text":"","code":"hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") sig <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") is_observed(sig)"},{"path":"https://signaturescience.github.io/rplanes/reference/month-subtraction.html","id":null,"dir":"Reference","previous_headings":"","what":"Month subtraction — %m-%","title":"Month subtraction — %m-%","text":"See lubridate::%m-% details.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month-subtraction.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Month subtraction — %m-%","text":"e1 period date-time object class POSIXlt, POSIXct Date. e2 period date-time object class POSIXlt, POSIXct Date. Note one e1 e2 must period date-time object.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month-subtraction.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Month subtraction — %m-%","text":"date-time object class POSIXlt, POSIXct Date","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":null,"dir":"Reference","previous_headings":"","what":"Month start — month_start","title":"Month start — month_start","text":"unexported helper identifies date first day month given date. function used internally inside valid_dates.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Month start — month_start","text":"","code":"month_start(date)"},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Month start — month_start","text":"date Date queried","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Month start — month_start","text":"Date first day month input date.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":null,"dir":"Reference","previous_headings":"","what":"Pipe operator — %>%","title":"Pipe operator — %>%","text":"See magrittr::%>% details.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Pipe operator — %>%","text":"","code":"lhs %>% rhs"},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Pipe operator — %>%","text":"lhs value magrittr placeholder. rhs function call using magrittr semantics.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Pipe operator — %>%","text":"result calling rhs(lhs).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":null,"dir":"Reference","previous_headings":"","what":"Coverage component — plane_cover","title":"Coverage component — plane_cover","text":"function evaluates whether evaluated signal interval covers last observed value. interval used plausibility component drawn upper lower bounds forecasted prediction interval. , accepted signal format forecast, include upper lower bounds.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Coverage component — plane_cover","text":"","code":"plane_cover(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Coverage component — plane_cover","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Coverage component — plane_cover","text":"list following values: indicator: Logical whether last value falls outside interval (e.g., lower upper bounds prediction interval) evaluated signal last_value: vector last value recorded seed bounds: list two elements corresponding upper lower bounds evaluated signal interval","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Coverage component — plane_cover","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_cover(location = \"08\", input = prepped_forecast, seed = prepped_seed) plane_cover(location = \"47\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":null,"dir":"Reference","previous_headings":"","what":"Difference component — plane_diff","title":"Difference component — plane_diff","text":"function implements point--point difference plausibility component. Differences evaluated signals calculated input values iteratively subtracted previous values (.e., x time point , difference calculated xi - xi-1). plausibility analysis uses evaluated differences compare maximum difference observed recorded seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Difference component — plane_diff","text":"","code":"plane_diff(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Difference component — plane_diff","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast observed seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Difference component — plane_diff","text":"list following values: indicator: Logical whether absolute value evaluated differences exceeds maximum difference values: vector values assessed including last value seed concatenated evaluated signal values evaluated_differences: vector consecutive differences values maximum_difference: vector one value maximum difference observed seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Difference component — plane_diff","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_diff(location = \"10\", input = prepped_forecast, seed = prepped_seed) plane_diff(location = \"51\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":null,"dir":"Reference","previous_headings":"","what":"Repeat component — plane_repeat","title":"Repeat component — plane_repeat","text":"function evaluates whether consecutive values observations forecasts repeated k number times. function takes forecast observed object either observed dataset forecast dataset. Note signal contant (.e., value repeated time points) repeat component return FALSE.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Repeat component — plane_repeat","text":"","code":"plane_repeat(location, input, seed, tolerance = NULL, prepend = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Repeat component — plane_repeat","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast observed seed Prepared seed tolerance Integer value number allowed repeats flag raised. Default NULL allowed repeats determined seed. prepend Integer value number values seed add evaluated signal. Default NULL number values determined seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Repeat component — plane_repeat","text":"list following values: indicator: Logical whether value repeated sequentially k number times. repeats: tibble repeating values found. repeats (.e., indicator FALSE) tibble 0 rows.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Repeat component — plane_repeat","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component ## use defaults plane_repeat(location = \"12\", input = prepped_forecast, seed = prepped_seed) ## set tolerated repeats to 2 plane_repeat(location = \"12\", input = prepped_forecast, seed = prepped_seed, tolerance = 2) ## use defaults plane_repeat(location = \"49\", input = prepped_forecast, seed = prepped_seed) ## set number of values prepended for evaluation to 4 plane_repeat(location = \"49\", input = prepped_forecast, seed = prepped_seed, prepend = 4)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":null,"dir":"Reference","previous_headings":"","what":"Score PLANES components — plane_score","title":"Score PLANES components — plane_score","text":"function wraps PLANES scoring specified components across locations single step.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Score PLANES components — plane_score","text":"","code":"plane_score(input, seed, components = \"all\", args = NULL, weights = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Score PLANES components — plane_score","text":"input Input signal data scored; object must one forecast observed seed Prepared seed components Character vector specifying component; must either \"\" combination \"cover\", \"diff\", \"taper\", \"trend\", \"repeat\", \"shape\", \"zero\"; default \"\" use available components given signal args Named list arguments component functions. List elements must named match given component arguments passed nested list (e.g., args = list(\"trend\" = list(\"sig_lvl\" = 0.05))). Default NULL defaults components used weights Named vector weights applied; default NULL components equally weighted; NULL length vector must equal number components, component given numeric weight (see Examples). Specified weights must real numbers greater equal 1.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Score PLANES components — plane_score","text":"list scoring results locations.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Score PLANES components — plane_score","text":"","code":"# \\donttest{ ## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane scoring with all components plane_score(input = prepped_forecast, seed = prepped_seed) ## run plane scoring with select components plane_score(input = prepped_forecast, seed = prepped_seed, components = c(\"cover\",\"taper\")) ## run plane scoring with all components and additional args trend_args <- list(\"sig_lvl\" = 0.05) repeat_args <- list(\"prepend\" = 4, \"tolerance\" = 8) shape_args <- list(\"method\" = \"dtw\") comp_args <- list(\"trend\" = trend_args, \"repeat\" = repeat_args, \"shape\" = shape_args) plane_score(input = prepped_forecast, seed = prepped_seed, args = comp_args) ## run plane scoring with specific components and weights comps <- c(\"cover\", \"taper\", \"diff\") wts <- c(\"cover\" = 1.5, \"taper\" = 1, \"diff\" = 4) plane_score(input = prepped_forecast, seed = prepped_seed, components = comps, weights = wts) # }"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":null,"dir":"Reference","previous_headings":"","what":"Create seed — plane_seed","title":"Create seed — plane_seed","text":"function wraps seed_engine operate across locations input signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create seed — plane_seed","text":"","code":"plane_seed(input, cut_date = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create seed — plane_seed","text":"input Input signal data used seeding; must observed signal object cut_date Maximum date (inclusive) seeding performed; default NULL entire input used seeding","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create seed — plane_seed","text":"named list length n, multiple elements corresponding seed characteristics metadata n locations nested independent lists.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create seed — plane_seed","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## prepare seed with no cut date plane_seed(prepped_observed) ## prepare seed with cut date plane_seed(prepped_observed, cut_date = \"2022-10-29\")"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":null,"dir":"Reference","previous_headings":"","what":"Shape component — plane_shape","title":"Shape component — plane_shape","text":"function identifies shape trajectory forecasted signal compare existing shapes seed data. shape identified novel, flag raised, signal considered implausible. See Details section information.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Shape component — plane_shape","text":"","code":"plane_shape(location, input, seed, method = \"sdiff\")"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Shape component — plane_shape","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast seed Prepared seed method method determining shapes; must one \"sdiff\" \"dtw\" (see Details); default \"sdiff\"","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Shape component — plane_shape","text":"list following values: indicator: Logical whether shape evaluated signal novel (TRUE shape novel, FALSE familiar shape exists seed)","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Shape component — plane_shape","text":"approach determining shapes can customized user plane_shape() \"method\" argument. two methods available \"sdiff\" (default) \"dtw\". Compared \"sdiff\", \"dtw\" method shown higher sensitivity, lower specificity, much greater computational cost circumstances. \"sdiff\" method recommended computational efficiency concern. \"sdiff\" method use consecutive scaled differences construct shapes. algorithm operates three steps: prepared seed data combined forecasted point estimates point--point difference calculated. differences centered scaled, cut categories. Differences greater equal one standard deviation mean differences considered \"increase\". Differences less equal one standard deviation mean differences considered \"decrease\". differences considered \"stable\". categorical differences combined windows equal size forecasted horizon. Collectively combined categorical differences create \"shape\" (e.g., \"increase;stable;stable;decrease\"). Lastly, algorithm compares shape forecast shapes observed. shape assessed previously observed time series flag raised indicator returned TRUE. \"dtw\" method uses Dynamic Time Warping (DTW) algorithm identify shapes within seed data compares shape forecast input signal observed shapes. done three broad steps: prepared seed data divided set sliding windows step size one, representing section overall time series. length windows determined horizon length input data signal (e.g., 2 weeks). example, seed data vector, c(1, 2, 3, 4, 5), horizon length 2, sliding windows observed seed data : c(1, 2), c(2, 3), c(3, 4), c(4, 5). sliding window subset total trajectory shape observed data. Shape-based DTW distances calculated every 1x1 combination observed sliding windows stored distance matrix. distances calibrate function identifying outlying shapes forecast data. algorithm finds minimum distances windowed time series use baseline \"observed distances\" chunks larger observed time series. maximum minimum distances across observed time series set threshold. minimum forecast:observed distance matrix greater threshold, forecast inferred unfamiliar (.e., novel shape). Next, algorithm calculates shape-based DTW distances forecast signal (including point estimate, lower, upper bounds) every observed sliding window. distance forecast observed sliding window less equal threshold defined , shape novel flag raised (indicator FALSE).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Shape component — plane_shape","text":"Toni Giorgino. Computing Visualizing Dynamic Time Warping Alignments R: dtw Package. Journal Statistical Software, 31(7), 1-24. doi:10.18637/jss.v031.i07 Tormene, P.; Giorgino, T.; Quaglini, S. & Stefanelli, M. Matching incomplete time series dynamic time warping: algorithm application post-stroke rehabilitation. Artif Intell Med, 2009, 45, 11-34. doi:10.1016/j.artmed.2008.11.007","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Shape component — plane_shape","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) tmp_hosp <- hosp %>% dplyr::select(date, location, flu.admits) %>% dplyr::mutate(date = as.Date(date)) prepped_observed <- to_signal(tmp_hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal prepped_forecast <- read_forecast(system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\")) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_shape(location = \"37\", input = prepped_forecast, seed = prepped_seed) ## run plane component with DTW method plane_shape(location = \"37\", input = prepped_forecast, seed = prepped_seed, method = \"dtw\")"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":null,"dir":"Reference","previous_headings":"","what":"Taper component — plane_taper","title":"Taper component — plane_taper","text":"function evaluates whether evaluated signal interval tapers (.e., decreases width) horizons progress. interval used plausibility component drawn upper lower bounds forecasted prediction interval. , accepted signal format forecast, include upper lower bounds.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Taper component — plane_taper","text":"","code":"plane_taper(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Taper component — plane_taper","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Taper component — plane_taper","text":"list following values: indicator: Logical whether prediction interval width tapers advancing horizons widths: Consecutive interval widths forecasted data","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Taper component — plane_taper","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_taper(location = \"19\", input = prepped_forecast, seed = prepped_seed) plane_taper(location = \"44\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":null,"dir":"Reference","previous_headings":"","what":"Trend component — plane_trend","title":"Trend component — plane_trend","text":"function identifies change points forecast data final observed data point. Change points identified significant change magnitude direction slope time series.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Trend component — plane_trend","text":"","code":"plane_trend(location, input, seed, sig_lvl = 0.1)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Trend component — plane_trend","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must forecast seed Prepared seed sig_lvl significance level identify change points (zero one); default 0.1","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Trend component — plane_trend","text":"list following values: indicator: Logical whether forecast data final observed data point significant change point output: n x 7 tibble. length forecast plus observed data determine length n. columns : Location: character vector location code Index: integer index observed forecast data Date: dates corresponding observed forecast data (formatted date) Value: incidence observed forecast data (e.g., hospitalization rates) Type: Indicates whether data row observed forecast data Changepoint: Logical identifying change point (whether observed forecast data). TRUE returned point determined change point based user defined significance level (sig_lvl). Flagged: Logical indicating whether change point flagged. Change points flagged forecast data final observed data point. TRUE returned Changepoint TRUE final observed data point forecast point. flagged_dates: date flagged change point(s). none, NA returned","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Trend component — plane_trend","text":"function uses e.divisive(), implements hierarchical divisive algorithm identify change points based distances segments (calculated using equations 3 5 Matteson James, 2014; larger distance, likely change point). permutation test used calculate approximate p-value. input e.divisive() transformed using differencing (.e., diff(x) instead raw data, x). slightly changes way change points identified, index aligns gap points rather points . Instead identifying change point based change size two points, identifies change points based change change . dataframe illustrates difference x diff(x): Given data, e.divisive(x) identify index 5 (74) change point, jump +37 index 4 5. e.divisive(diff(x)) pick index 3 (28) 5 (1), jump +28 index 2 3, jump -36 index 4 5. Internally, trend function uses extra argument e.divisive() min.size = 2, requires gap least 2 points detecting change points. can indirectly increase significance level decrease number change points identified.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Trend component — plane_trend","text":"Matteson, D. S., & James, N. . (2014). nonparametric approach multiple change point analysis multivariate data. Journal American Statistical Association, 109(505), 334–345. https://doi.org/10.1080/01621459.2013.849605 Matteson DS, James NA (2013). “Nonparametric Approach Multiple Change Point Analysis Multivariate Data.” ArXiv e-prints. appear Journal American Statistical Association, 1306.4933. Gandy, . (2009) \"Sequential implementation Monte Carlo tests uniformly bounded resampling risk.\" Journal American Statistical Association.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Trend component — plane_trend","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) tmp_hosp <- hosp %>% dplyr::select(date, location, flu.admits) %>% dplyr::mutate(date = as.Date(date)) prepped_observed <- to_signal(tmp_hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal prepped_forecast <- read_forecast(system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\")) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_trend(location = \"05\", input = prepped_forecast, seed = prepped_seed, sig_lvl = .2) ## change location plane_trend(location = \"09\", input = prepped_forecast, seed = prepped_seed, sig_lvl = .2) ## change sig_lvl plane_trend(location = \"06\", input = prepped_forecast, seed = prepped_seed, sig_lvl = .05)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":null,"dir":"Reference","previous_headings":"","what":"Zero component — plane_zero","title":"Zero component — plane_zero","text":"function checks presence value(s) equal zero evaluated signal. zeros found, function assesses whether zeros observed seed given location. , function consider evaluated zero plausible flag raised (.e., indicator returned FALSE). , function consider evaluated zero implausible flag raised (.e., indicator returned TRUE).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Zero component — plane_zero","text":"","code":"plane_zero(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Zero component — plane_zero","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast observed seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Zero component — plane_zero","text":"list following values: indicator: Logical whether zeros evaluated signal seed data","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Zero component — plane_zero","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_zero(location = \"10\", input = prepped_forecast, seed = prepped_seed) plane_zero(location = \"51\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":null,"dir":"Reference","previous_headings":"","what":"Quantile boundary — q_boundary","title":"Quantile boundary — q_boundary","text":"unexported helper generates vector lower bound, median, upper bound prediction interval specified width. function used internally inside read_forecast.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Quantile boundary — q_boundary","text":"","code":"q_boundary(pi_width)"},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Quantile boundary — q_boundary","text":"pi_width Interval width integer","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Quantile boundary — q_boundary","text":"Vector quantiles corresponding lower upper bounds centered median.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":null,"dir":"Reference","previous_headings":"","what":"Read in forecast file — read_forecast","title":"Read in forecast file — read_forecast","text":"function reads probabilistic (\"quantile\") forecast csv file prepares to_signal function downstream plausibility analysis. quantile forecast file can either \"legacy\" \"hubverse\" format (see Details information). object returned tibble summarized forecast data (.e., prediction interval) location horizon original file.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Read in forecast file — read_forecast","text":"","code":"read_forecast(file, pi_width = 95, format = \"legacy\")"},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Read in forecast file — read_forecast","text":"file Path csv file containing quantile forecasts pi_width Width prediction interval integer; default 95 corresponds 95% prediction interval format Format probabilistic format file; must one \"legacy\" \"hubverse\" (see Details information); default \"legacy\"","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Read in forecast file — read_forecast","text":"tibble following columns: location: Geographic unit FIPS code date: Date corresponding forecast horizon horizon: Forecast horizon lower: Lower limit prediction interval forecast point: Point estimate forecast upper: Upper limit prediction interval forecast","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Read in forecast file — read_forecast","text":"probabilistic forecast format used multiple forecasting hubs. general, format includes one row per combination quantile, location, target, horizon. row forecasted value provided. specific format, including columns required, changed time. function accommodates \"legacy\" well recent \"hubverse\" formats. details specific columns see links References.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Read in forecast file — read_forecast","text":"Hubverse: https://hubdocs.readthedocs.io/en/latest/user-guide/model-output.html Legacy: https://github.com/cdcepi/Flusight-forecast-data/tree/master/data-forecasts#forecast-file-format","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Read in forecast file — read_forecast","text":"","code":"## read in example forecast and prep forecast signal (legacy format) fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") read_forecast(fp) fp2 <- system.file(\"extdata/forecast/2023-11-04-SigSci-TSENS.csv\", package = \"rplanes\") read_forecast(fp2, format = \"hubverse\")"},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":null,"dir":"Reference","previous_headings":"","what":"Resolve resolution — resolve_resolution","title":"Resolve resolution — resolve_resolution","text":"helper function uses argument matching resolve resolution input. function also handles casing. allow, example, input resolution \"daily\" \"day\" resolved \"days\".","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Resolve resolution — resolve_resolution","text":"","code":"resolve_resolution(resolution)"},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Resolve resolution — resolve_resolution","text":"resolution Character vector specifying temporal resolution (e.g., \"days\", \"weeks\", \"months\")","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Resolve resolution — resolve_resolution","text":"resolution matches \"days\", \"weeks\", \"months\" match returned. , function throw error.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes-package.html","id":null,"dir":"Reference","previous_headings":"","what":"rplanes: Plausibility Analysis of Epidemiological Signals — rplanes-package","title":"rplanes: Plausibility Analysis of Epidemiological Signals — rplanes-package","text":"Provides functionality prepare data analyze plausibility forecasted reported epidemiological signals. functions implement set plausibility algorithms agnostic geographic time resolutions calculated independently presented combined score.","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"rplanes: Plausibility Analysis of Epidemiological Signals — rplanes-package","text":"Maintainer: VP Nagraj nagraj@nagraj.net (ORCID) Authors: Desiree Williams Amy Benefield","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":null,"dir":"Reference","previous_headings":"","what":"rplanes explorer app launcher — rplanes_explorer","title":"rplanes explorer app launcher — rplanes_explorer","text":"rplanes explorer app allows user interactively upload data (view internal example) explore plausibility analysis functionality.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"rplanes explorer app launcher — rplanes_explorer","text":"","code":"rplanes_explorer(...)"},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"rplanes explorer app launcher — rplanes_explorer","text":"... Additional arguments passed shiny::runApp","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"rplanes explorer app launcher — rplanes_explorer","text":"function operates side-effect starts rplanes Shiny app.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"rplanes explorer app launcher — rplanes_explorer","text":"","code":"if (FALSE) { # \\dontrun{ # Launch the explorer app rplanes_explorer(host = \"0.0.0.0\", launch.browser = TRUE, port = 80) } # }"},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":null,"dir":"Reference","previous_headings":"","what":"Seed engine — seed_engine","title":"Seed engine — seed_engine","text":"helper function used inside plane_seed evaluate characteristics observed data use downstream plausibility analysis.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Seed engine — seed_engine","text":"","code":"seed_engine(input, location, cut_date = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Seed engine — seed_engine","text":"input Input signal data used seeding; must observed signal object location Character vector location code cut_date Maximum date (inclusive) seeding performed; default NULL entire input used seeding","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Seed engine — seed_engine","text":"list length 1 multiple elements corresponding seed characteristics metadata given location.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":null,"dir":"Reference","previous_headings":"","what":"Chunk a vector — to_chunk","title":"Chunk a vector — to_chunk","text":"unexported helper function creates list contents vector spit chunks. user can specify large chunk \"size\" argument.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Chunk a vector — to_chunk","text":"","code":"to_chunk(x, size)"},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Chunk a vector — to_chunk","text":"x Vector split chunks large \"size\" specified size Width chunks \"x\" vector","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Chunk a vector — to_chunk","text":"list many elements number chunks created. element include vector length equal \"size\" specified.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":null,"dir":"Reference","previous_headings":"","what":"Create signal object — to_signal","title":"Create signal object — to_signal","text":"function creates object S3 class \"signal\". user can conditionally specify either \"forecast\" \"observed\" signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create signal object — to_signal","text":"","code":"to_signal( input, outcome, type = \"observed\", resolution = \"weeks\", horizon = NULL )"},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create signal object — to_signal","text":"input Data converted signal; see \"Details\" information outcome Name outcome column input data type Signal type; must one \"observed\" \"forecast\"; default \"observed\" resolution temporal resolution signal; data can aggregated daily, weekly, monthly; default \"weeks\"; see \"Details\" information horizon Number time steps ahead forecast signals; used type=\"forecast\"; default NULL","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create signal object — to_signal","text":"object class signal. object second class either observed forecast depending value passed \"type\" argument.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Create signal object — to_signal","text":"input signal data may either \"observed\" \"forecast\" data. Depending type, input data must conform certain format prior submission. cases, data must passed data frame. \"observed\" data data frame must minimum include columns location (geographic unit FIPS code) date (date reported value; must date class). data also include column contains outcome (e.g., case count). \"forecast\" data data frame must include columns location (geographic unit FIPS code), date (date corresponding forecast horizon; must date class character formatted 'YYYY-MM-DD'), horizon (forecast horizon), lower (lower limit prediction interval forecast), point (point estimate forecast), upper (upper limit prediction interval forecast). Note read_forecast function returns data format. input data must daily, weekly, monthly resolution. \"resolution\" parameter designed use string matching. allows flexibility user, , example, input \"day\", \"days\", \"daily\" resolve resolution days. rules apply designating weekly monthly resolution.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create signal object — to_signal","text":"","code":"hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") ex_forecast <- read_forecast(fp) to_signal(ex_forecast, outcome = \"flu.admits\", type = \"forecast\", horizon = 4, resolution = \"weeks\")"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":null,"dir":"Reference","previous_headings":"","what":"Validate dates — valid_dates","title":"Validate dates — valid_dates","text":"function validates gaps overlaps dates specified \"seed_date\" \"signal_date\". plausibility component analyses, function called validate seed evaluated signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Validate dates — valid_dates","text":"","code":"valid_dates(seed_date, signal_date, resolution, warn_incomplete = FALSE)"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Validate dates — valid_dates","text":"seed_date Last date available seed object signal_date First date available signal object resolution Character vector specifying temporal resolution (e.g., \"days\", \"weeks\", \"months\") warn_incomplete Logical whether validation warn completeness seed signal; default FALSE","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Validate dates — valid_dates","text":"validation return stop() overlap gap seed signal dates. Otherwise function invisibly return TRUE indicating date span valid.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Validate dates — valid_dates","text":"","code":"seed_date <- as.Date(\"2023-03-08\") signal_date <- as.Date(\"2023-03-15\") valid_dates(seed_date = seed_date, signal_date = signal_date, resolution=\"weeks\") x <- try(valid_dates(seed_date = seed_date, signal_date = signal_date, resolution=\"days\"), silent=TRUE) x x <- try(valid_dates(seed_date = seed_date, signal_date = signal_date, resolution=\"months\"), silent=TRUE) x"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":null,"dir":"Reference","previous_headings":"","what":"Validate location — valid_location","title":"Validate location — valid_location","text":"unexported helper used inside individual plausibility component functions (e.g., plane_diff()) validate location specified appears input signal seed location many values locations seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Validate location — valid_location","text":"","code":"valid_location(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Validate location — valid_location","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must forecast seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Validate location — valid_location","text":"validation return stop() location found seed input signal. Otherwise function invisibly return TRUE indicating location valid.","code":""},{"path":[]},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"performance-optimization-for-plane_shape-0-1-0","dir":"Changelog","previous_headings":"New features","what":"Performance optimization for plane_shape()","title":"rplanes 0.1.0","text":"release, introduced parameter customize “method” used identify shapes within plane_shape(). Previously, function able use Dynamic Time Warping (“dtw”) algorithm identify shapes time series. approach involved calculations computationally expensive, particularly datasets multiple locations seed. introduced second method uses scaled difference approach (“sdiff”) ascertain shapes. “sdiff” option set default, much computationally efficient “dtw” option. details methods see ?plane_shape().","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"interpretation-vignette-0-1-0","dir":"Changelog","previous_headings":"New features","what":"Interpretation vignette","title":"rplanes 0.1.0","text":"package now includes narrative vignette discusses interpret results PLANES analysis. Topics include apply weighting scheme plane_score(), strategies mitigate limitations may arise seed data, considerations operationally taking action based plausibility scores.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"more-informative-warning-for-missing-data-0-1-0","dir":"Changelog","previous_headings":"New features","what":"More informative warning for missing data","title":"rplanes 0.1.0","text":"release introduces messaging communicates location fewer time steps compared others seed. warning message formatted “{LOCATION} fewer values locations. may introduce issues downstream plausibility analysis.”","code":""},{"path":[]},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"better-handling-of-locations-with-all-missing-data-0-0-3","dir":"Changelog","previous_headings":"New features","what":"Better handling of locations with all missing data","title":"rplanes 0.0.3","text":"previous version package, user input signal data included location values missing plane_seed() function proceed. However, lead background characteristics seed used downstream algorithms (e.g., infinite range). now trigger error input data to_signal() includes locations values missing.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"more-intuitive-plane_repeat-behavior-0-0-3","dir":"Changelog","previous_headings":"New features","what":"More intuitive plane_repeat() behavior","title":"rplanes 0.0.3","text":"PLANES scoring includes plane_repeat() implement “repeat” algorithm (.e., checking evaluated signal creates repeat sequence longer previously observed seed). observed flagging instances values time series . release adjusted algorithm longer flag constant time series implausible.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"weighting-scheme-constraints-0-0-3","dir":"Changelog","previous_headings":"New features","what":"Weighting scheme constraints","title":"rplanes 0.0.3","text":"release, introduced new feature constrain component weights passed plane_score() values >= 1. adding constraint, saw inconsistent behavior cases weights set < 1. updated function documentation plane_score() “weights” argument reflect change.","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"documentation-typos-0-0-3","dir":"Changelog","previous_headings":"Bug fixes","what":"Documentation typos","title":"rplanes 0.0.3","text":"release introduces minor fixes typos function documentation README.","code":""},{"path":[]},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"new-plausibility-components-0-0-2","dir":"Changelog","previous_headings":"New features","what":"New plausibility components","title":"rplanes 0.0.2","text":"rplanes package now features two new plausibility components: “shape” “zero”. components delivered function (plane_shape() plane_zero(), respectively) run plane_score() alongside specified components. previously developed components, two operate binary classifications plausibility signal evaluated given location. “shape” component uses series distance calculations characterize “similar” evaluated signal previous windows observed data seed. distance evaluated shape exceeds maximum distance observed shapes signal flagged implausible. “shape” component can used forecast signal. “zero” component assesses whether zeros observed seed given location. , component look zeros evaluated signal. finds , signal flagged implausible. Note “zero” component work either forecast observed signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"rplanes_explorer-app-0-0-2","dir":"Changelog","previous_headings":"New features","what":"rplanes_explorer() app","title":"rplanes 0.0.2","text":"release introduces new feature deliver point--click interface PLANES scoring directly rplanes package. interface written Shiny app, maintained part package can launched using rplanes_explorer() function. user installs rplanes, app (stored inst/ directory) visible host machine. rplanes_explorer() wraps shiny::runApp() points “appDir” argument directory holds rplanes explorer app. Users can take advantage arguments inherited shiny::runApp() (e.g., launch.browser=TRUE open app directly browser window).","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"improved-documentation-0-0-2","dir":"Changelog","previous_headings":"New features","what":"Improved documentation","title":"rplanes 0.0.2","text":"added improvements overall documentation package. particular, release introduces two new vignettes: one describe individual components operate another briefly introduce explore app. addition new vignettes, also implemented handful grammatical wording changes make existing documentation clear concise.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"hubverse-forecast-format-0-0-2","dir":"Changelog","previous_headings":"New features","what":"“Hubverse” forecast format","title":"rplanes 0.0.2","text":"updates quantile format used forecast hubs, introduced option read_forecast() helper optionally read different formats. function now supports “Hubverse” format used 2023-24 FluSight initiative (https://hubdocs.readthedocs.io/en/latest/user-guide/model-output.html).","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"optional-weighting-scheme-0-0-2","dir":"Changelog","previous_headings":"New features","what":"Optional weighting scheme","title":"rplanes 0.0.2","text":"release introduce new feature users optionally weight importance individual components overall plausibility score. weights must specified named vector passed plane_score() function. argument optional default function use equal weights component.","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"default-components-with-plane_score-0-0-2","dir":"Changelog","previous_headings":"Bug fixes","what":"Default components with plane_score()","title":"rplanes 0.0.2","text":"Prior release, observed signal evaluated plane_score() strictly require user manually specify compatible components (v0.0.1 “diff” “repeat”). version, plane_score() can now detect type signal “” components selected function identify compatible. example, addition new components (see ), specifying plane_score(..., components = \"\") observed signal automatically use “diff”, “repeat”, “zero” components.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"hyphens-in-location-names-0-0-2","dir":"Changelog","previous_headings":"Bug fixes","what":"Hyphens in location names","title":"rplanes 0.0.2","text":"plane_score() wrapper uses - (hyphen) combine location component returned list object. release, locations hyphen names (e.g., “United-States”) one internal data manipulation steps function expected. updated internals plane_score() now allow location names may contain hyphens.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"data-ordering-in-seed-0-0-2","dir":"Changelog","previous_headings":"Bug fixes","what":"Data ordering in seed","title":"rplanes 0.0.2","text":"Previously, plane_seed() function used dates arranged incoming observed signal data. , seeding unexpected behavior. example, dates ordered descending “last value” actually first value chronologically. release, plane_seed() function internally now arranges data case input data ordered ascending date.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"rplanes-001","dir":"Changelog","previous_headings":"","what":"rplanes 0.0.1","title":"rplanes 0.0.1","text":"Alpha release rplanes package! Several key package features include: read_forecast(): Data prep function read forecasts quantile format used forecasting hubs to_signal(): Constructor “signal” S3 class used package plane_seed(): Function create baseline characteristics observed data given range dates plane_score(): Wrapper run plausibility components independently across locations release, five plausibility components included rplanes. continue develop package add components, update functionality, address issues needed. information features use-cases, refer “Basic Usage” vignette package website R console: vignette(\"basic-usage\", package=\"rplanes\")","code":""}]
+[{"path":"https://signaturescience.github.io/rplanes/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 Signature Science LLC Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"Basic Usage","text":"rplanes package (plausibility analysis epidemiological signals) provides functionality prepare data analyze plausibility forecasted observed epidemiological signals. functions implement set plausibility algorithms agnostic geographic time resolutions calculated independently presented combined score. package allows users : Prepare signal data (either forecast observed) evaluated Create set baseline characteristics previously observed data Compare characteristics evaluated data location Synthesize individual component results overall score package workflow demonstrated detail (see Figure 1). Figure 1 provides detailed description workflow used rplanes. rplanes processing begins forecast observed data prepared pre-specified format. required input data format documented package. convenience, package includes read_forecast() function prepare forecast data quantile format commonly used forecasting hubs. prepped forecast observed data converted signal object using to_signal(). signal data compared baseline characteristics previously observed data location. characteristics aggregated using plane_seed(). seed signal data prepared, user can run plausibility scoring independently location evaluated data. Scores comprised individual binary plausibility components. functions drive component wrapped plane_score() function ease--use. default plane_score() wrapper try use relevant components, however user can dictate specific components needed. important note depending type signal evaluated (.e., forecast versus observed data), components may apply.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"analyzing-plausibility-of-forecast-data","dir":"Articles","previous_headings":"","what":"Analyzing plausibility of forecast data","title":"Basic Usage","text":"Plausibility analysis can support operational forecasting outbreak analytic activities. demonstrate use rplanes score example forecasted data set. Several packages must loaded prior conducting analysis:","code":"library(rplanes) library(dplyr) library(purrr) library(ggplot2)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"prepare-observed-data","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Prepare observed data","title":"Basic Usage","text":"motivate example use incident flu hospitalization reported via HHS Protect. Note data aggregated daily weekly resolution, provided format internal rplanes package data. select columns ’re interested (“date”, “location”, “flu.admits”) make sure date field formatted date: important emphasize observed data must minimum include columns location (geographic unit FIPS code), date (date reported value; must date class), reported value location/date combination.","code":"hosp_all <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) %>% select(date, location, flu.admits) %>% mutate(date = as.Date(date)) head(hosp_all)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"convert-observed-data-into-a-signal-with-to_signal","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Convert observed data into a signal with to_signal()","title":"Basic Usage","text":"downstream plausibility analysis requires observed /forecasted data converted S3 “signal” class. to_signal() function constructs object applies additional “observed” “forecast” class depending type signal specified. convert observed data signal object:","code":"observed_signal <- to_signal(input = hosp_all, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\", horizon = NULL)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"create-a-seed-from-the-observed-data-via-plane_seed","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Create a seed from the observed data via plane_seed()","title":"Basic Usage","text":"plane_seed() function provides means internally calculate store baseline characteristics observed data package calls “seed”. characteristics summarized independently location, used downstream scoring functions. example, input prepped observed signal object make use “cut_date” argument. restricting dates specified cut date, ensure baseline characteristics computed based data overlaps forecast. practice, may possible use default (NULL) cut date analyzing forecasts, long reported data available (exceeding) first horizon forecast.","code":"prepped_seed <- plane_seed(observed_signal, cut_date = \"2022-10-29\")"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"prepare-forecast-data","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Prepare forecast data","title":"Basic Usage","text":"forecast data assessed must include point estimate representation uncertainty (.e., prediction interval) location horizon. analysis rplanes, forecast data must prepared include following: location: Geographic unit FIPS code date: Date corresponding forecast horizon horizon: Forecast horizon lower: Lower limit given prediction interval forecast point: Point estimate forecast upper: Upper limit given prediction interval forecast convenience, rplanes package includes read_forecast() convert forecasts quantile format used many forecast hubs1,2 format needed plausibility analysis. read_forecast() function reads csv input returns tibble summarized forecast data location horizon original file. example, use forecast incident weekly flu hospitalizations. forecast originally quantile format referenced included rplanes example data: can use read_forecast() load data convert required format:","code":"forecast_fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") read.csv(forecast_fp) %>% head(.) prepped_forecast <- read_forecast(forecast_fp) head(prepped_forecast)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"convert-forecast-data-into-a-signal-with-to_signal","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Convert forecast data into a signal with to_signal()","title":"Basic Usage","text":"forecast formatted appropriately, can convert signal object:","code":"forecast_signal <- prepped_forecast %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", resolution = \"weeks\", horizon = 4)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"run-plane_score-and-visualize-results","dir":"Articles","previous_headings":"Analyzing plausibility of forecast data","what":"Run plane_score() and visualize results","title":"Basic Usage","text":"planes_score() function wraps PLANES scoring plausibility components across locations single step. function can accept arguments specific component functions allows user dictate components use (default ). arguments see ?plane_score. pass input forecast signal function along prepped seed run scoring independently locations: Note forecasts evaluate time period, prepare forecast signal appropriately use seed (.e., recreate seed forecast). output plane_score() list scoring results locations. can convert scores_summary element list tibble. default, score uses equal weights components. However, users can modify behavior using “weights” argument needed. res object shows location, number flags raised (“n_flags”), weighted flags (“n_flags_weighted”), number components tested (“n_components”), overall sum weights components tested (“weights_denominator”), “score” (“n_flags_weighted” divided “weights_denominator”), names components tested, names components flagged (): evaluated forecast, locations one fewer flags raised. However, several locations two three seven possible components flagged implausibility.","code":"scores <- plane_score(input = forecast_signal, seed = prepped_seed) res <- scores$scores_summary %>% map_df(., as_tibble) head(res) res %>% count(n_flags) %>% mutate(n_flags = as.character(n_flags)) %>% ggplot(aes(n_flags,n)) + geom_col() + labs(x = \"Number of flags raised\", y = \"Count\")"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"analyzing-plausibility-of-observed-data","dir":"Articles","previous_headings":"","what":"Analyzing plausibility of observed data","title":"Basic Usage","text":"One might want test observed reported data plausibility check phenomena like backfill systematic errors reporting mechanisms. steps use rplanes analyze plausibility observed data similar forecast assessments. input data must converted signal, passed (along seed) scoring function. However, key difference observed data data source used create input signal can used seeding, albeit cut date differentiate data evaluated baseline.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"prepare-observed-data-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Prepare observed data","title":"Basic Usage","text":"example, also use reported HHS Protect flu hospitalization data. However, truncate data stop end 2022. scenario, interested assessing recent reported week (.e., week 2022-12-31) plausibility. Note practice, may interest assess multiple time points recently observed data. begin, read data filter dates prior 2023:","code":"hosp_pre23 <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) %>% select(date, location, flu.admits) %>% mutate(date = as.Date(date)) %>% filter(date < as.Date(\"2023-01-01\")) head(hosp_pre23)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"convert-observed-data-into-a-signal-with-to_signal-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Convert observed data into a signal with to_signal()","title":"Basic Usage","text":"data loaded, can convert hospitalization tibble signal object:","code":"observed_signal <- to_signal(input = hosp_pre23, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\", horizon = NULL)"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"create-a-seed-from-the-observed-data-via-plane_seed-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Create a seed from the observed data via plane_seed()","title":"Basic Usage","text":"can use observed signal input plane_score(), also input plane_seed(). However, must use argument restricts seeding dates prior cut date (inclusive). example, assessing observed data week 2022-12-31 want seed plausibility analysis characteristics recent reported date (.e., 2022-12-24):","code":"prepped_seed <- plane_seed(observed_signal, cut_date = \"2022-12-24\")"},{"path":"https://signaturescience.github.io/rplanes/articles/basic-usage.html","id":"run-plane_score-and-visualize-results-1","dir":"Articles","previous_headings":"Analyzing plausibility of observed data","what":"Run plane_score() and visualize results","title":"Basic Usage","text":"forecast assessments, PLANES scoring wrapped convenience plane_score() function. Since assessing observed signal case, can explicitly tell scoring use certain components. important emphasize components work forecasts observed signals. Currently, plane_cover(), plane_taper(), plane_trend(), plane_shape() (run inside plane_score()) work forecasts observed data: results indicate just one location flag raised. , case two components used scoring results interpreted accordingly. Furthermore, consider reported signals date observed data retrieved paramount. likely meaningful analyze plausibility observed data real time (near real time) opposed retrospectively, since backfill reporting issues may corrected prior assessment.","code":"scores <- plane_score(observed_signal, seed = prepped_seed, components = c(\"repeat\",\"diff\")) res <- scores$scores_summary %>% map_df(., as_tibble) head(res) res %>% count(n_flags) %>% mutate(n_flags = as.character(n_flags)) %>% ggplot(aes(n_flags,n)) + geom_col() + labs(x = \"Number of flags raised\", y = \"Count\")"},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"PLANES Interpretation","text":"rplanes package includes vignettes detailing basic usage descriptions individual components package uses plausibility analysis. vignette focuses interpreting rplanes plausibility outputs. content includes primer weighting scheme plausibility components, discussion limitations may arise relying seed data, considerations flag raised.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"weighting-scheme-within-plane_score","dir":"Articles","previous_headings":"","what":"Weighting scheme within plane_score()","title":"PLANES Interpretation","text":"plane_score() function allows users evaluate multiple plausibility components simultaneously (.e., without call individual scoring functions given component). wrapper returns overall score summarize components evaluated. plane_score() function includes optional “weights” argument allows user-specified weighting components overall score. default (weights = NULL), component given equal weighting. optionally weight certain components higher lower, user must specify named vector value representing weight given component. length vector must equal number components used “components” argument plane_score(). technical details plane_score() apply weighting scheme, users refer function documentation (?plane_score) basic usage vignette.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"motivations-for-weighting","dir":"Articles","previous_headings":"Weighting scheme within plane_score()","what":"Motivations for weighting","title":"PLANES Interpretation","text":"weighting scheme incorporated scores may context-dependent. words, users may varying concerns specific components evaluated given timing, historical data patterns, specific goals plausibility assessment. included several examples highlighting use-cases applying weighting scheme plane_score(): users retrospectively analyzing forecast signals ground-truth, observed data horizon reported, may aware large jump reported cases actually occurred. scenario, might less interested difference component, evaluates forecast raises flag point--point difference greater difference found observed seed. However, users might still concerned unreasonable jumps forecasted cases. Rather eliminating difference component altogether, users can reduce weight within plane_score(). expected large uptick cases, users might increase weight trend component heavily penalize unexpected dips cases. ensures significant trends given appropriate emphasis analysis. beginning season, zeros may common locations, users might decide reduce relative weight zero repeat components. adjustment may help account seasonality expected patterns data. working relatively short time series seed data (e.g., several months), users may encounter many shape flags due limited number shapes found seed data. cases, users can reduce relative weight shape component. evaluating forecasts operationally, users may interested ensuring prediction intervals appropriately calibrated (e.g., narrow). case, cover taper components might merit higher weighting.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"limitations-that-arise-from-seed-data","dir":"Articles","previous_headings":"","what":"Limitations that arise from seed data","title":"PLANES Interpretation","text":"described basic usage vignette, rplanes plausibility analysis procedure requires establishing “seed” object based observed signal. seed data serves basis background characteristics used assess plausibility. , plausibility results depend upon reliability length time series used establish seed data. discuss factors potentially impact plausibility analysis rplanes.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"reliability-of-seed-data","dir":"Articles","previous_headings":"Limitations that arise from seed data","what":"Reliability of seed data","title":"PLANES Interpretation","text":"plausibility analysis rplanes assumes users access observed data establish baseline characteristics time series. Presumably, observed signal trustworthy faithful representation one expect signal evaluated. However, practice, data issues lagged reporting, backfill, systematic biases ascertainment may lead unexpected behaviors rplanes (.e., many flags raised). known issues within seed data, users carefully consider individual components used plausibility scoring determine might impact results plausibility analysis. example, consider observed data may lack consistent reporting certain locations, particularly early time series. case, seed data might contain many consecutive zeros across long time span followed reliable reporting locations, therefore rplanes rarely (ever) raise flags repeat zero components. scenario, truncating observed data begin reporting becomes reliable creating seed may appropriate.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"length-of-seed-data","dir":"Articles","previous_headings":"Limitations that arise from seed data","what":"Length of seed data","title":"PLANES Interpretation","text":"Besides reliability, length (.e., number observations) observed signal used create seed can influence rplanes plausibility scoring. general, data provides higher resolution characteristics manifest evaluated signal. However, users aware computational costs potential reduction sensitivity components amount available seed data increases. provide several considerations examples balancing length observed data used create seed. scenarios seed created relatively small number observations, users may notice components higher sensitivity resulting flags raised. individual components required seed signal length ratio must met function run (e.g., shape requires seed least four times length forecast evaluated). However, even built-minimum length, cases seed data may short produce reasonable results. example, consider evaluating forecast four weeks ahead. case, seed must contain least 16 weekly observations given location. However, 16 weeks roughly four months data, (depending seasonality timing observations) may adequately capture shapes plausibly manifest four weeks future. table detailing potential complications caused seed object short. possible issues, recommend users manually examine flagged locations feasible consider reducing relative weights within plane_score() function. observations seed may lead limitations described , many seed values can also trigger unexpected behavior. amount seed data increases, plausibility components lower sensitivity, result fewer flags. rplanes package includes options mitigate . using repeat component, increasing “prepend” length decreasing repeat tolerance increase sensitivity. circumstances, decreased sensitivity mitigated adjusting component parameters. evaluating shape component, longer seed time-series likely contain unique shapes, resulting fewer potentially novel shapes forecasts therefore fewer flags raised. observed similar epidemiological signal (alone) enough justification infer shape unusual flagged. example, may appropriate flag forecasts COVID-19 activity 2024 exhibit trajectories similar extreme surges 2020-2021. However, situation user’s reference seed data included pandemic activity levels, flag raised. Unlike situations seed data short, changing relative weights components flagged much impact overall scores. -weighting components using short seed object causes potentially erroneous flags less effect overall score, however increasing weights cause flags raised (.e., changing weights change sensitivity components). , manual inspection “missed flags” much challenging time-consuming. suggest users suspect sensitivity components plane_score() negatively impacted many seed values consider truncating data prior creating seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"what-to-do-when-a-flag-is-raised","dir":"Articles","previous_headings":"","what":"What to do when a flag is raised","title":"PLANES Interpretation","text":"rplanes package provides mechanism review plausibility epidemiological signals. considering interpret results, paramount distinguish signals may plausible versus possible. signal perceived implausible, may come reflect true patterns reporting horizons evaluated eclipsed. recommend users consider plausibility analysis primarily guide rather replacement subsequent manual review. extent feasible, users may consider manually inspecting flagged signals. inspecting flags, suggest users plot observed seed data along signal evaluated. many flags raised signal appears implausible subject matter experts, users can likely accept plausibility score either censor adjust forecast observed signal evaluated. score also used downstream weight forecast (e.g., ensemble model). flags raised signal appear implausible, inspect individual flagged components. Adjusting arguments repeat trend can increase decrease sensitivity. Short seed data can cause certain components overly-sensitive (diff, repeat, shape, zero), users can either weight components less within plane_score() remove altogether. drawing conclusions rplanes results, recommend users first analyze retrospective data package understand distribution flags expect signal. example, reviewing operational forecasts flu hospitalizations, users may consider retrieving historical forecasts signal, retrospectively masking observed data available forecast week, summarizing plausibility scores. analysis provide critical insight baseline sensitivity signal scoring. Users may consider setting thresholds action future evaluated signals based distribution flags raised analysis.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/interpretation.html","id":"summary","dir":"Articles","previous_headings":"","what":"Summary","title":"PLANES Interpretation","text":"many reasons user might want change relative weights individual components leave components plane_score() function altogether. Manual inspection raised flags may informative, particularly users suspect flags raised erroneously (reasons discussed vignette). also recommend collecting (simulating) signals expect trigger flags calibration purposes. Lastly, suggest retrospective analysis plausibility scores batch (across multiple evaluation time points) can highly informative guiding interpretation.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"PLANES Components","text":"rplanes package currently set seven components perform plausibility analysis epidemiological signals (PLANES). individual components assesses different characteristics evaluated signal, resolving binary indicator (.e., TRUE FALSE whether signal implausible). components wrapped via plane_score() function generate overall score based number components flag raised. provide narrative walk individual PLANES components. full list components, along corresponding functions parameters (applicable), provided table . important emphasize rplanes designed work forecasted observed epidemiological signals. However, components work types signals. Several components (including coverage, taper, trend, shape) can used assess plausibility forecasts. components designed take location (.e., string specifying location code), signal prepared to_signal() evaluated, seed prepared plane_seed() holds baseline characteristics. customize behavior, functions accept additional arguments, detailed examples follow. component function returns list standardized minimum return “indicator” element, returns TRUE component flag raised (.e., data implausible) FALSE component flag raised (.e., data implausible). important emphasize individual components wrapped plane_score() function ease--use, practice users likely use wrapper instead accessing functions directly. However, examples use functions outside plane_score() clearly demonstrate operate. Likewise, created mock forecast data examples demonstrate usage. Users refer “Basic Usage” vignette practical guidance prepare data rplanes analyses.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"data-preparation","dir":"Articles","previous_headings":"","what":"Data preparation","title":"PLANES Components","text":"mentioned , data evaluated examples follow mock forecasts. compare forecasted values HHS Protect incident flu hospitalization data aggregated daily weekly resolution, provided internal rplanes package data. details data preparation rplanes see “Basic Usage” vignette. code load required packages, prepare observed data signal to_signal(), convert observed signal seed plane_seed(). Note examples use cut date “2022-06-04” seed data:","code":"## load packages library(rplanes) library(dplyr) library(ggplot2) ## read in observed data hosp_all <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) %>% select(date, location, flu.admits) %>% mutate(date = as.Date(date)) ## prepare observed signal observed_signal <- to_signal(input = hosp_all, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\", horizon = NULL) ## create seed with cut date prepped_seed <- plane_seed(observed_signal, cut_date = \"2022-06-04\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"difference---plane_diff","dir":"Articles","previous_headings":"","what":"Difference - plane_diff()","title":"PLANES Components","text":"difference component checks point--point differences evaluated signal. component can used either forecasts observed signals. function internally computes maximum observed difference (using absolute value) checks see point--point differences evaluated data exceed threshold. , flag raised.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible","dir":"Articles","previous_headings":"Difference - plane_diff()","what":"Flagged as implausible","title":"PLANES Components","text":"example uses forecasted signal 1 week-ahead forecast dramatically jumps recent observed data: seed stores last observed value maximum difference given location: expect implausibility flag raised case: can visualize point--point differences see data jumps forecast:","code":"point_est <- c(100, 120, 140, 160) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(10, 20, 30, 40), ## make a large jump in hospitalizations to trigger diff component point = point_est, upper = point_est + c(10, 20, 30, 40), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 prepped_seed$`01`$diff$max #> [1] 21 plane_diff(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE #> #> $values #> [1] 19 100 120 140 160 #> #> $evaluated_differences #> [1] 81 20 20 20 #> #> $maximum_difference #> [1] 21 diff_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) diff_flags <- diff_dat %>% filter(type == \"forecast\") %>% filter(date == min(date)) diff_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = diff_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Difference component\\nFlagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible","dir":"Articles","previous_headings":"Difference - plane_diff()","what":"Not flagged as implausible","title":"PLANES Components","text":"next example include data “jump” absolute difference beyond observed time series previously: , can see last value maximum observed difference given location used internally seed: Given max difference, expect implausibility flag raised case: plot shows forecasted data raise difference flag:","code":"point_est <- c(28, 31, 34, 37) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 prepped_seed$`01`$diff$max #> [1] 21 plane_diff(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE #> #> $values #> [1] 19 28 31 34 37 #> #> $evaluated_differences #> [1] 9 3 3 3 #> #> $maximum_difference #> [1] 21 diff_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) diff_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Difference component\\nNot flagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"coverage---plane_cover","dir":"Articles","previous_headings":"","what":"Coverage - plane_cover()","title":"PLANES Components","text":"coverage component compares prediction interval first horizon evaluated signal recent value seed. interval cover recent data point, flag raised implausible. component requires prediction interval, can used assess plausibility forecast signals.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-1","dir":"Articles","previous_headings":"Coverage - plane_cover()","what":"Flagged as implausible","title":"PLANES Components","text":"can create forecast data includes prediction interval cover recent value seed: prediction interval quite narrow departs last observed value seed: expect coverage flag raised: plot shows coverage forecast prediction intervals relation seed data:","code":"## make sure the 1 week-ahead point estimate and PI do not cover the last reported obs point_est <- c(60, 62, 64, 66) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(2, 4, 6, 8), point = point_est, upper = point_est + c(2, 4, 6, 8) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 plane_cover(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE #> #> $last_value #> [1] 19 #> #> $bounds #> $bounds$lower #> [1] 58 #> #> $bounds$upper #> [1] 62 cover_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) cov_flags <- cover_dat %>% filter(type == \"observed\") %>% filter(date == max(date)) ggplot(data = cover_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = cov_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Coverage component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-1","dir":"Articles","previous_headings":"Coverage - plane_cover()","what":"Not flagged as implausible","title":"PLANES Components","text":"can put together example prediction interval first horizon covers recent value seed data: Given coverage, expect signal flagged implausible: , can visualize coverage forecast relative seed data:","code":"## make sure the 1 week-ahead point estimate and PI cover the last reported obs point_est <- c(28, 31, 34, 37) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - 28, point = point_est, upper = point_est + 28 ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$last_value #> [1] 19 plane_cover(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE #> #> $last_value #> [1] 19 #> #> $bounds #> $bounds$lower #> [1] 0 #> #> $bounds$upper #> [1] 56 cover_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) ggplot(data = cover_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Coverage component\\nNot flagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"taper---plane_taper","dir":"Articles","previous_headings":"","what":"Taper - plane_taper()","title":"PLANES Components","text":"taper component checks whether prediction interval evaluated signal decreases width (.e., certainty increases) horizons progress. component requires prediction interval, can used assess plausibility forecast signals.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-2","dir":"Articles","previous_headings":"Taper - plane_taper()","what":"Flagged as implausible","title":"PLANES Components","text":"create mock forecast narrowing prediction interval: width prediction interval narrows 40 30 20 10 forecasted horizons. expect taper flag raised: plot visually demonstrates tapering effect:","code":"point_est <- c(30, 33, 36, 39) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, ## make the lower and upper bounds get narrower as horizon increases lower = point_est - c(20, 15, 10, 5), point = point_est, upper = point_est + c(20, 15, 10, 5) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_taper(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE #> #> $widths #> [1] 40 30 20 10 taper_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) taper_flags <- taper_dat %>% filter(type == \"forecast\") taper_dat %>% ggplot(data = taper_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = taper_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu Hospital Admissions\") + ggtitle(paste(\"Taper component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-2","dir":"Articles","previous_headings":"Taper - plane_taper()","what":"Not flagged as implausible","title":"PLANES Components","text":"Now can look example forecasted prediction interval increases width horizons progress: expect implausibility flag raised case: visualization see forecast prediction interval taper:","code":"point_est <- c(30, 33, 36, 39) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, ## make the lower and upper bounds get wider as horizon increases lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_taper(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE #> #> $widths #> [1] 10 20 30 40 taper_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) taper_dat %>% ggplot(data = taper_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu Hospital Admissions\") + ggtitle(paste(\"Taper component\\nNot flagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"repeat---plane_repeat","dir":"Articles","previous_headings":"","what":"Repeat - plane_repeat()","title":"PLANES Components","text":"repeat component checks whether consecutive values observed forecasted signal repeated k times. seed created, stores maximum number consecutive repeats location uses default value k. evaluated data exceeds k signal considered implausible flag raised. k threshold repeats can customized using “tolerance” parameter. function also allows users customize “prepend” length (.e., number recent values seed concatenated evaluated signal checking repeats). illustrate repeat parameters, can contrive simple example. Consider seed values 11, 12, 13, 13, 13 evaluated forecast point estimates 13, 13, 15, 16. tolerance threshold set 4 prepend length 2 sequence 13, 13, 13, 13, 15, 16 checked set four values repeated consecutively. case, flag raised. value 13 repeated four times tolerate four repeats. However, keep tolerance 4 change prepend length 3, evaluated sequence 13, 13, 13, 13, 13, 15, 16, flag raised, repeats tolerance threshold. parameters see ?plane_repeat().","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-3","dir":"Articles","previous_headings":"Repeat - plane_repeat()","what":"Flagged as implausible","title":"PLANES Components","text":"can mock example data repeats point estimate: can check maximum number repeats seen seed data: number repeated point estimates defined exceeds maximum repeats expect flag raised: can visualize repeats forecast data:","code":"## make sure the point estimates repeat point_est <- c(55, 55, 55, 55) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$max_repeats #> [1] 2 plane_repeat(location = \"01\", input = prepped_forecast, seed = prepped_seed, tolerance = NULL, prepend = NULL) #> $indicator #> [1] TRUE #> #> $repeats #> # A tibble: 4 × 6 #> point location date horizon lower upper #> #> 1 55 01 2022-06-11 1 50 60 #> 2 55 01 2022-06-18 2 45 65 #> 3 55 01 2022-06-25 3 40 70 #> 4 55 01 2022-07-02 4 35 75 repeat_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) repeat_flags <- repeat_dat %>% filter(type == \"forecast\") repeat_dat %>% ggplot(data = repeat_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_point(data = repeat_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_ribbon(aes(ymin = lower, ymax = upper,fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Repeat component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"controlling-sensitivity-with-parameters","dir":"Articles","previous_headings":"Repeat - plane_repeat()","what":"Controlling sensitivity with parameters","title":"PLANES Components","text":"described , “tolerance” parameter allows user override default behavior sets maximum number repeats via seed. Setting higher tolerance decrease sensitivity repeat assessment. example, increase tolerance 4 expect flag raised:","code":"plane_repeat(location = \"01\", input = prepped_forecast, seed = prepped_seed, tolerance = 4, prepend = NULL) #> $indicator #> [1] FALSE #> #> $repeats #> # A tibble: 0 × 6 #> # ℹ 6 variables: point , location , date , horizon , #> # lower , upper "},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-3","dir":"Articles","previous_headings":"Repeat - plane_repeat()","what":"Not flagged as implausible","title":"PLANES Components","text":"prepare mock forecast data repeating point estimates: can see maximum number repeats seed: Based threshold, expect implausibility flag repeats raised: Lastly, can visualize repeats signal:","code":"## make sure the point estimates do not repeat point_est <- c(55, 57, 59, 61) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$max_repeats #> [1] 2 plane_repeat(location = \"01\", input = prepped_forecast, seed = prepped_seed, tolerance = NULL, prepend = NULL) #> $indicator #> [1] FALSE #> #> $repeats #> # A tibble: 0 × 6 #> # ℹ 6 variables: point , location , date , horizon , #> # lower , upper repeat_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) repeat_dat %>% ggplot(data = repeat_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Repeat component\\nNot flagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"trend---plane_trend","dir":"Articles","previous_headings":"","what":"Trend - plane_trend()","title":"PLANES Components","text":"trend component assesses whether significant change magnitude direction slope evaluated signal compared recent data seed. “change point” identified forecasted horizons /recent seed value, flag raised implausibility. trend component requires least four times many seed values evaluated values. Furthermore, component currently can used forecasted signals. One parameters trend function “sig_lvl”, defines significance level internal permutation test used detect change points. default value set 0.1. significance level determines sensitivity trend plausibility assessment, lower value corresponding less sensitive evaluation. trend algorithm methods see ?plane_trend().","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-4","dir":"Articles","previous_headings":"Trend - plane_trend()","what":"Flagged as implausible","title":"PLANES Components","text":"create example data doubles forecasted horizon: expect dramatic increase slope detected change point flag raised: plot shows forecasted value identified change point:","code":"point_est <- c(25, 50, 100, 200) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 20, 40), point = point_est, upper = point_est + c(5, 10, 20, 40), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1) #> $indicator #> [1] TRUE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 01 1 2022-02-19 20 Observed FALSE FALSE #> 2 01 2 2022-02-26 14 Observed FALSE FALSE #> 3 01 3 2022-03-05 35 Observed FALSE FALSE #> 4 01 4 2022-03-12 30 Observed FALSE FALSE #> 5 01 5 2022-03-19 30 Observed FALSE FALSE #> 6 01 6 2022-03-26 25 Observed FALSE FALSE #> 7 01 7 2022-04-02 32 Observed FALSE FALSE #> 8 01 8 2022-04-09 29 Observed FALSE FALSE #> 9 01 9 2022-04-16 19 Observed FALSE FALSE #> 10 01 10 2022-04-23 30 Observed FALSE FALSE #> 11 01 11 2022-04-30 13 Observed FALSE FALSE #> 12 01 12 2022-05-07 25 Observed FALSE FALSE #> 13 01 13 2022-05-14 15 Observed FALSE FALSE #> 14 01 14 2022-05-21 12 Observed FALSE FALSE #> 15 01 15 2022-05-28 22 Observed FALSE FALSE #> 16 01 16 2022-06-04 19 Observed FALSE FALSE #> 17 01 17 2022-06-11 25 Forecast FALSE FALSE #> 18 01 18 2022-06-18 50 Forecast TRUE TRUE #> 19 01 19 2022-06-25 100 Forecast FALSE FALSE #> 20 01 20 2022-07-02 200 Forecast FALSE FALSE #> #> $flagged_dates #> [1] \"2022-06-18\" trend_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) trend_flags <- plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1)$output %>% filter(Changepoint == TRUE) ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = trend_flags, mapping = aes(x = Date, y = Value), shape=23, size=4) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Trend component\\nFlagged\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"controlling-sensitivity-with-parameters-1","dir":"Articles","previous_headings":"Trend - plane_trend()","what":"Controlling sensitivity with parameters","title":"PLANES Components","text":"toggling significance level, can control sensitivity trend assessment. lower significance level 0.001 see flag longer raised using data :","code":"plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.001) #> $indicator #> [1] FALSE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 01 1 2022-02-19 20 Observed FALSE FALSE #> 2 01 2 2022-02-26 14 Observed FALSE FALSE #> 3 01 3 2022-03-05 35 Observed FALSE FALSE #> 4 01 4 2022-03-12 30 Observed FALSE FALSE #> 5 01 5 2022-03-19 30 Observed FALSE FALSE #> 6 01 6 2022-03-26 25 Observed FALSE FALSE #> 7 01 7 2022-04-02 32 Observed FALSE FALSE #> 8 01 8 2022-04-09 29 Observed FALSE FALSE #> 9 01 9 2022-04-16 19 Observed FALSE FALSE #> 10 01 10 2022-04-23 30 Observed FALSE FALSE #> 11 01 11 2022-04-30 13 Observed FALSE FALSE #> 12 01 12 2022-05-07 25 Observed FALSE FALSE #> 13 01 13 2022-05-14 15 Observed FALSE FALSE #> 14 01 14 2022-05-21 12 Observed FALSE FALSE #> 15 01 15 2022-05-28 22 Observed FALSE FALSE #> 16 01 16 2022-06-04 19 Observed FALSE FALSE #> 17 01 17 2022-06-11 25 Forecast FALSE FALSE #> 18 01 18 2022-06-18 50 Forecast FALSE FALSE #> 19 01 19 2022-06-25 100 Forecast FALSE FALSE #> 20 01 20 2022-07-02 200 Forecast FALSE FALSE #> #> $flagged_dates #> [1] NA"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-4","dir":"Articles","previous_headings":"Trend - plane_trend()","what":"Not flagged as implausible","title":"PLANES Components","text":"can also make example data reflects consistent trend seed: case expect implausibility flag raised: visualization shows consistency forecasted trend comparison data seed: Note cases plane_trend() identify change point seed data raise implausibility flag forecast. trend component checks change points forecasted horizons recent value seed. significant change point found elsewhere seed time series, function raise flag. However, output includes change points detected regardless whether raised implausibility flag. demonstrate , can look location “06”. example, need define new prepped_seed object change point occurs previously defined cut date: case expect implausibility flag raised, see change point: Note 2022-09-17, change point detected, forecast, last observed data point flag raised. visualization shows change point observed data:","code":"point_est <- c(40, 41, 40, 43) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1) #> $indicator #> [1] FALSE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 01 1 2022-02-19 20 Observed FALSE FALSE #> 2 01 2 2022-02-26 14 Observed FALSE FALSE #> 3 01 3 2022-03-05 35 Observed FALSE FALSE #> 4 01 4 2022-03-12 30 Observed FALSE FALSE #> 5 01 5 2022-03-19 30 Observed FALSE FALSE #> 6 01 6 2022-03-26 25 Observed FALSE FALSE #> 7 01 7 2022-04-02 32 Observed FALSE FALSE #> 8 01 8 2022-04-09 29 Observed FALSE FALSE #> 9 01 9 2022-04-16 19 Observed FALSE FALSE #> 10 01 10 2022-04-23 30 Observed FALSE FALSE #> 11 01 11 2022-04-30 13 Observed FALSE FALSE #> 12 01 12 2022-05-07 25 Observed FALSE FALSE #> 13 01 13 2022-05-14 15 Observed FALSE FALSE #> 14 01 14 2022-05-21 12 Observed FALSE FALSE #> 15 01 15 2022-05-28 22 Observed FALSE FALSE #> 16 01 16 2022-06-04 19 Observed FALSE FALSE #> 17 01 17 2022-06-11 40 Forecast FALSE FALSE #> 18 01 18 2022-06-18 41 Forecast FALSE FALSE #> 19 01 19 2022-06-25 40 Forecast FALSE FALSE #> 20 01 20 2022-07-02 43 Forecast FALSE FALSE #> #> $flagged_dates #> [1] NA trend_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) trend_flags <- plane_trend(location = \"01\", input = prepped_forecast, seed = prepped_seed, sig_lvl = 0.1)$output %>% filter(Changepoint == TRUE) ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = trend_flags, mapping = aes(x = Date, y = Value), shape=23, size=4) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Trend component\\nNot flagged\")) ## create seed with cut date prepped_seed2 <- plane_seed(observed_signal, cut_date = \"2022-10-29\") point_est <- c(40, 41, 40, 43) prepped_forecast <- tibble( location = \"06\", date = seq(as.Date(\"2022-11-05\"), as.Date(\"2022-11-26\"), by = 7), horizon = 1:4, lower = point_est - c(5, 10, 15, 20), point = point_est, upper = point_est + c(5, 10, 15, 20), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_trend(location = \"06\", input = prepped_forecast, seed = prepped_seed2, sig_lvl = 0.1) #> $indicator #> [1] FALSE #> #> $output #> # A tibble: 20 × 7 #> Location Index Date Value Type Changepoint Flagged #> #> 1 06 1 2022-07-16 102 Observed FALSE FALSE #> 2 06 2 2022-07-23 64 Observed FALSE FALSE #> 3 06 3 2022-07-30 46 Observed FALSE FALSE #> 4 06 4 2022-08-06 39 Observed FALSE FALSE #> 5 06 5 2022-08-13 38 Observed FALSE FALSE #> 6 06 6 2022-08-20 39 Observed FALSE FALSE #> 7 06 7 2022-08-27 33 Observed FALSE FALSE #> 8 06 8 2022-09-03 35 Observed FALSE FALSE #> 9 06 9 2022-09-10 29 Observed FALSE FALSE #> 10 06 10 2022-09-17 24 Observed TRUE FALSE #> 11 06 11 2022-09-24 35 Observed FALSE FALSE #> 12 06 12 2022-10-01 72 Observed FALSE FALSE #> 13 06 13 2022-10-08 93 Observed FALSE FALSE #> 14 06 14 2022-10-15 97 Observed FALSE FALSE #> 15 06 15 2022-10-22 124 Observed FALSE FALSE #> 16 06 16 2022-10-29 211 Observed FALSE FALSE #> 17 06 17 2022-11-05 40 Forecast FALSE FALSE #> 18 06 18 2022-11-12 41 Forecast FALSE FALSE #> 19 06 19 2022-11-19 40 Forecast FALSE FALSE #> 20 06 20 2022-11-26 43 Forecast FALSE FALSE #> #> $flagged_dates #> [1] NA trend_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"06\") %>% filter(date <= \"2022-10-29\") %>% mutate(type=\"observed\"), . ) trend_flags <- plane_trend(location = \"06\", input = prepped_forecast, seed = prepped_seed2, sig_lvl = 0.1)$output %>% filter(Changepoint == TRUE) ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) + geom_line(lty=\"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = trend_flags, mapping = aes(x = Date, y = Value), shape=23, size=4) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(paste(\"Trend component\\nNot flagged but change point in seed\"))"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"shape---plane_shape","dir":"Articles","previous_headings":"","what":"Shape - plane_shape()","title":"PLANES Components","text":"shape component evaluates shape trajectory forecast signal compares shape existing shapes observed seed data. shape identified novel, flag raised, signal considered implausible. component one additional argument defines method used identify shapes - one “sdiff” (scaled difference; set default) “dtw” (Dynamic Time Warping). Based preliminary analyses, “dtw” method higher sensitivity slightly lower specificity “sdiff” method much computationally expensive. information shape algorithm, see ?plane_shape().","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-5","dir":"Articles","previous_headings":"Shape - plane_shape()","what":"Flagged as implausible","title":"PLANES Components","text":"example , set point estimates prediction intervals forecast signal shape novel compared seed data (see plot ). expect implausibility flag raised example: indicator TRUE, meaning forecast implausible, shape novel relative seed data. can visualize shape differences see shape flagged. forecast plot (red line) clearly looks different shape observed seed data (blue line):","code":"point_est <- c(60, 60, 60, 10) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - 10, ## make an unusual shape in hospitalizations to trigger shape component point = point_est, upper = point_est + 10, ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_shape(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE shape_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) shape_flags <- shape_dat %>% filter(type == \"forecast\") shape_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + geom_point(data = shape_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Shape component\\nFlagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-5","dir":"Articles","previous_headings":"Shape - plane_shape()","what":"Not flagged as implausible","title":"PLANES Components","text":"Next ’ll look example forecast familiar shape shouldn’t trigger flag: expect implausibility flag raised example: indicator FALSE, meaning forecast considered plausible, shape familiar relative seed data. can visualize shape similarities/differences see shape flagged. forecast plot (red line) looks similar shape see observed seed data (blue line) mid April mid June:","code":"point_est <- c(28, 18, 30, 20) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = point_est - 10, ## make a familiar shape in hospitalizations to not trigger shape component point = point_est, upper = point_est + 10, ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data plane_shape(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE shape_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) shape_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Shape component\\nNot Flagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"zero---plane_zero","dir":"Articles","previous_headings":"","what":"Zero - plane_zero()","title":"PLANES Components","text":"function checks presence value(s) equal zero evaluated signal. zeros found, function look seed see zeros anywhere else time series. , function consider evaluated zero plausible flags raised (.e., indicator returned FALSE). , function consider evaluated zero implausible flag raised (.e., indicator returned TRUE). function can used either forecast observed signals.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"flagged-as-implausible-6","dir":"Articles","previous_headings":"Zero - plane_zero()","what":"Flagged as implausible","title":"PLANES Components","text":"example , add zero signal point estimate location seed zeros: seed stores logical indicating whether zeros present seed data, none example: expect implausibility flag raised location: indicator TRUE, meaning forecast signal implausible zeros forecast signal observed seed. can visualize . signal red (forecast example) zero early July, zeros found seed data blue.","code":"point_est <- c(31, 30, 31, 0) prepped_forecast <- tibble( location = \"01\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = c(26,24,24,0), ## add zeros in hospitalizations to trigger zero component point = point_est, upper = c(36,36,38,15) ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`01`$any_zeros #> [1] FALSE plane_zero(location = \"01\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] TRUE zero_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"01\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) zero_flags <- zero_dat %>% filter(flu.admits == 0) zero_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(data = zero_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Zero component\\nFlagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/planes-components.html","id":"not-flagged-as-implausible-6","dir":"Articles","previous_headings":"Zero - plane_zero()","what":"Not flagged as implausible","title":"PLANES Components","text":"function trigger implausibility flag zero signal (either observed forecast) one seed. words, flag raised : (1) zeros signal (2) zeros seed. Let’s look example zeros signal (location “02”) seed. flag triggered: seed stores logical indicating whether zeros present seed data, zeros example: expect implausibility flag raised location: indicator FALSE, meaning forecast signal plausible, zeros forecast signal observed seed. can visualize . signal red (forecast example) zero around early-mid June, also zeros found seed data blue.","code":"point_est <- c(0, 6, 2, 3) prepped_forecast <- tibble( location = \"02\", date = seq(as.Date(\"2022-06-11\"), as.Date(\"2022-07-02\"), by = 7), horizon = 1:4, lower = c(0,5,0,1), ## add zeros in hospitalizations point = point_est, upper = c(1,7,4,5), ) %>% to_signal(outcome = \"flu.admits\", type = \"forecast\", horizon = 4) prepped_forecast$data prepped_seed$`02`$any_zeros #> [1] TRUE plane_zero(location = \"02\", input = prepped_forecast, seed = prepped_seed) #> $indicator #> [1] FALSE zero_dat <- prepped_forecast$data %>% mutate(type = \"forecast\") %>% rename(flu.admits = point) %>% bind_rows(observed_signal$data %>% filter(location == \"02\") %>% filter(date <= \"2022-06-04\") %>% mutate(type=\"observed\"), . ) zero_flags <- zero_dat %>% filter(flu.admits == 0) zero_dat %>% ggplot(mapping = aes(x = date, y = flu.admits)) + geom_line(lty = \"dotted\") + geom_line(aes(colour = type)) + geom_point(data = zero_flags, mapping = aes(x = date, y = flu.admits), shape=23, size=4, color = \"black\") + geom_point(aes(colour = type)) + geom_ribbon(aes(ymin = lower, ymax = upper, fill = type), alpha = 0.2) + xlab(\"Date\") + ylab(\"Flu hospitalizations\") + ggtitle(\"Zero component\\nNot Flagged\")"},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"rplanes Explorer","text":"rplanes features Shiny app allows users interact package functions perform plausibility analysis epidemiological signals. rplanes Explorer app developed maintained part R package. Users can launch app locally use hosted Shiny server running rplanes_explorer() function.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"analysis-steps","dir":"Articles","previous_headings":"","what":"Analysis steps","title":"rplanes Explorer","text":"application allows users run plausibility analysis several steps: Select type signal evaluated Upload data use plausibility analysis seed Upload data containing signal evaluated (observed signal identify number points evaluate) Enter resolution, outcome, forecast horizon (applicable) Optionally modify default parameters used analysis Click “Analyze”","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"example-data","dir":"Articles","previous_headings":"","what":"Example data","title":"rplanes Explorer","text":"app includes example data help users familiarize plausibility analysis features. example based observed data originally obtained healthdata.gov flu admissions (“previous_day_admission_influenza_confirmed” field) aggregated location epidemiological week. data includes states national resolution United States. selection observed data used example provided : example forecast data set evaluated selected CDC FluSight hospitalization forecasts submitted 2021-2022 2022-2023 influenza seasons. selection forecast data used example provided :","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"inputs-and-outputs","dir":"Articles","previous_headings":"Usage","what":"Inputs and outputs","title":"rplanes Explorer","text":"app includes inputs type signal evaluated, file uploads (needed), parameter modifications. analysis complete, output analysis displayed visually user collection plots tables. “Help” tab app includes detailed information inputs outputs explorer app.","code":""},{"path":"https://signaturescience.github.io/rplanes/articles/rplanes-explorer.html","id":"launching-the-app","dir":"Articles","previous_headings":"Usage","what":"Launching the app","title":"rplanes Explorer","text":"app delivered function rplanes package. launch app, users can run rplanes_explorer() function. Note function wraps shiny::runApp() inherits arguments. example, adding argument launch.browser = TRUE open app web browser setting port = 80 run app port 80 localhost.","code":"library(rplanes) rplanes_explorer(host = \"0.0.0.0\", launch.browser = TRUE, port = 80)"},{"path":"https://signaturescience.github.io/rplanes/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"VP Nagraj. Author, maintainer. Desiree Williams. Author. Amy Benefield. Author.","code":""},{"path":"https://signaturescience.github.io/rplanes/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Nagraj V, Williams D, Benefield (2024). rplanes: Plausibility Analysis Epidemiological Signals. R package version 0.1.0, https://signaturescience.github.io/rplanes/.","code":"@Manual{, title = {rplanes: Plausibility Analysis of Epidemiological Signals}, author = {VP Nagraj and Desiree Williams and Amy Benefield}, year = {2024}, note = {R package version 0.1.0}, url = {https://signaturescience.github.io/rplanes/}, }"},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"introduction","dir":"","previous_headings":"","what":"Introduction","title":"Plausibility Analysis of Epidemiological Signals","text":"rplanes package (plausibility analysis epidemiological signals) provides functionality prepare data analyze plausibility forecasted reported epidemiological signals. functions implement set plausibility algorithms agnostic geographic time resolutions calculated independently presented combined score.","code":""},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Plausibility Analysis of Epidemiological Signals","text":"package available install CRAN: Alternatively can install package GitHub:","code":"install.packages(\"rplanes\") #install.packages(\"remotes\") remotes::install_github(\"signaturescience/rplanes\", build_vignettes=TRUE)"},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"getting-started","dir":"","previous_headings":"","what":"Getting Started","title":"Plausibility Analysis of Epidemiological Signals","text":"rplanes package includes vignettes describing package features detail. get started, refer “Basic Usage” vignette package website R console:","code":"vignette(\"basic-usage\", package=\"rplanes\")"},{"path":"https://signaturescience.github.io/rplanes/index.html","id":"contributing","dir":"","previous_headings":"","what":"Contributing","title":"Plausibility Analysis of Epidemiological Signals","text":"Please use GitHub issues report bugs request features. Contributions reviewed via pull requests.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":null,"dir":"Reference","previous_headings":"","what":"Check completeness of seed and signal data — check_incomplete","title":"Check completeness of seed and signal data — check_incomplete","text":"unexported helper used internally valid_dates optionally issue warning potential completeness seed signal data based dates provided.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check completeness of seed and signal data — check_incomplete","text":"","code":"check_incomplete(seed_date, signal_date, resolution)"},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check completeness of seed and signal data — check_incomplete","text":"seed_date Last date available seed object signal_date First date available signal object resolution Character vector specifying temporal resolution (e.g., \"weeks\", \"months\")","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/check_incomplete.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check completeness of seed and signal data — check_incomplete","text":"Operates side-effect returns warning() seed signal dates combined indicate incomplete week month.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":null,"dir":"Reference","previous_headings":"","what":"Sliding windows — create_sliding_windows_df","title":"Sliding windows — create_sliding_windows_df","text":"unexported helper function used within plane_shape() generate sliding windows vector return data frame row subset (sliding window) time series. length windowed time series (therefore number columns) equal \"window_size\". number windows equal (length(vector) - window_size) + 1. example, given time series length 38 window size length 4, 35 windowed time series (rows), 4 time stamps (columns).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sliding windows — create_sliding_windows_df","text":"","code":"create_sliding_windows_df(vector, window_size)"},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sliding windows — create_sliding_windows_df","text":"vector numeric integer vector time series used create sliding windows window_size integer specifying size (.e., number elements) windowed time series desired","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/create_sliding_windows_df.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Sliding windows — create_sliding_windows_df","text":"data.frame row subset (sliding window) time series.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":null,"dir":"Reference","previous_headings":"","what":"Cut into categorical differences — cutter","title":"Cut into categorical differences — cutter","text":"unexported helper function takes input number observed difference cuts categorical description (e.g., \"increase\", \"decrease\", \"stable\") change.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cut into categorical differences — cutter","text":"","code":"cutter(x, threshold = 1)"},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cut into categorical differences — cutter","text":"x Vector length 1 scaled difference categorized threshold Limit used define categorical differences; default 1","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/cutter.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Cut into categorical differences — cutter","text":"Character vector length 1 categorical description difference","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":null,"dir":"Reference","previous_headings":"","what":"Epiweek start — epiweek_start","title":"Epiweek start — epiweek_start","text":"unexported helper identifies date first day epiweek given date. function used internally inside valid_dates.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Epiweek start — epiweek_start","text":"","code":"epiweek_start(date)"},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Epiweek start — epiweek_start","text":"date Date queried","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/epiweek_start.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Epiweek start — epiweek_start","text":"Date first day epiweek input date.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":null,"dir":"Reference","previous_headings":"","what":"Determine shapes — get_shapes","title":"Determine shapes — get_shapes","text":"unexported helper function used identify shape plane_shape() function's scaled difference (\"sdiff\") method.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Determine shapes — get_shapes","text":"","code":"get_shapes(input_data, window_size)"},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Determine shapes — get_shapes","text":"input_data data frame containing least two columns, one must named \"value\" value assessed another named \"dates\" date observed data window_size number categorical differences used define shape","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/get_shapes.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Determine shapes — get_shapes","text":"vector shapes identified. element vector include shape, cluster categorical differences (size specified \"window_size\") collapsed \";\" (e.g., c(\"decrease;stable;stable;stable\",\"stable;stable;stable;increase\",\"stable;stable;increase;increase\")).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":null,"dir":"Reference","previous_headings":"","what":"Check forecast — is_forecast","title":"Check forecast — is_forecast","text":"function checks object class signal forecast.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check forecast — is_forecast","text":"","code":"is_forecast(x)"},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check forecast — is_forecast","text":"x Input object checked","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check forecast — is_forecast","text":"Logical whether input object inherits \"signal\" \"forecast\" classes.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_forecast.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check forecast — is_forecast","text":"","code":"## get path to example forecast file fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") ex_forecast <- read_forecast(fp) sig <- to_signal(ex_forecast, outcome=\"flu.admits\", type=\"forecast\", horizon=4, resolution=\"weeks\") is_forecast(sig)"},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":null,"dir":"Reference","previous_headings":"","what":"Check observed — is_observed","title":"Check observed — is_observed","text":"function checks object class signal observed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check observed — is_observed","text":"","code":"is_observed(x)"},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check observed — is_observed","text":"x Input object checked","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check observed — is_observed","text":"Logical whether input object inherits \"signal\" \"observed\" classes.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/is_observed.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check observed — is_observed","text":"","code":"hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") sig <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") is_observed(sig)"},{"path":"https://signaturescience.github.io/rplanes/reference/month-subtraction.html","id":null,"dir":"Reference","previous_headings":"","what":"Month subtraction — %m-%","title":"Month subtraction — %m-%","text":"See lubridate::%m-% details.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month-subtraction.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Month subtraction — %m-%","text":"e1 period date-time object class POSIXlt, POSIXct Date. e2 period date-time object class POSIXlt, POSIXct Date. Note one e1 e2 must period date-time object.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month-subtraction.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Month subtraction — %m-%","text":"date-time object class POSIXlt, POSIXct Date","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":null,"dir":"Reference","previous_headings":"","what":"Month start — month_start","title":"Month start — month_start","text":"unexported helper identifies date first day month given date. function used internally inside valid_dates.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Month start — month_start","text":"","code":"month_start(date)"},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Month start — month_start","text":"date Date queried","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/month_start.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Month start — month_start","text":"Date first day month input date.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":null,"dir":"Reference","previous_headings":"","what":"Pipe operator — %>%","title":"Pipe operator — %>%","text":"See magrittr::%>% details.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Pipe operator — %>%","text":"","code":"lhs %>% rhs"},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Pipe operator — %>%","text":"lhs value magrittr placeholder. rhs function call using magrittr semantics.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/pipe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Pipe operator — %>%","text":"result calling rhs(lhs).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":null,"dir":"Reference","previous_headings":"","what":"Coverage component — plane_cover","title":"Coverage component — plane_cover","text":"function evaluates whether evaluated signal interval covers last observed value. interval used plausibility component drawn upper lower bounds forecasted prediction interval. , accepted signal format forecast, include upper lower bounds.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Coverage component — plane_cover","text":"","code":"plane_cover(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Coverage component — plane_cover","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Coverage component — plane_cover","text":"list following values: indicator: Logical whether last value falls outside interval (e.g., lower upper bounds prediction interval) evaluated signal last_value: vector last value recorded seed bounds: list two elements corresponding upper lower bounds evaluated signal interval","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_cover.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Coverage component — plane_cover","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_cover(location = \"08\", input = prepped_forecast, seed = prepped_seed) plane_cover(location = \"47\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":null,"dir":"Reference","previous_headings":"","what":"Difference component — plane_diff","title":"Difference component — plane_diff","text":"function implements point--point difference plausibility component. Differences evaluated signals calculated input values iteratively subtracted previous values (.e., x time point , difference calculated xi - xi-1). plausibility analysis uses evaluated differences compare maximum difference observed recorded seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Difference component — plane_diff","text":"","code":"plane_diff(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Difference component — plane_diff","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast observed seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Difference component — plane_diff","text":"list following values: indicator: Logical whether absolute value evaluated differences exceeds maximum difference values: vector values assessed including last value seed concatenated evaluated signal values evaluated_differences: vector consecutive differences values maximum_difference: vector one value maximum difference observed seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_diff.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Difference component — plane_diff","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_diff(location = \"10\", input = prepped_forecast, seed = prepped_seed) plane_diff(location = \"51\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":null,"dir":"Reference","previous_headings":"","what":"Repeat component — plane_repeat","title":"Repeat component — plane_repeat","text":"function evaluates whether consecutive values observations forecasts repeated k number times. function takes forecast observed object either observed dataset forecast dataset. Note signal contant (.e., value repeated time points) repeat component return FALSE.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Repeat component — plane_repeat","text":"","code":"plane_repeat(location, input, seed, tolerance = NULL, prepend = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Repeat component — plane_repeat","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast observed seed Prepared seed tolerance Integer value number allowed repeats flag raised. Default NULL allowed repeats determined seed. prepend Integer value number values seed add evaluated signal. Default NULL number values determined seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Repeat component — plane_repeat","text":"list following values: indicator: Logical whether value repeated sequentially k number times. repeats: tibble repeating values found. repeats (.e., indicator FALSE) tibble 0 rows.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_repeat.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Repeat component — plane_repeat","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component ## use defaults plane_repeat(location = \"12\", input = prepped_forecast, seed = prepped_seed) ## set tolerated repeats to 2 plane_repeat(location = \"12\", input = prepped_forecast, seed = prepped_seed, tolerance = 2) ## use defaults plane_repeat(location = \"49\", input = prepped_forecast, seed = prepped_seed) ## set number of values prepended for evaluation to 4 plane_repeat(location = \"49\", input = prepped_forecast, seed = prepped_seed, prepend = 4)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":null,"dir":"Reference","previous_headings":"","what":"Score PLANES components — plane_score","title":"Score PLANES components — plane_score","text":"function wraps PLANES scoring specified components across locations single step.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Score PLANES components — plane_score","text":"","code":"plane_score(input, seed, components = \"all\", args = NULL, weights = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Score PLANES components — plane_score","text":"input Input signal data scored; object must one forecast observed seed Prepared seed components Character vector specifying component; must either \"\" combination \"cover\", \"diff\", \"taper\", \"trend\", \"repeat\", \"shape\", \"zero\"; default \"\" use available components given signal args Named list arguments component functions. List elements must named match given component arguments passed nested list (e.g., args = list(\"trend\" = list(\"sig_lvl\" = 0.05))). Default NULL defaults components used weights Named vector weights applied; default NULL components equally weighted; NULL length vector must equal number components, component given numeric weight (see Examples). Specified weights must real numbers greater equal 1.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Score PLANES components — plane_score","text":"list scoring results locations.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_score.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Score PLANES components — plane_score","text":"","code":"# \\donttest{ ## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane scoring with all components plane_score(input = prepped_forecast, seed = prepped_seed) ## run plane scoring with select components plane_score(input = prepped_forecast, seed = prepped_seed, components = c(\"cover\",\"taper\")) ## run plane scoring with all components and additional args trend_args <- list(\"sig_lvl\" = 0.05) repeat_args <- list(\"prepend\" = 4, \"tolerance\" = 8) shape_args <- list(\"method\" = \"dtw\") comp_args <- list(\"trend\" = trend_args, \"repeat\" = repeat_args, \"shape\" = shape_args) plane_score(input = prepped_forecast, seed = prepped_seed, args = comp_args) ## run plane scoring with specific components and weights comps <- c(\"cover\", \"taper\", \"diff\") wts <- c(\"cover\" = 1.5, \"taper\" = 1, \"diff\" = 4) plane_score(input = prepped_forecast, seed = prepped_seed, components = comps, weights = wts) # }"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":null,"dir":"Reference","previous_headings":"","what":"Create seed — plane_seed","title":"Create seed — plane_seed","text":"function wraps seed_engine operate across locations input signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create seed — plane_seed","text":"","code":"plane_seed(input, cut_date = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create seed — plane_seed","text":"input Input signal data used seeding; must observed signal object cut_date Maximum date (inclusive) seeding performed; default NULL entire input used seeding","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create seed — plane_seed","text":"named list length n, multiple elements corresponding seed characteristics metadata n locations nested independent lists.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_seed.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create seed — plane_seed","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## prepare seed with no cut date plane_seed(prepped_observed) ## prepare seed with cut date plane_seed(prepped_observed, cut_date = \"2022-10-29\")"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":null,"dir":"Reference","previous_headings":"","what":"Shape component — plane_shape","title":"Shape component — plane_shape","text":"function identifies shape trajectory forecasted signal compare existing shapes seed data. shape identified novel, flag raised, signal considered implausible. See Details section information.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Shape component — plane_shape","text":"","code":"plane_shape(location, input, seed, method = \"sdiff\")"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Shape component — plane_shape","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast seed Prepared seed method method determining shapes; must one \"sdiff\" \"dtw\" (see Details); default \"sdiff\"","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Shape component — plane_shape","text":"list following values: indicator: Logical whether shape evaluated signal novel (TRUE shape novel, FALSE familiar shape exists seed)","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Shape component — plane_shape","text":"approach determining shapes can customized user plane_shape() \"method\" argument. two methods available \"sdiff\" (default) \"dtw\". Compared \"sdiff\", \"dtw\" method shown higher sensitivity, lower specificity, much greater computational cost circumstances. \"sdiff\" method recommended computational efficiency concern. \"sdiff\" method use consecutive scaled differences construct shapes. algorithm operates three steps: prepared seed data combined forecasted point estimates point--point difference calculated. differences centered scaled, cut categories. Differences greater equal one standard deviation mean differences considered \"increase\". Differences less equal one standard deviation mean differences considered \"decrease\". differences considered \"stable\". categorical differences combined windows equal size forecasted horizon. Collectively combined categorical differences create \"shape\" (e.g., \"increase;stable;stable;decrease\"). Lastly, algorithm compares shape forecast shapes observed. shape assessed previously observed time series flag raised indicator returned TRUE. \"dtw\" method uses Dynamic Time Warping (DTW) algorithm identify shapes within seed data compares shape forecast input signal observed shapes. done three broad steps: prepared seed data divided set sliding windows step size one, representing section overall time series. length windows determined horizon length input data signal (e.g., 2 weeks). example, seed data vector, c(1, 2, 3, 4, 5), horizon length 2, sliding windows observed seed data : c(1, 2), c(2, 3), c(3, 4), c(4, 5). sliding window subset total trajectory shape observed data. Shape-based DTW distances calculated every 1x1 combination observed sliding windows stored distance matrix. distances calibrate function identifying outlying shapes forecast data. algorithm finds minimum distances windowed time series use baseline \"observed distances\" chunks larger observed time series. maximum minimum distances across observed time series set threshold. minimum forecast:observed distance matrix greater threshold, forecast inferred unfamiliar (.e., novel shape). Next, algorithm calculates shape-based DTW distances forecast signal (including point estimate, lower, upper bounds) every observed sliding window. distance forecast observed sliding window less equal threshold defined , shape novel flag raised (indicator FALSE).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Shape component — plane_shape","text":"Toni Giorgino. Computing Visualizing Dynamic Time Warping Alignments R: dtw Package. Journal Statistical Software, 31(7), 1-24. doi:10.18637/jss.v031.i07 Tormene, P.; Giorgino, T.; Quaglini, S. & Stefanelli, M. Matching incomplete time series dynamic time warping: algorithm application post-stroke rehabilitation. Artif Intell Med, 2009, 45, 11-34. doi:10.1016/j.artmed.2008.11.007","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_shape.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Shape component — plane_shape","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) tmp_hosp <- hosp %>% dplyr::select(date, location, flu.admits) %>% dplyr::mutate(date = as.Date(date)) prepped_observed <- to_signal(tmp_hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal prepped_forecast <- read_forecast(system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\")) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_shape(location = \"37\", input = prepped_forecast, seed = prepped_seed) ## run plane component with DTW method plane_shape(location = \"37\", input = prepped_forecast, seed = prepped_seed, method = \"dtw\")"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":null,"dir":"Reference","previous_headings":"","what":"Taper component — plane_taper","title":"Taper component — plane_taper","text":"function evaluates whether evaluated signal interval tapers (.e., decreases width) horizons progress. interval used plausibility component drawn upper lower bounds forecasted prediction interval. , accepted signal format forecast, include upper lower bounds.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Taper component — plane_taper","text":"","code":"plane_taper(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Taper component — plane_taper","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Taper component — plane_taper","text":"list following values: indicator: Logical whether prediction interval width tapers advancing horizons widths: Consecutive interval widths forecasted data","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_taper.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Taper component — plane_taper","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_taper(location = \"19\", input = prepped_forecast, seed = prepped_seed) plane_taper(location = \"44\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":null,"dir":"Reference","previous_headings":"","what":"Trend component — plane_trend","title":"Trend component — plane_trend","text":"function identifies change points forecast data final observed data point. Change points identified significant change magnitude direction slope time series.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Trend component — plane_trend","text":"","code":"plane_trend(location, input, seed, sig_lvl = 0.1)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Trend component — plane_trend","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must forecast seed Prepared seed sig_lvl significance level identify change points (zero one); default 0.1","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Trend component — plane_trend","text":"list following values: indicator: Logical whether forecast data final observed data point significant change point output: n x 7 tibble. length forecast plus observed data determine length n. columns : Location: character vector location code Index: integer index observed forecast data Date: dates corresponding observed forecast data (formatted date) Value: incidence observed forecast data (e.g., hospitalization rates) Type: Indicates whether data row observed forecast data Changepoint: Logical identifying change point (whether observed forecast data). TRUE returned point determined change point based user defined significance level (sig_lvl). Flagged: Logical indicating whether change point flagged. Change points flagged forecast data final observed data point. TRUE returned Changepoint TRUE final observed data point forecast point. flagged_dates: date flagged change point(s). none, NA returned","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Trend component — plane_trend","text":"function uses e.divisive(), implements hierarchical divisive algorithm identify change points based distances segments (calculated using equations 3 5 Matteson James, 2014; larger distance, likely change point). permutation test used calculate approximate p-value. input e.divisive() transformed using differencing (.e., diff(x) instead raw data, x). slightly changes way change points identified, index aligns gap points rather points . Instead identifying change point based change size two points, identifies change points based change change . dataframe illustrates difference x diff(x): Given data, e.divisive(x) identify index 5 (74) change point, jump +37 index 4 5. e.divisive(diff(x)) pick index 3 (28) 5 (1), jump +28 index 2 3, jump -36 index 4 5. Internally, trend function uses extra argument e.divisive() min.size = 2, requires gap least 2 points detecting change points. can indirectly increase significance level decrease number change points identified.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Trend component — plane_trend","text":"Matteson, D. S., & James, N. . (2014). nonparametric approach multiple change point analysis multivariate data. Journal American Statistical Association, 109(505), 334–345. https://doi.org/10.1080/01621459.2013.849605 Matteson DS, James NA (2013). “Nonparametric Approach Multiple Change Point Analysis Multivariate Data.” ArXiv e-prints. appear Journal American Statistical Association, 1306.4933. Gandy, . (2009) \"Sequential implementation Monte Carlo tests uniformly bounded resampling risk.\" Journal American Statistical Association.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_trend.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Trend component — plane_trend","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) tmp_hosp <- hosp %>% dplyr::select(date, location, flu.admits) %>% dplyr::mutate(date = as.Date(date)) prepped_observed <- to_signal(tmp_hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal prepped_forecast <- read_forecast(system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\")) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_trend(location = \"05\", input = prepped_forecast, seed = prepped_seed, sig_lvl = .2) ## change location plane_trend(location = \"09\", input = prepped_forecast, seed = prepped_seed, sig_lvl = .2) ## change sig_lvl plane_trend(location = \"06\", input = prepped_forecast, seed = prepped_seed, sig_lvl = .05)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":null,"dir":"Reference","previous_headings":"","what":"Zero component — plane_zero","title":"Zero component — plane_zero","text":"function checks presence value(s) equal zero evaluated signal. zeros found, function assesses whether zeros observed seed given location. , function consider evaluated zero plausible flag raised (.e., indicator returned FALSE). , function consider evaluated zero implausible flag raised (.e., indicator returned TRUE).","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Zero component — plane_zero","text":"","code":"plane_zero(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Zero component — plane_zero","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must one forecast observed seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Zero component — plane_zero","text":"list following values: indicator: Logical whether zeros evaluated signal seed data","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/plane_zero.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Zero component — plane_zero","text":"","code":"## read in example observed data and prep observed signal hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) hosp$date <- as.Date(hosp$date, format = \"%Y-%m-%d\") prepped_observed <- to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") ## read in example forecast and prep forecast signal fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") prepped_forecast <- read_forecast(fp) %>% to_signal(., outcome = \"flu.admits\", type = \"forecast\", horizon = 4) ## prepare seed with cut date prepped_seed <- plane_seed(prepped_observed, cut_date = \"2022-10-29\") ## run plane component plane_zero(location = \"10\", input = prepped_forecast, seed = prepped_seed) plane_zero(location = \"51\", input = prepped_forecast, seed = prepped_seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":null,"dir":"Reference","previous_headings":"","what":"Quantile boundary — q_boundary","title":"Quantile boundary — q_boundary","text":"unexported helper generates vector lower bound, median, upper bound prediction interval specified width. function used internally inside read_forecast.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Quantile boundary — q_boundary","text":"","code":"q_boundary(pi_width)"},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Quantile boundary — q_boundary","text":"pi_width Interval width integer","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/q_boundary.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Quantile boundary — q_boundary","text":"Vector quantiles corresponding lower upper bounds centered median.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":null,"dir":"Reference","previous_headings":"","what":"Read in forecast file — read_forecast","title":"Read in forecast file — read_forecast","text":"function reads probabilistic (\"quantile\") forecast csv file prepares to_signal function downstream plausibility analysis. quantile forecast file can either \"legacy\" \"hubverse\" format (see Details information). object returned tibble summarized forecast data (.e., prediction interval) location horizon original file.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Read in forecast file — read_forecast","text":"","code":"read_forecast(file, pi_width = 95, format = \"legacy\")"},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Read in forecast file — read_forecast","text":"file Path csv file containing quantile forecasts pi_width Width prediction interval integer; default 95 corresponds 95% prediction interval format Format probabilistic format file; must one \"legacy\" \"hubverse\" (see Details information); default \"legacy\"","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Read in forecast file — read_forecast","text":"tibble following columns: location: Geographic unit FIPS code date: Date corresponding forecast horizon horizon: Forecast horizon lower: Lower limit prediction interval forecast point: Point estimate forecast upper: Upper limit prediction interval forecast","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Read in forecast file — read_forecast","text":"probabilistic forecast format used multiple forecasting hubs. general, format includes one row per combination quantile, location, target, horizon. row forecasted value provided. specific format, including columns required, changed time. function accommodates \"legacy\" well recent \"hubverse\" formats. details specific columns see links References.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Read in forecast file — read_forecast","text":"Hubverse: https://hubdocs.readthedocs.io/en/latest/user-guide/model-output.html Legacy: https://github.com/cdcepi/Flusight-forecast-data/tree/master/data-forecasts#forecast-file-format","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/read_forecast.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Read in forecast file — read_forecast","text":"","code":"## read in example forecast and prep forecast signal (legacy format) fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") read_forecast(fp) fp2 <- system.file(\"extdata/forecast/2023-11-04-SigSci-TSENS.csv\", package = \"rplanes\") read_forecast(fp2, format = \"hubverse\")"},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":null,"dir":"Reference","previous_headings":"","what":"Resolve resolution — resolve_resolution","title":"Resolve resolution — resolve_resolution","text":"helper function uses argument matching resolve resolution input. function also handles casing. allow, example, input resolution \"daily\" \"day\" resolved \"days\".","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Resolve resolution — resolve_resolution","text":"","code":"resolve_resolution(resolution)"},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Resolve resolution — resolve_resolution","text":"resolution Character vector specifying temporal resolution (e.g., \"days\", \"weeks\", \"months\")","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/resolve_resolution.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Resolve resolution — resolve_resolution","text":"resolution matches \"days\", \"weeks\", \"months\" match returned. , function throw error.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes-package.html","id":null,"dir":"Reference","previous_headings":"","what":"rplanes: Plausibility Analysis of Epidemiological Signals — rplanes-package","title":"rplanes: Plausibility Analysis of Epidemiological Signals — rplanes-package","text":"Provides functionality prepare data analyze plausibility forecasted reported epidemiological signals. functions implement set plausibility algorithms agnostic geographic time resolutions calculated independently presented combined score.","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"rplanes: Plausibility Analysis of Epidemiological Signals — rplanes-package","text":"Maintainer: VP Nagraj nagraj@nagraj.net (ORCID) Authors: Desiree Williams Amy Benefield","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":null,"dir":"Reference","previous_headings":"","what":"rplanes explorer app launcher — rplanes_explorer","title":"rplanes explorer app launcher — rplanes_explorer","text":"rplanes explorer app allows user interactively upload data (view internal example) explore plausibility analysis functionality.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"rplanes explorer app launcher — rplanes_explorer","text":"","code":"rplanes_explorer(...)"},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"rplanes explorer app launcher — rplanes_explorer","text":"... Additional arguments passed shiny::runApp","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"rplanes explorer app launcher — rplanes_explorer","text":"function operates side-effect starts rplanes Shiny app.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/rplanes_explorer.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"rplanes explorer app launcher — rplanes_explorer","text":"","code":"if (FALSE) { # \\dontrun{ # Launch the explorer app rplanes_explorer(host = \"0.0.0.0\", launch.browser = TRUE, port = 80) } # }"},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":null,"dir":"Reference","previous_headings":"","what":"Seed engine — seed_engine","title":"Seed engine — seed_engine","text":"helper function used inside plane_seed evaluate characteristics observed data use downstream plausibility analysis.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Seed engine — seed_engine","text":"","code":"seed_engine(input, location, cut_date = NULL)"},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Seed engine — seed_engine","text":"input Input signal data used seeding; must observed signal object location Character vector location code cut_date Maximum date (inclusive) seeding performed; default NULL entire input used seeding","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/seed_engine.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Seed engine — seed_engine","text":"list length 1 multiple elements corresponding seed characteristics metadata given location.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":null,"dir":"Reference","previous_headings":"","what":"Chunk a vector — to_chunk","title":"Chunk a vector — to_chunk","text":"unexported helper function creates list contents vector spit chunks. user can specify large chunk \"size\" argument.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Chunk a vector — to_chunk","text":"","code":"to_chunk(x, size)"},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Chunk a vector — to_chunk","text":"x Vector split chunks large \"size\" specified size Width chunks \"x\" vector","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_chunk.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Chunk a vector — to_chunk","text":"list many elements number chunks created. element include vector length equal \"size\" specified.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":null,"dir":"Reference","previous_headings":"","what":"Create signal object — to_signal","title":"Create signal object — to_signal","text":"function creates object S3 class \"signal\". user can conditionally specify either \"forecast\" \"observed\" signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create signal object — to_signal","text":"","code":"to_signal( input, outcome, type = \"observed\", resolution = \"weeks\", horizon = NULL )"},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create signal object — to_signal","text":"input Data converted signal; see \"Details\" information outcome Name outcome column input data type Signal type; must one \"observed\" \"forecast\"; default \"observed\" resolution temporal resolution signal; data can aggregated daily, weekly, monthly; default \"weeks\"; see \"Details\" information horizon Number time steps ahead forecast signals; used type=\"forecast\"; default NULL","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create signal object — to_signal","text":"object class signal. object second class either observed forecast depending value passed \"type\" argument.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Create signal object — to_signal","text":"input signal data may either \"observed\" \"forecast\" data. Depending type, input data must conform certain format prior submission. cases, data must passed data frame. \"observed\" data data frame must minimum include columns location (geographic unit FIPS code) date (date reported value; must date class). data also include column contains outcome (e.g., case count). \"forecast\" data data frame must include columns location (geographic unit FIPS code), date (date corresponding forecast horizon; must date class character formatted 'YYYY-MM-DD'), horizon (forecast horizon), lower (lower limit prediction interval forecast), point (point estimate forecast), upper (upper limit prediction interval forecast). Note read_forecast function returns data format. input data must daily, weekly, monthly resolution. \"resolution\" parameter designed use string matching. allows flexibility user, , example, input \"day\", \"days\", \"daily\" resolve resolution days. rules apply designating weekly monthly resolution.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/to_signal.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create signal object — to_signal","text":"","code":"hosp <- read.csv(system.file(\"extdata/observed/hdgov_hosp_weekly.csv\", package = \"rplanes\")) to_signal(hosp, outcome = \"flu.admits\", type = \"observed\", resolution = \"weeks\") fp <- system.file(\"extdata/forecast/2022-10-31-SigSci-TSENS.csv\", package = \"rplanes\") ex_forecast <- read_forecast(fp) to_signal(ex_forecast, outcome = \"flu.admits\", type = \"forecast\", horizon = 4, resolution = \"weeks\")"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":null,"dir":"Reference","previous_headings":"","what":"Validate dates — valid_dates","title":"Validate dates — valid_dates","text":"function validates gaps overlaps dates specified \"seed_date\" \"signal_date\". plausibility component analyses, function called validate seed evaluated signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Validate dates — valid_dates","text":"","code":"valid_dates(seed_date, signal_date, resolution, warn_incomplete = FALSE)"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Validate dates — valid_dates","text":"seed_date Last date available seed object signal_date First date available signal object resolution Character vector specifying temporal resolution (e.g., \"days\", \"weeks\", \"months\") warn_incomplete Logical whether validation warn completeness seed signal; default FALSE","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Validate dates — valid_dates","text":"validation return stop() overlap gap seed signal dates. Otherwise function invisibly return TRUE indicating date span valid.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_dates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Validate dates — valid_dates","text":"","code":"seed_date <- as.Date(\"2023-03-08\") signal_date <- as.Date(\"2023-03-15\") valid_dates(seed_date = seed_date, signal_date = signal_date, resolution=\"weeks\") x <- try(valid_dates(seed_date = seed_date, signal_date = signal_date, resolution=\"days\"), silent=TRUE) x x <- try(valid_dates(seed_date = seed_date, signal_date = signal_date, resolution=\"months\"), silent=TRUE) x"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":null,"dir":"Reference","previous_headings":"","what":"Validate location — valid_location","title":"Validate location — valid_location","text":"unexported helper used inside individual plausibility component functions (e.g., plane_diff()) validate location specified appears input signal seed location many values locations seed.","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Validate location — valid_location","text":"","code":"valid_location(location, input, seed)"},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Validate location — valid_location","text":"location Character vector location code; location must appear input seed input Input signal data scored; object must forecast seed Prepared seed","code":""},{"path":"https://signaturescience.github.io/rplanes/reference/valid_location.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Validate location — valid_location","text":"validation return stop() location found seed input signal. Otherwise function invisibly return TRUE indicating location valid.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"rplanes-010","dir":"Changelog","previous_headings":"","what":"rplanes 0.1.0","title":"rplanes 0.1.0","text":"CRAN release: 2024-07-17","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"performance-optimization-for-plane_shape-0-1-0","dir":"Changelog","previous_headings":"New features","what":"Performance optimization for plane_shape()","title":"rplanes 0.1.0","text":"release, introduced parameter customize “method” used identify shapes within plane_shape(). Previously, function able use Dynamic Time Warping (“dtw”) algorithm identify shapes time series. approach involved calculations computationally expensive, particularly datasets multiple locations seed. introduced second method uses scaled difference approach (“sdiff”) ascertain shapes. “sdiff” option set default, much computationally efficient “dtw” option. details methods see ?plane_shape().","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"interpretation-vignette-0-1-0","dir":"Changelog","previous_headings":"New features","what":"Interpretation vignette","title":"rplanes 0.1.0","text":"package now includes narrative vignette discusses interpret results PLANES analysis. Topics include apply weighting scheme plane_score(), strategies mitigate limitations may arise seed data, considerations operationally taking action based plausibility scores.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"more-informative-warning-for-missing-data-0-1-0","dir":"Changelog","previous_headings":"New features","what":"More informative warning for missing data","title":"rplanes 0.1.0","text":"release introduces messaging communicates location fewer time steps compared others seed. warning message formatted “{LOCATION} fewer values locations. may introduce issues downstream plausibility analysis.”","code":""},{"path":[]},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"better-handling-of-locations-with-all-missing-data-0-0-3","dir":"Changelog","previous_headings":"New features","what":"Better handling of locations with all missing data","title":"rplanes 0.0.3","text":"previous version package, user input signal data included location values missing plane_seed() function proceed. However, lead background characteristics seed used downstream algorithms (e.g., infinite range). now trigger error input data to_signal() includes locations values missing.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"more-intuitive-plane_repeat-behavior-0-0-3","dir":"Changelog","previous_headings":"New features","what":"More intuitive plane_repeat() behavior","title":"rplanes 0.0.3","text":"PLANES scoring includes plane_repeat() implement “repeat” algorithm (.e., checking evaluated signal creates repeat sequence longer previously observed seed). observed flagging instances values time series . release adjusted algorithm longer flag constant time series implausible.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"weighting-scheme-constraints-0-0-3","dir":"Changelog","previous_headings":"New features","what":"Weighting scheme constraints","title":"rplanes 0.0.3","text":"release, introduced new feature constrain component weights passed plane_score() values >= 1. adding constraint, saw inconsistent behavior cases weights set < 1. updated function documentation plane_score() “weights” argument reflect change.","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"documentation-typos-0-0-3","dir":"Changelog","previous_headings":"Bug fixes","what":"Documentation typos","title":"rplanes 0.0.3","text":"release introduces minor fixes typos function documentation README.","code":""},{"path":[]},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"new-plausibility-components-0-0-2","dir":"Changelog","previous_headings":"New features","what":"New plausibility components","title":"rplanes 0.0.2","text":"rplanes package now features two new plausibility components: “shape” “zero”. components delivered function (plane_shape() plane_zero(), respectively) run plane_score() alongside specified components. previously developed components, two operate binary classifications plausibility signal evaluated given location. “shape” component uses series distance calculations characterize “similar” evaluated signal previous windows observed data seed. distance evaluated shape exceeds maximum distance observed shapes signal flagged implausible. “shape” component can used forecast signal. “zero” component assesses whether zeros observed seed given location. , component look zeros evaluated signal. finds , signal flagged implausible. Note “zero” component work either forecast observed signal.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"rplanes_explorer-app-0-0-2","dir":"Changelog","previous_headings":"New features","what":"rplanes_explorer() app","title":"rplanes 0.0.2","text":"release introduces new feature deliver point--click interface PLANES scoring directly rplanes package. interface written Shiny app, maintained part package can launched using rplanes_explorer() function. user installs rplanes, app (stored inst/ directory) visible host machine. rplanes_explorer() wraps shiny::runApp() points “appDir” argument directory holds rplanes explorer app. Users can take advantage arguments inherited shiny::runApp() (e.g., launch.browser=TRUE open app directly browser window).","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"improved-documentation-0-0-2","dir":"Changelog","previous_headings":"New features","what":"Improved documentation","title":"rplanes 0.0.2","text":"added improvements overall documentation package. particular, release introduces two new vignettes: one describe individual components operate another briefly introduce explore app. addition new vignettes, also implemented handful grammatical wording changes make existing documentation clear concise.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"hubverse-forecast-format-0-0-2","dir":"Changelog","previous_headings":"New features","what":"“Hubverse” forecast format","title":"rplanes 0.0.2","text":"updates quantile format used forecast hubs, introduced option read_forecast() helper optionally read different formats. function now supports “Hubverse” format used 2023-24 FluSight initiative (https://hubdocs.readthedocs.io/en/latest/user-guide/model-output.html).","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"optional-weighting-scheme-0-0-2","dir":"Changelog","previous_headings":"New features","what":"Optional weighting scheme","title":"rplanes 0.0.2","text":"release introduce new feature users optionally weight importance individual components overall plausibility score. weights must specified named vector passed plane_score() function. argument optional default function use equal weights component.","code":""},{"path":[]},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"default-components-with-plane_score-0-0-2","dir":"Changelog","previous_headings":"Bug fixes","what":"Default components with plane_score()","title":"rplanes 0.0.2","text":"Prior release, observed signal evaluated plane_score() strictly require user manually specify compatible components (v0.0.1 “diff” “repeat”). version, plane_score() can now detect type signal “” components selected function identify compatible. example, addition new components (see ), specifying plane_score(..., components = \"\") observed signal automatically use “diff”, “repeat”, “zero” components.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"hyphens-in-location-names-0-0-2","dir":"Changelog","previous_headings":"Bug fixes","what":"Hyphens in location names","title":"rplanes 0.0.2","text":"plane_score() wrapper uses - (hyphen) combine location component returned list object. release, locations hyphen names (e.g., “United-States”) one internal data manipulation steps function expected. updated internals plane_score() now allow location names may contain hyphens.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"data-ordering-in-seed-0-0-2","dir":"Changelog","previous_headings":"Bug fixes","what":"Data ordering in seed","title":"rplanes 0.0.2","text":"Previously, plane_seed() function used dates arranged incoming observed signal data. , seeding unexpected behavior. example, dates ordered descending “last value” actually first value chronologically. release, plane_seed() function internally now arranges data case input data ordered ascending date.","code":""},{"path":"https://signaturescience.github.io/rplanes/news/index.html","id":"rplanes-001","dir":"Changelog","previous_headings":"","what":"rplanes 0.0.1","title":"rplanes 0.0.1","text":"Alpha release rplanes package! Several key package features include: read_forecast(): Data prep function read forecasts quantile format used forecasting hubs to_signal(): Constructor “signal” S3 class used package plane_seed(): Function create baseline characteristics observed data given range dates plane_score(): Wrapper run plausibility components independently across locations release, five plausibility components included rplanes. continue develop package add components, update functionality, address issues needed. information features use-cases, refer “Basic Usage” vignette package website R console: vignette(\"basic-usage\", package=\"rplanes\")","code":""}]