## Copyright (C) 2024 Andreas Bertsatos <abertsatos@biol.uoa.gr>
## Copyright (C) 2025 Swayam Shah <swayamshah66@gmail.com>
##
## This file is part of the statistics package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see <http://www.gnu.org/licenses/>.

classdef RayleighDistribution < prob.ProbabilityDistribution
  ## -*- texinfo -*-
  ## @deftp {statistics} prob.RayleighDistribution
  ##
  ## Rayleigh probability distribution object.
  ##
  ## A @code{prob.RayleighDistribution} object consists of parameters, a model
  ## description, and sample data for a Rayleigh probability distribution.
  ##
  ## The Rayleigh distribution is a continuous probability distribution for
  ## nonnegative random variables.  It is often used to model the magnitude of
  ## a vector in two dimensions where the components are normally distributed
  ## with zero mean and equal variance.  It is defined by scale parameter
  ## @var{B}.
  ##
  ## @var{B} is the @math{sigma} of the usual mathematical notation.  The
  ## @code{rayl*} functions name the same quantity @var{sigma}; this class
  ## follows MATLAB.
  ##
  ## There are several ways to create a @code{prob.RayleighDistribution} object.
  ##
  ## @itemize
  ## @item Fit a distribution to data using the @code{fitdist} function.
  ## @item Create a distribution with fixed parameter values using the
  ## @code{makedist} function.
  ## @item Use the constructor @qcode{prob.RayleighDistribution (@var{B})}
  ## to create a Rayleigh distribution with fixed parameter value @var{B}.
  ## @item Use the static method @qcode{prob.RayleighDistribution.fit (@var{x},
  ## @var{censor}, @var{freq})} to fit a distribution to the data in @var{x}
  ## using the same input arguments as the @code{raylfit} function.
  ## @end itemize
  ##
  ## It is highly recommended to use @code{fitdist} and @code{makedist}
  ## functions to create probability distribution objects, instead of the class
  ## constructor or the aforementioned static method.
  ##
  ## Further information about the Rayleigh distribution can be found at
  ## @url{https://en.wikipedia.org/wiki/Rayleigh_distribution}
  ##
  ## @seealso{fitdist, makedist, raylcdf, raylinv, raylpdf, raylrnd, raylfit,
  ## rayllike, raylstat}
  ## @end deftp

  properties(Dependent = true)
    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} B
    ##
    ## Scale parameter
    ##
    ## A positive scalar value characterizing the scale of the
    ## Rayleigh distribution.  You can access the @qcode{B}
    ## property using dot name assignment.
    ##
    ## @end deftp
    B
  endproperties

  properties(GetAccess = public, Constant = true)
    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} DistributionName
    ##
    ## Probability distribution name
    ##
    ## A character vector specifying the name of the probability distribution
    ## object.  This property is read-only.
    ##
    ## @end deftp
    DistributionName = 'Rayleigh';

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} NumParameters
    ##
    ## Number of parameters
    ##
    ## A scalar integer value specifying the number of parameters characterizing
    ## the probability distribution.  This property is read-only.
    ##
    ## @end deftp
    NumParameters = 1;

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} ParameterNames
    ##
    ## Names of parameters
    ##
    ## A cell array of character vectors with each element containing
    ## the name of a distribution parameter.  This property is read-only.
    ##
    ## @end deftp
    ParameterNames = {'B'};

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} ParameterDescription
    ##
    ## Description of parameters
    ##
    ## A cell array of character vectors with each element containing
    ## a short description of a distribution parameter.  This property is
    ## read-only.
    ##
    ## @end deftp
    ParameterDescription = {'Scale'};
  endproperties

  properties(GetAccess = public, Constant = true, Hidden)
    CensoringAllowed = true;
    DistributionCode = 'rayl';
    ParameterRange = [realmin; Inf];
    ParameterLogCI = true;
  endproperties

  properties(GetAccess = public , SetAccess = protected)
    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} ParameterValues
    ##
    ## Distribution parameter values
    ##
    ## A numeric vector containing the values of the distribution
    ## parameters.  This property is read-only. You can change the distribution
    ## parameters by assigning new values to the @qcode{B}
    ## property.
    ##
    ## @end deftp
    ParameterValues

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} Truncation
    ##
    ## Truncation interval
    ##
    ## A @math{1*2} numeric vector specifying the truncation interval for the
    ## probability distribution.  First element contains the lower boundary,
    ## second element contains the upper boundary.  This property is read-only.
    ## You can only truncate a probability distribution with the
    ## @qcode{truncate} method.
    ##
    ## @end deftp
    Truncation

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} IsTruncated
    ##
    ## Flag for truncated probability distribution
    ##
    ## A logical scalar value specifying whether a probability distribution is
    ## truncated or not.  This property is read-only.
    ##
    ## @end deftp
    IsTruncated

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} ParameterCovariance
    ##
    ## Covariance matrix of the parameter estimates
    ##
    ## A numeric matrix containing the variance-covariance of the
    ## parameter estimates.  Diagonal elements contain the variance of each
    ## estimated parameter, and non-diagonal elements contain the covariance
    ## between the parameter estimates.  The covariance matrix is only
    ## meaningful when the distribution was fitted to data.  If the distribution
    ## object was created with fixed parameters, or a parameter of a fitted
    ## distribution is modified, then all elements of the variance-covariance
    ## are zero.  This property is read-only.
    ##
    ## @end deftp
    ParameterCovariance

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} ParameterIsFixed
    ##
    ## Flag for fixed parameters
    ##
    ## A logical vector specifying which parameters are fixed and
    ## which are estimated.  @qcode{true} values correspond to fixed parameters,
    ## @qcode{false} values correspond to parameter estimates.  This property is
    ## read-only.
    ##
    ## @end deftp
    ParameterIsFixed

    ## -*- texinfo -*-
    ## @deftp {prob.RayleighDistribution} {property} InputData
    ##
    ## Data used for fitting a probability distribution
    ##
    ## A scalar structure containing the following fields:
    ## @itemize
    ## @item @qcode{data}: a numeric vector containing the data used for
    ## distribution fitting.
    ## @item @qcode{cens}: a numeric vector of logical values indicating
    ## censoring information corresponding to the elements of the data used for
    ## distribution fitting.  If no censoring vector was used for distribution
    ## fitting, then this field defaults to an empty array.
    ## @item @qcode{freq}: a numeric vector of non-negative integer values
    ## containing the frequency information corresponding to the elements of the
    ## data used for distribution fitting.  If no frequency vector was used for
    ## distribution fitting, then this field defaults to an empty array.
    ## @end itemize
    ##
    ## @end deftp
    InputData
  endproperties

  properties(GetAccess = public, SetAccess = protected, Hidden)
    ParameterCI
  endproperties

  methods(Hidden)

    function this = RayleighDistribution (B)
      if (nargin == 0)
        B = 1;
      endif
      checkparams (B);
      this.InputData = [];
      this.IsTruncated = false;
      this.ParameterValues = B;
      this.ParameterIsFixed = true;
      this.ParameterCovariance = zeros (this.NumParameters);
    endfunction

    function display (this)
      fprintf ("%s =\n", inputname (1));
      __disp__ (this, 'Rayleigh distribution');
    endfunction

    function disp (this)
      __disp__ (this, 'Rayleigh distribution');
    endfunction

    function this = set.B (this, B)
      checkparams (B);
      this.InputData = [];
      this.ParameterValues(1) = B;
      this.ParameterIsFixed = true;
      this.ParameterCovariance = zeros (this.NumParameters);
    endfunction

    function B = get.B (this)
      B = this.ParameterValues(1);
    endfunction

  endmethods

  methods(Access = public)

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{p} =} cdf (@var{pd}, @var{x})
    ## @deftypefnx {prob.RayleighDistribution} {@var{p} =} cdf (@var{pd}, @var{x}, @qcode{'upper'})
    ##
    ## Compute the cumulative distribution function (CDF).
    ##
    ## @code{@var{p} = cdf (@var{pd}, @var{x})} computes the CDF of the
    ## probability distribution object, @var{pd}, evaluated at the values in
    ## @var{x}.
    ##
    ## @code{@var{p} = cdf (@dots{}, @qcode{'upper'})} returns the complement of
    ## the CDF of the probability distribution object, @var{pd}, evaluated at
    ## the values in @var{x}.
    ##
    ## @end deftypefn
    function p = cdf (this, x, uflag)
      if (! isscalar (this))
        error ("cdf: requires a scalar probability distribution.");
      endif
      ## Check for "upper" flag
      if (nargin > 2 && strcmpi (uflag, 'upper'))
        utail = true;
      elseif (nargin > 2 && ! strcmpi (uflag, 'upper'))
        error ("cdf: invalid argument for upper tail.");
      else
        utail = false;
      endif
      ## Do the computations
      p = raylcdf (x, this.B);
      if (this.IsTruncated)
        lx = this.Truncation(1);
        lb = x < lx;
        ux = this.Truncation(2);
        ub = x > ux;
        p(lb) = 0;
        p(ub) = 1;
        p(! (lb | ub)) -= raylcdf (lx, this.B);
        p(! (lb | ub)) /= diff (raylcdf ([lx, ux], this.B));
      endif
      ## Apply uflag
      if (utail)
        p = 1 - p;
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{x} =} icdf (@var{pd}, @var{p})
    ##
    ## Compute the inverse cumulative distribution function (iCDF).
    ##
    ## @code{@var{x} = icdf (@var{pd}, @var{p})} computes the quantile (the
    ## inverse of the CDF) of the probability distribution object, @var{pd},
    ## evaluated at the values in @var{p}.
    ##
    ## @end deftypefn
    function x = icdf (this, p)
      if (! isscalar (this))
        error ("icdf: requires a scalar probability distribution.");
      endif
      if (this.IsTruncated)
        lp = raylcdf (this.Truncation(1), this.B);
        up = raylcdf (this.Truncation(2), this.B);
        ## Adjust p values within range of p @ lower limit and p @ upper limit
        is_nan = p < 0 | p > 1;
        p(is_nan) = NaN;
        np = lp + (up - lp) .* p;
        x = raylinv (np, this.B);
        x(x < this.Truncation(1)) = this.Truncation(1);
        x(x > this.Truncation(2)) = this.Truncation(2);
      else
        x = raylinv (p, this.B);
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{r} =} iqr (@var{pd})
    ##
    ## Compute the interquartile range of a probability distribution.
    ##
    ## @code{@var{r} = iqr (@var{pd})} computes the interquartile range of the
    ## probability distribution object, @var{pd}.
    ##
    ## @end deftypefn
    function r = iqr (this)
      if (! isscalar (this))
        error ("iqr: requires a scalar probability distribution.");
      endif
        r = diff (icdf (this, [0.25, 0.75]));
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{m} =} mean (@var{pd})
    ##
    ## Compute the mean of a probability distribution.
    ##
    ## @code{@var{m} = mean (@var{pd})} computes the mean of the probability
    ## distribution object, @var{pd}.
    ##
    ## @end deftypefn
    function m = mean (this)
      if (! isscalar (this))
        error ("mean: requires a scalar probability distribution.");
      endif
      if (this.IsTruncated)
        fm = @(x) x .* pdf (this, x);
        m = integral (fm, this.Truncation(1), this.Truncation(2));
      else
        m = raylstat (this.B);
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{m} =} median (@var{pd})
    ##
    ## Compute the median of a probability distribution.
    ##
    ## @code{@var{m} = median (@var{pd})} computes the median of the probability
    ## distribution object, @var{pd}.
    ##
    ## @end deftypefn
    function m = median (this)
      if (! isscalar (this))
        error ("median: requires a scalar probability distribution.");
      endif
      if (this.IsTruncated)
        lx = this.Truncation(1);
        ux = this.Truncation(2);
        Fa_b = raylcdf ([lx, ux], this.B);
        m = raylinv (sum (Fa_b) / 2, this.B);
      else
        m = this.B .* sqrt (2 * log (2));
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{nlogL} =} negloglik (@var{pd})
    ##
    ## Compute the negative loglikelihood of a probability distribution.
    ##
    ## @code{@var{nlogL} = negloglik (@var{pd})} computes the negative
    ## loglikelihood of the probability distribution object, @var{pd}.
    ##
    ## @end deftypefn
    function nlogL = negloglik (this)
      if (! isscalar (this))
        error ("negloglik: requires a scalar probability distribution.");
      endif
      if (isempty (this.InputData))
        nlogL = [];
        return
      endif
      nlogL = rayllike (this.B, this.InputData.data, ...
                          this.InputData.cens, this.InputData.freq);
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{ci} =} paramci (@var{pd})
    ## @deftypefnx {prob.RayleighDistribution} {@var{ci} =} paramci (@var{pd}, @var{Name}, @var{Value})
    ##
    ## Compute the confidence intervals for probability distribution parameters.
    ##
    ## @code{@var{ci} = paramci (@var{pd})} computes the lower and upper
    ## boundaries of the 95% confidence interval for each parameter of the
    ## probability distribution object, @var{pd}.
    ##
    ## @code{@var{ci} = paramci (@var{pd}, @var{Name}, @var{Value})} computes
    ## the confidence intervals with additional options specified by
    ## @qcode{Name-Value} pair arguments listed below.
    ##
    ## @multitable @columnfractions 0.18 0.8
    ## @headitem @var{Name} @tab @var{Value}
    ##
    ## @item @qcode{'Alpha'} @tab A scalar value in the range @math{(0,1)}
    ## specifying the significance level for the confidence interval.  The
    ## default value 0.05 corresponds to a 95% confidence interval.
    ##
    ## @item @qcode{'Parameter'} @tab A character vector or a cell array of
    ## character vectors specifying the parameter names for which to compute
    ## confidence intervals.  By default, @code{paramci} computes confidence
    ## intervals for all distribution parameters.
    ## @end multitable
    ##
    ## @code{paramci} is meaningful only when @var{pd} is fitted to data,
    ## otherwise an empty array, @qcode{[]}, is returned.
    ##
    ## @end deftypefn
    function ci = paramci (this, varargin)
      if (! isscalar (this))
        error ("paramci: requires a scalar probability distribution.");
      endif
      if (isempty (this.InputData))
        ci = [this.ParameterValues; this.ParameterValues];
      else
        ci = __paramci__ (this, varargin{:});
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{y} =} pdf (@var{pd}, @var{x})
    ##
    ## Compute the probability distribution function (PDF).
    ##
    ## @code{@var{y} = pdf (@var{pd}, @var{x})} computes the PDF of the
    ## probability distribution object, @var{pd}, evaluated at the values in
    ## @var{x}.
    ##
    ## @end deftypefn
    function y = pdf (this, x)
      if (! isscalar (this))
        error ("pdf: requires a scalar probability distribution.");
      endif
      y = raylpdf (x, this.B);
      if (this.IsTruncated)
        lx = this.Truncation(1);
        lb = x < lx;
        ux = this.Truncation(2);
        ub = x > ux;
        y(lb | ub) = 0;
        y(! (lb | ub)) /= diff (raylcdf ([lx, ux], this.B));
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {} plot (@var{pd})
    ## @deftypefnx {prob.RayleighDistribution} {} plot (@var{pd}, @var{Name}, @var{Value})
    ## @deftypefnx {prob.RayleighDistribution} {@var{h} =} plot (@dots{})
    ##
    ## Plot a probability distribution object.
    ##
    ## @code{plot (@var{pd})} plots a probability density function (PDF) of the
    ## probability distribution object @var{pd}.  If @var{pd} contains data,
    ## which have been fitted by @code{fitdist}, the PDF is superimposed over a
    ## histogram of the data.
    ##
    ## @code{plot (@var{pd}, @var{Name}, @var{Value})} specifies additional
    ## options with the @qcode{Name-Value} pair arguments listed below.
    ##
    ## @multitable @columnfractions 0.18 0.8
    ## @headitem @var{Name} @tab @var{Value}
    ##
    ## @item @qcode{'PlotType'} @tab A character vector specifying the plot
    ## type.  @qcode{'pdf'} plots the probability density function (PDF).  When
    ## @var{pd} is fit to data, the PDF is superimposed on a histogram of the
    ## data.  @qcode{'cdf'} plots the cumulative density function (CDF).  When
    ## @var{pd} is fit to data, the CDF is superimposed over an empirical CDF.
    ## @qcode{'probability'} plots a probability plot using a CDF of the data
    ## and a CDF of the fitted probability distribution.  This option is
    ## available only when @var{pd} is fitted to data.
    ##
    ## @item @qcode{'Discrete'} @tab A logical scalar to specify whether to
    ## plot the PDF or CDF of a discrete distribution object as a line plot or a
    ## stem plot, by specifying @qcode{false} or @qcode{true}, respectively.  By
    ## default, it is @qcode{true} for discrete distributions and @qcode{false}
    ## for continuous distributions.  When @var{pd} is a continuous distribution
    ## object, option is ignored.
    ##
    ## @item @qcode{'Parent'} @tab An axes graphics object for plot.  If
    ## not specified, the @code{plot} function plots into the current axes or
    ## creates a new axes object if one does not exist.
    ## @end multitable
    ##
    ## @code{@var{h} = plot (@dots{})} returns a graphics handle to the plotted
    ## objects.
    ##
    ## @end deftypefn
    function [varargout] = plot (this, varargin)
      if (! isscalar (this))
        error ("plot: requires a scalar probability distribution.");
      endif
      h = __plot__ (this, false, varargin{:});
      if (nargout > 0)
        varargout{1} = h;
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {[@var{nlogL}, @var{param}] =} proflik (@var{pd}, @var{pnum})
    ## @deftypefnx {prob.RayleighDistribution} {[@var{nlogL}, @var{param}] =} proflik (@var{pd}, @var{pnum}, @qcode{'Display'}, @var{display})
    ## @deftypefnx {prob.RayleighDistribution} {[@var{nlogL}, @var{param}] =} proflik (@var{pd}, @var{pnum}, @var{setparam})
    ## @deftypefnx {prob.RayleighDistribution} {[@var{nlogL}, @var{param}] =} proflik (@var{pd}, @var{pnum}, @var{setparam}, @qcode{'Display'}, @var{display})
    ## @deftypefnx {prob.RayleighDistribution} {[@var{nlogL}, @var{param}] =} proflik (@var{pd})
    ## @deftypefnx {prob.RayleighDistribution} {[@var{nlogL}, @var{param}, @var{other}] =} proflik (@dots{})
    ##
    ## Profile likelihood function for a probability distribution object.
    ##
    ## @code{[@var{nlogL}, @var{param}] = proflik (@var{pd}, @var{pnum})}
    ## returns a vector @var{nlogL} of negative loglikelihood values and a
    ## vector @var{param} of corresponding parameter values for the parameter in
    ## the position indicated by @var{pnum}.  By default, @code{proflik} uses
    ## the lower and upper bounds of the 98% confidence interval and computes
    ## 101 equispaced values for the selected parameter when it is the only one
    ## being estimated, and 21 values otherwise.  @var{pd} must be fitted to
    ## data.
    ##
    ## @code{[@var{nlogL}, @var{param}] = proflik (@var{pd}, @var{pnum},
    ## @qcode{'Display'}, @qcode{'on'})} also plots the profile likelihood
    ## against the default range of the selected parameter.
    ##
    ## @code{[@var{nlogL}, @var{param}] = proflik (@var{pd}, @var{pnum},
    ## @var{setparam})} defines a user-defined range of the selected parameter.
    ##
    ## @code{[@var{nlogL}, @var{param}] = proflik (@var{pd}, @var{pnum},
    ## @var{setparam}, @qcode{'Display'}, @qcode{'on'})} also plots the profile
    ## likelihood against the user-defined range of the selected parameter.
    ##
    ## @code{[@var{nlogL}, @var{param}] = proflik (@var{pd})} selects the
    ## first parameter that is not fixed.
    ##
    ## @code{[@var{nlogL}, @var{param}, @var{other}] = proflik (@dots{})} also
    ## returns a matrix @var{other} holding, in each row, the values of the
    ## remaining parameters that maximize the likelihood at the corresponding
    ## value of @var{param}.  A fixed parameter keeps its own value.
    ##
    ## For the Rayleigh distribution, @qcode{@var{pnum} = 1} selects
    ## the parameter @qcode{B}.
    ##
    ## When opted to display the profile likelihood plot, @code{proflik} also
    ## plots the baseline loglikelihood computed at the lower bound of the 95%
    ## confidence interval and estimated maximum likelihood.  The latter might
    ## not be observable if it is outside of the used-defined range of parameter
    ## values.
    ##
    ## @end deftypefn
    function [varargout] = proflik (this, pnum, varargin)
      if (! isscalar (this))
        error ("proflik: requires a scalar probability distribution.");
      endif
      if (isempty (this.InputData))
        error ("proflik: no fitted data available.");
      endif
      if (nargin < 2)
        pnum = [];
      endif
      [varargout{1:nargout}] = __proflik__ (this, pnum, varargin{:});
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{r} =} random (@var{pd})
    ## @deftypefnx {prob.RayleighDistribution} {@var{r} =} random (@var{pd}, @var{rows})
    ## @deftypefnx {prob.RayleighDistribution} {@var{r} =} random (@var{pd}, @var{rows}, @var{cols}, @dots{})
    ## @deftypefnx {prob.RayleighDistribution} {@var{r} =} random (@var{pd}, [@var{sz}])
    ##
    ## Generate random arrays from the probability distribution object.
    ##
    ## @code{@var{r} = random (@var{pd})} returns a random number from the
    ## distribution object @var{pd}.
    ##
    ## When called with a single size argument, @code{betarnd} returns a square
    ## matrix with the dimension specified.  When called with more than one
    ## scalar argument, the first two arguments are taken as the number of rows
    ## and columns and any further arguments specify additional matrix
    ## dimensions.  The size may also be specified with a row vector of
    ## dimensions, @var{sz}.
    ##
    ## @end deftypefn
    function r = random (this, varargin)
      if (! isscalar (this))
        error ("random: requires a scalar probability distribution.");
      endif
      if (this.IsTruncated)
        lp = raylcdf (this.Truncation(1), this.B);
        up = raylcdf (this.Truncation(2), this.B);
        u = unifrnd (lp, up, varargin{:});
        r = sqrt (-2 .* log (1 - u) .* this.B .^ 2);
      else
        r = raylrnd (this.B, varargin{:});
      endif
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{s} =} std (@var{pd})
    ##
    ## Compute the standard deviation of a probability distribution.
    ##
    ## @code{@var{s} = std (@var{pd})} computes the standard deviation of the
    ## probability distribution object, @var{pd}.
    ##
    ## @end deftypefn
    function s = std (this)
      if (! isscalar (this))
        error ("std: requires a scalar probability distribution.");
      endif
      v = var (this);
      s = sqrt (v);
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{t} =} truncate (@var{pd}, @var{lower}, @var{upper})
    ##
    ## Truncate a probability distribution.
    ##
    ## @code{@var{t} = truncate (@var{pd}, @var{lower}, @var{upper})} returns a
    ## probability distribution @var{t}, which is the probability distribution
    ## @var{pd} truncated to the specified interval with lower limit,
    ## @var{lower}, and upper limit, @var{upper}.  If @var{pd} is fitted to data
    ## with @code{fitdist}, the returned probability distribution @var{t} is not
    ## fitted, does not contain any data or estimated values, and it is as it
    ## has been created with the @var{makedist} function, but it includes the
    ## truncation interval.
    ##
    ## @end deftypefn
    function this = truncate (this, lower, upper)
      if (! isscalar (this))
        error ("truncate: requires a scalar probability distribution.");
      endif
      if (nargin < 3)
        error ("truncate: missing input argument.");
      elseif (lower >= upper)
        error ("truncate: invalid lower upper limits.");
      endif
      ## Check boundaries and constrain within support [0, Inf)
      lower(lower < 0) = 0;
      this.Truncation = [lower, upper];
      this.IsTruncated = true;
      this.InputData = [];
      this.ParameterIsFixed = true;
      this.ParameterCovariance = zeros (this.NumParameters);
    endfunction

    ## -*- texinfo -*-
    ## @deftypefn  {prob.RayleighDistribution} {@var{v} =} var (@var{pd})
    ##
    ## Compute the variance of a probability distribution.
    ##
    ## @code{@var{v} = var (@var{pd})} computes the variance of the
    ## probability distribution object, @var{pd}.
    ##
    ## @end deftypefn
    function v = var (this)
      if (! isscalar (this))
        error ("var: requires a scalar probability distribution.");
      endif
      if (this.IsTruncated)
        fm = @(x) x .* pdf (this, x);
        m = integral (fm, this.Truncation(1), this.Truncation(2));
        fv =  @(x) ((x - m) .^ 2) .* pdf (this, x);
        v = integral (fv, this.Truncation(1), this.Truncation(2));
      else
        [~, v] = raylstat (this.B);
      endif
    endfunction

  endmethods

  methods(Static, Hidden)

    function pd = fit (x, varargin)
      ## Check input arguments
      if (nargin < 2)
        alpha = 0.05;
      else
        alpha = varargin{1};
      endif
      if (nargin < 3)
        censor = [];
      else
        censor = varargin{2};
      endif
      if (nargin < 4)
        freq = [];
      else
        freq = varargin{3};
      endif
      ## Fit data
      [phat, pci] = raylfit (x, alpha, censor, freq);
      [~, acov] = rayllike (phat, x, censor, freq);
      ## Create fitted distribution object
      pd = prob.RayleighDistribution.makeFitted ...
           (phat, pci, acov, x, censor, freq);
    endfunction

    function pd = makeFitted (phat, pci, acov, x, censor, freq)
      B = phat(1);
      pd = prob.RayleighDistribution (B);
      pd.ParameterCI = pci;
      pd.ParameterIsFixed = false;
      pd.ParameterCovariance = acov;
      pd.InputData = struct ('data', x, 'cens', censor, 'freq', freq);
    endfunction

  endmethods

