parameter-checks | R Documentation |
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")
).
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, cop_year)
check_schema(schema, cop_year, tool)
checkDataPackName(datapack_name, country_uids, cop_year)
checkTemplatePath(template_path, cop_year, tool)
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,
schema,
datapack_name,
template_path,
wb,
model_data,
snuxim_model_data,
output_folder,
results_archive,
sheets,
...
)
country_uids |
Unique IDs for countries to include in the Data Pack.
For full list of these IDs, see |
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
|
tool |
Type of tool this function will create or interact with. Either
|
schema |
Which datapackr schema to use in guiding this function. If left
|
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
|
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. |
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_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.
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.
Other parameter-helpers:
datapackr_params()
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.