@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 operator writes running percentile values for each day of year 
in @file{ifile1} to @file{ofile}. 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 101. The default can be overridden by setting the
environment variable @env{CDO_PCTL_NBINS} to a different value. The files
@file{ifile2} and @file{ifile3} should 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 have to 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 only yields physically meaningful results 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
\vspace*{3mm}

@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 101.
@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