endclassdef

function checkparams (B)
  if (! (isscalar (B) && isnumeric (B) && isreal (B)
                          && isfinite (B) && B > 0))
    error ("RayleighDistribution: SIGMA must be a positive real scalar.")
  endif
endfunction

%!demo
%! ## Generate a data set of 5000 random samples from a Rayleigh distribution with
%! ## parameter B = 2.  Fit a Rayleigh distribution to this data and plot
%! ## a PDF of the fitted distribution superimposed on a histogram of the data.
%!
%! pd_fixed = makedist ('Rayleigh', 'B', 2)
%! rand ('seed', 2);
%! data = random (pd_fixed, 5000, 1);
%! pd_fitted = fitdist (data, 'Rayleigh')
%! plot (pd_fitted)
%! msg = 'Fitted Rayleigh distribution with B = %0.2f';
%! title (sprintf (msg, pd_fitted.B))

## Test output
%!shared pd, t
%! pd = prob.RayleighDistribution;
%! t = truncate (pd, 2, 4);
%!assert_equal (cdf (pd, [0:5]), [0, 0.3935, 0.8647, 0.9889, 0.9997, 1], 1e-4);
%!assert_equal (cdf (t, [0:5]), [0, 0, 0, 0.9202, 1, 1], 1e-4);
%!assert_equal (cdf (pd, [1.5, 2, 3, 4, NaN]), [0.6753, 0.8647, 0.9889, 0.9997, NaN], 1e-4);
%!assert_equal (cdf (t, [1.5, 2, 3, 4, NaN]), [0, 0, 0.9202, 1, NaN], 1e-4);
%!assert_equal (icdf (pd, [0:0.2:1]), [0, 0.6680, 1.0108, 1.3537, 1.7941, Inf], 1e-4);
%!assert_equal (icdf (t, [0:0.2:1]), [2, 2.1083, 2.2402, 2.4135, 2.6831, 4], 1e-4);
%!assert_equal (icdf (pd, [-1, 0.4:0.2:1, NaN]), [NaN, 1.0108, 1.3537, 1.7941, Inf, NaN], 1e-4);
%!assert_equal (icdf (t, [-1, 0.4:0.2:1, NaN]), [NaN, 2.2402, 2.4135, 2.6831, 4, NaN], 1e-4);
%!assert_equal (iqr (pd), 0.9066, 1e-4);
%!assert_equal (iqr (t), 0.4609, 1e-4);
%!assert_equal (mean (pd), 1.2533, 1e-4);
%!assert_equal (mean (t), 2.4169, 1e-4);
%!assert_equal (median (pd), 1.1774, 1e-4);
%!assert_equal (median (t), 2.3198, 1e-4);
%!assert_equal (pdf (pd, [0:5]), [0, 0.6065, 0.2707, 0.0333, 0.0013, 0], 1e-4);
%!assert_equal (pdf (t, [0:5]), [0, 0, 2.0050, 0.2469, 0.0099, 0], 1e-4);
%!assert_equal (pdf (pd, [-1, 1.5, NaN]), [0, 0.4870, NaN], 1e-4);
%!assert_equal (pdf (t, [-1, 1.5, NaN]), [0, 0, NaN], 1e-4);
%!assert_equal (isequal (size (random (pd, 100, 50)), [100, 50]), true)
%!assert_equal (any (random (t, 1000, 1) < 2), false);
%!assert_equal (any (random (t, 1000, 1) > 4), false);
%!assert_equal (std (pd), 0.6551, 1e-4);
%!assert_equal (std (t), 0.3591, 1e-4);
%!assert_equal (var (pd), 0.4292, 1e-4);
%!assert_equal (var (t), 0.1290, 1e-4);

