@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 timesteps in running windows of which the medium 
timestep 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 timesteps after the first timestep of the input time series and ends (nts-1)/2 
timesteps 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
FLOAT    Percentile number in {0, ..., 100}
@Item = nts
INTEGER  Number of timesteps
@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 timesteps 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
