| Title: | A Data Specification Format and Interface |
|---|---|
| Description: | Creates a data specification that describes the columns of a table (data.frame). Provides methods to read, write, and update the specification. Checks whether a table matches its specification. See specification.data.frame(),read.spec(), write.spec(), as.csv.spec(), respecify.character(), and %matches%.data.frame(). |
| Authors: | Tim Bergsma |
| Maintainer: | Tim Bergsma <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.9 |
| Built: | 2024-11-27 05:55:49 UTC |
| Source: | https://github.com/bergsmat/spec |
Checks whether character matches y, treating x as filepath.
## S3 method for class 'character' x %matches% y, ...## S3 method for class 'character' x %matches% y, ...
x |
character |
y |
object |
... |
passed arguments |
Other matches:
%matches%.data.frame(),
%matches%.spec(),
%matches%()
data(drug) file <- tempfile() spec <- specification(drug, tol = 3) library(csv) as.csv(drug, file) file %matches% specdata(drug) file <- tempfile() spec <- specification(drug, tol = 3) library(csv) as.csv(drug, file) file %matches% spec
Checks whether data.frame matches spec. Column names, count, and order are enforced. Encodings are enforced (all non-missing values must be valid codes). Integer and numeric ranges are enforced. Values of required are parsed and evaluated in data context: Where TRUE, the corresponding data value for column cannot be missing.
## S3 method for class 'data.frame' x %matches% y, ...## S3 method for class 'data.frame' x %matches% y, ...
x |
spec |
y |
coerced to spec (spec object or filepath for spec file). |
... |
passed arguments |
logical; TRUE if all checks above are enforceable.
Other matches:
%matches%.character(),
%matches%.spec(),
%matches%()
data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file) drug %matches% specdata(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file) drug %matches% spec
Coerces to class spec, a specification object
as.spec(x, ...)as.spec(x, ...)
x |
object |
... |
passed arguments |
Other as.spec:
as.spec.character(),
as.spec.data.frame(),
read.spec(),
write.spec()
Coerces to specification from character (length-one filepath).
## S3 method for class 'character' as.spec(x, ...)## S3 method for class 'character' as.spec(x, ...)
x |
character path to spec-formatted file |
... |
passed arguments |
spec
Other as.spec:
as.spec.data.frame(),
as.spec(),
read.spec(),
write.spec()
data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file) as.spec(file)data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file) as.spec(file)
Coerces to spec from data.frame already having basic properties.
## S3 method for class 'data.frame' as.spec(x, ...)## S3 method for class 'data.frame' as.spec(x, ...)
x |
data.frame |
... |
passed arguments |
spec
Other as.spec:
as.spec.character(),
as.spec(),
read.spec(),
write.spec()
data(drug) as.spec(specification(drug, tol = 3))data(drug) as.spec(specification(drug, tol = 3))
A fictitious dataset giving doses and pharmacometric samples for multiple subjects in an imaginary Phase * drug trial.
drugdrug
A data frame with 600 rows and 24 variables:
a comment flag, typically NA but 'C' for records that should be ignored
integer subject identifier
relative time (h)
sequence identifier to break ties when sorting
event type identifier, 0: pk sample, 1: dose
drug amount (mg)
plasma drug concentration (ng/mL)
subject identifier
nominal hour (h)
height (cm)
weight (kg)
sex, 0: female, 1: male
age (y)
dose group (mg)
prandial state, 0: fasted, 1: fed
smoker status, 0: non, 1: smoker
disease state, 0: no disease
normalized creatinine clearance (mL/min)
time since first dose (h)
time since most recent dose (h)
amount of most recent dose (mg)
missing dependent value, 0: not missing, 1: missing
predose flag, 0: record not predose, 1: record is predose
zero DV flag, 0, DV not zero, 1: DV is zero
Reads specification from file. If first line contains tab characters, assumes format is tab-delimited text. Otherwise, assumes format is comma-separated variable (csv).
read.spec(x, clean = TRUE, ...)read.spec(x, clean = TRUE, ...)
x |
character (file path) |
clean |
whether to strip balanced double quotes and outer white space from character values |
... |
passed arguments (ignored) |
spec
Other as.spec:
as.spec.character(),
as.spec.data.frame(),
as.spec(),
write.spec()
data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file) read.spec(file)data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file) read.spec(file)
Respecify specification, supplied as filepath. Updates numeric ranges. Useful if these have changed and spec no longer matches.
## S3 method for class 'character' respecify(x, data = sub("spec$", "csv", x), file = x, ...)## S3 method for class 'character' respecify(x, data = sub("spec$", "csv", x), file = x, ...)
x |
character filepath for a spec file (*.spec) |
data |
character filepath for a dataset |
file |
where to write the result (over-write source, by default) |
... |
passed arguments |
Other respecify:
respecify.spec(),
respecify()
Respecify specification. Updates numeric ranges. Useful if these have changed and spec no longer matches.
## S3 method for class 'spec' respecify(x, data, file = NULL, ...)## S3 method for class 'spec' respecify(x, data, file = NULL, ...)
x |
spec |
data |
a data.frame or path to csv file |
file |
where to write the result (default: do not write) |
... |
passed arguments |
Other respecify:
respecify.character(),
respecify()
data(drug) file <- tempfile() spec <- specification(drug,tol = 3) write.spec(spec, file = file) drug %matches% spec drug %matches% file max <- max(drug$DV,na.rm=TRUE) drug$DV[!is.na(drug$DV) & drug$DV == max] <- max + 1 drug %matches% file respecify(file, drug) drug %matches% filedata(drug) file <- tempfile() spec <- specification(drug,tol = 3) write.spec(spec, file = file) drug %matches% spec drug %matches% file max <- max(drug$DV,na.rm=TRUE) drug$DV[!is.na(drug$DV) & drug$DV == max] <- max + 1 drug %matches% file respecify(file, drug) drug %matches% file
Makes a specification for data.frame. Creates a template based on the data.frame. Uses column names for labels where columns do not have a label attribute. Factors will be encoded. numerics will be rounded to digits and like integers will be expressed as ranges in guide column. Integers and character with less than or exactly tol unique values will be encoded.
## S3 method for class 'data.frame' specification(x, tol = 10, digits = 20, ...)## S3 method for class 'data.frame' specification(x, tol = 10, digits = 20, ...)
x |
object |
tol |
integer |
digits |
integer |
... |
passed arguments |
spec data.frame with columns as follows.
Column name.
A descriptive label. Save and edit as necessary using external tool.
A guide to interpretation. NA for arbitrary character; range [low:high] for integer and numeric; an encoding e.g. //0/no//1/yes// for factor-like items ... save and edit factor labels as necessary using external tool.
For numeric ranges you can add text, such as units. E.g. if default guide is '[0:100]' you can edit to give 'mg [0:100]'. Or you can just substitute 'mg'. guidetext extracts just the character portion, and matches enforces the numeric range.
An R expression that can be coerced to logical. TRUE means item cannot be NA.
Arbitrary comment, e.g. derivation of the item given by column.
link{read.spec} write.spec respecify.character write.spec matches
Other specification:
specification.comment(),
specification.default(),
specification()
data(drug) file <- tempfile() spec <- specification(drug, tol = 3)data(drug) file <- tempfile() spec <- specification(drug, tol = 3)
Attach specifics to a data.frame, supplied as csv filepath.
## S3 method for class 'character' specify(x, file = sub("csv$", "spec", x), spec = read.spec(file), ...)## S3 method for class 'character' specify(x, file = sub("csv$", "spec", x), spec = read.spec(file), ...)
x |
character filepath for a csv file |
file |
character filepath for a matching spec file (ignored if spec provided) |
spec |
a data specification (spec) |
... |
passed arguments |
Other specify:
specify.data.frame(),
specify()
Attach specifics to a data.frame as attributes, including label and guide.
## S3 method for class 'data.frame' specify(x, spec, na.rm = TRUE, empty.rm = TRUE, ...)## S3 method for class 'data.frame' specify(x, spec, na.rm = TRUE, empty.rm = TRUE, ...)
x |
data.frame |
spec |
a data spec (or corresponding filepath) to use as source of attributes |
na.rm |
if TRUE, don't assign NA where encountered |
empty.rm |
if TRUE, don't assign empty string where encountered |
... |
passed arguments |
Other specify:
specify.character(),
specify()
data(drug) spec <- specification(drug,tol = 3) drug %matches% spec drug <- specify(drug,spec) attributes(drug$HEIGHT)data(drug) spec <- specification(drug,tol = 3) drug %matches% spec drug <- specify(drug,spec) attributes(drug$HEIGHT)
Writes specification to storage in tab-delimited format. Use as.csv() for CSV format.
write.spec(x, file, ...)write.spec(x, file, ...)
x |
spec |
file |
character filepath for storage location |
... |
passed arguments |
Other as.spec:
as.spec.character(),
as.spec.data.frame(),
as.spec(),
read.spec()
data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file)data(drug) file <- tempfile() spec <- specification(drug, tol = 3) write.spec(spec, file = file)