%!test
%! ## The profile over the first free parameter: 101 grid values, one row of
%! ## OTHER per value, and the likelihood peaking at the fitted estimate.
%! x = [1.2; 0.4; 3.1; 0.7; 2.5; 1.8; 0.3; 4.2; 1.1; 0.9; ...
%!      2.2; 0.6; 1.5; 3.7; 0.8; 2.9; 1.3; 0.5; 2.0; 1.6];
%! pd = fitdist (x, 'Rayleigh');
%! [nlogL, param, other] = proflik (pd, 1);
%! assert_equal (size (param), [1, 101]);
%! assert_equal (size (other), [101, 0]);
%! assert_equal (proflik (pd), nlogL);
%! [~, imax] = max (nlogL);
%! assert_equal (abs (param(imax) - pd.ParameterValues(1)) <= param(2) - param(1), true);

## Test input validation
## 'prob.RayleighDistribution' constructor
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution (0)
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution (-1)
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution (Inf)
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution (i)
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution ('a')
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution ([1, 2])
%!error <RayleighDistribution: SIGMA must be a positive real scalar.> ...
%! prob.RayleighDistribution (NaN)

## 'cdf' method
%!error <cdf: invalid argument for upper tail.> ...
%! cdf (prob.RayleighDistribution, 2, 'uper')
%!error <cdf: invalid argument for upper tail.> ...
%! cdf (prob.RayleighDistribution, 2, 3)

