% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_Histogram.R
\name{plot_Histogram}
\alias{plot_Histogram}
\title{Plot a histogram with separate error plot}
\usage{
plot_Histogram(
  data,
  na.rm = TRUE,
  mtext = "",
  cex.global = 1,
  se = TRUE,
  rug = TRUE,
  normal_curve = FALSE,
  summary = "",
  summary.pos = "sub",
  colour = c("white", "black", "red", "black"),
  interactive = FALSE,
  ...
)
}
\arguments{
\item{data}{\link{data.frame} or \linkS4class{RLum.Results} object (\strong{required}):
for \code{data.frame}: two columns: De (\code{data[,1]}) and De error (\code{data[,2]}).
If the error column is missing or only contains \code{NA} values, then the error
at each measurement is assumed to be 10^-9.}

\item{na.rm}{\link{logical} (\emph{with default}):
excludes \code{NA} values from the data set prior to any further operations.}

\item{mtext}{\link{character} (\emph{optional}):
further sample information (\link{mtext}).}

\item{cex.global}{\link{numeric} (\emph{with default}):
global scaling factor.}

\item{se}{\link{logical} (\emph{with default}):
plots standard error points over the histogram, default is \code{TRUE}.}

\item{rug}{\link{logical} (\emph{with default}):
adds rugs to the histogram, default is \code{TRUE}.}

\item{normal_curve}{\link{logical} (\emph{with default}):
adds a normal curve to the histogram. Mean and standard deviation are
calculated from the input data. If \code{TRUE}, the y-axis in the histogram
will show the probability density.}

\item{summary}{\link{character} (\emph{with default}):
add statistic measures of centrality and dispersion to the plot.
Can be one or more of several keywords. See details for available keywords.}

\item{summary.pos}{\link{numeric} or \link{character} (\emph{with default}):
optional position coordinates or keyword (e.g. \code{"topright"})
for the statistical summary. Alternatively, the keyword \code{"sub"} may be
specified to place the summary below the plot header. However, this latter
option in only possible if \code{mtext} is not used. In case of coordinate
specification, y-coordinate refers to the right y-axis.}

\item{colour}{\link{numeric} or \link{character} (\emph{with default}):
optional vector of length 4 which specifies the colours of the following
plot items in exactly this order: histogram bars, rug lines and summary
text, normal distribution curve, standard error points
(e.g., \code{c("grey", "black", "red", "grey")}).}

\item{interactive}{\link{logical} (\emph{with default}):
create an interactive histogram plot (requires the 'plotly' package)}

\item{...}{further arguments and graphical parameters passed to \link{plot} or
\link{hist}. If y-axis labels are provided, these must be specified as a vector
of length 2 since the plot features two axes
(e.g. \code{ylab = c("axis label 1", "axis label 2")}). Y-axes limits
(\code{ylim}) must be provided as vector of length four, with the first two
elements specifying the left axes limits and the latter two elements giving
the right axis limits.}
}
\description{
Function plots a predefined histogram with an accompanying error plot as
suggested by Rex Galbraith at the UK LED in Oxford 2010.

If the normal curve is added, the y-axis in the histogram will show the
probability density.

A statistic summary, i.e. a collection of statistic measures of
centrality and dispersion (and further measures) can be added by specifying
one or more of the following keywords:
\itemize{
\item \code{"n"} (number of samples),
\item \code{"mean"} (mean De value),
\item \code{"mean.weighted"} (error-weighted mean),
\item \code{"median"} (median of the De values),
\item \code{"median.weighted"} (error-weighted median),
\item \code{"sdrel"} (relative standard deviation in percent),
\item \code{"sdrel.weighted"} (error-weighted relative standard deviation in percent),
\item \code{"sdabs"} (absolute standard deviation),
\item \code{"sdabs.weighted"} (error-weighted absolute standard deviation),
\item \code{"serel"} (relative standard error),
\item \code{"serel.weighted"} (error-weighted relative standard error),
\item \code{"seabs"} (absolute standard error),
\item \code{"seabs.weighted"} (error-weighted absolute standard error),
\item \code{"kurtosis"} (kurtosis) and
\item \code{"skewness"} (skewness).
}
}
\note{
The input data is not restricted to a special type.
}
\section{Function version}{
 0.4.5
}

\examples{

## load data
data(ExampleData.DeValues, envir = environment())
ExampleData.DeValues <- convert_Second2Gray(ExampleData.DeValues$BT998,
                                            dose.rate = c(0.0438,0.0019))

## plot histogram the easiest way
plot_Histogram(ExampleData.DeValues)

## plot histogram with some more modifications
plot_Histogram(ExampleData.DeValues,
               rug = TRUE,
               normal_curve = TRUE,
               cex.global = 0.9,
               pch = 2,
               colour = c("grey", "black", "blue", "green"),
               summary = c("n", "mean", "sdrel"),
               summary.pos = "topleft",
               main = "Histogram of De-values",
               mtext = "Example data set",
               ylab = c(expression(paste(D[e], " distribution")),
                        "Standard error"),
               xlim = c(100, 250),
               ylim = c(0, 0.1, 5, 20))


}
\seealso{
\link{hist}, \link{plot}
}
\author{
Michael Dietze, GFZ Potsdam (Germany)\cr
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team} 

\section{How to cite}{
Dietze, M., Kreutzer, S., 2025. plot_Histogram(): Plot a histogram with separate error plot. Function version 0.4.5. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., Steinbuch, L., Boer, A.d., 2025. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 1.1.2. https://r-lum.github.io/Luminescence/
}

