Package {DDIwR}

Title:	DDI with R
Version:	0.23
URL:	https://github.com/dusadrian/DDIwR
BugReports:	https://github.com/dusadrian/DDIwR/issues
Description:	Useful functions for various DDI (Data Documentation Initiative) related inputs and outputs. Converts data files to and from DDI, SPSS, Stata, SAS, R and Excel, including user declared missing values.
License:	GPL (≥ 3)
Depends:	R (≥ 4.1.0)
Imports:	admisc (> 0.36), base64enc, declared (> 0.25), digest, tools, xml2, readxl, writexl
Language:	en-US
Encoding:	UTF-8
NeedsCompilation:	yes
Packaged:	2026-11-08 19:55:43 UTC; dusadrian
Author:	Adrian Dusa [aut, cre, cph]
Maintainer:	Adrian Dusa <dusa.adrian@unibuc.ro>
Repository:	CRAN
Date/Publication:	2026-11-08 20:10:02 UTC

Useful functions for various DDI (Data Documentation Initiative) related outputs.

Description

This package provides various functions to read DDI based metadata documentation and write dedicated setup files for R, SPSS, Stata and SAS to read an associated .csv file containing the raw data, apply labels for variables and values and also deal with the treatment of missing values.

It can also generate a DDI metadata file out of an R information object, which can be used to export directly to the standard statistical packages files (such as SPSS, Stata and SAS, or even Excel). For R, the default object to store data and metadata is a data.frame, and labelled data are automatically coerced to class declared.

The research leading to the initial functions in this package has received funding from the European Union's Seventh Framework Program (FP7/2007-2013) under grant agreement no. 262608 (DwB - Data without Boundaries)

Details

Author(s)

Adrian Dusa
Department of Sociology
University of Bucharest
dusa.adrian@unibuc.ro

Add/remove/change one or more children or attributes from a DDI Codebook attribute.

Description

addChildren() adds one or more children to a standard DDI Codebook element (see makeElement), anyChildren() checks if an element has any children at all, hasChildren() checks if the element has specific children, indexChildren() returns the positions of the children among all containing children, and getChildren() extracts them. For attributes and content, there are dedicated functions to ⁠add*()⁠, ⁠remove*()⁠ and ⁠change*()⁠.

Usage

addChildren(children, to, overwrite = TRUE, ...)

anyChildren(element)

getChildren(xpath, from, ...)

hasChildren(element, name)

indexChildren(element, name)

removeChildren(name, from, overwrite = TRUE, ...)

addContent(content, to, overwrite = TRUE)

makePath(xpath, from, overwrite = TRUE, ...)

moveChild(xpath, from, to, overwrite = TRUE, ...)

replaceChild(xpath, with, overwrite = TRUE, ...)

changeContent(content, to, overwrite = TRUE)

removeContent(from, overwrite = TRUE)

addAttributes(attrs, to, overwrite = TRUE)

anyAttributes(element)

changeAttributes(attrs, from, overwrite = TRUE)

hasAttributes(element, name)

removeAttributes(name, from, overwrite = TRUE)

Arguments

Details

Although an XML list generally allows for multiple contents, sometimes spread between the children elements, it is preferable to maintain a single content (eventually separated with carriage return characters for separate lines). XPath resolution accepts indexed segments using ⁠[n]⁠. When an index is missing, the first matching element is selected.

Arguments are unique, and can be changed by simply referring to their names.

Elements can be repeated. For example, dataDscr contains one var element per dataset variable. When multiple var elements exist, referring only to the name is ambiguous. Use indexed xpaths like var[3] to target a specific instance, or use indexChildren() to list all positions for iteration.

If more than one children, they should be grouped into a list. Functions addContent, changeContent, removeContent, addAttributes, changeAttributes, and removeAttributes accept either a standard DDI element or a character xpath. When an xpath is provided, the target element is resolved and replaced in the root element. Child occurrence limits and choices are evaluated in the immediate parent. Required children may be added later while building an element; use testValid() to check completeness. Sequence slots are ordered according to the schema, while insertion order within repeated choices is preserved.

Value

An invisible standard DDI element. Functions ⁠any*()⁠ and ⁠has*()⁠ return a logical (vector).

Author(s)

Adrian Dusa

Parallel variable analysis

Description

Native worker control for variable summaries and metadata format inference. The serial and parallel paths use the same calculation routines.

Details

Set options(DDIwR.variable_threads = 1L) to run variable analysis serially. A positive whole number up to 256 requests a worker limit, bounded by the available processors and the number of variables. The calling R thread counts toward this limit. 0L, or an unset option, selects automatic execution: at most four workers for summaries and two for format inference, with serial execution below 10,000 input values. These are conservative defaults; an explicit positive limit bypasses the small-input threshold.

This option applies to unweighted variable summaries and format inference. It does not change the separate DDIwR.readstat_threads input-reader option. Invalid values produce an error before variable analysis starts.

The C metadata collector with include_formats = FALSE stays on the calling R thread. It reads variable attributes, without scanning observations. Its workload depends on the number of columns and metadata materialized (for example, factor levels), not the number of rows. Format inference additionally scans values, so its workload depends on both column count and row count. The 10,000-value threshold applies to value scans, not metadata-only sweeps. The R wrapper collectRMetadata() also cleans labels and, by default, infers variable types by examining values. Set both infer_type = FALSE and include_formats = FALSE when requesting only existing metadata from it.

Workers use plain C data and do not call the R API. Results are assembled by the calling R thread. If workers cannot be started, unfinished jobs are completed by the calling thread. Temporary-memory allocation failure during summary calculation produces an error instead of an incomplete result.

Stock WebR uses the serial native path. Running the shared calculation core in separate browser workers requires application-side orchestration; this R option does not start browser workers.

See Also

collectRMetadata(), collectMetadata()

DDIwR internal functions

Description

Functions to be used internally, only by developers and contributors.

ascii: Convert accented unicode characters to pure ascii

changeXMLang: Remove the xmlang attribute from all elements.

checkArgument: Check function arguments

checkDots: Check the three dots ... argument. If the argument is not supplied via dots, returns a default

checkElement: Check if an element is a DDI Codebook element

checkExisting: Check if a certain (sub)element exists in a DDI Codebook.

checkType: Determine the variable type: categorical, numerical or mixed

checkXMList: Determine if an XML list is a DDI Codebook

cleanup: Rectify texts read from a metadata object

coerceDDI: Recursive coerce an element to a DDI class

collectMetadata: Collect metadata from a file or a dataframe object

collectRMetadata: Collect metadata from a dataframe object

extractData: Extract data from an DDI Codebook XML document or list.

formatExample: Format an example from the DDI Codebook specification

generateID: Generate simple, custom unique ID codes

getDateTime: Current date and time

getDelimiter: Guess the column delimiter from a text file

getDNS: Extracts the Default Name Space from an XML object

getEnter: Get the carriage return code from the current Operating System

getFiles: Get information about the files in a given directory

getFormat: Use the vendor list format, then the legacy attribute, then infer the SPSS / Stata format. A present NULL list field suppresses legacy fallback.

getHashes: Compute hashes of XML nodes

