Package 'coreval'

Description

For when you are writing the code that builds a domain and want to know what is wrong with it right now. Give it the data frame you already have open, or the path to a single file.

Usage

check_dataset(
  x,
  domain = NULL,
  standard = NULL,
  version = NULL,
  use_case = NULL,
  max_records = 1000,
  include_deprecated = FALSE,
  ct_package = NULL
)

Arguments

Value

An object of class coreval_result: a list of the three tables findings, skipped and truncated, the same shape check_study() returns, so write_findings() and filter_findings() work on it unchanged. Because it has a class, typing the result's name prints a readable report rather than dumping the list.

skipped carries a reason for every rule that did not run - a dataset you did not supply, a missing Define-XML, or (for 9 rules) CDISC's controlled terminology, if you did not say which package the study follows - see ct_package. Nothing skipped is ever counted as a pass.

Provenance rides along as attributes: checks_run (how many rules were evaluated), domains, and excluded_by_standard (how many rules the standard/version filter set aside). write_findings() writes these into the file it saves.

What it cannot check on its own

Plenty of CDISC rules compare one dataset against another - an adverse event date against the subject's reference dates in DM, a visit against the trial design. Hand over a single dataset and those questions cannot be answered.

coreval does not guess. Those rules are skipped, and ⁠$skipped⁠ names the dataset each one wanted. Running them anyway would compare your data against columns that are not there and report problems that do not exist.

Most rules still run on a single dataset. But the ones that cannot are the cross-dataset checks, which are often the ones that matter.

So a short ⁠$findings⁠ table here does not mean the data is clean. It is a quick first pass, not a verdict. Run check_study() on the whole folder before drawing conclusions.

See Also

check_study() to check a whole study folder.

Examples

ae <- data.frame(
  STUDYID = "S1", DOMAIN = "AE", USUBJID = c("01", "01"),
  AESEQ = c(1, 2), AETERM = c("Headache", "Rash"),
  AESTDTC = c("2024-01-10", "2024-02-30") # 30 February is not a date
)
result <- check_dataset(ae)
result$findings[result$findings$Value == "2024-02-30", ]

# Always look at what could not run:
nrow(result$skipped)

Description

Runs every rule that applies to every dataset in the study, including the ones that compare datasets against each other. Use this once the datasets exist as files; to check a single dataset while you are still writing the code that builds it, see check_dataset().

Usage

check_study(
  study,
  standard = NULL,
  version = NULL,
  use_case = NULL,
  max_records = 1000,
  include_deprecated = FALSE,
  ct_package = NULL,
  usdm = FALSE
)

Arguments

Details

Findings come back one row per (dataset, record, variable), pointing at the exact spot. Some rules ask about a dataset as a whole rather than a particular row - those leave Record blank. A few ask about the study as a whole, such as "is DM present at all?"; those are answered once and reported under Dataset = "STUDY" rather than repeated for every domain.

Rules comparing against a define.xml do run, as long as the study has one and the xml2 package is installed. Without both, they are skipped with a reason instead of being run against columns that are not there, which would report problems that do not exist. The same goes for any rule needing an operator or join coreval does not implement yet.

Value

An object of class coreval_result, holding three tables. Because it has a class, typing the result's name prints a readable report rather than dumping the list, and provenance rides along as attributes: checks_run, domains and excluded_by_standard.

• findings - what is wrong. One row per affected record, with Dataset, Record, Variable, Value, the issue in words, and its triage. ⁠Not in dataset⁠ under Value means the rule wanted a variable you do not have, which is usually the finding itself.

• skipped - what could not be checked, with a reason for each. Read this one: an empty findings table can mean clean data or rules that never ran, and they look identical otherwise. Reasons include a dataset the study does not have, a missing Define-XML, and a controlled terminology version that neither the study nor ct_package names. Nothing skipped is ever counted as a pass.

• truncated - rules that flagged more records than max_records kept, with how many they really found.

Progress

A large study takes long enough that silence looks like a hang, so an interactive session shows a progress bar naming the domain being checked and how far through the study it is:

  AE        4/7  |=====================       |  75%

The percentage is weighted by how many records each domain holds, not by a plain count of rules, because a check against a 161,600-row AE costs hundreds of times one against a 200-row SJ. It tracks elapsed time closely but is still an estimate - rules differ in cost among themselves too - so treat it as "roughly how far through", not a clock.

