Package {TwoSampleCalImpute}

TwoSampleCalImpute

Description

Two-Sample Calibrated Imputation for Incomplete Survey Data

Details

The TwoSampleCalImpute package provides computational implementations of the Two-Sample Calibrated Imputation framework for incomplete survey data when auxiliary information is available from a separate reference sample.

The package implements the computational chain: Theory -> Algorithm -> R Implementation -> Validation -> Simulation -> Reproducible Results.

The package is developed as part of the four-volume TwoSampleCalImpute research programme.

Author(s)

Maintainer: Samuel Joel Kamun samuelkamun@gmail.com

Authors:

• Samuel Joel Kamun samuelkamun@gmail.com

See Also

Useful links:

• https://github.com/Kamun2026/TwoSampleCalImpute

• Report bugs at https://github.com/Kamun2026/TwoSampleCalImpute/issues

Print a tsci_data object

Description

Displays a summary of a standardized TSCI data object, including its sample type, number of observations, and number of variables.

Usage

## S3 method for class 'tsci_data'
print(x, ...)

Arguments

Value

Invisibly returns x, the original tsci_data object. The object retains its tsci_data and list classes.

Examples

survey_data <- data.frame(
  id = 1:3,
  outcome = c(1, 0, 1)
)

obj <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

print(obj)

Print a tsci_design object

Description

Displays the sample type, number of observations, and whether sampling weights have been specified for a survey-design object.

Usage

## S3 method for class 'tsci_design'
print(x, ...)

Arguments

Value

Invisibly returns x, the original tsci_design object. The object retains its tsci_design and list classes.

Examples

survey_data <- data.frame(
  id = 1:3,
  outcome = c(1, 0, 1),
  weight = c(1, 1, 1)
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight"
)

print(design_object)

Clean survey data

Description

Performs controlled data-cleaning operations on a tsci_data object without silently changing observed values. Completely empty rows or columns are removed only when the corresponding option is set to TRUE.

Usage

tsci_clean_data(data, remove_empty_rows = FALSE, remove_empty_columns = FALSE)

Arguments

Value

A cleaned tsci_data object containing the resulting data, with its sample type, identifier, and metadata preserved. The variable list is updated to include only variables still present.

Examples

survey_data <- data.frame(
  id = c(1, 2, 3),
  outcome = c(1, NA, 0),
  auxiliary = c(NA, NA, NA)
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

cleaned <- tsci_clean_data(
  imported,
  remove_empty_columns = TRUE
)
names(cleaned$data)

Extract the Cluster Variable

Description

Extracts the name of the cluster variable stored in a tsci_design object. If no cluster variable was specified, the function returns NULL. The stored specification is validated against the variables in the design data before the name is returned.

Usage

tsci_clusters(design)

Arguments

Value

A character string of length one containing the name of the cluster variable, or NULL if no cluster variable was specified. An error is raised if design is not a tsci_design object, if the stored cluster specification is invalid, or if the specified variable is absent from the design data.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 1, 1, 1),
  cluster = c("C1", "C1", "C2", "C2")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  clusters = "cluster"
)

tsci_clusters(design_object)

design_without_clusters <- tsci_create_design(
  data_object,
  weights = "weight"
)
tsci_clusters(design_without_clusters)

Create a survey design object

Description

Constructs a tsci_design object from a tsci_data object and specified survey-design variables. The weight variable must contain numeric, finite, strictly positive values. If supplied, the finite-population-correction (FPC) variable must also contain numeric, finite, strictly positive values.

Usage

tsci_create_design(data, weights, strata = NULL, clusters = NULL, fpc = NULL)

Arguments

Value

An object of class tsci_design, represented as a list containing the survey-design information constructed from the input data object. The object includes the survey weights and the specified design variables, with the underlying data-object information retained according to the package's design-object constructor.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2),
  stratum = c("A", "A", "B", "B")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  strata = "stratum"
)

print(design_object)

Create a data dictionary for a TSCI data object

Description

Produces a structured data dictionary describing the variables in a tsci_data object.