canonicalVariableMetadata: Canonicalize variable metadata for hashing

hashVariableMetadata: Hash canonical variable metadata

getMetadataHashes: Compute hashes from metadata lists

getXMLMetadataInfo: Extract and hash variable metadata from XML nodes

getValues: Extract values, labels and missing values from a var element

getXML: Read the DDI XML file, testing if it can be loaded.

hasLabels: Check if a dataset has (declared) labels

hasMissingLabels: Check if variables have missing labels

makeLabelled: Coerce variables to declared objects

missingValuesSPSS: Prepares the missing values for the SPSS export syntax.

prespace: Prepend a text with a certain number of space characters.

removeExtra: Removes extra information from a DDI Codebook element

repeatSpace: Allows indentation of XML or HTML files

replaceChars: Replace certain characters, in preparation for XML export

replaceTicks: Recode all tick characters with a single quote.

splitrows: Split the written rows in the setup file.

treatPath: Determine which specific type of files are present in a certain directory.

writeMetadata: Utility function to write the metadata part in the setup file.

XMLtoRmetadata: Extract metadata from a single XML variable

import_excel: Import from an Excel file (containing metadata)

makeNotes: (deprecated) use makeDataNotes() instead.

getMetadata: (deprecated) use getCodebook() instead.

exportDDI: (deprecated) use exportCodebook() instead.

writeRlist: Write an .R file containing a metadata specific list.

Usage

ascii(x)

changeXMLang(x, remove = FALSE)

checkArgument(argument, default, length = 1, ...)

checkDots(dotsvalue, default, length = 1)

checkElement(x)

checkExisting(xpath, inside, attribute = NULL)

checkType(x, labels = NULL, na_values = NULL, na_range = NULL)

checkXMList(xmlist)

cleanup(x, cdata = TRUE)

coerceDDI(element, name = NULL)

collectMetadata(from, ..., session = NULL, revision = NULL)

collectRMetadata(from, infer_type = TRUE, include_formats = TRUE, ...)

extractData(xml)

formatExample(xml_node, level = 0, indent = 2, output = NULL, ...)

generateID(x, nchars = 16)

getDateTime()

getDelimiter(x)

getDNS(xml)

getEnter(OS)

getFiles(path = ".", type = "*", currdir)

getFormat(x, type = c("SPSS", "Stata"), ...)

getHashes(nodes)

canonicalVariableMetadata(metadata)

hashVariableMetadata(metadata)

getMetadataHashes(metadata)

getXMLMetadataInfo(xmlvars, dns, language = NULL)

getValues(variable)

getXML(path, encoding = "UTF-8")

hasLabels(x)

hasMissingLabels(variables)

makeLabelled(x, variables, declared = TRUE)

missingValuesSPSS(variables, range = FALSE, numvars = TRUE)

prespace(text, indent = NULL)

removeExtra(element)

repeatSpace(times, indent)

replaceChars(x)

replaceTicks(x)

splitrows(x, enter, y = 80, spacerep = "")

treatPath(path, type = "*", single = FALSE, check = TRUE)

writeMetadata(variables, OS = "", indent = 4)

XMLtoRmetadata(xmlvar, dns, language = NULL)

import_excel(from, dots)

makeNotes(data)

getEnv()

getMetadata(...)

exportDDI(...)

writeRlist(variables, OS = "windows", indent = 4, dirpath = "", filename = "")

Arguments

Value

changeXMLang: A modified codeBook element.

checkElement: Boolean.

checkExisting: Boolean.

checkType: A character scalar

cleanup: A character vector

coerceDDI: A standard element of class DDI

collectMetadata: a standard DDI Codebook element dataDscr, containing variable level metadata information

collectRMetadata: an R list containing variable level metadata information

extractData: An R data frame, if existing, or NULL

generateID: Character vector

getDateTime: Character vector

getDelimiter: Character scalar

getDNS: Character scalar

getEnter: Character scalar

getFiles: A list with four components: the complete path, the files, the file names and the file extensions

getFormat: Character scalar

getHashes: Character vector

canonicalVariableMetadata: A normalized list

hashVariableMetadata: Character scalar

getMetadataHashes: Character vector

getXMLMetadataInfo: A list with metadata and hashes

getValues: A list with two components: labels and na_values

getXML: An XML document

hasLabels: Boolean

hasMissingLabels: Boolean vector

makeLabelled: A modified data frame.

missingValuesSPSS: A vector of missing values representation.

prespace: A modified text.

removeExtra: A modified element.

repeatSpace: Character spaces

replaceChars: Character vector

replaceTicks: A recoded string.

splitrows: A character vector.

treatPath: A list with four components: the complete path, the files, the file names and the file extensions

XMLtoRmetadata: An R list containing metadata

import_excel: An R data frame

Build a dictionary of missing-value recodes

Description

Build a dataset-level dictionary of missing values and their recoded targets for internal SPSS-style normalization or export-oriented Stata/SAS mapping.

Usage

buildDictionary(dataset, to = c("SPSS", "Stata", "SAS"), start = -91)

Arguments

Value

A data frame with columns such as label, old, new, count, and n_variables.

Clear statistical variable formats and widths

Description

Removes format or width metadata from a vector, or from every column of a data frame, across the supported statistical vendors.

Usage

clearFormats(x)

clearWidths(x)

Arguments

Details

clearFormats() removes format.spss, format.stata and format.sas, together with the format field in spss_metadata, stata_metadata and sas_metadata.

clearWidths() removes the existing width and display_width attributes, the width and display_width fields in spss_metadata, and the width fields in stata_metadata and sas_metadata. The existing width attribute is shared by the writers, including Stata string storage. Stata's type field is retained.

Both helpers remove matching list fields even when their value is NULL. Clearing the corresponding existing attributes at the same time prevents writer fallback from restoring a cleared format or width. Subsequent exports use the writer's defaults, including formats inferred from temporal classes and widths sufficient for string values.

Other metadata is retained, including labels, missing-value definitions, temporal classes and units, SAS informats, SPSS measurement and alignment, and custom attributes. A vendor list is removed when clearing its last field; otherwise its remaining fields, including unrelated NULL fields, are preserved. Existing empty lists are left unchanged.

For data frames, only column attributes are changed; dataset attributes are retained. List columns are treated as individual vectors without traversing their contents. Malformed vendor lists examined by the helper cause an error. Inputs are not modified; assign the returned object to keep the changes.

Value

An object with the same values, class and structure as x, with the selected column metadata removed.

See Also

convert(), inspectFile()

Examples

x <- structure(c(1, 2), format.spss = "F12.3", width = 8L)
attr(x, "spss_metadata") <- list(format = "F16.4", measure = "scale")
clearFormats(x)
clearWidths(x)

Converts a dataset from one statistical software to another

Description

This function converts (or transfers) between R, Stata, SPSS, SAS, Excel and DDI XML files. It uses the DDI standard as an exchange platform and facilitates a consistent conversion of missing values. Statistical files are read and written through ReadStat directly, without the haven package.

Usage

convert(
  from,
  to = NULL,
  declared = TRUE,
  chartonum = FALSE,
  recode = TRUE,
  encoding = "UTF-8",
  csv = NULL,
  n_max = -1L,
  skip = 0L,
  ...
)

