% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metadatatemplate.R
\name{metadatatemplate}
\alias{metadatatemplate}
\alias{metadata}
\title{Metadata and helper function for metadata}
\usage{
metadatatemplate(
  data,
  file = NULL,
  includevrt = NULL,
  excludevrt = NULL,
  addsummary2metadata = FALSE,
  backupfiles = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{data}{A dataset, given as a \link[base:data.frame]{data frame}
or as a file path to a csv file.}

\item{file}{Character or \code{NULL} (default): name of csv file where the metadata should be saved; if \code{NULL}: output metadata as \code{VALUE}.}

\item{includevrt}{Character or \code{NULL}: name of variates in dataset to be included.}

\item{excludevrt}{Character or \code{NULL}: name of variates in dataset to be excluded.}

\item{addsummary2metadata}{Logical: also output some diagnostic statistics
in the metadata? Default \code{FALSE}.}

\item{backupfiles}{Logical: rename previous metadata file if it exists?
Default \code{TRUE}.}

\item{verbose}{Logical: output heuristics for each variate? Default \code{TRUE}.}
}
\value{
A preliminary \link[base:data.frame]{data frame} containing the metadata, \link[base:invisible]{invisibly} if \code{file = NULL}. If argument \code{file} is a character, a preliminary metadata file is also created with that name or path.
}
\description{
Metadata and helper function to create a template metadata file or object.
}
\details{
The \code{\link[=learn]{learn()}} function needs metadata about the variates present in the data. Such metadata can be provided either as a \code{csv} file or as a \code{\link[base:data.frame]{base::data.frame()}}. The function \code{buildmetadata} creates a template metadata csv-file, or outputs a metadata data.frame, by trying to \emph{guess} metadata information from the dataset.The guesses may be very incorrect (as already said, metadata is information not contained in the data, so no algorithm can exist that extracts it from the data). \strong{The user \emph{must} modify and correct this template, using it as a starting point to prepare the correct metadata information.}
}
\section{Metadata information and format}{


In order to correctly learn from a dataset, the \code{\link[=learn]{learn()}} function needs information that is not contained in the data themeselves; that is, it needs \emph{meta}data. Metadata are provided either as a \code{csv} file or as a \code{\link[base:data.frame]{base::data.frame()}}.

A metadata file or data.frame must contain one row for each simple variate in the given inference problem, and the following fields (columns), even if some of them may be empty:

\code{name}, \code{type}, \code{domainmin}, \code{domainmax}, \code{datastep}, \code{minincluded}, \code{maxincluded}, \code{V1}, \code{V2}, (possibly additional \code{V}-fields, sequentially numbered)

The \code{type} field has three possible values: \code{nominal}, \code{ordinal}, \code{continuous}. The remaining fields that must be filled in depend on the \code{type} field. Here is a list of requirements:
\itemize{
\item \strong{\code{nominal}} and \strong{\code{ordinal}}: require \emph{either} \code{V1}, \code{V2}, ... fields \emph{or} \code{domainmin}, \code{domainmax}, \code{datastep} (all three) fields. No other fields are required.
\item \strong{\code{continuous}}: requires \code{domainmin}, \code{domainmax}, \code{datastep}, \code{minincluded}, \code{maxincluded}.
}

Here are the meanings and possible values of the fields:

\strong{\code{name}}: The name of the variate. This must be the same character string as it appears in the dataset (be careful about upper- and lower-case).

\strong{\code{type}}: The data type of variate \code{name}. Possible values are \code{nominal}, \code{ordinal}, \code{continuous}.
\itemize{
\item A \emph{nominal} (also called \emph{categorical}) variate has a discrete, finite number of possible values which have no intrinsic ordering. Examples could be a variate related to colour, with values "red", "green", "blue", and so on; or a variate related to cat breeds, with values "Siamese", "Abyssinian", "Persian", and so on. The possible values of the variate must be given in the fields \code{V1}, \code{V2}, and so on. It is important to include values that are possible but are \emph{not} present in the dataset. A variate having only two possible values (binary variate), for example "yes" and "no", can be specified as nominal.
\item An \emph{ordinal} variate has a discrete, finite number of possible values which do have an intrinsic ordering. Examples could be a Likert-scaled variate for the results of a survey, with values "very dissatisfied", "dissatisfied", "satisfied", "very satisfied"; or a variate related to the levels of some quantities, with values "low", "medium", "high"; or a variate having a numeric scale with values from 1 to 10. Whether a variate is nominal or ordinal often depends on the context. The possible values of the variate but be given in either one (but not both) or two ways: (1) in the fields \code{V1}, \code{V2}, ..., as for nominal variates; (2) as the fields \code{domainmin}, \code{domainmax}, \code{datastep}. Option (2) only works with numeric, equally spaced values: it assumes that the first value is \code{domainmin}, the second is \code{domainmin}+\code{datastep}, the third is \code{domainmin}+2*\code{datastep}, and so on up to the last value, \code{domainmax}.
\item A \emph{continuous} variate has a continuum of values with an intrinsic ordering. Examples could be a variate related to the width of an object; or to the age of a person; or one coordinate of an object in a particular reference system. A continuous variate requires specification of the fields \code{domainmin}, \code{domainmax}, \code{datastep}, \code{minincluded}, \code{maxincluded}. Some naturally continuous variates are often rounded to a given precision; for instance, the age of a person might be reported as rounded to the nearest year (25 years, 26 years, and so on); or the length of an object might be reported to the nearest centimetre (1 m, 1.01 m, 1.02 m, and so on). The minimum distance between such rounded values \strong{must} be reported in the \code{datastep} field; this would be \code{1} in the age example and \code{0.01} in the length example above. See below for further explanation of why reporting such rounding is important.
}

\strong{\code{domainmin}}: The minimum value that the variate (ordinal or continuous) can take on. Possible values are a real number or an empty value, which is then interpreted as \code{-Inf} (explicit values like \code{-Inf}, \code{-inf}, \code{-infinity} should also work). Some continuous variates, like age or distance or temperature, are naturally positive, and therefore have \code{domainmin} equal \code{0}. But in other contexts the minimum value could be different. For instance, if a given inference problem only involves people of age 18 or more, then \code{domainmin} would be set to \code{18}.

\strong{\code{domainmax}}: The maximum value that the variate (ordinal or continuous) can take on. Possible values are a real number, or an empty value, which is then interpreted as \code{+Inf} (explicit values like \code{Inf}, \code{inf}, \code{infinity} should also work). As with \code{domainmin}, the maximum value depends on the context. An age-related variate could theoretically have \code{domainmax} equal to infinity (empty value in the metadata file); but if a given study categorizes some people as "90 years old or older", then \code{domainmax} should be set to \code{90}.

\strong{\code{datastep}}: The minimum distance between the values of a variate (ordinal or continuous). Possible values are a positive real number or an empty value, which is then interpreted as 0 (the explicit value \code{0} is also accepted). For a numeric ordinal variate, \code{datastep} is the step between consecutive values. For a continuous \emph{rounded} variate, \code{datastep} is the minimum distance between different values that occurs because of rounding; see the examples given above. The function \code{buildmetadata} has some heuristics to determine whether the variate is rounded or not. See further details under the section Rounding below.

\strong{\code{minincluded}}, \strong{\code{maxincluded}}: Whether the minimum (\code{domainmin}) and maximum(\code{domainmax}) values of a \emph{continuous} variate can really appear in the data or not. Possible values are \code{true} (or \code{t} or \code{yes}) or \code{false} (or \code{f}, \code{no}, or an empty field); upper- or lower-case is irrelevant. Here are some examples about the meaning of these fields. (a) A continuous \emph{unrounded} variate such as temperature has 0 as a minimum possible value \code{domainmin}, but this value itself is physically impossible and can never appear in data; in this case \code{minincluded} is empty (or set to \code{false} or \code{no}). (b) A variate related to the \emph{unrounded} length, in metres, of some objects may take on any positive real value; but suppose that all objects of length 5 or less are grouped together under the value \code{5}. It is then possible for several datapoints to have value \code{5}: one such datapoint could originally have the value 3.782341...; another the value 4.929673..., and so on. In this case \code{domainmin} is set to \code{5}, and \code{minincluded} is set to \code{true} (or \code{yes}). Similarly for the maximum value of a variate and \code{maxincluded}. Note that if \code{domainmin} is minus-infinity (empty value in the metadata file), then \code{minincluded} is automatically empty (that is, \code{false}), and similarly for \code{maxincluded} if \code{domainmax} is infinity.
}

\examples{
## Create a preliminary data frame of metadata for the `penguins` dataset
metadata <- metadatatemplate(data = datasets::penguins, file = NULL)

## Note how the preliminary data frame includes additional spots
## for values of nominal and ordinal variates
## which could be missing from the data
print(metadata)


## Create a preliminary data frame of metadata for the `penguins` dataset,
## including only the 'species' and 'bill_len' variates:
metadata2 <- metadatatemplate(
  data = datasets::penguins, file = NULL,
  includevrt = c('species', 'bill_len')
)

print(metadata2)


## Create a preliminary data frame of metadata for the `penguins` dataset,
## excluding the 'year' variate:
metadata3 <- metadatatemplate(
  data = datasets::penguins, file = NULL,
  excludevrt = 'year'
)

print(metadata3)

## Generate 10 points for a continuous variate in (0, 1)
dataset <- runif(10)

## `metadatatemplate` correctly guesses the variate minimum,
## but not the maximum (`NA` is equivalent to `+Inf`)
metadata <- metadatatemplate(data = dataset, file = NULL)
print(metadata)

}
\seealso{
\code{\link[=learn]{learn()}}, which generates the information necessary to calculate posterior probabilities, based on data and metadata.
}
