calc_path_TURN: Calculate TURN by pathogen
In MartinHoldrege/turnr: Normalization of Test Utilization Rate

Description Usage Arguments Value Examples

Calculates test utilization rate normalization (Y”) for each pathogen, using daily site level data. See ?calc_TURN for details on how TURN is calculated (that function is for caclulating overall/total TURN–not for a specific pathogen).

calc_path_TURN(
  df,
  TURN_df,
  means,
  group_vars = vars(InstrumentVersion),
  site_info = NULL,
  add_path_dates = FALSE,
  run_check = FALSE
)

`df`	dataframe of daily pathogen data. Columns must include "date", "InstrumentVersion", "daily_count", "TargetName", "SiteID"
`TURN_df`	dataframe created by `calc_TURN()`. Must include columns of "epidate", "n_active", "n_active_adj", "epi_n_days", "Y", "Y_prime", "Y_prime_3wma", as well as columns listed in group_vars argument.
`means`	named vector of means. The vector needs to be length of three giving the means of Y (tests/adjusted active instrument) for the FA1.5, FA2.0 and Torch system (with those names provided as names of elements in the vector). This should be created by the `calc_TURN()` function when aggregating to the national level.
`group_vars`	columns to group by. Unquoted names of columns enclosed in vars(). Must at least include InstrumentVersion (which would then result in a national level TURN)
`site_info`	NULL or dataframe (if additonal group_vars are needed). must contain a SiteID column, so that it can be merged with df. Additional columns (e.g. Region) need to be present in the site_info dataframe to be used as group_vars.
`add_path_dates`	logical whether to fill in date gaps with NA when smoothing Y". May slow down the function. Can be needed when if get error for non continuous epidates (there are some cases when data from some instrument versions has been removed where this is needed)
`run_check`	logical, whether to run a check to see if the sum of individual pathogens TURNs equals the total TURN, for each epiweek. This check is only relevant when co-detections and negatives are pathogen categories, in which case you would expect the check to not throw an error.

Dataframe. The dataframe contains the following columns: epiweek, epiyear, epidate (date of middle of epiweek), epi_count (count of number of detections of pathogen that epiweek), TargetName (pathogen), path_Y (positives for that pathogen/adjust active instruments), path_Y_prime (path_Y adjusted to mean of FA1.5, or when InstrumentVersion == all_adj, this is the weighted average of path Y prime for the other instruments). Y_prime_3wma (3 week moving average applied to path_Y_prime, this is TURN for pathogen when InstrumentVersion == 'all_adj'). Other columns as supplied in TURN_df and site_info

# list of national turn and means by instrument (means should be
#    calculated at national level)
national_list <- calc_TURN(TUR_dat, return_means = TRUE)
means <- national_list$means
# national TURN
TURN_national <- national_list$df

# regional (state) TURN
site_info <- get_site_info(rp_raw)
TURN_region <- calc_TURN(TUR_dat,
                         group_vars = vars(InstrumentVersion, Region),
                         site_info = site_info,
                         means = means)

# calculate TURN for each pathogen -- national
calc_path_TURN(df = path_dat,
               TURN_df = TURN_national,
               means = means)

# calculate TURN for each pathogen -- regional
calc_path_TURN(df = path_dat,
               TURN_df = TURN_region,
               means = means,
               group_vars = vars(InstrumentVersion, Region),
               site_info = site_info)