Arguments

Details

When the argument to specifies a certain statistical package ("R", "Stata", "SPSS", "SAS", "XPT") or "Excel", the name of the destination file will be identical to the one in the argument from, with an automatically added software specific extension. to = "SAS" retains the XPT destination. Supply an explicit .sas7bdat path to select native SAS7BDAT output.

SPSS portable file (with the extension ".por") can only be read, but not written.

SPSS exports default to byte compression for .sav destinations and ZSAV compression for .zsav destinations. Supply compress = "none", "byte" or "zsav" through ... to override that default. compress = FALSE selects no compression and compress = TRUE selects ZSAV compression.

SAS transport exports (.xpt or to = "SAS") accept data frames without labels. A companion SAS setup script is generated only when the data has variable or value labels.

SPSS system files (.sav and .zsav) preserve custom dataset and variable attributes. They are stored in the R attribute spss.attributes on the data frame and on each column, as a named list of character vectors. For example, attr(data, "spss.attributes") <- list(source = "Archive") and attr(data$answer, "spss.attributes") <- list(foo = "bar") are written as SPSS dataset and variable attributes, respectively. A character vector with several elements represents an attribute array; a single element represents a scalar. Custom names such as label remain separate from standard R metadata. Names must be valid SPSS attribute names of at most 64 UTF-8 bytes, unique ignoring case within their scope. Values must be non-missing strings without line feeds, which the SPSS attribute format cannot represent.

Stata dataset and variable characteristics are preserved in .dta files through the R attribute stata.characteristics on the data frame and each column. Use a named list of single, non-missing strings, for example attr(data, "stata.characteristics") <- list(Source = "Archive") and attr(data$answer, "stata.characteristics") <- list(Foo = "bar"). Characteristic names are case sensitive and may contain at most 32 characters. Values may contain line feeds and trailing spaces, and may use at most 67783 bytes in the target encoding (67784 including the terminating zero byte). Stata 14 and later use UTF-8. Earlier versions write characteristic values in Windows-1252 and require ASCII characteristic names; unrepresentable values are rejected. When importing these older files with convert(), specify encoding = "windows-1252" (or their actual source encoding). Dataset and variable note characteristics, including note0, are retained. Raw dataset note characteristics take precedence over the legacy R notes attribute when writing, preserving note numbering and contents. If no raw note characteristics are present, dataset notes are written as Stata note characteristics.

Import to R and conversion to RDS retain the formats, storage widths, display widths, temporal classes and units, and custom SPSS/Stata metadata returned by the readers, including during declared conversion and missing recoding. Dataset labels and notes are retained in R. Character-to-numeric recoding removes obsolete string formats and storage widths. Preservation in exported statistical files depends on the destination writer's support.

SPSS exports and the native SAS7BDAT writer preserve the data frame's label attribute as the dataset label. When exporting to SPSS, label in ... overrides that attribute: convert(data, "data.sav", label = "Survey"). An explicit label = NULL or label = "" clears the exported dataset label; omitting the argument retains it. Variable labels and custom attributes named label are separate. Dataset labels must be single, non-missing character strings of at most 64 UTF-8 bytes for SPSS or 256 bytes for native SAS7BDAT, or NULL. Invalid labels cause an error before opening the destination file. Trailing padding spaces are removed on import. Export does not modify the input object's label.

Optional spss_metadata, stata_metadata and sas_metadata attributes group format-specific metadata in ordinary named R lists on data frames or columns. These are DDIwR's metadata containers. Field names must be nonempty and unique. Statistical file readers store formats, storage widths, display widths and dataset notes only in these lists. Shared attributes such as label, labels, na_values and na_range remain separate. Edit the list fields after import; legacy attributes are accepted as writer fallbacks for older R objects but are not emitted by readers.

Writers use explicit arguments first, then fields in the destination vendor's list, then existing attributes, then their usual defaults. A missing list field falls back to the existing attribute; a present NULL field clears it and uses the writer default. For example, attr(data$answer, "spss_metadata") <- list(format = "F12.3") overrides format.spss, while list(format = NULL) clears it. Other vendors' lists are not interpreted. Input objects are not modified. Use vendorMetadata() to read or replace list fields without editing attributes. Use clearFormats() or clearWidths() to remove the corresponding column metadata from both vendor lists and existing attributes, preventing legacy fallback from restoring cleared fields.

Supported column fields are format for all three vendors, width for all three vendors, and display_width, measure and alignment for SPSS. SPSS measurement levels are "nominal", "ordinal" and "scale"; alignments are "left", "right" and "center". SAS also supports informat. Formats and informats are single, non-missing, nonempty strings; widths are nonnegative whole numbers up to R's integer maximum. String storage is enlarged when needed to fit the values. Numeric storage width is fixed at eight bytes in SAV output. Numeric SAS7BDAT and XPT widths must be 3 through 8 bytes, or 0 for the eight-byte default. Native SAS7BDAT output discards the least significant bytes of the stored double, which can change fractions and large integers. Date/time values are shortened after conversion to SAS units. Use eight bytes to retain full precision. Numeric SAS7BDAT widths in the existing width attribute follow the same rules. Invalid widths cause an error before opening the destination.

Stata column type selects "byte", "int", "long", "float", "double" or "strL". Numeric storage must represent all exported values exactly, including converted date/time units; unsafe choices cause an error. Clear type to restore automatic storage selection after editing values. "strL" requires a character column and Stata 13 or later. Readers retain numeric storage types and strL in stata_metadata. Fixed Stata string width records the on-disk byte capacity, excluding the buffer terminator.

Dataset notes are supported for SPSS and Stata as character vectors without missing values. SPSS notes allow at most 80 UTF-8 bytes per entry, including empty entries; trailing padding spaces are removed on import. Stata list notes override both legacy notes and raw dataset note characteristics. Unchanged imported notes retain their original raw numbering; other characteristics remain intact. Dataset version uses Stata release numbers 8 through 15, or 5 and 8 for SAS XPT. On import, shared Stata file formats map to the earliest supported release that writes them (8, 10, 12, 13, 14 or 15). Without metadata, convert() defaults to Stata 14 or XPT 5; version = NULL explicitly selects that default. SAS dataset table_name is supported for SAS7BDAT and XPT, and supplies the default for the XPT writer's name argument.

Dataset created and modified timestamps are read as POSIXct values displayed in UTC. Fields are included only when the format provides a timestamp that the reader can parse. Blank or unavailable timestamps remain absent through conversion, recoding and RDS storage; the Unix epoch (zero) is a valid timestamp and is not treated as missing. SPSS and Stata imports expose their single header timestamp as created, without a modified field. created can be written for all three vendors, and sas_metadata$modified can be written to SAS7BDAT and XPT versions 5 and 8. Each writable timestamp must be one finite POSIXct value with whole-second precision. An absent or NULL modified uses the creation timestamp; setting only modified leaves creation at the writer's current-time default. The current-time default also applies when exporting without created. Local time is used for file headers without timezone information; Stata timestamps have minute precision. SPSS creation years must be 1970 through 2069 and both XPT timestamps must use years 1960 through 2059 because their headers use two-digit years. XPT imports use the dataset member's timestamps, falling back to the corresponding library timestamps when the member fields are blank. Creation and modification are resolved independently; one does not substitute for the other. SAS7BDAT stores separate UTC offsets for the two timestamps, preserving instants across timezone changes. SPSS and Stata headers have no separate modification timestamp: spss_metadata$modified and stata_metadata$modified remain preserved in R and RDS but are ignored on export, leaving the creation timestamp unchanged.

