% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/makeProblem.R
\name{makeProblem}
\alias{makeProblem}
\title{Create a problem instance}
\usage{
makeProblem(
  data,
  dimList,
  dimVarInd = NULL,
  freqVarInd = NULL,
  numVarInd = NULL,
  weightInd = NULL,
  sampWeightInd = NULL
)
}
\arguments{
\item{data}{a data frame featuring at least one column for each desired
dimensional variable. Optionally the input data can feature variables
that contain information on cell counts, weights that should be used during
the cut and branch algorithm, additional numeric variables or variables that
hold information on sampling weights.}

\item{dimList}{a (named) list where the names refer to variable names in
input \code{data}. If the list is not named, it is required to specify argument
\code{dimVarInd}. Each list element can be one of:
\itemize{
\item \code{tree}: generated with \verb{hier_*()} functions from package \code{sdcHierarchies}
\item \code{data.frame}: a two column \code{data.frame} containing the full hierarchy of
a dimensional variable using a top-to-bottom approach. The format of this
\code{data.frame} is as follows:
\itemize{
\item \strong{first column:} a character vector specifying levels with each vector
element being a string only containing of \code{@}s from length 1 to n.
If a vector element consists of \code{i}-chars, the corresponding code
is of level \code{i}. The code \code{@} (one character) equals the grand
total (level=1), the code \verb{@@} (two characters) is of level 2 (directly
below the overall total).
\item \strong{second column:} a character vector specifying level codes
}
\item \code{path}: absolute or relative path to a \code{.csv} file that
contains two columns seperated by semicolons (\verb{;}) having the same structure
as the \code{"@;levelname"}-structure described above
}}

\item{dimVarInd}{if \code{dimList} is a named list, this argument is
ignored (\code{NULL}). Else either a numeric or character vector
defining the column indices or names of dimensional variables
(specifying the table) within argument \code{data} are expected.}

\item{freqVarInd}{if not \code{NULL}, a scalar numeric or character vector
defining the column index or variable name of a variable holding counts
in \code{data}}

\item{numVarInd}{if not \code{NULL}, a numeric or character vector
defining the column indices or variable names of additional numeric
variables with respect to \code{data}}

\item{weightInd}{if not \code{NULL}, a scalar numeric or character vector
defining the column index or variable name holding costs within \code{data}
that should be used as objective coefficients when solving secondary
cell suppression problems.}

\item{sampWeightInd}{if not \code{NULL}, a scalar numeric or character vector
defining the column index or variable name of a variable holding sampling
weights within \code{data}. In case a complete table is provided, this parameter is
ignored.}
}
\value{
a \link[=sdcProblem-class]{sdcProblem} object
}
\description{
Function \code{\link[=makeProblem]{makeProblem()}} is used to create \link[=sdcProblem-class]{sdcProblem} objects.
}
\section{Cell Status Codes}{


When an object of class \code{sdcProblem} is created, every cell is assigned an
internal anonymization state. These codes track the lifecycle of a
cell throughout the suppression process:
\itemize{
\item \code{"s"} (\emph{"Publishable"}): The cell is safe and can be published (default).
\item \code{"z"}(\emph{"Forced Publishable"}): The cell must not be suppressed under any
circumstances.
\item \code{"u"} (*"Primary Suppressed"): The cell is identified as sensitive and
requires protection (typically assigned via \code{\link[=primarySuppression]{primarySuppression()}}).
\item \code{"x"} (\emph{"Secondary Suppressed"}): The cell is suppressed to protect
primary sensitive cells (typically assigned via \code{\link[=protectTable]{protectTable()}}).
\item \code{"w"} (\emph{"Extension Cell"}): The cell exists in the object but will never
be published. It is treated as a suppressed cell by internal algorithms.
This is useful if it is known in advance that specific codes of a hierarchy
will be excluded from publication.
}

Initially in \code{\link[=makeProblem]{makeProblem()}}, cells are coded as \code{"s"} or \code{"z"}. Their
status transitions to \code{"u"} or \code{"x"} as suppression algorithms are applied.

While \code{\link[=setInfo]{setInfo()}} or \code{\link[=change_cellstatus]{change_cellstatus()}} allow for manual state
modifications, \code{\link[=primarySuppression]{primarySuppression()}} automatically identifies primary
sensitive cells and assigns state \code{"u"}. In \code{\link[=protectTable]{protectTable()}}, additional
cells are identified and set to \code{"x"} to ensure all primary sensitive
cells are adequately protected.
}

\examples{
# loading micro data
utils::data("microdata1", package = "sdcTable")

# we can observe that we have a micro data set consisting
# of two spanning variables ('region' and 'gender') and one
# numeric variable ('val')

# specify structure of hierarchical variable 'region'
# levels 'A' to 'D' sum up to a Total
dim.region <- data.frame(
 levels=c('@','@@','@@','@@','@@'),
 codes=c('Total', 'A','B','C','D'),
 stringsAsFactors=FALSE)

# specify structure of hierarchical variable 'gender'
# using create_node() and add_nodes() (see ?manage_hierarchies)
dim.gender <- hier_create(root = "Total", nodes = c("male", "female"))
hier_display(dim.gender)

# create a named list with each element being a data-frame
# containing information on one dimensional variable and
# the names referring to variables in the input data
dimList <- list(region = dim.region, gender = dim.gender)

# third column containts a numeric variable
numVarInd <- 3

# no variables holding counts, numeric values, weights or sampling
# weights are available in the input data
# creating an problem instance using numeric indices
p1 <- makeProblem(
  data = microdata1,
  dimList = dimList,
  numVarInd = 3 # third variable in `data`
)

# using variable names is also possible
p2 <- makeProblem(
  data = microdata1,
  dimList = dimList,
  numVarInd = "val"
)

# what do we have?
print(class(p1))

# have a look at the data
df1 <- sdcProb2df(p1, addDups = TRUE,
  addNumVars = TRUE, dimCodes = "original")
df2 <- sdcProb2df(p2, addDups=TRUE,
  addNumVars = TRUE, dimCodes = "original")
print(df1)

identical(df1, df2)
}
\seealso{
\link{sdcProb2df}
}
\author{
Bernhard Meindl
}
