parameter-checks: Standardized Parameter Defaults

In pepfar-datim/datapackr: A Package that Packs and Unpacks all Data Packs and Target Setting Tools

Standardized Parameter Defaults

Description

Standardized package functions,in terms of parameter defaults and checks. These can be run individually (e.g., check_country_uids), or in bulk (e.g., check_params(country_uids = "abcdefgh123", tool = "Data Pack")).

Usage

check_country_uids(country_uids, cop_year, force = TRUE)

check_PSNUs(PSNUs = NULL, country_uids = NULL, cop_year = NULL)

check_cop_year(cop_year, tool)

check_tool(tool, season, cop_year)

check_season(season, tool)

check_schema(schema, cop_year, tool, season)

checkDataPackName(datapack_name, country_uids, cop_year)

checkTemplatePath(template_path, cop_year, tool, season)

checkWB(
  wb = NULL,
  country_uids = NULL,
  cop_year = NULL,
  tool = NULL,
  datapack_name = NULL,
  template_path = NULL
)

checkOutputFolder(output_folder = NULL)

checkResultsArchive(results_archive = FALSE)

checkSheets(
  sheets,
  cop_year,
  tool,
  all_sheets = FALSE,
  operation = "schema",
  psnuxim = FALSE
)

check_params(
  country_uids,
  PSNUs,
  cop_year,
  tool,
  season,
  schema,
  datapack_name,
  template_path,
  wb,
  model_data,
  snuxim_model_data,
  output_folder,
  results_archive,
  sheets,
  ...
)

Arguments

country_uids	Unique IDs for countries to include in the Data Pack. For full list of these IDs, see datapackr::valid_OrgUnits.
cop_year	COP Year to use for tailoring functions. Remember, FY22 targets = COP21.
force	logical. Should country_uids be required?
PSNUs	Dataframe of PSNUs to use in this function, containing at least psnu_uid.
tool	Type of tool this function will create or interact with. Either OPU Data Pack or Data Pack
season	Either COP or OPU.
schema	Which datapackr schema to use in guiding this function. If left NULL will select the default based on cop_year and tool.
datapack_name	Name you would like associated with this Data Pack. (Example: "Western Hemisphere", or "Caribbean Region", or "Kenya".)
template_path	Local filepath to Data Pack template Excel (XLSX) file. This file MUST NOT have any data validation formats present. If left NULL, will select the default based on cop_year and tool.
wb	Openxlsx workbook object.
output_folder	Local folder where you would like your Data Pack to be saved upon export.
results_archive	If TRUE, will export compiled results of all tests and processes to output_folder.
sheets	Character vector. Names of sheets/tabs within tool.
all_sheets	Logical. Return/check against all sheets (as opposed to only those with targets)?
operation	String. Options = "unpack", "pack", "schema", or "other".
psnuxim	Logical. Return/check against PSNUxIM tab as well?
model_data	Data from DATIM needed to pack into a COP Data Pack.
snuxim_model_data	Export from DATIM needed to allocate data across mechanisms in the PSNUxIM tab.
...	Additional arguments to pass.

Value

For lower-level functions, a valid function parameter value/object. For the higher-level check_params, a list object containing one valid parameter value/object for each non-missing parameter supplied.

• check_country_uids: List of country_uids.

• check_PSNUs: Dataframe of valid PSNUs (uid and names).

• check_cop_year: Valid cop_year as numeric value.

• check_tool: Valid tool type as string.

• check_season: Valid season as string.

• check_schema: Valid schema as dataframe.

• checkDataPackName: Valid datapack_name as string.

• checkTemplatePath: Valid template_path as string.

• checkWB: Valid Data Pack shell for specified cop_year and tool type.

• checkOutputFolder: Valid output_folder as string.

• checkResultsArchive: Valid results_archive as .rds list object, equivalent to the d object used throughout this package.

• check_params: List object containing one valid parameter value/object for each non-missing parameter supplied.

Defining Parameter Defaults

As much as possible throughout this package, we have adhered to the principle outlined in the Tidyverse Design Guide regarding parameter defaults for functions: "Default values should be short and sweet. This makes the function specification easier to scan."

Where feasible, we have used the common approach of using NULL as the parameter default. In many cases, we set this in the function parameter definition upfront, and then calculate the default only when this value is unsupplied or otherwise left NULL. The virtue of this approach is that not supplying this value at all still supplies NULL to the function's internal logic without a missing error. In many cases, we use the following custom function to make this simpler and cleaner:

`%||%` <- function(x, y) if (is.null(x)) y else x

For example:

example_function <- function(arg1 = NULL) {
  arg2 <- arg1 %||% 10
  arg2 + 10
}

example_function()
20

However, in some cases within this package, NULL is an equally valid value that could be passed to a parameter from a higher-level function. To distinguish these from truly missing values, we have in some places left the default undefined in the function parameter and employed the following custom function:

`%missing%` <- function(x, y = NULL) rlang::maybe_missing(x, y)

For example:

example_function2 <- function(arg1) {
  arg1 <- arg1 %missing% NULL
  arg2 <- arg1 %||% 10
  arg2 + 10
}

This function allows the following to return equivalent values without missing errors:

test_arg <- rlang::missing_arg()
test_arg2 <- NULL
example_function2()
20

example_function2(test_arg)
20

example_function2(test_arg2)
20

Similarly, when nested within a higher-level function, this approach also accommodates scenarios where missing or NULL values may be meaningful:

example_function3 <- function(arg1, arg2) {
  example_function2(arg1)
}

example_function3(arg1 = test_arg, arg2 = 3)
20

example_function3(arg1 = test_arg2, arg2 = 3)
20

So, within this package, we alternatively use ⁠%||%⁠ and ⁠%missing%⁠ to determine default parameters based on the situation and package usage.

Because of the sometimes complicated manner in determining default parameters, which can often change from year to year, we have attempted to centralize and standardize how all parameters are validated and how default parameters are determined here within this function.

See Also

Other parameter-helpers: datapackr_params()

pepfar-datim/datapackr documentation built on April 14, 2024, 10:35 p.m.