SPSS multiple-response definitions are read and written through dataset spss_metadata$mr_sets, a list named by set name. Each entry contains type, label, is_dichotomy, counted_value, counted_string, variables and label_from_var_label. Counted fields apply to dichotomies; counted_string retains the source token, including string values. Variable references use long variable names; exports translate them to the file's short names. Definitions are retained in R and RDS and written in SAV and ZSAV files.

To create a set, supply type ("C" for categories, "D" for dichotomies labelled by variables, or "E" for dichotomies labelled by counted values) and at least two distinct, existing variables, all numeric or all string. Set names must begin with $, follow SPSS naming rules, fit in 64 UTF-8 bytes, and be unique ignoring case. For example, this defines a numeric dichotomy set:

attr(data, "spss_metadata") <- list(mr_sets = list(
    "$choices" = list(type = "D", variables = c("first", "second"), counted_value = 1)
))

Optional label defaults to "" and is limited to 256 UTF-8 bytes. label_from_var_label = TRUE is allowed only for type "E" with an empty label. is_dichotomy, when supplied, must agree with type.

For dichotomies, counted_string takes precedence over counted_value. Numeric sets require an integer token or a finite whole-number counted_value; string sets require counted_string, which must fit the narrowest exported member. Category sets cannot specify either counted field. Trailing padding spaces are removed from counted strings; imported labels also lose trailing padding spaces. Labels and counted strings cannot contain line breaks. Unknown fields, invalid definitions and missing member variables cause an error before opening the destination. NULL or empty mr_sets writes no definitions. Files group types "C" and "D" before "E", preserving relative set order within each group.

All list fields, including unsupported ones, are retained during conversion to R or RDS and missing-value recoding. Character-to-numeric recoding removes list fields describing string storage (format, width, SAS informat and Stata type). Export warns about non-NULL destination-vendor fields the writer cannot honor, apart from the read-only dataset modified field for SPSS and Stata. These lists are separate from custom spss.attributes and stata.characteristics. Malformed lists and supported fields with invalid types or shapes cause an error before the destination file is opened. The native writers also enforce their format-specific restrictions.

Stata export converts R Date columns to days since 1960-01-01 and POSIXct columns to milliseconds since that date. Integer storage is used only when the converted values fit its range and precision. System and extended missing values are preserved separately from the date/time values.

The argument to can also be specified as a path to a specific file, in which case the software package is determined from its file extension. Home-directory paths beginning with ~ are supported. DDI exports include the required study description with generic defaults. Supply titl, IDNo, agency, distrbtr, URI and abstract through ... to describe the actual study. XML exports are validated against the bundled DDI Codebook 2.6 schema before writing. Invalid XML causes an error and leaves destination files unchanged. The following extentions are currently recognized: .xml for DDI, .rds for R, .dta for Stata, .sav and .zsav for SPSS, .xpt for SAS, and .xlsx for Excel.

Additional parameters can be specified via the three dots argument ..., for the destination or source format. For example, version selects the Stata release when writing a .dta file. Excel import options are passed to readxl.

The formal arguments n_max and skip are used only when importing foreign data files through the direct ReadStat readers, namely SPSS (.sav, .zsav, .por), Stata (.dta) and SAS (.sas7bdat, .xpt). They can be used to read only the first n_max rows or to import large files in batches by skipping the first skip rows. Use inspectFile() to inspect column definitions and metadata without decoding observations, including the original row count when the file's metadata provides one. Unlike inspection, n_max = 0 uses a limited data read.

SPSS user-defined missing codes are retained by default. Specify user_na = FALSE in convert() to discard them during import.

The same three dots argument is used to pass additional parameters to other functions in this package, for instance exportCodebook() when writing to a DDI file. One of its argument embed (activated by default) can be used to control embedding the data in the XML file. Deactivating it will create a CSV file in the same directory, using the same file name as the XML file.

When converting from DDI, if the dataset is not embedded in the XML file, the CSV file is expected to be found in the same directory as the DDI Codebook, and it should have the same file name as the XML file. The path to the CSV file can be provided via the csv argument. Additional formal parameters of the function read.csv() can be passed via the same three dots ... argument. Alternatively, the csv argument can also be an R data frame.

A multilingual DDI Codebook is imported in one language at a time. The DDI-specific language option is supplied via ..., for example convert("codebook.xml", language = "en"). When it is omitted, the effective xml:lang of the first variable label is used. Supplying it selects that translation throughout the variable and category labels. Language declarations inherited from a parent DDI element are honored. An unqualified label is used as a neutral fallback, but a label in a different language is not substituted.

When converting to DDI, if the argument embed is set to FALSE, users have the option to save the data in a separate CSV file (the default) or not to save the data at all, by setting csv to FALSE.

The DDI .xml file generates unique IDs for all variables, if not already present in the attributes. These IDs are useful for referencing purposes, in newer versions of the DDI Codebook.

The argument chartonum signals recoding character categorical variables, and employs the function recodeCharcat(). This only makes sense when recoding to Stata, which does not allow allocating labels for anything but integer variables.

If the argument to is left to NULL, the data is (invisibly) returned to the R enviroment. Conversion to R, either in the working space or as a data file, will result (by default) in a data frame containing declared labelled variables, as defined in package declared.

The current version reads DDI Codebook versions 1.2.2, 2.5 and 2.6, and creates version 2.6, with future versions to extend the functionality for DDI Lifecycle versions 3.x and link to the future package DDI4R for the UML model based version 4. It extends the standard DDI Codebook by offering the possibility to embed a serialized version of the R dataset into the XML file containing the Codebook, within a notes child of the fileDscr component. This type of generated codebook is unique to this package and automatically detected when converting to another statistical software. This will likely be replaced with a time insensitive text version.

Native SAS import uses ReadStat directly. SAS value-label definitions are read from a companion format catalog. Supply its path via catalog_file, or place it alongside the .sas7bdat file with the same base name and the extension .sas7bcat for automatic discovery. When a catalog does not declare an encoding, it inherits the effective data-file encoding. Use encoding and catalog_encoding to override their encodings independently; a catalog override does not affect data-file decoding.

Catalog labels for .A through .Z use numeric keys -91 through -116 in the R labels attribute. A label for ._ retains an underscore-tagged NA key, distinct from the ordinary NA key for system missing. These keys also apply to dates and timestamps and are preserved in RDS storage.

Standalone SAS7BDAT and XPT output does not contain value-label definitions. Native SAS7BDAT output supports an optional paired value-label catalog: convert(data, "data.sas7bdat", catalog_to = "data.sas7bcat"). catalog_file and catalog_encoding apply only to the input catalog; catalog_to is the output catalog path and is supported only with a .sas7bdat destination. Omitting catalog_to, or setting it to NULL, writes only the data file and leaves existing catalog files unchanged. An input catalog is never reused as an output destination implicitly. For example, this reads one catalog and writes another:

convert("input.sas7bdat", "output.sas7bdat",
    catalog_file = "input.sas7bcat", catalog_to = "output.sas7bcat")

Native SAS7BDAT output preserves system missing, ._ and existing letter missing tags using SAS's native ordinal encoding at every numeric storage width. Readers also accept the older ASCII-tagged representation. Automatically generated dictionaries assign other missing codes to unused letters. An explicit dictionary can override that mapping. Native output does not generate an additional SAS setup script. Other destinations retain their existing behavior. Numeric, integer and logical columns, including factor codes, can have exact numeric value labels, system missing labels, ._ and .A through .Z labels. Character columns accept named character vectors of exact value-label keys, including an empty key for the blank character value. Keys must be non-missing and at most 32767 UTF-8 bytes. Trailing ASCII spaces are removed from character keys to match SAS padding semantics; leading spaces and other characters remain significant. Character label text retains its leading and trailing spaces, including empty labels. Keys that become duplicates after removing padding cause an error. NA_character_ is not a catalog key; use "" for a blank key. Unused definitions and empty datasets are supported. Labelled Date, POSIXct, hms and difftime columns are supported. Ordinary label keys use the column's R units, just like its data values: days since 1970 for dates, seconds since 1970 for timestamps, and the column's declared units for durations. Export converts both rows and keys to SAS days/seconds since 1960 or time seconds. Durations are normalized to seconds on import; timestamps retain their instant and are returned in UTC. System and extended missing-label keys are categories, never shifted or scaled. Numeric and character ranges, endpoint exclusions, LOW/HIGH and OTHER rules use column sas_metadata$catalog_rules, a data frame with character fields start, end, label, hlo, sexcl and eexcl, integer default and numeric fuzz. end defaults to start, hlo to "", exclusions to "N", default to the longest label's byte width (at least one), and fuzz to zero. default and fuzz must be constant within each format. HLO accepts "", "L", "H", "LH" or "O"; exclusions accept "N" or "Y". An OTHER row has no endpoints; L/H mark unbounded ordinary numeric/character bounds. Numeric endpoints are strings containing finite SAS numbers or missing tokens ".", "._", ".A" through ".Z". Temporal endpoints use native SAS units (days/seconds since 1960 or time seconds), as in PROC FORMAT/CNTLIN, rather than R date/time units. Character endpoints retain leading spaces and drop trailing ASCII padding. Endpoints and labels allow up to 32767 UTF-8 bytes, subject to native record/page capacity. Overlapping or empty intervals, multiple OTHER rows and unsupported rule fields are rejected before publication. Rule tables take precedence over labels; a NULL table restores exact labels. Imported ranges are retained as rules, never misrepresented as point labels; exact entries remain available in labels. Native default widths and numeric fuzz are retained. Rules are written only with a paired catalog. Multilabel, PICTURE, nested formats and executable expressions are not supported. Catalog output uses the native 64-bit layout, including SAS directory, index and format records. SAS catalogs depend on host layout; compatibility is checked with SAS 9.4M9 on Linux x86-64 in UTF-8.

A custom label format cannot also identify a temporal type. Paired temporal export therefore supplies an absent sas_metadata$informat as DATE9, DATETIME25.6 or TIME20.6. An existing compatible informat is retained; an explicitly NULL, unrecognized or conflicting informat causes an error. On SAS import, a recognized temporal display format takes precedence; otherwise a recognized temporal informat determines the date/time class and unit conversion, even without a catalog. Ordinary catalog keys follow the same conversion; missing-code surrogates remain unchanged.

A labelled column's SAS format reference must name a user-defined format. Numeric names allow up to 32 ASCII letters, digits and underscores, starting and ending with a letter or underscore. Character format names use a $ prefix followed by up to 31 such characters. The prefix must match the column's type; numeric and character names are distinct. Display width is preserved separately. Decimal places apply only to numeric formats. Common built-in display formats are rejected; use clearFormats() before export to request generated names. Missing or explicitly cleared references get unique DDI...F names for numeric columns or ⁠$DDI...F⁠ for character columns. Columns can share a format only when their exported keys and label texts agree. Label texts must be non-missing and at most 32767 UTF-8 bytes each. Duplicate keys, conflicting definitions and reduced numeric widths that cannot retain a label key exactly cause an error.

Catalog imports retain a sas_metadata$label_tags character vector aligned with the value labels: "" for ordinary keys, "." for system missing, "_" or an uppercase letter for tagged missing. This distinguishes label definitions even when no observations use them, without treating ordinary negative values as missing. Paired exports use these tags and the same missing-code dictionary as the data writer; mismatched tag-vector lengths and stale definitions cause an error. label_tags applies only to numeric label definitions and must be absent or NULL for character catalogs. Standalone SAS7BDAT and XPT exports retain their existing behavior and do not write these label definitions.

Paired export writes both files to temporary siblings before replacing the destinations. Publication retains backups and attempts to restore both originals if either rename fails. The two renames are not a single atomic operation. Input objects are not modified. SAS value-label catalogs can also be supplied as setup commands; see setupfile().

The argument recode controls how missing values are treated. If the input file has SPSS like numeric codes, they will be recoded to extended (a-z) missing types when converting to Stata or SAS. If the input has Stata like extended codes, they will be recoded to SPSS like numeric codes.

Missing values are harmonized across the entire dataset by default when exporting to Stata or SAS. This automatically builds a dataset-level missing value dictionary when possible. Use harmonize = FALSE via the three dots argument to deactivate this behavior. The alias harmonise = FALSE is also accepted. If the dataset-level dictionary exceeds 26 codes, conversion falls back to separate dictionaries for each variable. A variable with more than 26 distinct numeric missing codes cannot be represented this way and export fails. SAS's additional ._ tag is preserved as an NA with the name "_" in the column's na_index attribute, for numeric columns, dates and timestamps. It does not consume a letter-tag dictionary entry; the A-Z tags retain their existing numeric codes from -91 to -116.

The character encoding is passed to the direct ReadStat readers that accept an encoding override. Set it to NULL to use the file's encoding information and the reader's fallback.

Converting to SPSS works with numerical and character labelled vectors, with or without labels. The native date/time adapters write SPSS dates and timestamps as seconds since 1582-10-14, SAS dates as days since 1960-01-01, and SAS timestamps as seconds since 1960-01-01. Integer-backed R temporal columns use double storage when exporting to SPSS or SAS to avoid overflow. SPSS user-missing codes and ranges remain separate from date/time values; they are retained when importing with user_na = TRUE and discarded with user_na = FALSE.

Value

An invisible R data frame, when the argument to is NULL.

Author(s)

Adrian Dusa

References

DDI - Data Documentation Initiative, see the DDI Alliance website.

See Also

setupfile, getCodebook, declared

Examples

## Not run: 
# Assuming an SPSS file called test.sav is located in the working directory
# The following command imports the file into the R environment:
test <- convert("test.sav")