## 'paramci' method
%!shared x
%! x = raylrnd (1, [1, 100]);
%!error <paramci: optional arguments must be in NAME-VALUE pairs.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha')
%!error <paramci: invalid VALUE for 'Alpha' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', 0)
%!error <paramci: invalid VALUE for 'Alpha' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', 1)
%!error <paramci: invalid VALUE for 'Alpha' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', [0.5 2])
%!error <paramci: invalid VALUE for 'Alpha' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', '')
%!error <paramci: invalid VALUE for 'Alpha' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', {0.05})
%!error <paramci: invalid VALUE for 'Alpha' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'parameter', 'B', 'alpha', {0.05})
%!error <paramci: invalid VALUE size for 'Parameter' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'parameter', {'B', 'param'})
%!error <paramci: invalid VALUE size for 'Parameter' argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', 0.01, ...
%!          'parameter', {'B', 'param'})
%!error <paramci: unknown distribution parameter.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'parameter', 'param')
%!error <paramci: unknown distribution parameter.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', 0.01, 'parameter', 'param')
%!error <paramci: invalid NAME for optional argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'NAME', 'value')
%!error <paramci: invalid NAME for optional argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', 0.01, 'NAME', 'value')
%!error <paramci: invalid NAME for optional argument.> ...
%! paramci (prob.RayleighDistribution.fit (x), 'alpha', 0.01, ...
%!          'parameter', 'B', 'NAME', 'value')

