@BeginModule
@NewPage
@Name      = Ydrunpctl
@Title     = Multi-year daily running percentile values
@Section   = Statistical values
@Class     = Statistic
@Arguments = ifile1 ifile2 ifile3 ofile
@Operators = ydrunpctl

@BeginDescription
This module writes to @file{ofile} running percentile values for each
day of year in @file{ifile1}. A certain percentile is computed for all
time steps in running windows of which the medium time step corresponds
to a certain day of year. 
The algorithm uses histograms with minimum and maximum bounds given in
@file{ifile2} and @file{ifile3}, respectively. The default number of
histogram bins is 100. The default can be overridden by setting the
environment variable CDO_PCTL_NBINS to a different value. The files
@file{ifile2} and @file{ifile3} must be the result of corresponding
@mod{ydrunmin} and @mod{ydrunmax} operations, respectively.
The date information in an output field is the date of the medium time
step in the last contributing running window.
Note that the operator must be applied to a continuous time series of daily
measurements in order to yield physically meaningful results. Also note that
the output time series begins (nts-1)/2 time steps after the first time step
of the input time series and ends (nts-1)/2 time steps before the last.
For input data which are complete but not continuous, such as time series of
daily measurements for the same month or season within different years, the
operator yields physically meaningful results only if the input time series
does include the (nts-1)/2 days before and after each period of interest.
@EndModule


@BeginOperator_ydrunpctl
@Title     = Multi-year daily running percentiles
@Parameter = p
@Parameter = nts

@BeginDescription
@IfMan
o(001,x) = pth percentile {i(t,x), i(t+1,x), ..., i(t+nts-1,x); day[(i(t+(nts-1)/2)] = 001}
                 ...
o(366,x) = pth percentile {i(t,x), i(t+1,x), ..., i(t+nts-1,x); day[(i(t+(nts-1)/2)] = 366}
@EndifMan
@IfDoc
@BeginMath
\begin{array}{c}
o(\mbox{001},x) = \mbox{\bf pth percentile} \{i(t,x), i(t+1,x), ..., i(t+nts-1,x); \mbox{day}[(i(t+(nts-1)/2)] = \mbox{001}\} \\
\vdots \\
o(\mbox{366},x) = \mbox{\bf pth percentile} \{i(t,x), i(t+1,x), ..., i(t+nts-1,x); \mbox{day}[(i(t+(nts-1)/2)] = \mbox{366}\} \\
\end{array}
@EndMath
@EndifDoc
@EndDescription
@EndOperator


@BeginParameter
@Item = p
INTEGER  Percentile number in {1, ..., 99}
@Item = nts
INTEGER  Number of time steps
@EndParameter


@BeginEnvironment
@Item = CDO_PCTL_NBINS
Sets the number of histogram bins. The default number is 100.
@EndEnvironment


@BeginExample
Assume the input data provide a continuous time series of daily measurements. To compute
the running multi-year daily 90th percentile over all input time steps for a running
window of five days, use:
@BeginVerbatim
   cdo ydrunmin,5 ifile minfile
   cdo ydrunmax,5 ifile maxfile
   cdo ydrunpctl,90,5 ifile minfile maxfile ofile
@EndVerbatim
Or shorter using operator piping:
@BeginVerbatim
   cdo ydrunpctl,90,5 ifile -ydrunmin ifile -ydrunmax ifile ofile
@EndVerbatim
@EndExample