# The following command will extract the metadata in a DDI Codebook and
# produce a test.xml file in the same directory
convert("test.sav", to = "DDI")

# The data may be saved separately from the DDI file, using:
convert("test.sav", to = "DDI", embed = FALSE)

# Format-specific options are supplied through the three dots. For example,
# import the English labels from a multilingual DDI Codebook using:
test <- convert("test.xml", language = "en")

# To produce a Stata file:
convert("test.sav", to = "Stata")

# To produce an R file:
convert("test.sav", to = "R")

# To produce an Excel file:
convert("test.sav", to = "Excel")

## End(Not run)

Export a DDI Codebook to an XML file.

Description

Create a DDI Codebook version 2.6, XML file structure.

Usage

exportCodebook(
  codeBook,
  to = "",
  OS = "",
  indent = 2,
  ...,
  session = NULL,
  revision = NULL
)

Arguments

Details

#' The information object is a codeBook DDI element having at least two main children:

• fileDscr, with the data provided as a sub-component named datafile

• dataDscr, having as many components as the number of variables in the (meta)data.

For the moment, only DDI codebook version 2.6 is exported, and DDI Lifecycle is planned for future releases.

A small number of required DDI specific elements and attributes have generic default values, if not otherwise specified in the codeBook list object. For the current version, these are: monolang, xmlang, IDNo, titl, agency, URI (for the holdings element), distrbtr, abstract and level (for the otherMat element).

The finished XML is always validated against the bundled, pinned DDI Codebook 2.6 schema and its local dependencies before writing. Invalid or incomplete documents, or unavailable schemas, cause an error. Validation failure leaves the destination and any companion CSV unchanged, and writes nothing to an output connection. No network access is needed for validation. Most of these arguments help create the mandatory element stdyDscr, which cannot be harvested from the dataset. If this element is not already present, providing any of these arguments via the three dots ... gate, signal an automatic creation and inclusion with the values provided.

Argument xmlang expects a two letter ISO country coding, for instance "en" to indicate English, or "ro" to indicate Romanian etc. The original DDI Codebook attribute is called xml:lang, which for obvious reasons had to be renamed into this R function.

A logical argument monolang signal if the document is monolingual, in which case the attribute xmlang is placed a single time for the entire document in the codeBook element. For multilingual documents, xmlang should be placed in the attributes of various other (child) elements, for instance abstract, or the study title, name of the distributing institution, variable labels etc.

The argument OS can be either:
"windows" (default), or "Windows", "Win", "win",
"MacOS", "Darwin", "Apple", "Mac", "mac",
"Linux", "linux".

The end of line separator changes only when the target OS is different from the running OS.

The argument indent controls how many spaces will be used in the XML file, to indent the different sub-elements. Formatting and target line endings also apply when writing to a connection.

Value

An XML file containing a DDI version 2.6 metadata.

Author(s)

Adrian Dusa

See Also

https://ddialliance.org/hubfs/Specification/DDI-Codebook/2.5/XMLSchema/field_level_documentation.html

Examples

## Not run: 
exportCodebook(codeBook, to = "codebook.xml")

# using a namespace
exportCodebook(codeBook, to = "codebook.xml", xmlns = "ddi")

## End(Not run)

Extract metadata information

Description

Extract a list containing the variable labels, value labels and any available information about missing values.

Usage

getCodebook(from = NULL, encoding = "auto", ignore = NULL, ...)

Arguments

Details

This function extracts the metadata from an R dataset, or alternatively it can read an XML file containing a DDI Codebook version 1.2.2, 2.5 or 2.6, or an SPSS or Stata file and returns a list containing the variable labels, value labels and information about the missing values.

If the input is a dataset, it will extract the variable level metadata (labels, missing values etc.). From a DDI XML file, it will import all metadata elements, the most expensive being the data description.

It additionally attempts to automatically detect a type for each variable:

Apart from utf8, other encodings might be necessary when reading from SPSS or DDI XML files, for instance latin1 or windows-1252, and it also accepts bytes for multi-byte encodings. To use the one specified in the file, set encoding = NULL. The default is encoding = "auto", which tries to detect the encoding automatically.

For the moment, only DDI Codebook is supported, but DDI Lifecycle is planned to be implemented.

Value

An R list roughly equivalent to a DDI Codebook, containing all variables, their corresponding variable labels and value labels, and (if applicable) missing values if imported and found.

Author(s)

Adrian Dusa

Examples

x <- data.frame(
    A = declared(
        c(1:5, -92),
        labels = c(Good = 1, Bad = 5, NR = -92),
        na_values = -92
    ),
    C = declared(
        c(1, -91, 3:5, -92),
        labels = c(DK = -91, NR = -92),
        na_values = c(-91, -92)
    )
)

getCodebook(from = x)

Inspect statistical file metadata without importing observations

Description

Reads column definitions and dataset metadata from SPSS, Stata and SAS files without decoding observations or allocating vectors for data rows.

Usage

inspectFile(
  file,
  encoding = NULL,
  catalog_file = NULL,
  catalog_encoding = encoding
)

Arguments

Details

Supported extensions are .sav, .zsav, .por, .dta, .sas7bdat and .xpt. The file's original row count is returned when its metadata provides one, including zero for a known empty dataset. Unknown counts are NA_real_; observations are never scanned to calculate them. POR and XPT 5 do not store row counts. XPT 8 counts are returned when the observation header supplies one; blank or all-zero reserved fields mean unknown. SAS7BDAT counts exclude rows marked as deleted in the metadata.

Column definitions retain source order, ReadStat storage type and byte width. Types are "string", "int8", "int16", "int32", "float", "double" or "string_ref". A metadata list column holds each column's R attributes, including labels, missing definitions, formats, temporal classes, vendor metadata and custom attributes. Data-derived attributes such as missing-value row positions are unavailable. Dataset metadata uses the same attribute names as convert(), including label, spss_metadata, stata_metadata, sas_metadata, spss.attributes and stata.characteristics.

Metadata may occur after observations, so the reader can seek beyond data sections to obtain definitions such as Stata value labels. SAS metadata pages may also contain observation bytes; those pages are read as blocks, but observations are not decoded or decompressed. Inspection does not validate observation content. Supply catalog_file to include SAS value labels from a separate format catalog. No catalog is selected automatically.

Value

A list with numeric row_count, integer column_count, a columns data frame with name, type, width and metadata, and a named list of dataset metadata.

Examples

## Not run: 
info <- inspectFile("survey.sav")
info$row_count
info$columns
info$metadata$label

## End(Not run)

Create the catgry elements for a particular variable

Description

Utility function to create the catgry elements, as well as all necessary sub-elements (e.g. catValu, labl, varFormat) along with their associated XML attributes.

Usage

makeCategories(metadata)

Arguments

Value

A list of standard catgry DDI elements.

Author(s)

Adrian Dusa

Create a notes element for the dataset.

Description

Create the notes element to embed a serialized, gzip-ed version of the data in the fileDscr section of the codeBook.

Usage

makeDataNotes(data)

Arguments

Value

A standard notes DDI element.

Author(s)

Adrian Dusa

Make a DDI Codebook element

Description