## 'plot' method
%!error <plot: optional arguments must be in NAME-VALUE pairs.> ...
%! plot (prob.RayleighDistribution, 'Parent')
%!error <plot: invalid VALUE for 'PlotType' argument.> ...
%! plot (prob.RayleighDistribution, 'PlotType', 12)
%!error <plot: invalid VALUE size for 'Parameter' argument.> ...
%! plot (prob.RayleighDistribution, 'PlotType', {'pdf', 'cdf'})
%!error <plot: invalid VALUE for 'PlotType' argument.> ...
%! plot (prob.RayleighDistribution, 'PlotType', 'pdfcdf')
%!error <plot: invalid VALUE for 'Discrete' argument.> ...
%! plot (prob.RayleighDistribution, 'Discrete', 'pdfcdf')
%!error <plot: invalid VALUE for 'Discrete' argument.> ...
%! plot (prob.RayleighDistribution, 'Discrete', [1, 0])
%!error <plot: invalid VALUE for 'Discrete' argument.> ...
%! plot (prob.RayleighDistribution, 'Discrete', {true})
%!error <plot: invalid VALUE for 'Parent' argument.> ...
%! plot (prob.RayleighDistribution, 'Parent', 12)
%!error <plot: invalid VALUE for 'Parent' argument.> ...
%! plot (prob.RayleighDistribution, 'Parent', 'hax')
%!error <plot: invalid NAME for optional argument.> ...
%! plot (prob.RayleighDistribution, 'invalidNAME', 'pdf')
%!error <plot: no fitted DATA to plot a probability plot.> ...
%! plot (prob.RayleighDistribution, 'PlotType', 'probability')