Usage

tsci_data_dictionary(data)

Arguments

Value

A data frame with one row per variable and five columns: variable (variable name), class (R class or classes), n (number of observations), missing (number of missing values), and description (variable description from the object's metadata, or NA if no matching description is available).

Examples

survey_data <- data.frame(
  id = 1:3,
  outcome = c(1, NA, 0),
  age = c(35, 42, 29)
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id",
  metadata = list(
    description = c(
      outcome = "Recorded outcome",
      age = "Age in years"
    )
  )
)

tsci_data_dictionary(imported)

Validate survey-design information

Description

Checks the structural and numerical validity of a tsci_design object, including its underlying data object, number of observations, survey weights, stratification variable, and finite-population correction values.

Usage

tsci_design_check(design)

Arguments

Value

An object of class c("tsci_design_check", "list") containing:

valid

Logical value indicating whether all checks pass.

checks

Named list of logical results for the individual structural and numerical checks.

sample_type

Sample type recorded in the underlying tsci_data object.

observations

Number of rows in the underlying data.

id

Identifier information stored in the design object.

strata

Stratification variable information stored in the design object.

has_weights

Logical value indicating whether survey weights are stored.

has_fpc

Logical value indicating whether finite-population correction values are stored.

The valid field is TRUE only when every individual check passes. An input that is not a tsci_design object causes an error.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2),
  stratum = c("A", "A", "B", "B")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  strata = "stratum"
)

check_result <- tsci_design_check(design_object)
check_result$valid
check_result$checks

Plot the Survey-Design Structure

Description

Produces a base-R plot indicating whether weights, strata, clusters, and finite-population correction (FPC) values are specified in a tsci_design object. A component is displayed as specified when its corresponding stored value is not NULL.

Usage

tsci_design_plot(design)

Arguments

Value

The input tsci_design object, returned invisibly. The function also produces a plot with one indicator for each of the four design components: weights, strata, clusters, and FPC. An error is raised if design is not a tsci_design object.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2),
  stratum = c("A", "A", "B", "B")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  strata = "stratum"
)

returned_design <- tsci_design_plot(design_object)
stopifnot(inherits(returned_design, "tsci_design"))

Summarise a survey design

Description

Produces a concise summary of the main components of a tsci_design object.

Usage

tsci_design_summary(design)

Arguments

Value

A one-row data frame with seven columns: sample_type (type of sample represented by the underlying data), observations (number of observations), variables (number of variables in the data), id (identifier variable name, or NA if none is specified), weights (logical indicator of whether survey weights are stored), strata (stratification variable name, or NA if none is specified), and fpc (logical indicator of whether finite-population-correction values are stored).

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2),
  stratum = c("A", "A", "B", "B")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  strata = "stratum"
)

tsci_design_summary(design_object)

Export survey data

Description

Exports the data contained in a tsci_data object to a CSV file.

Usage

tsci_export_data(data, file, row_names = FALSE)

Arguments

Value

Invisibly returns the original tsci_data object supplied through data. The object retains its existing data and metadata.

Examples

survey_data <- data.frame(
  id = 1:3,
  outcome = c(1, 0, 1)
)
imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

output_file <- tempfile(fileext = ".csv")
returned <- tsci_export_data(imported, file = output_file)
file.exists(output_file)
identical(returned, imported)
unlink(output_file)

Extract the finite-population correction

Description

Extracts and validates the finite-population-correction (FPC) values stored in a tsci_design object.

Usage

tsci_fpc(design)

Arguments

Value

A numeric vector containing one finite, strictly positive FPC value per observation, in the stored order, or NULL if no FPC was specified. An error is raised if design is not a tsci_design object, or if the stored FPC is non-numeric, has an incorrect length, contains missing or non-finite values, or contains non-positive values.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2),
  fpc = c(100, 100, 200, 200)
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  fpc = "fpc"
)

tsci_fpc(design_object)

design_without_fpc <- tsci_create_design(
  data_object,
  weights = "weight"
)
tsci_fpc(design_without_fpc)