Creates a standard DDI element.

Usage

makeElement(
  name,
  children = NULL,
  attributes = NULL,
  content = NULL,
  fill = FALSE,
  ...
)

Arguments

Details

The structure of a DDI element in R follows the usual structure of an XML node, as returned by the function as_list() from package xml2, with one additional (first) component named ".extra" to accommodate any other information that is not part of the DDI element.

In the DDI Codebook, most elements and their attributes are optional, but some are mandatory. In case of attributes, some become mandatory only if the element itself is present. The mandatory elements need to be present in the final version of the Codebook, to pass the validation against the XML schema.

By activating the argument fill, this function creates DDI elements containing all mandatory (sub)elements and (their) attributes, filled with arbitrary values that can be changed later on. Some recommended elements are also filled, as expected by the CESSDA Data Catalogue profile for DDI Codebook.

By default, the Codebook is assumed to have a single language for all elements. The argument monolang can be deactivated through the "..." gate, in which situation the appropriate elements will receive a default argument xmlang = "en". For other languages, that argument can also be provided through the "..." gate.

One such DDI Codebook element is the stdyDscr (Study Description), with the associated mandatory children, for instance title, ID number, distributor, citation, abstract etc.

The complete list of elements for which default values are added is: "IDNo", "titl", "titlStmt", "distrbtr", "distStmt", "holdings", "citation", "abstract", "stdyInfo", "stdyDscr", "prodDate", "software", "prodStmt", "docDscr" and "otherMat".

Value

A standard list element of class "DDI" with reserved component names.

Author(s)

Adrian Dusa

See Also

addChildren getChildren showDetails

Examples

stdyDscr <- makeElement("stdyDscr", fill = TRUE)

# easier to extract with:
getChildren("citation/titlStmt/titl", from = stdyDscr)

Recode character categorical variables

Description

Recodes a character categorical variables to a numerical categorical variable.

Usage

recodeCharcat(x, ...)

Arguments

Details

For this function, a categorical variable is something else than a base factor. It should be an object of class "declared" with a specific attribute called "labels" that stores the value labels.

Variable labels, display widths, custom SPSS attributes and Stata characteristics are retained. String formats and storage widths are removed when the values become numeric; subsequent exports derive numeric formats. The spss_metadata, stata_metadata and sas_metadata lists are also retained, except for their string storage fields (format, width, SAS informat and Stata type).

Value

A numeric categorical variable of the same class as the input.

Author(s)

Adrian Dusa

Examples

x <- declared(
    c(letters[1:5], -91),
    labels = c(Good = "a", Bad = "e", NR = -91),
    na_values = -91
)

recodeCharcat(x)

Consistent recoding of (extended) missing values

Description

A function to recode all missing values to either SPSS or Stata types, uniformly (re)using the same codes across all variables.

Usage

recodeMissings(
  dataset,
  to = c("SPSS", "Stata", "SAS"),
  dictionary = NULL,
  start = -91,
  ...
)

Arguments

Details

Package DDIwR uses numeric declared missing codes as its internal R representation. Recoding to "Stata" or "SAS" is therefore best viewed as an export-oriented temporary representation, not as a preferred internal storage strategy for declared vectors in R. SAS's ._ tag is retained separately as "_" in na_index when it is absent from the recoding dictionary. Columns with missing metadata alone are accepted, even without variable or value labels.

Recoding retains variable formats, widths, temporal classes and units, custom SPSS attributes, Stata characteristics, the spss_metadata, stata_metadata and sas_metadata lists, and dataset labels and notes. Labels and missing-value definitions are updated to match the recoded values. Character-to-numeric recoding clears obsolete string storage fields in these lists, as described in recodeCharcat().

When no dictionary is provided, export-oriented recoding can be performed either by scanning the entire dataset for a harmonized mapping, or by recoding each variable independently. The package now defaults to the faster per-variable strategy in export preparation. Supplying a dictionary keeps the harmonized cross-dataset behavior.

When a dictionary is not provided, it is automatically constructed from the available data and metadata, using negative numbers starting from -91 and up to 27 letters starting with "a".

If the dataset contains mixed variables with SPSS and Stata style missing values, unless otherwise specified in a dictionary it uses other codes than the existing ones.

For the SPSS type of missing values, the resulting variables are coerced to a declared labelled format.

Unlike SPSS, Stata does not allow labels for character values. Both cannot be transported from SPSS to Stata, it is either one or another. If labels are more important to preserve than original values (especially the information about the missing values), the argument chartonum replaces all character values with suitable, non-overlapping numbers and adjusts the labels accordingly.

If no labels are found in the metadata, the original values are preserved.

Value

A data frame with all missing values recoded consistently.

Author(s)

Adrian Dusa

Examples

# x <- data.frame(
#     A = declared(
#         c(1:5, -92),
#         labels = c(Good = 1, Bad = 5, NR = -92),
#         na_values = -92
#     ),
#     B = labelled(
#         c(1:5, tagged_na('a')),
#         labels = c(DK = tagged_na('a'))
#     ),
#     C = declared(
#         c(1, -91, 3:5, -92),
#         labels = c(DK = -91, NR = -92),
#         na_values = c(-91, -92)
#     )
# )

# xrec <- recodeMissings(x, to = "Stata")

# attr(xrec, "dictionary")

# Supply a dictionary to harmonize missing meanings across variables
# dictionary <- data.frame(
#     old = c(-91, -92, "a"),
#     new = c("c", "d", "c")
# )
# recodeMissings(x, to = "Stata", dictionary = dictionary)

# recodeMissings(x, to = "SPSS")

# dictionary$new <- c(-97, -98, -97)

# recodeMissings(x, to = "SPSS", dictionary = dictionary)

# recodeMissings(x, to = "SPSS", start = 991)

# recodeMissings(x, to = "SPSS", start = -8)

Search for key words

Description

Search function to return elements that contain a certain word or regular expression pattern.

Usage

searchFor(
  x,
  where = c("everywhere", "title", "description", "attributes", "examples"),
  ...
)

Arguments

Value

Character vector of DDI element names.

Author(s)

Adrian Dusa

Create setup files for SPSS, Stata, SAS and R

Description

Creates a setup file, based on a list of variable and value labels.

Usage

setupfile(
  obj,
  file = "",
  type = "all",
  csv = NULL,
  recode = TRUE,
  OS = "",
  stringnum = TRUE,
  ...
)

Arguments

Details

A codeBook object is an R list containing DDI metadata, such as variable labels and value labels. It can be created from a labelled data frame with getCodebook(). A data frame can also be passed directly to setupfile(). The generated commands have a configuration section where input and output paths must be set before running them in the target software. Validation errors do not write blank lines to standard output. Output sinks already active in the caller are retained on success and error.

When a path to a metadata directory is specified for the argument obj, then next argument file is silently ignored and all created setup files are saved in a directory called "Setup Files" that (if not already found) is created in the working directory.

The argument file expects the name of the final setup file being saved on the disk. If not specified, the name of the object provided for the obj argument will be used as a filename.

If file is specified, the argument type is automatically determined from the file's extension, otherwise when type = "all", the function produces one setup file for each supported type.

