create_ptable {ptable}

Noise Probability Generator for the Cell-Key Method (CKM)

Description

ptable makes it easy to create perturbation tables that can be used for applying noise to statistical tables with any cell-key method approach - among others either the cellKey()-package or the standalone tool TauArgus.

The package provides four main functions to create the perturbation tables:

• create_ptable(): generic function that creates a ptable, either for frequency count or magnitude tables with a various set of options.

• create_cnt_ptable(): creates a ptable suitable for frequency count tables.

• create_num_ptable(): creates a ptable suitable for magnitude tables (i.e. with numerical variables).

• modify_cnt_ptable(): modifies the ptable for a higher level of protection

Usage

create_ptable(
  D,
  V,
  js = 0,
  pstay = NULL,
  optim = 1,
  mono = TRUE,
  step = 1,
  icat = NULL,
  table = "cnts",
  type = "all",
  label = paste0("D", D, "V", V * 100),
  monitoring = FALSE,
  debugging = FALSE,
  create = TRUE,
  params = NULL
)

create_cnt_ptable(
  D,
  V,
  js = 0,
  pstay = NULL,
  optim = 1,
  mono = TRUE,
  label = paste0("D", D, "V", V * 100),
  monitoring = FALSE,
  create = TRUE
)

create_num_ptable(
  D,
  V,
  pstay = NULL,
  optim = 1,
  mono = TRUE,
  step = 2,
  icat = NULL,
  type = "all",
  label = paste0("D", D, "V", V * 100),
  monitoring = FALSE,
  create = TRUE
)

Arguments

D

perturbation parameter for maximum noise (scalar integer)

V

perturbation parameter for variance (scalar double)

js

threshold value for blocking of small frequencies (i.e. the perturbation will not produce positive cell values that are equal to or smaller than the threshold value). (scalar integer)

pstay

optional parameter to set the probability (0 < p < 1) of an original frequency to remain unperturbed: NA (default) no preset probability (i.e. produces the maximum entropy solution)

optim

optimization parameter: 1 standard approach (default) with regular constraints, 4 alternative approach with simplified constraints (may work if constraints using the standard approach are violated)

mono

(logical) vector specifying optimization parameter for monotony condition

step

(integer) number of steps for the noise (between two integer values). Whereas the cell-key approach for frequency count tables only allows to have noise values that are integers (step = 1)

-D, 1-D, 2-D, ..., -1, 0, 1, ..., D-2, D-1, D

the noise distribution for magnitude values does not have to be integer valued:

-D, (1/step)-D, (2/step)-D, ..., 0, ..., D-(2/step), D-(1/step), D

The reciprocal of step (='step width') is computed and used internally for the perturbation table.

icat

(integer) categorized original frequencies i

table

(character) type of the table: frequency count (cnts) or magnitude table (nums)

type

(character) type indicator for the extra column 'type' used for magnitude tables: 'even', 'odd' or 'all' (default)

label

(character) label of the Output

monitoring

(logical) output monitoring on/off

debugging

(logical) debug monitoring on/off

create

(logical) scalar specifying to create just the input parameters of class ptable_params (FALSE) or also to create the perturbation table object of class ptable (default: TRUE)

params

object of class ptable_params can be used as input instead of the remaining parameters

Details

The perturbation probabilities are constructed given the following constraints:

• Maximum noise

• Zero mean (unbiased noise)

• Fixed noise variance

• Transition probabilities are between zero and one and the sum up to 1

• Perturbations will not produce negative cell values or positive cell values equal to or less than a specific threshold value

Value

Returns ptable object including the created perturbation table by default. If the argument create = FALSE, a ptable_params object is returned.

See Also

• plot() to analyze the created perturbation table visually

• pt_export() to export the perturbation table for external sdcTools like TauArgus or SAS.

Examples

# create ptable for frequency count tables
create_cnt_ptable(D = 3, V = 1.08, js = 1, label = "ptable_frequency_tab")

# create ptable for magnitude tables
create_num_ptable(D = 5, V = 2, step = 4, icat = c(1, 3, 5))

# create ptable for frequency or magnitude tables
create_ptable(D = 3, V = 1.08, js = 1, table="cnts")
create_ptable(D = 5, V = 2, step = 4, icat = c(1, 4, 5), table="nums")