It is off in scripts and non-interactive runs, where it would only clutter a log. Turn it on or off with options(coreval.progress = TRUE) or FALSE.

Examples

dir <- tempfile("coreval_study_")
dir.create(dir)
haven::write_xpt(data.frame(USUBJID = c("1", "2"), AGE = c(30, 65)), file.path(dir, "dm.xpt"))

result <- check_study(dir)
result$findings
unlink(dir, recursive = TRUE)

Description

Saves writing subset() over ⁠$findings⁠ by hand, and - because it returns a result rather than a plain table - what comes back still prints as a readable report.

Usage

filter_findings(
  result,
  triage = NULL,
  dataset = NULL,
  rule = NULL,
  variable = NULL
)

Arguments

Value

A coreval_result holding the matching findings. ⁠$skipped⁠ is left alone: what could not be checked does not become less true because you narrowed what you are looking at.

Examples

ae <- data.frame(
  STUDYID = "S1", DOMAIN = "AE", USUBJID = c("01", "01"),
  AESEQ = c(1, 2), AETERM = c("Headache", "Rash"),
  AESTDTC = c("2024-01-10", "2024-02-30")
)
result <- check_dataset(ae)

# Just the things that are definitely wrong:
filter_findings(result, triage = "wrong value")

Description

Which version of CDISC's Controlled Terminology a study follows decides whether a value is a legal term, and the answer changes between releases - SEX gained INTERSEX and lost UNDIFFERENTIATED. So coreval never picks one for you: pass the one your study declares as check_study(ct_package =) and this is the list to pick from.

Usage

list_ct_packages(family = NULL)

Arguments

Details

Only what a conformance rule can ask about is bundled - each codelist's submission value and C-code, its terms' submission values and C-codes, and whether it is extensible. Definitions and synonyms are not, which is how 438 MB of CDISC's own caches becomes half a megabyte here.

Value

A character vector of package names, oldest first.

Examples

head(list_ct_packages("sdtm"))

Description

One way in for every question about the rule set: what rules exist, what a particular one checks, and which of them apply to a domain.

Usage

list_rules(
  id = NULL,
  domain = NULL,
  standard = NULL,
  version = NULL,
  use_case = NULL,
  include_deprecated = TRUE
)

Arguments

Details

The columns are the same whatever you ask for, so the result is safe to filter, join and script against.

Value

A data.table::data.table(), one row per rule: id, the one-line issue it reports, its fuller description, the guidance sentence from the Implementation Guide it enforces, the legacy_ids Pinnacle 21 uses for it, standard and standard_version, authority, rule_type, sensitivity, executability, source and status.

The commit the bundled rules came from is on the result as attr(x, "rules_version"); write_findings() records it in every exported file.

What source tells you

Not every bundled rule carries the same weight:

• "published" - ⁠Published/⁠ upstream, fully tested. The trusted core.

• "deprecated_dir" - superseded by a published replacement. Not returned unless you ask for it, since running both reports the same defect twice.

• "fda_business_rules_draft" - FDA drafts that already ship test data.

Examples

# Everything
nrow(list_rules())

# What does the rule the report just named actually check?
list_rules(id = "CORE-000547")$issue

# What applies to AE under SDTMIG 3.4?
nrow(list_rules(domain = "AE", standard = "SDTMIG", version = "3.4"))

# Which snapshot of CDISC's rules is this?
attr(list_rules(), "rules_version")

Description

Describes each problem in the rule's own words, worst first, with the rows and values that caused it. A whole-study result is grouped by dataset, with a summary first, so you can see where the trouble is before reading detail.

Usage

## S3 method for class 'coreval_result'
print(x, n = 10, rows = 3, guidance = FALSE, ...)

Arguments

Value

x, invisibly.

Examples

ae <- data.frame(
  STUDYID = "S1", DOMAIN = "AE", USUBJID = c("01", "01"),
  AESEQ = c(1, 2), AETERM = c("Headache", "Rash"),
  AESTDTC = c("2024-01-10", "2024-02-30")
)
check_dataset(ae)

Description