If batch processing multiple files, the function will inspect all files in the provided directory, and retain only those with the extension .R or .r or DDI versions with the extension .xml or .XML (it will subsequently generate an error if the .R files do not contain an object list, or if the .xml files do not contain a DDI structured metadata file).

If the metadata directory contains a subdirectory called "data" or "Data", it will match the name of the metadata file with the name of the .csv file (their names have to be exactly the same, regardless of their extension).

The csv argument can provide a data frame object produced by reading the .csv file, or a path to the directory where the .csv files are located. If the user doesn't provide something for this argument, the function will check the existence of a subdirectory called data in the directory where the metadata files are located.

In batch mode, the code starts with the argument delim = ",", but if the .csv file is delimited differently it will also try hard to find other delimiters that will match the variable names in the metadata file. At the initial version 0.1-0, the automatically detected delimiters include ";" and "\t".

The argument OS (case insensitive) can be either:
"Windows" (default), or "Win",
"MacOS", "Darwin", "Apple", "Mac",
"Linux".

The end of line character(s) changes only when the target OS is different from the running OS.

Stored formats in spss_metadata and stata_metadata take precedence over legacy format attributes when the input is a data frame. A present format = NULL suppresses legacy fallback and uses the inferred format.

Value

A setup file to complement the imported raw dataset.

Author(s)

Adrian Dusa

Examples

# A small dataset with variable and value labels
survey <- data.frame(
    age = declared(
        c(28, 35, 42),
        label = "Age in years"
    ),
    device = declared(
        c(1, 2, 1),
        label = "Device used",
        labels = c(Desktop = 1, Mobile = 2)
    )
)

# Use a temporary directory for the files created in this example
temp_dir <- tempdir()
csv_file <- file.path(temp_dir, "survey.csv")
admisc::export(undeclare(survey, drop = TRUE), file = csv_file)

# codeBook is an R object containing DDI metadata extracted from survey.
# It describes the variables and their labels; the observations are in the CSV.
codeBook <- getCodebook(survey)

# Create Stata commands to import the CSV and apply the metadata
# Edit the generated file's configuration paths before running it in Stata.
setupfile(codeBook, file = file.path(temp_dir, "survey.do"), csv = csv_file)

# A labelled data frame can also be supplied directly
setupfile(survey, file = file.path(temp_dir, "survey.sps"))

# The file extension selects the software: .do, .sps, .sas or .R.
# A setup file contains import commands, not the observations themselves.

## Not run: 
# Alternatively, read metadata from an existing DDI XML file
setupfile("/path/to/metadata.xml", file = "survey.do",
    csv = "/path/to/survey.csv")

# Batch processing: read metadata and CSV files from matching directories
setupfile("/path/to/metadata/directory", csv = "/path/to/csv/directory")

## End(Not run)

Describe what a DDI element is

Description

Describe what a DDI element is

Usage

showDetails(x, ...)

showDescription(x, ...)

showAttributes(x, name = NULL, ...)

globalAttributes()

showExamples(x, ...)

showRelations(x, ...)

showLineages(x, ...)

Arguments

Details

All arguments having predefined values such as "(Y | N) : N" are mandatory if the element is used

Author(s)

Adrian Dusa

Examples

showDetails("codeBook")

showAttributes("catgry")

showExamples("abstract")

showLineages("titl")

Validate a DDI element.

Description

Checks parent-specific child occurrences, sequences, choices and mandatory attributes throughout a DDI Codebook element.

Usage

testValid(element, monolang = TRUE)

Arguments

Details

Each existing instance is checked separately, including repeated and recursively nested elements. Required children are checked only when their parent exists. Repeated choices may use different alternatives. An incomplete element can be built incrementally with addChildren(); testValid() also checks the required minimum occurrences and child order.

Validation follows the curated DDI child model. It does not expand imported markup groups or validate all XML datatypes, ID references or mixed text. Use XML Schema validation on exported XML for those additional checks.

To ease the validation of the DDI Codebook XML files, the argument monolang is activated by default. This means a single attribute xmlang in the main codeBook element. For multi-language codebooks, an error is flagged if this argument is missing where appropriate.

Value

A list of class validation, with character vectors mandatory and optional. The latter contains missing required attributes of optional children; both components report validation problems, not recommendations.

Author(s)

Adrian Dusa

See Also

makeElement

Update Codebook.

Description

Update an XML file containing a DDI Codebook.

Usage

updateCodebook(xmlfile, with, ...)

Arguments

Details

This function replaces entire Codebook sections. Any such section present in the R object will replace the corresponding section from the XML document. Sections are matched as XML elements, including in compact or prefixed XML, and inserted in schema order. Repeated sections are replaced as a group. The document namespace, root attributes and untouched sections are preserved. Both inputs must have a codeBook root. Invalid root inputs are rejected before the file is written. The finished document must conform to the bundled DDI Codebook 2.6 schema. Validation is mandatory and offline; failure leaves the original file unchanged. Documents using another DDI namespace are rejected rather than silently converted to 2.6.

Author(s)

Adrian Dusa

Update the internal DDI Codebook schema object.

Description

Extract structural facts from a Codebook XSD while preserving the existing R naming conventions and curated descriptive metadata.

Usage

updateSchema(xsd = NULL, return = FALSE)

Arguments

Details

The extractor follows type inheritance, restrictions, local elements and attribute groups. Each element receives a parent-specific contentModel containing sequence/choice particles and numeric min/max occurrence bounds. PHRASE, FORM, imported markup groups and wildcards remain outside the simplified child model. Existing descriptions, examples, recommendations and deprecation flags are preserved; new records use schema documentation.

Inspect updateSchema(xsd, return = TRUE) before applying a different schema. Structural facts are refreshed, including removed/prohibited attributes. Legacy element-wide optional/repeatable flags are retained for existing records; validation uses contentModel. No source files are overwritten.

Author(s)

Adrian Dusa

Read and edit vendor-specific metadata

Description

Accesses statistical metadata without editing attributes directly. Replacement returns a modified object and preserves unrelated metadata and values.

Usage

vendorMetadata(x, vendor, field = NULL)

vendorMetadata(x, vendor, field = NULL) <- value

Arguments

Details

vendor is "SPSS", "Stata" or "SAS" (case insensitive). With no field, the getter returns the stored vendor list. With a field, it returns that field, falling back to legacy format/width/display-width/notes attributes only when the field is absent. A stored NULL suppresses that fallback.

Replacing one field with NULL stores an explicit clearing marker; it does not delete the field. Replacing the whole list with NULL removes that container, allowing legacy fallback again. Use clearFormats() or clearWidths() to remove the corresponding fields and legacy attributes together. Replacement validates list structure; field values are validated by the destination writer. Dataset and column metadata use the same interface. The function does not traverse data-frame columns: select a column explicitly to edit its metadata.

Value

The metadata list or field; replacement returns the modified object.

Examples

x <- c(1, 2)
vendorMetadata(x, "SAS", "format") <- "BEST12."
vendorMetadata(x, "SAS", "informat") <- "BEST32."
vendorMetadata(x, "SAS", "format")
vendorMetadata(x, "SAS", "format") <- NULL