## 'proflik' method
%!error <proflik: no fitted data available.> ...
%! proflik (prob.RayleighDistribution, 2)
%!error <proflik: PNUM must be a scalar number indexing a non-fixed parameter.> ...
%! proflik (prob.RayleighDistribution.fit (x), 3)
%!error <proflik: PNUM must be a scalar number indexing a non-fixed parameter.> ...
%! proflik (prob.RayleighDistribution.fit (x), [1, 2])
%!error <proflik: PNUM must be a scalar number indexing a non-fixed parameter.> ...
%! proflik (prob.RayleighDistribution.fit (x), {1})
%!error <proflik: SETPARAM must be a numeric vector.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, ones (2))
%!error <proflik: missing VALUE for 'Display' argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'Display')
%!error <proflik: invalid VALUE type for 'Display' argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'Display', 1)
%!error <proflik: invalid VALUE type for 'Display' argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'Display', {1})
%!error <proflik: invalid VALUE type for 'Display' argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'Display', {'on'})
%!error <proflik: invalid VALUE size for 'Display' argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'Display', ['on'; 'on'])
%!error <proflik: invalid VALUE for 'Display' argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'Display', 'onnn')
%!error <proflik: invalid NAME for optional arguments.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, 'NAME', 'on')
%!error <proflik: invalid optional argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, {'NAME'}, 'on')
%!error <proflik: invalid optional argument.> ...
%! proflik (prob.RayleighDistribution.fit (x), 1, {[1 2 3 4]}, 'Display', 'on')