Reads a study folder: SAS transport (.xpt) and SAS (.sas7bdat) files, Dataset-JSON (.json, .ndjson), or a USDM study document, plus a Define-XML when one is there. A CORE test-case ⁠data/⁠ folder (⁠_variables.csv⁠ and one CSV per dataset) is read too. All of them come out in the same internal representation, so the evaluator never has to know which one it got.

Usage

read_study(path, usdm = FALSE)

Arguments

Details

Character columns use "" for blank/missing (never NA) to match how SAS XPT round-trips blanks; numeric columns use NA. Column types are taken from the source (XPT's own types, or ⁠_variables.csv⁠'s declared Char/Num) rather than guessed from the data, so numeric-looking identifiers (e.g. "007") are never silently coerced.

Value

A study object: ⁠list(datasets = <named list of domain -> list(data, meta, label)>, define, ct = NULL, standard = list(product, version))⁠. define is the parsed Define-XML if one was found in path and the xml2 package is installed, and NULL otherwise; ct is always NULL. Each data is a data.table::data.table(); each meta is a data.table with columns variable, label, type; label is the dataset's own label (e.g. "Adverse Events"), or NA if unavailable. standard is the study's declared standard/version (e.g. list(product = "SDTMIG", version = "3-4")), read from a CORE test case's .env file or a USDM document, and both NA for a folder of datasets, which does not declare one.

Examples

dir <- tempfile("coreval_study_")
dir.create(dir)
haven::write_xpt(data.frame(USUBJID = c("1", "2"), AGE = c(30, 65)), file.path(dir, "dm.xpt"))
study <- read_study(dir)
study$datasets$DM$data
unlink(dir, recursive = TRUE)

Description

The short form of print.coreval_result(), for when you have run a check inside a script, or just want to know whether the last fix helped.

Usage

## S3 method for class 'coreval_result'
summary(object, ...)

Arguments

Value

A one-row data.table::data.table(), invisibly, with the counts it printed - so it can be logged or compared.

Examples

ae <- data.frame(
  STUDYID = "S1", DOMAIN = "AE", USUBJID = c("01", "01"),
  AESEQ = c(1, 2), AETERM = c("Headache", "Rash"),
  AESTDTC = c("2024-01-10", "2024-02-30")
)
summary(check_dataset(ae))

Description

Saves the result of check_study() to CSV or Excel, so findings can be shared with people who don't use R, tracked in a spreadsheet, or attached to a data-review document.

Usage

write_findings(result, path, tracking = TRUE)

Arguments

Details

Both tables are always written, never just the findings. A short findings table can mean clean data, or it can mean many rules were skipped, and those two situations look identical if the skipped table is dropped:

• Excel (.xlsx) - one workbook with a sheet per table: findings, skipped, about, and truncated when any rule matched more records than were kept.

• CSV (.csv) - one file per table, since CSV has no notion of sheets. Findings go to path; the others go to sibling files with a suffix before the extension, so issues.csv gives issues_skipped.csv and issues_about.csv.

An existing file at path, or at a sibling path, is replaced.

In CSV files, a text value that begins with =, +, - or @ and is not a plain number is written with a leading ⁠'⁠. Findings quote the submission data, and a spreadsheet program opening the CSV would otherwise run such a value as a formula. Excel files store every value as text and need no such change. CSV files are written as UTF-8 with a byte order mark, which Excel needs to show non-English text correctly.

Excel output needs the writexl package. It is a Suggests, so if it isn't installed you get a clear message telling you to install it or use .csv instead, rather than a failure part-way through writing.

Value

The paths actually written, invisibly. One element for Excel (a single workbook). For CSV, one path per file written: the findings, plus siblings for skipped and about, plus one for truncated when any rule flagged more records than were kept.

Columns for tracking

Three empty columns are added to the findings - Status, Owner and Notes - for you to fill in by hand once the file is open. They exist so a finding you have looked at and decided not to act on ("expected, see protocol deviation log") can be recorded next to the finding itself, rather than in a separate document nobody reads.

Examples

dir <- tempfile("coreval_study_")
dir.create(dir)
haven::write_xpt(data.frame(USUBJID = c("1", "2"), AGE = c(30, 65)), file.path(dir, "dm.xpt"))
study <- read_study(dir)
result <- check_study(study)

out <- file.path(dir, "findings.csv")
written <- write_findings(result, out)
basename(written)

unlink(dir, recursive = TRUE)