Import survey data

Description

Imports a data set from a supported file or an existing R object and returns it as a standardized tsci_data object.

Usage

tsci_import_data(
  data,
  sample_type = c("primary", "auxiliary"),
  id = NULL,
  variables = NULL,
  metadata = list()
)

Arguments

Value

A tsci_data object, represented as a list containing the imported data, sample type, identifier, variable names, and metadata.

Examples

survey_data <- data.frame(
  id = 1:3,
  outcome = c(1, 0, 1),
  age = c(35, 42, 29)
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

print(imported)

Merge two TSCI data objects

Description

Merge two TSCI data objects

Usage

tsci_merge_data(x, y, by, all = FALSE)

Arguments

Details

Merges two tsci_data objects using one or more key variables.

Value

A tsci_data object containing the merged data. The result retains the sample type and metadata from x; its identifier is retained only if that identifier is present in the merged data.

Examples

primary_data <- data.frame(
  id = c(1, 2, 3),
  outcome = c(1, 0, 1)
)

auxiliary_data <- data.frame(
  id = c(1, 2, 3),
  age_group = c("young", "middle", "older")
)

primary <- tsci_import_data(
  primary_data,
  sample_type = "primary",
  id = "id"
)

auxiliary <- tsci_import_data(
  auxiliary_data,
  sample_type = "auxiliary",
  id = "id"
)

merged <- tsci_merge_data(
  primary,
  auxiliary,
  by = "id"
)

names(merged$data)

Summarize missing values in a TSCI data object

Description

Produces a variable-level summary of missing and observed values in a tsci_data object.

Usage

tsci_missing_summary(data, variables = NULL)

Arguments

Value

A data frame with one row per selected variable and five columns: variable (variable name), n (total number of observations), missing (number of missing values), observed (number of non-missing values), and missing_percent (percentage of observations with missing values, on a 0–100 scale).

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, NA, 0, NA),
  group = c("A", "B", "A", "B")
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

tsci_missing_summary(imported, variables = "outcome")

Prepare survey data

Description

Prepares a tsci_data object for subsequent validation and Two-Sample Calibrated Imputation analysis by applying the specified empty-row and empty-column cleaning operations.

Usage

tsci_prepare_data(
  data,
  remove_empty_rows = FALSE,
  remove_empty_columns = FALSE
)

Arguments

Value

A prepared tsci_data object. Its data reflect the requested cleaning operations; its sample type, identifier, and metadata are preserved by the cleaning operation.

Examples

survey_data <- data.frame(
  id = c(1, 2, 3),
  outcome = c(1, NA, 0),
  empty_variable = c(NA, NA, NA)
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

prepared <- tsci_prepare_data(
  imported,
  remove_empty_columns = TRUE
)
names(prepared$data)

Recode variables in a TSCI data object

Description

Applies user-supplied recoding functions to one or more variables in a tsci_data object.

Usage

tsci_recode_variables(data, recodes)

Arguments

Value

A tsci_data object containing the recoded variables. The sample type, identifier, variable list, and metadata are preserved from the input object.

Examples

survey_data <- data.frame(
  id = 1:4,
  response = c("Yes", "No", "Yes", "No")
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

recoded <- tsci_recode_variables(
  imported,
  recodes = list(response = function(x) {
    ifelse(x == "Yes", 1, 0)
  })
)

recoded$data$response

Extract the Stratification Variable

Description

Extracts the name of the stratification variable stored in a tsci_design object. If no stratification variable was specified, the function returns NULL. The stored specification is validated against the variables in the design data before the name is returned.

Usage

tsci_strata(design)

Arguments

Value

A character string of length one containing the name of the stratification variable, or NULL if no stratification variable was specified. An error is raised if design is not a tsci_design object, if the stored stratification specification is invalid, or if the specified variable is absent from the design data.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 1, 1, 1),
  stratum = c("A", "A", "B", "B")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  strata = "stratum"
)

tsci_strata(design_object)