## 'truncate' method
%!error <truncate: missing input argument.> ...
%! truncate (prob.RayleighDistribution)
%!error <truncate: missing input argument.> ...
%! truncate (prob.RayleighDistribution, 2)
%!error <truncate: invalid lower upper limits.> ...
%! truncate (prob.RayleighDistribution, 4, 2)

## Catch errors when using array of probability objects with available methods
%!shared pd
%! pd = prob.RayleighDistribution (1);
%! pd(2) = prob.RayleighDistribution (3);
%!error <cdf: requires a scalar probability distribution.> cdf (pd, 1)
%!error <icdf: requires a scalar probability distribution.> icdf (pd, 0.5)
%!error <iqr: requires a scalar probability distribution.> iqr (pd)
%!error <mean: requires a scalar probability distribution.> mean (pd)
%!error <median: requires a scalar probability distribution.> median (pd)
%!error <negloglik: requires a scalar probability distribution.> negloglik (pd)
%!error <paramci: requires a scalar probability distribution.> paramci (pd)
%!error <pdf: requires a scalar probability distribution.> pdf (pd, 1)
%!error <plot: requires a scalar probability distribution.> plot (pd)
%!error <proflik: requires a scalar probability distribution.> proflik (pd, 2)
%!error <random: requires a scalar probability distribution.> random (pd)
%!error <std: requires a scalar probability distribution.> std (pd)
%!error <truncate: requires a scalar probability distribution.> ...
%! truncate (pd, 2, 4)
%!error <var: requires a scalar probability distribution.> var (pd)
