Package 'nesstarR'

Compare a dataset with a reference data frame

Description

Compares one dataset of a Nesstar file with the same data from a different source, for example a Stata or SPSS export. Use this function to make sure that nesstarR decodes a file correctly.

Usage

nesstar_compare(x, dataset_number, reference)

Arguments

x	A nesstar_binary object from nesstar_parse.
dataset_number	Integer dataset number.
reference	A data frame with the same rows, in the same order.

Details

The function matches the columns by name. Before the match, it changes each group of characters that are not letters or digits to _, removes _ from the start and the end, and changes the names to upper case. Thus, Srl._No. and Srl_No are the same column.

If all values in the two columns are numbers, the function compares the numbers. Thus, "010" and 10 are equal. Otherwise, it compares the values as text, without leading and trailing spaces. Empty strings and NA are equal.

Remove value labels from reference before the comparison, for example with haven::zap_labels().

Value

A data frame with one row for each column name and these columns:

column

The column name after the change.

in_nesstar, in_reference

TRUE if the column is in the source.

different_values

The number of rows with different values. NA if the column is in only one source.

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
reference <- nesstar_read_dataset(x, dataset_number = 1)
reference$AGE[1] <- 26
nesstar_compare(x, dataset_number = 1, reference = reference)

---

List the datasets in a Nesstar file

Description

List the datasets in a Nesstar file

Usage

nesstar_datasets(x)

Arguments

x	A nesstar_binary object from nesstar_parse.

Value

A data frame with columns dataset_number, row_count, variable_count.

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
nesstar_datasets(x)

---

Export datasets to CSV files

Description

Writes each dataset to a different CSV file. The file name contains the name of the Nesstar file and the dataset number.

Usage

nesstar_export(
  x,
  output_dir,
  datasets = NULL,
  compress = TRUE,
  chunk_size = 50000L
)

Arguments

x	A nesstar_binary object.
output_dir	Directory for the output files. If the directory does not exist, the function makes it.
datasets	Integer vector of the dataset numbers to export. If NULL (the default), the function exports all datasets.
compress	Logical. If TRUE (the default), the function writes gzip files (.csv.gz).
chunk_size	Number of rows to read at a time. A smaller value decreases the memory use.

Value

Invisibly, a character vector of output file paths.

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
out <- nesstar_export(x, output_dir = tempdir())
read.csv(out[1])

---

Read the XML metadata of a Nesstar file

Description

Decodes the Huffman-coded XML blocks in the file. The XML blocks contain the dataset file names, the variable labels and the category labels.

Usage

nesstar_metadata(x)

Arguments

x	A nesstar_binary object from nesstar_parse.

Details

Some older NSS files use different record IDs. For these files, the function cannot decode the metadata. It gives a warning and returns NULL.

Value

A named list:

datasets

A list with one element for each dataset. Each element contains dataset_number, file_name and variables. variables is a list with one list for each variable. Each variable list contains name, label and categories.

If the function cannot decode the metadata, it returns NULL.

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
meta <- nesstar_metadata(x)
meta$datasets[[1]]$variables[[1]]$label

---

Parse a Nesstar file

Description

Decodes the resource index, the dataset descriptors and the variable directories. Does not decode row data.

Usage

nesstar_parse(path)

Arguments

path	Path to a .Nesstar file.

Details

The function does not keep the file in memory. The other functions read only the bytes that they need from the file. Thus, the memory use does not increase with the file size. Do not move or change the file while you use the result.

Value

A nesstar_binary list (S3 class).

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
x

---

Read one dataset into an R data frame

Description

Numeric columns become numeric and string columns become character. Older files can mark numeric columns as strings (mode 0 or 1); these are detected from their data size. Missing values become NA.

Usage

nesstar_read_dataset(x, dataset_number, columns = NULL)

Arguments

x	A nesstar_binary object.
dataset_number	Integer dataset number.
columns	Character vector of the column names to read. If NULL (the default), the function reads all columns.

Value

A data.frame.

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
nesstar_read_dataset(x, dataset_number = 1)
nesstar_read_dataset(x, dataset_number = 1, columns = c("AGE", "NAME"))

---

List variables in one dataset

Description

List variables in one dataset

Usage

nesstar_variables(x, dataset_number)

Arguments

x	A nesstar_binary object.
dataset_number	Integer dataset number (as shown by nesstar_datasets).

Value

A data frame with one row for each variable. The columns give the storage format of the variable.

Examples

path <- system.file("extdata", "example.Nesstar", package = "nesstarR")
x <- nesstar_parse(path)
nesstar_variables(x, dataset_number = 1)

---