design_without_strata <- tsci_create_design(
  data_object,
  weights = "weight"
)
tsci_strata(design_without_strata)

Subset a TSCI data object

Description

Subsets observations in a tsci_data object using a logical condition while preserving the TSCI data-object structure.

Usage

tsci_subset_data(data, subset)

Arguments

Value

A tsci_data object containing the selected observations. The sample type, identifier, and metadata are preserved, and the variable list is restricted to variables present in the result.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0)
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

selected <- tsci_subset_data(
  imported,
  subset = c(TRUE, FALSE, TRUE, FALSE)
)

nrow(selected$data)
selected$data$id

Transform variables in a TSCI data object

Description

Applies a user-supplied transformation function to one or more variables in a tsci_data object while preserving the TSCI data object structure.

Usage

tsci_transform_data(data, variables, fun, ...)

Arguments

Value

A tsci_data object containing the transformed variables.

Examples

x <- data.frame(id = 1:3, y = c(2, 4, 6))
obj <- tsci_import_data(x, sample_type = "primary", id = "id")
tsci_transform_data(obj, variables = "y", fun = log)

Update a survey design object

Description

Updates selected components of an existing tsci_design object. Non-NULL values supplied for weights, strata, and fpc replace the corresponding stored components. The clusters argument is passed to the design-object constructor, so omitting it does not guarantee that a previously specified cluster setting is retained.

Usage

tsci_update_design(
  design,
  weights = NULL,
  strata = NULL,
  clusters = NULL,
  fpc = NULL
)

Arguments

Value

An object of class tsci_design containing the updated survey-design components and the underlying data-object information. The weights and FPC values are checked for numeric, finite, strictly positive values when their variable names are supplied. Invalid design inputs cause an error.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2),
  updated_weight = c(2, 2, 3, 3),
  stratum = c("A", "A", "B", "B")
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight",
  strata = "stratum"
)

updated_design <- tsci_update_design(
  design_object,
  weights = "updated_weight"
)

print(updated_design)

Validate a survey data set

Description

Performs data-integrity checks before Two-Sample Calibrated Imputation analysis, including input validation, optional variable and weight checks, missingness summaries, and duplicate-key checks.

Usage

tsci_validate_data(
  data,
  data_name = "data",
  variables = NULL,
  weights = NULL,
  key = NULL
)

Arguments

Value

An object of class c("tsci_validation", "list") containing valid (validation status), data_name (the supplied data label), n (number of rows), p (number of columns), variables (column names), missing (missingness-check results), and duplicates (duplicate-key-check results). Invalid inputs cause an error.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, NA, 1),
  weight = c(1, 1, 1, 1)
)

validation <- tsci_validate_data(
  survey_data,
  variables = c("outcome", "weight"),
  weights = survey_data$weight,
  key = "id"
)

validation$valid
validation$n
validation$missing

Summarize variables in a TSCI data object

Description

Produces descriptive summaries for selected variables in a tsci_data object.

Usage

tsci_variable_summary(data, variables = NULL)

Arguments

Value

A data frame with one row per selected variable and five columns: variable (variable name), class (R class), n (number of observations), missing (number of missing values), and unique (number of distinct non-missing values).

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, NA, 1),
  group = c("A", "B", "A", "B")
)

imported <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

tsci_variable_summary(imported, variables = "outcome")

Extract survey weights

Description

Extracts and validates the numeric survey weights stored in a tsci_design object.

Usage

tsci_weights(design)

Arguments

Value

A numeric vector containing the survey weights in their stored order. The vector has one element per observation and contains only finite, strictly positive values. An error is raised if the design object is invalid, weights are absent, weights are non-numeric, or any weight is missing, non-finite, or non-positive.

Examples

survey_data <- data.frame(
  id = 1:4,
  outcome = c(1, 0, 1, 0),
  weight = c(1, 2, 1, 2)
)

data_object <- tsci_import_data(
  survey_data,
  sample_type = "primary",
  id = "id"
)

design_object <- tsci_create_design(
  data_object,
  weights = "weight"
)

tsci_weights(design_object)